Diff: RA8875.h

Revision:

125:7a0b70f56550

Parent:

124:1690a7ae871c

Child:

127:db7f2c704693

--- a/RA8875.h	Sun Jul 31 20:59:01 2016 +0000
+++ b/RA8875.h	Mon Aug 01 22:31:42 2016 +0000
@@ -13,8 +13,9 @@
 /// of the parallel port options.
 ///
 /// The controller additionally supports backlight control (via PWM), keypad scanning
-/// (for a 4 x 5 matrix) and resistive touch-panel support. Others have provides
-/// support for a capacitive touch screen.
+/// (for a 4 x 5 matrix) and resistive touch-panel support. Recently support for a 
+/// capacitive touch screen was integrated, in a manner that makes the resistive and
+/// capactive interfaces nearly identical.
 ///
 /// @section Display_Config Display Configuration
 ///
@@ -219,7 +220,7 @@
 /// the top-left corner of the display, and the width (x) extends positive to the
 /// right and the height (y) extends positive toward the bottom.
 ///
-/// @caution As there are both graphics and text commands, one must take care to use
+/// @note As there are both graphics and text commands, one must take care to use
 /// the proper coordinate system for each. Some of the text APIs are in units
 /// of column and row, which is measured in character positions (and dependent
 /// on the font size), where other text APIs permit pixel level positioning.
@@ -368,6 +369,7 @@
     ///
     typedef RetCode_t (* PrintCallback_T)(filecmd_t cmd, uint8_t * buffer, uint16_t size);
     
