Revision 1:1cb0fcbce1bf, committed 2015-01-23

Comitter:

frankvnk

Date:

Fri Jan 23 20:21:32 2015 +0000

Parent:

0:282710e02ef4

Commit message:

Added documentation

Changed in this revision

--- a/GraphicsDisplay.cpp	Wed Jan 21 19:40:58 2015 +0000
+++ b/GraphicsDisplay.cpp	Fri Jan 23 20:21:32 2015 +0000
@@ -125,9 +125,7 @@
 }
     
 void GraphicsDisplay::putp(int colour) {
-    // put pixel at current pixel location
     pixel(_x, _y, colour);
-    // update pixel location based on window settings
     _x++;
     if(_x > _x2) {
         _x = _x1;

--- a/GraphicsDisplay.h	Wed Jan 21 19:40:58 2015 +0000
+++ b/GraphicsDisplay.h	Fri Jan 23 20:21:32 2015 +0000
@@ -16,26 +16,112 @@
 
 #include "TextDisplay.h"
 
+/** A common base class for Graphics displays
+*/
 class GraphicsDisplay : public TextDisplay {
 
 public:         
           
+    /** Create a GraphicsDisplay interface
+    * @param name The name used by the parent class to access the interface
+    */
     GraphicsDisplay(const char* name);
      
+    // functions needing implementation in derived implementation class
+    // ----------------------------------------------------------------
+    /** Draw a pixel in the specified color.
+    * @note this method must be supported in the derived class.
+    * @param x is the horizontal offset to this pixel.
+    * @param y is the vertical offset to this pixel.
+    * @param colour defines the color for the pixel.
+    */
     virtual void pixel(int x, int y, int colour) = 0;
+
+    /** get the screen width in pixels
+    * @note this method must be supported in the derived class.
+    * @returns screen width in pixels.
+    */
     virtual int width() = 0;
+
+    /** get the screen height in pixels
+    * @note this method must be supported in the derived class.
+    * @returns screen height in pixels.
+    */
     virtual int height() = 0;
         
+    // functions that come for free, but can be overwritten
+    // ----------------------------------------------------
+    /** Set the window, which controls where items are written to the screen.
+    * When something hits the window width, it wraps back to the left side
+    * and down a row. If the initial write is outside the window, it will
+    * be captured into the window when it crosses a boundary.
+    * @param x is the left edge in pixels.
+    * @param y is the top edge in pixels.
+    * @param w is the window width in pixels.
+    * @param h is the window height in pixels.
+    * @note this method may be overridden in a derived class.
+    */
     virtual void window(int x, int y, int w, int h);
+
+    /** Put a single pixel at the current pixel location
+    * and update the pixel location based on window settings.
+    * @param colour is the pixel colour.
+    * @note this method may be overridden in a derived class.
+    */
     virtual void putp(int colour);
     
+    /** clear the entire screen
+    */
     virtual void cls();
+
+    /** Fill a region using a single colour.
+    * @param x is the left-edge of the region.
+    * @param y is the top-edge of the region.
+    * @param w specifies the width of the region.
+    * @param h specifies the height of the region.
+    * @param colour is the fill colour.
+    * @note this method may be overridden in a derived class.
+    */
     virtual void fill(int x, int y, int w, int h, int colour);
+
+    /** Fill a region using an array.
+    * @param x is the left-edge of the region.
+    * @param y is the top-edge of the region.
+    * @param w specifies the width of the region.
+    * @param h specifies the height of the region.
+    * @param colour is a pointer to the array with size = w * h.
+    * @note this method may be overridden in a derived class.
+    */
     virtual void blit(int x, int y, int w, int h, const int *colour);    
+
+    /** Fill a region using a font array.
+    * @param x is the left-edge of the region.
+    * @param y is the top-edge of the region.
+    * @param w specifies the width of the region.
+    * @param h specifies the height of the region.
+    * @param colour is a pointer to the font array.
+    * @note this method may be overridden in a derived class.
+    */
     virtual void blitbit(int x, int y, int w, int h, const char* colour);
     
+    /** Print one character at the specified row, column.
+    * @param column is the horizontal character position.
+    * @param row is the vertical character position.
+    * @param value is the character to print.
+    * @note this method may be overridden in a derived class.
+    */
     virtual void character(int column, int row, int value);
+
+    /** Get the number of columns based on the currently active font.
+    * @returns number of columns.
+    * @note this method may be overridden in a derived class.
+    */
     virtual int columns();
+
+    /** Get the number of rows based on the currently active font.
+    * @returns number of rows.
+    * @note this method may be overridden in a derived class.
+    */
     virtual int rows();
     
 protected:

--- a/TextDisplay.h	Wed Jan 21 19:40:58 2015 +0000
+++ b/TextDisplay.h	Fri Jan 23 20:21:32 2015 +0000
@@ -18,47 +18,73 @@
 
 #include "mbed.h"
 
+/** A common base class for Text displays
+*/
 class TextDisplay : public Stream {
 public:
 
-  // functions needing implementation in derived implementation class
-  /** Create a TextDisplay interface
-     *
-     * @param name The name used in the path to access the strean through the filesystem
-     */
+    // functions needing implementation in derived implementation class
+    // ----------------------------------------------------------------
+    /** Create a TextDisplay interface
+    * @param name The name used in the path to access the strean through the filesystem
+    */
     TextDisplay(const char *name = NULL);
 
     /** output a character at the given position
-     *
-     * @param column column where charater must be written
-     * @param  row where character must be written
-     * @param c the character to be written to the TextDisplay
-     */
+    *
+    * @param column column where charater must be written
+    * @param  row where character must be written
+    * @param c the character to be written to the TextDisplay
+    * @note this method may be overridden in a derived class.
+    */
     virtual void character(int column, int row, int c) = 0;
 
-    /** return number if rows on TextDisplay
-     * @result number of rows
-     */
+    /** return number of rows on TextDisplay
+    * @result number of rows
+    * @note this method must be supported in the derived class.
+    */
     virtual int rows() = 0;
 
-    /** return number if columns on TextDisplay
-    * @result number of rows
+    /** return number of columns on TextDisplay
+    * @result number of columns
+    * @note this method must be supported in the derived class.
     */
     virtual int columns() = 0;
     
     // functions that come for free, but can be overwritten
-
+    // ----------------------------------------------------
     /** redirect output from a stream (stoud, sterr) to  display
     * @param stream stream that shall be redirected to the TextDisplay
+    * @note this method may be overridden in a derived class.
+    * @returns true if the claim succeeded.
     */
     virtual bool claim (FILE *stream);
 
-    /** clear screen
+    /** clear the entire screen
+    * @note this method may be overridden in a derived class.
     */
     virtual void cls();
+
+    /** locate the cursor at a character position.
+    * Based on the currently active font, locate the cursor on screen.
+    * @note this method may be overridden in a derived class.
+    * @param column is the horizontal offset from the left side.
+    * @param row is the vertical offset from the top.
+    */
     virtual void locate(int column, int row);
+
+    /** set the foreground color
+    * @note this method may be overridden in a derived class.
+    * @param color is color to use for foreground drawing.
+    */
     virtual void foreground(uint16_t colour);
+
+    /** set the background color
+    * @note this method may be overridden in a derived class.
+    * @param color is color to use for background drawing.
+    */
     virtual void background(uint16_t colour);
+
     // putc (from Stream)
     // printf (from Stream)