+    /// Idle reason provided in the Idle Callback
     typedef enum {
         unknown,            ///< reason has not been assigned (this should not happen)
         status_wait,        ///< driver is polling the status register while busy
@@ -380,24 +382,44 @@
     /// Idle Callback 
     ///
     /// This defines the interface for an idle callback. That is, when the 
-    /// driver is held up, pending some event, it can call a registered
+    /// driver is held up, pending some event, it can call a previously registered
     /// idle function. This could be most useful for servicing a watchdog.
     ///
     /// The user code, which is notified via this API, can force the idle
     /// to abort, by returning the external_abort value back to the driver.
-    ///
-    /// @param info informs the callback why it is idle.
+    /// It is important to note that the abort could leave the driver in
+    /// an undesireable state, so this should be used with care.
+    ///
+    /// @note Should it be called the BusyCallback? It is true, that it will
+    ///     call this function when the RA8875 is busy, but this is also
+    ///     when the CPU is largely idle.
+    ///
+    /// @code
+    /// RetCode_t myIdle_handler(RA8875::IdleReason_T reason)
+    /// {
+    ///     idleFlasher = !idleFlasher;
+    ///     if (it_has_been_too_long())
+    ///         return external_abort;
+    ///     else
+    ///         return noerror;
+    /// }
+    /// @endcode
+    ///
+    /// @param reason informs the callback why it is idle.
     /// @returns noerror to allow the driver continue waiting.
     /// @returns external_abort if the pending action should be aborted.
     ///
-    typedef RetCode_t (* IdleCallback_T)(IdleReason_T info);
+    typedef RetCode_t (* IdleCallback_T)(IdleReason_T reason);
 
-    /// Constructor for a display based on the RAiO RA8875 
-    /// display controller (use for TouchScreen: Resistive or none)
+    /// Basic constructor for a display based on the RAiO RA8875 
+    /// display controller, which can be used with no touchscreen,
+    /// or the RA8875 managed resistive touchscreen.
     ///
     /// This constructor differs from the alternate by supportting
     /// either No Touch Screen, or the RA8875 built-in resistive
-    /// touch screen.
+    /// touch screen. If the application requires the use of the
+    /// capacitive touchscreen, the alternate constructor should 
+    /// be used.
     ///
     /// This configures the registers and calls the @ref init method.
     ///
@@ -434,6 +456,21 @@
     /// This constructor differs from the alternate by including support
     /// for the Capactive Touch screen.
     ///
+    /// @code
+    /// #include "RA8875.h"
+    /// RA8875 lcd(p5, p6, p7, p12, NC, p9,p10,p13, "tft");
+    /// 
+    /// int main()
+    /// {
+    ///     lcd.init();
+    ///     lcd.printf("printing 3 x 2 = %d", 3*2);
+    ///     lcd.circle(400,25, 25, BrightRed);
+    ///     TouchCode_t tp = lcd.TouchPanelReadable();
+    ///     if (tp == touch)
+    ///         ...
+    /// }
+    /// @endcode
+    ///
     /// @param[in] mosi is the SPI master out slave in pin on the mbed.
     /// @param[in] miso is the SPI master in slave out pin on the mbed.
     /// @param[in] sclk is the SPI shift clock pin on the mbed.
@@ -470,7 +507,7 @@
     /// @param[in] color_bpp can be either 8 or 16, but must be consistent
     ///             with the width and height parameters. This parameter is optional
     ///             and the default is 16.
-    /// @param[in] power defines if the display should be left in the power-on or off state.
+    /// @param[in] poweron defines if the display should be left in the power-on or off state.
     ///            If power is true (on), the backlight is set to 100%. This parameter is optional
     ///             and the default is true (on). See @ref Power.
     /// @param[in] keypadon defines if the keypad support should be enabled. This parameter is optional
@@ -486,6 +523,7 @@
     RetCode_t init(int width = 480, int height = 272, int color_bpp = 16, 
         bool poweron = true, bool keypadon = true, bool touchscreeenon = true);
 
+
     /// Get a pointer to the error code.
     ///
     /// This method returns a pointer to a text string that matches the
@@ -494,6 +532,7 @@
     /// @param[in] code is the return value from RetCode_t to look up.
     /// @returns a pointer to the text message representing code. If code
     ///     is not a valid value, then it returns the text for bad_parameter;
+    ///
     const char * GetErrorMessage(RetCode_t code);
     
     
@@ -523,6 +562,7 @@
     /// @returns success/failure code. See @ref RetCode_t.
     ///
     RetCode_t SelectDrawingLayer(uint16_t layer);
+ 
     
     /// Get the currently active drawing layer.
     ///
@@ -544,6 +584,7 @@
     /// @returns the current drawing layer; 0 or 1.
     /// 
     uint16_t GetDrawingLayer(void);
+ 
     
     /// Set the Layer presentation mode.
     ///
@@ -566,6 +607,7 @@
     /// @returns success/failure code. See @ref RetCode_t.
     ///
     RetCode_t SetLayerMode(LayerMode_T mode);
+ 
     
     /// Get the Layer presentation mode.
     ///
@@ -574,6 +616,7 @@
     /// @returns layer mode.
     ///
     LayerMode_T GetLayerMode(void);
+ 
     
     /// Set the layer transparency for each layer.
     ///
@@ -595,6 +638,7 @@
     /// @returns success/failure code. See @ref RetCode_t.
     /// 
     RetCode_t SetLayerTransparency(uint8_t layer1, uint8_t layer2);
+ 
     
     /// Set the background color register used for transparency.
     ///
@@ -617,6 +661,7 @@
     ///
     color_t GetBackgroundTransparencyColor(void);
  
+ 
     /// Initialize theTouch Panel controller with default values 
     ///
     /// This activates the simplified touch panel init, which may work for
@@ -627,6 +672,7 @@
     ///
     RetCode_t TouchPanelInit(void);
         
+ 
     /// Initialize the Touch Panel controller with detailed settings.
     ///
     /// This is the detailed touch panel init, which provides the ability
@@ -703,6 +749,7 @@
     ///
     TouchCode_t TouchPanelReadable(point_t * TouchPoint = NULL);
 
+
     /// Get the reported touch gesture, if any.
     /// 
     /// If it could detect a gesture, it will return a value based on
@@ -727,12 +774,14 @@
     /// @returns count of touch points to communicate; 0 to 5.
     ///
     int TouchCount(void) { return numberOfTouchPoints; }
+
     
     /// Get the count of possible touch channels.
     ///
     /// @returns count of touch channels supported by the hardware.
     ///
     int TouchChannels(void);
+
     
     /// Get the Touch ID value for a specified touch channel.
     ///
@@ -753,6 +802,7 @@
     /// @returns 0 if an invalid channel is queried.
     ///
     uint8_t TouchID(uint8_t channel = 0) { return (channel < 5) ? touchInfo[channel].touchID : touchInfo[0].touchID; }
+
     
     /// Get the Touch Code for a touch channel.
     ///
@@ -766,6 +816,7 @@
     ///
     TouchCode_t TouchCode(uint8_t channel = 0) { return (channel < 5) ? touchInfo[channel].touchCode : touchInfo[0].touchCode; }
 
+
     /// Get the coordinates for a touch channel.
     ///
     /// This returns the (X,Y) coordinates for a touch channel.
@@ -780,6 +831,7 @@
     /// @returns channel 0 information if an invalid channel is queried.
     ///
     point_t TouchCoordinates(uint8_t channel = 0)  { return (channel < 5) ? touchInfo[channel].coordinates : touchInfo[0].coordinates; }
+
     
     /// Poll the TouchPanel and on a touch event return the a to d filtered x, y coordinates.
     ///
@@ -803,6 +855,7 @@
     ///
     TouchCode_t TouchPanelA2DFiltered(int *x, int *y);
 
+
     /// Poll the TouchPanel and on a touch event return the a to d raw x, y coordinates.
     ///
     /// This method reads the touch controller, which has a 10-bit range for each the
@@ -825,6 +878,7 @@
     ///         - release:  indicates a release, touch coordinates are returned.
     ///
     TouchCode_t TouchPanelA2DRaw(int *x, int *y);
+
     
     /// Wait for a touch panel touch and return it.
     /// 
@@ -917,6 +971,7 @@
     ///
     RetCode_t TouchPanelCalibrate(tpMatrix_t * matrix = NULL);
 
+
     /// Perform the touch panel calibration process.
     ///
     /// This method provides the easy "shortcut" to calibrating the touch panel.
@@ -937,6 +992,7 @@
     ///
     RetCode_t TouchPanelCalibrate(const char * msg, tpMatrix_t * matrix = NULL, int maxwait_s = 15);
 
+
     /// Set the calibration matrix for the touch panel.
     ///
     /// This method is used to set the calibration matrix for the touch panel. After
@@ -961,6 +1017,7 @@
     ///
     RetCode_t TouchPanelSetMatrix(tpMatrix_t * matrix);
    
+
 #if 0
     /// Append interrupt handler for specific RA8875 interrupt source
     ///
@@ -988,13 +1045,14 @@
     void UnAppendISR(uint8_t bISRType);
 #endif
 
+
     /// Initialize the keypad interface on the RA8875 controller.
     ///
     /// Enables the keypad subsystem. It will scan the 4 x 5 matrix
     /// and make available key presses. 
     ///
     /// @note See section 5-13 of RAIO RA8875 data sheet for more details.
-    /// @caution When using the display from buy-display.com, be sure that
+    /// @note When using the display from buy-display.com, be sure that
     ///     the option for the keypad is configured on the hardware.
     ///
     /// All parameters are optional.
@@ -1013,6 +1071,7 @@
         uint8_t longTimeAdjustment = 0,
         bool interruptEnable = false, bool wakeupEnable = false);
 
+
     /// Create Key Code definitions for the key matrix.
     ///
     /// This API provides a table of 22 key-code assignments for the matrix of keys.
@@ -1021,7 +1080,7 @@
     ///
     /// In this way, a keypad could easily emulate a piece of a keyboard, transforming
     /// 0 - 20 into the values 0, '0', '1', '2', '3', '4', '5', '6', '7', '8',
-    /// '9', '+', '-', '*' , '/', '=', '<bs>', '<cr>', and so on...
+    /// '9', '+', '-', '*' , '/', '=', '(bs)', '(cr)', and so on...
     ///
     /// @code
     /// //        Return Value by Row, Column   Example reassignment
@@ -1052,15 +1111,17 @@
     ///
     RetCode_t SetKeyMap(const uint8_t * CodeList = NULL);
 
+
     /// Determine if a key has been hit
     ///
     /// @returns true if a key has been hit
     ///
     bool readable();
 
+
     /// Blocking read of the keypad.
     ///
-    /// @caution: This is a blocking read, so it is important to first call _kbhit()
+    /// @note: This is a blocking read, so it is important to first call _kbhit()
     ///         to avoid hanging your processes.
     ///
     /// A keypad connected to the RA8875 is connected in a matrix of 4 rows and 5 columns.
@@ -1096,6 +1157,7 @@
     ///
     RetCode_t WriteCommandW(uint8_t command, uint16_t data);
 
+
     /// Write a command to the display
     ///
     /// This is a high level command, and may invoke several primitives.
@@ -1106,6 +1168,7 @@
     /// @returns success/failure code. See @ref RetCode_t.
     ///
     virtual RetCode_t WriteCommand(unsigned char command, unsigned int data = 0xFFFF);
+
     
     /// Write a data word to the display
     ///
@@ -1115,6 +1178,7 @@
     /// @returns success/failure code. See @ref RetCode_t.
     ///
     RetCode_t WriteDataW(uint16_t data);
+
     
     /// Write a data byte to the display
     ///
@@ -1124,6 +1188,7 @@
     /// @returns success/failure code. See @ref RetCode_t.
     ///
     virtual RetCode_t WriteData(unsigned char data);
+
     
     /// Read a command register
     ///
@@ -1132,6 +1197,7 @@
     ///
     unsigned char ReadCommand(unsigned char command);
     
+
     /// Read a data byte from the display
     ///
     /// This is a high level command, and may invoke several primitives.
@@ -1139,6 +1205,7 @@
     /// @returns data that was read.
     ///
     unsigned char ReadData(void);
+
     
     /// Read a word from the display
     ///
@@ -1148,6 +1215,7 @@
     ///
     uint16_t ReadDataW(void);
 
+
     /// Read the display status
     ///
     /// This is a high level command, and may invoke several primitives.
@@ -1156,17 +1224,20 @@
     ///
     unsigned char ReadStatus(void);
 
+
     /// get the width in pixels of the currently active font
     ///
     /// @returns font width in pixels.
     ///    
     dim_t fontwidth(void);
     
+
     /// get the height in pixels of the currently active font
     ///
     /// @returns font height in pixels.
     ///    
     dim_t fontheight(void);
+
     
     /// get the number of colums based on the currently active font
     ///
@@ -1174,24 +1245,28 @@
     ///    
     virtual int columns(void);
 
+
     /// get the number of rows based on the currently active font
     ///
     /// @returns number of rows.
     ///    
     virtual int rows(void);
 
+
     /// get the screen width in pixels
     ///
     /// @returns screen width in pixels.
     ///
     virtual dim_t width(void);
 
+
     /// get the screen height in pixels
     ///
     /// @returns screen height in pixels.
     ///
     virtual dim_t height(void);
 
+
     /// get the color depth in bits per pixel.
     ///
     /// @returns 8 or 16 only.
@@ -1206,6 +1281,7 @@
     ///
     virtual RetCode_t locate(textloc_t column, textloc_t row);
 
+
     /// Prepare the controller to write text to the screen by positioning
     /// the cursor.
     ///
@@ -1220,6 +1296,7 @@
     ///
     RetCode_t SetTextCursor(loc_t x, loc_t y);
 
+
     /// Prepare the controller to write text to the screen by positioning
     /// the cursor.
     ///
@@ -1234,6 +1311,7 @@
     ///
     RetCode_t SetTextCursor(point_t p);
 
+
     /// Get the current cursor position in pixels.
     ///
     /// @code
@@ -1246,18 +1324,21 @@
     ///
     point_t GetTextCursor(void);
     
+
     /// Get the current cursor horizontal position in pixels.
     ///
     /// @returns cursor position horizontal offset.
     ///
     loc_t GetTextCursor_X(void);
 
+
     /// Get the current cursor vertical position in pixels.
     ///
     /// @returns cursor position vertical offset.
     ///
     loc_t GetTextCursor_Y(void);
 
+
     /// Configure additional Cursor Control settings.
     ///
     /// This API lets you modify other cursor control settings; 
@@ -1270,12 +1351,13 @@
     /// @returns success/failure code. See @ref RetCode_t
     ///
     RetCode_t SetTextCursorControl(cursor_t cursor = NOCURSOR, bool blink = false);
+
     
     /// Select the built-in ISO 8859-X font to use next.
     ///
     /// Supported fonts: ISO 8859-1, -2, -3, -4
     ///
-    /// @caution This only modifies the choice of font from the RA8875 internal
+    /// @note This only modifies the choice of font from the RA8875 internal
     ///     fonts.
     ///
     /// @param[in] font selects the font for the subsequent text rendering.
@@ -1286,6 +1368,7 @@
     ///
     RetCode_t SetTextFont(font_t font = ISO8859_1);
     
+
     /// Sets the display orientation.
     ///
     /// @note This command does not let you "merge" text onto an existing
@@ -1294,7 +1377,7 @@
     ///       to sending text to the screen, or you end with a blended
     ///       image that is probably not as intended.
     ///
-    /// @caution This command only operates on the RA8875 internal fonts.
+    /// @note This command only operates on the RA8875 internal fonts.
     ///
     /// @code
     ///     lcd.cls();
@@ -1327,12 +1410,13 @@
     ///
     RetCode_t SetOrientation(orientation_t angle = normal);
     
+
     /// Control the font behavior.
     ///
     /// This command lets you make several modifications to any text that
     /// will be written to the screen.
     ///
-    /// @caution This command only operates on the RA8875 internal fonts.
+    /// @note This command only operates on the RA8875 internal fonts.
     ///
     /// Options can be combined:
     /// Default:
@@ -1364,13 +1448,14 @@
         VerticalScale vScale = 1, 
         alignment_t alignment = align_none);
     
+
     /// Control the font size of the RA8875 internal fonts.
     ///
     /// This command lets you set the font enlargement for both horizontal
     /// and vertical, independent of the rotation, background, and 
     /// alignment. See @ref SetTextFontControl.
     ///
-    /// @caution This command only operates on the RA8875 internal fonts.
+    /// @note This command only operates on the RA8875 internal fonts.
     ///
     /// @param[in] hScale defaults to 1, but can be 1, 2, 3, or 4,
     ///     and scales the font size by this amount.
@@ -1392,6 +1477,7 @@
     ///
     RetCode_t SetTextFontSize(HorizontalScale hScale = 1, VerticalScale vScale = -1);
     
+
     /// put a character on the screen.
     ///
     /// @param[in] c is the character.
@@ -1399,6 +1485,7 @@
     ///
     virtual int _putc(int c);
 
+
     /// Write string of text to the display
     ///
     /// @code
@@ -1408,6 +1495,7 @@
     /// @param[in] string is the null terminated string to send to the display.
     ///
     void puts(const char * string);
+
     
     /// Write string of text to the display at the specified location.
     ///
@@ -1421,6 +1509,7 @@
     ///
     void puts(loc_t x, loc_t y, const char * string);
     
+
     /// Prepare the controller to write binary data to the screen by positioning
     /// the memory cursor.
     ///
@@ -1429,6 +1518,7 @@
     /// @returns success/failure code. See @ref RetCode_t.
     ///
     virtual RetCode_t SetGraphicsCursor(loc_t x, loc_t y);
+
     
     /// Prepare the controller to read binary data from the screen by positioning
     /// the memory read cursor.
@@ -1439,6 +1529,7 @@
     ///
     virtual RetCode_t SetGraphicsCursorRead(loc_t x, loc_t y);
     
+
     /// Set the window, constraining where items are written to the screen.
     ///
     /// After setting the window, text and graphics are constrained to this
@@ -1465,6 +1556,7 @@
     ///
     virtual RetCode_t window(rect_t r);
     
+
     /// Set the window, constraining where items are written to the screen.
     ///
     /// After setting the window, text and graphics are constrained to this
@@ -1495,6 +1587,7 @@
     ///
     virtual RetCode_t window(loc_t x = 0, loc_t y = 0, dim_t width = (dim_t)-1, dim_t height = (dim_t)-1);
     
+
     /// Clear either the specified layer, or the active layer.
     ///
     /// The behavior is to clear the whole screen for the specified
@@ -1514,6 +1607,7 @@
     /// @returns success/failure code. See @ref RetCode_t.
     ///
     virtual RetCode_t cls(uint16_t layers = 0);
+
     
     /// Clear the screen, or clear only the active window.
     ///
@@ -1532,12 +1626,14 @@
     ///
     RetCode_t clsw(RA8875::Region_t region = FULLWINDOW);
 
+
     /// Set the background color.
     ///
     /// @param[in] color is expressed in 16-bit format.
     /// @returns success/failure code. See @ref RetCode_t.
     ///
     virtual RetCode_t background(color_t color);
+
     
     /// Set the background color.
     ///
@@ -1548,6 +1644,7 @@
     ///
     virtual RetCode_t background(unsigned char r, unsigned char g, unsigned char b);
     
+
     /// Set the foreground color.
     ///
     /// @param[in] color is expressed in 16-bit format.
@@ -1555,6 +1652,7 @@
     ///
     virtual RetCode_t foreground(color_t color);
     
+
     /// Set the foreground color.
     ///
     /// @param[in] r is the red element of the color.
@@ -1564,12 +1662,14 @@
     ///
     virtual RetCode_t foreground(unsigned char r, unsigned char g, unsigned char b);
     
+    
     /// Get the current foreground color value.
     ///
     /// @returns the current foreground color.
     ///
     color_t GetForeColor(void);
     
+    
     /// Draw a pixel in the specified color.
     ///
     /// @note Unlike many other operations, this does not
@@ -1580,12 +1680,14 @@
     ///
     virtual RetCode_t pixel(point_t p, color_t color);
     
+    
     /// Draw a pixel in the current foreground color.
     ///
     /// @param[in] p is the point_t defining the location.
     /// @returns success/failure code. See @ref RetCode_t.
     ///
     virtual RetCode_t pixel(point_t p);
+    
         
     /// Draw a pixel in the specified color.
     ///
@@ -1599,6 +1701,7 @@
     ///
     virtual RetCode_t pixel(loc_t x, loc_t y, color_t color);
     
+    
     /// Draw a pixel in the current foreground color.
     ///
     /// @param[in] x is the horizontal offset to this pixel.
@@ -1607,6 +1710,7 @@
     ///
     virtual RetCode_t pixel(loc_t x, loc_t y);
     
+    
     /// Get a pixel from the display.
     ///
     /// @param[in] x is the horizontal offset to this pixel.
@@ -1615,6 +1719,7 @@
     ///
     virtual color_t getPixel(loc_t x, loc_t y);
     
+    
     /// Write a stream of pixels to the display.
     ///
     /// @param[in] p is a pointer to a color_t array to write.
@@ -1625,6 +1730,7 @@
     ///
     virtual RetCode_t pixelStream(color_t * p, uint32_t count, loc_t x, loc_t y);
     
+    
     /// Get a stream of pixels from the display.
     ///
     /// @param[in] p is a pointer to a color_t array to accept the stream.
@@ -1635,6 +1741,7 @@
     ///
     virtual RetCode_t getPixelStream(color_t * p, uint32_t count, loc_t x, loc_t y);
     
+    
     /// Write a boolean stream to the display.
     ///
     /// This takes a bit stream in memory and using the current color settings
@@ -1654,6 +1761,7 @@
     /// @returns success/failure code. See @ref RetCode_t.
     ///
     virtual RetCode_t booleanStream(loc_t x, loc_t y, dim_t w, dim_t h, const uint8_t * boolStream);
+
     
     /// Draw a line in the specified color
     ///
@@ -1667,6 +1775,7 @@
     ///
     RetCode_t line(point_t p1, point_t p2, color_t color);
 
+
     /// Draw a line
     ///
     /// Draws a line using the foreground color setting.
@@ -1676,6 +1785,7 @@
     /// @returns success/failure code. See @ref RetCode_t.
     ///
     RetCode_t line(point_t p1, point_t p2);
+
     
     /// Draw a line in the specified color
     ///
@@ -1691,6 +1801,7 @@
     ///
     RetCode_t line(loc_t x1, loc_t y1, loc_t x2, loc_t y2, color_t color);
 
+
     /// Draw a line
     ///
     /// Draws a line using the foreground color setting.
@@ -1703,6 +1814,7 @@
     ///
     RetCode_t line(loc_t x1, loc_t y1, loc_t x2, loc_t y2);
 
+
     /// Draw a rectangle in the specified color
     ///
     /// @note As a side effect, this changes the current
@@ -1715,7 +1827,8 @@
     ///
     RetCode_t rect(rect_t rect, color_t color, fill_t fillit = NOFILL);
     
-     /// Draw a filled rectangle in the specified color
+
+    /// Draw a filled rectangle in the specified color
     ///
     /// @note As a side effect, this changes the current
     ///     foreground color for subsequent operations.
@@ -1727,6 +1840,7 @@
     ///
     RetCode_t fillrect(rect_t rect, color_t color, fill_t fillit = FILL);
 
+
     /// Draw a rectangle in the specified color
     ///
     /// @note As a side effect, this changes the current
@@ -1743,6 +1857,7 @@
     RetCode_t rect(loc_t x1, loc_t y1, loc_t x2, loc_t y2, 
         color_t color, fill_t fillit = NOFILL);
 
+
     /// Draw a filled rectangle in the specified color
     ///
     /// @note As a side effect, this changes the current
@@ -1759,6 +1874,7 @@
     virtual RetCode_t fillrect(loc_t x1, loc_t y1, loc_t x2, loc_t y2, 
         color_t color, fill_t fillit = FILL);
 
+
     /// Draw a rectangle
     ///
     /// Draws a rectangle using the foreground color setting.
@@ -1773,6 +1889,7 @@
     RetCode_t rect(loc_t x1, loc_t y1, loc_t x2, loc_t y2, 
         fill_t fillit = NOFILL);
 
+
     /// Draw a filled rectangle with rounded corners using the specified color.
     ///
     /// This draws a rounded rectangle. A numbers of checks are made on the values,
@@ -1800,6 +1917,7 @@
     RetCode_t fillroundrect(loc_t x1, loc_t y1, loc_t x2, loc_t y2, 
         dim_t radius1, dim_t radius2, color_t color, fill_t fillit = FILL);
 
+
     /// Draw a filled rectangle with rounded corners using the specified color.
     ///
     /// This draws a rounded rectangle. A numbers of checks are made on the values,
@@ -1824,6 +1942,7 @@
     RetCode_t fillroundrect(rect_t r, 
         dim_t radius1, dim_t radius2, color_t color, fill_t fillit = FILL);
 
+
     /// Draw a rectangle with rounded corners using the specified color.
     ///
     /// This draws a rounded rectangle. A numbers of checks are made on the values,
@@ -1848,6 +1967,7 @@
     RetCode_t roundrect(rect_t r, 
         dim_t radius1, dim_t radius2, color_t color, fill_t fillit = NOFILL);
 
+
     /// Draw a rectangle with rounded corners using the specified color.
     ///
     /// This draws a rounded rectangle. A numbers of checks are made on the values,
@@ -1875,6 +1995,7 @@
     RetCode_t roundrect(loc_t x1, loc_t y1, loc_t x2, loc_t y2, 
         dim_t radius1, dim_t radius2, color_t color, fill_t fillit = NOFILL);
 
+
     /// Draw a rectangle with rounded corners.
     ///
     /// This draws a rounded rectangle. A numbers of checks are made on the values,
@@ -1898,6 +2019,7 @@
     RetCode_t roundrect(loc_t x1, loc_t y1, loc_t x2, loc_t y2, 
         dim_t radius1, dim_t radius2, fill_t fillit = NOFILL);
 
+
     /// Draw a triangle in the specified color.
     ///
     /// @note As a side effect, this changes the current
@@ -1916,6 +2038,7 @@
     RetCode_t triangle(loc_t x1, loc_t y1, loc_t x2, loc_t y2, 
         loc_t x3, loc_t y3, color_t color, fill_t fillit = NOFILL);
     
+
     /// Draw a filled triangle in the specified color.
     ///
     /// @note As a side effect, this changes the current
@@ -1934,6 +2057,7 @@
     RetCode_t filltriangle(loc_t x1, loc_t y1, loc_t x2, loc_t y2, 
         loc_t x3, loc_t y3, color_t color, fill_t fillit = FILL);
 
+
     /// Draw a triangle
     ///
     /// Draws a triangle using the foreground color setting.
@@ -1959,10 +2083,12 @@
     /// @param[in] p defines the center of the circle.
     /// @param[in] radius defines the size of the circle.
     /// @param[in] color defines the foreground color.
+    /// @param[in] fillit is optional to FILL the circle. default is NOFILL.
     /// @returns success/failure code. See @ref RetCode_t.
     ///
     RetCode_t circle(point_t p, dim_t radius, color_t color, fill_t fillit = NOFILL);
 
+
     /// Draw a filled circle using the specified color.
     ///
     /// @note As a side effect, this changes the current
@@ -1971,20 +2097,24 @@
     /// @param[in] p defines the center of the circle.
     /// @param[in] radius defines the size of the circle.
     /// @param[in] color defines the foreground color.
+    /// @param[in] fillit is optional to FILL the circle. default is FILL.
     /// @returns success/failure code. See @ref RetCode_t.
     ///
     RetCode_t fillcircle(point_t p, dim_t radius, color_t color, fill_t fillit = FILL);
 
+
     /// Draw a circle.
     ///
     /// Draws a circle using the foreground color setting.
     ///
     /// @param[in] p defines the center of the circle.
     /// @param[in] radius defines the size of the circle.
+    /// @param[in] fillit is optional to FILL the circle. default is NOFILL.
     /// @returns success/failure code. See @ref RetCode_t.
     ///
     RetCode_t circle(point_t p, dim_t radius, fill_t fillit = NOFILL);
 
+
     /// Draw a circle using the specified color.
     ///
     /// @note As a side effect, this changes the current
@@ -1994,10 +2124,12 @@
     /// @param[in] y is the vertical center of the circle.
     /// @param[in] radius defines the size of the circle.
     /// @param[in] color defines the foreground color.
+    /// @param[in] fillit is optional to FILL the circle. default is NOFILL.
     /// @returns success/failure code. See @ref RetCode_t.
     ///
     RetCode_t circle(loc_t x, loc_t y, dim_t radius, color_t color, fill_t fillit = NOFILL);
 
+
     /// Draw a filled circle using the specified color.
     ///
     /// @note As a side effect, this changes the current
@@ -2007,10 +2139,12 @@
     /// @param[in] y is the vertical center of the circle.
     /// @param[in] radius defines the size of the circle.
     /// @param[in] color defines the foreground color.
+    /// @param[in] fillit is optional to FILL the circle. default is FILL.
     /// @returns success/failure code. See @ref RetCode_t.
     ///
     RetCode_t fillcircle(loc_t x, loc_t y, dim_t radius, color_t color, fill_t fillit = FILL);
 
+
     /// Draw a circle.
     ///
     /// Draws a circle using the foreground color setting.
@@ -2018,6 +2152,7 @@
     /// @param[in] x is the horizontal center of the circle.
     /// @param[in] y is the vertical center of the circle.
     /// @param[in] radius defines the size of the circle.
+    /// @param[in] fillit is optional to FILL the circle. default is NOFILL.
     /// @returns success/failure code. See @ref RetCode_t.
     ///
     RetCode_t circle(loc_t x, loc_t y, dim_t radius, fill_t fillit = NOFILL);
@@ -2038,6 +2173,7 @@
     RetCode_t ellipse(loc_t x, loc_t y, dim_t radius1, dim_t radius2, 
         color_t color, fill_t fillit = NOFILL);
 
+
     /// Draw a filled Ellipse using the specified color
     ///
     /// @note As a side effect, this changes the current
@@ -2054,6 +2190,7 @@
     RetCode_t fillellipse(loc_t x, loc_t y, dim_t radius1, dim_t radius2, 
         color_t color, fill_t fillit = FILL);
 
+
     /// Draw an Ellipse
     ///
     /// Draws it using the foreground color setting.
@@ -2067,6 +2204,7 @@
     ///
     RetCode_t ellipse(loc_t x, loc_t y, dim_t radius1, dim_t radius2, fill_t fillit = NOFILL);
     
+
     /// Control display power
     ///
     /// @param[in] on when set to true will turn on the display, when false it is turned off.
@@ -2074,12 +2212,14 @@
     ///
     RetCode_t Power(bool on);
 
+
     /// Reset the display controller via the Software Reset interface.
     ///
     /// @returns success/failure code. See @ref RetCode_t.
     ///
     RetCode_t Reset(void);
     
+
     /// Set backlight brightness.
     ///
     /// When the built-in PWM is used to control the backlight, this 
@@ -2089,6 +2229,7 @@
     /// @returns success/failure code. See @ref RetCode_t.
     ///
     RetCode_t Backlight_u8(unsigned char brightness);
+
     
     /// Get backlight brightness.
     ///
@@ -2106,12 +2247,14 @@
     ///
     RetCode_t Backlight(float brightness);
 
+
     /// Get backlight brightness.
     ///
     /// @returns backlight setting from 0 (off) to 1.0 (full on).
     /// 
     float GetBacklight(void);
 
+
     /// Select a User Font for all subsequent text.
     ///
     /// @note Tool to create the fonts is accessible from its creator
@@ -2124,24 +2267,33 @@
     ///
     virtual RetCode_t SelectUserFont(const uint8_t * font = NULL);
 
-    typedef uint8_t byte;
 
     /// Get the RGB value for a DOS color.
     ///
+    /// @code
+    ///     color_t color = DOSColor(12);
+    /// @endcode
+    ///
     /// @param[in] i is the color, in the range 0 to 15;
     /// @returns the RGB color of the selected index, or 0 
     ///     if the index is out of bounds.
     ///
     color_t DOSColor(int i);
 
+
     /// Get the color name (string) for a DOS color.
     ///
+    /// @code
+    ///     printf("color is %s\n", DOSColorNames(12));
+    /// @endcode
+    ///
     /// @param[in] i is the color, in the range 0 to 15;
     /// @returns a pointer to a string with the color name,
     ///     or NULL if the index is out of bounds.
     /// 
     const char * DOSColorNames(int i);
 
+
     /// Advanced method indicating the start of a graphics stream.
     ///
     /// This is called prior to a stream of pixel data being sent.
@@ -2158,6 +2310,7 @@
     /// @returns error code.
     ///
     virtual RetCode_t _StartGraphicsStream(void);
+
     
     /// Advanced method to put a single color pixel to the screen.
     ///
@@ -2165,10 +2318,15 @@
     /// See @ref _StartGraphicsStream() is called, and it should be followed 
     /// by _EndGraphicsStream.
     ///
+    /// @code
+    ///     _putp(DOSColor(12));
+    /// @endcode
+    ///
     /// @param[in] pixel is a color value to be put on the screen.
     /// @returns error code.
     ///
     virtual RetCode_t _putp(color_t pixel);
+
     
     /// Advanced method indicating the end of a graphics stream.
     ///
@@ -2181,6 +2339,7 @@
     ///
     virtual RetCode_t _EndGraphicsStream(void);
 
+
     /// Set the SPI port frequency (in Hz).
     ///
     /// This uses the mbed SPI driver, and is therefore dependent on
@@ -2209,7 +2368,8 @@
     /// @returns success/failure code. See @ref RetCode_t.
     ///
     RetCode_t frequency(unsigned long Hz = RA8875_DEFAULT_SPI_FREQ, unsigned long Hz2 = 0);
-    
+
+
     /// This method captures the specified area as a 24-bit bitmap file.
     ///
     /// Even though this is a 16-bit display, the stored image is in
@@ -2228,6 +2388,7 @@
     /// @return success or error code.
     ///
     RetCode_t PrintScreen(loc_t x, loc_t y, dim_t w, dim_t h, const char *Name_BMP);
+
     
     /// This method captures the specified area as a 24-bit bitmap file
     /// and delivers it to the previously attached callback.
@@ -2248,6 +2409,7 @@
     /// @return success or error code.
     ///
     RetCode_t PrintScreen(loc_t x, loc_t y, dim_t w, dim_t h);
+
     
     /// PrintScreen callback registration.
     ///
@@ -2260,6 +2422,7 @@
     ///
     void AttachPrintHandler(PrintCallback_T callback = NULL) { c_callback = callback; }
 
+
     /// PrintScreen callback registration.
     ///
     /// This method attaches a c++ class method as a callback of type PrintCallback_T.
@@ -2275,10 +2438,11 @@
         method_callback = (uint32_t (FPointerDummy::*)(uint32_t, uint8_t *, uint16_t))method;
     }
 
+
     /// This method captures the specified area as a 24-bit bitmap file,
     /// including the option of layer selection.
     ///
-    /// @caution This method is deprecated as the alternate PrintScreen API
+    /// @note This method is deprecated as the alternate PrintScreen API
     ///         automatically examines the display layer configuration.
     ///         Therefore, calls to this API will ignore the layer parameter
     ///         and automatically execute the other method.
@@ -2295,10 +2459,11 @@
     /// @return success or error code.
     ///
     RetCode_t PrintScreen(uint16_t layer, loc_t x, loc_t y, dim_t w, dim_t h, const char *Name_BMP);
+
     
     /// idle callback registration.
     ///
-    /// This method attaches a simple c-compatible callback of type XXXXXXXXXXX.
+    /// This method attaches a simple c-compatible callback of type IdleCallback_T.
     /// Then, at any time when the display driver is waiting, it will call the
     /// registered function. This is probably most useful if you want to service
     /// a watchdog, when you may have called an API that will "hang" waiting