Diff: TextDisplay.h

Revision:

37:f19b7e7449dc

Parent:

33:b6b710758ab3

Child:

61:8f3153bf0baa

--- a/TextDisplay.h	Sat Jan 25 00:00:02 2014 +0000
+++ b/TextDisplay.h	Sat Jan 25 19:47:33 2014 +0000
@@ -20,49 +20,100 @@
 
 #include "DisplayDefs.h"
 
+/// A text display class that supports character based
+/// presentation.
+///
 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
-    */
+    /// Create a TextDisplay interface
+    ///
+    /// @param name The name used in the path to access the display through 
+    ///     the stdio stream.
+    ///
     TextDisplay(const char *name = NULL);
 
-    /** output a character at the given position
-     *
-     * @param x position in pixels
-     * @param y position in pixels
-     * @param c the character to be written to the TextDisplay
-     * @returns number of pixels to advance the cursor.
-     */
+    /// output a character at the given position
+    ///
+    /// @note this method may be overridden in a derived class.
+    ///
+    /// @param x position in pixels
+    /// @param y position in pixels
+    /// @param c the character to be written to the TextDisplay
+    /// @returns number of pixels to advance the cursor which could be the cell width
+    ///     for non-proportional characters, or the actual character width for
+    ///     proportional characters.
+    ///
     virtual int character(int x, int y, int c) = 0;
 
-    /** return number if rows on TextDisplay
-     * @result number of rows
-     */
+    /// return number of rows on TextDisplay
+    ///
+    /// @note this method may be overridden in a derived class.
+    ///
+    /// @returns number of text rows for the display for the currently 
+    ///     active font.
+    ///
     virtual int rows() = 0;
 
-    /** return number if columns on TextDisplay
-    * @result number of rows
-    */
+    /// return number if columns on TextDisplay
+    ///
+    /// @note this method may be overridden in a derived class.
+    ///
+    /// @returns number of text rows for the display for the currently
+    ///     active font.
+    ///
     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
-    */
+    /// redirect output from a stream (stoud, sterr) to  display
+    ///
+    /// @note this method may be overridden in a derived class.
+    ///
+    /// @param stream that shall be redirected to the TextDisplay
+    /// @returns true if the claim succeeded.
+    ///
     virtual bool claim (FILE *stream);
 
-    /** clear screen
-    */
+    /// clear screen
+    ///
+    /// @note this method may be overridden in a derived class.
+    ///
+    /// @returns error code.
+    ///
     virtual RetCode_t cls() = 0;
-    virtual RetCode_t locate(unsigned int column, unsigned int row) = 0;
-    virtual RetCode_t foreground(uint16_t color) = 0;
-    virtual RetCode_t background(uint16_t color) = 0;
+    
+    /// 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.
+    /// @returns error code.
+    ///
+    virtual RetCode_t locate(textloc_t column, textloc_t row) = 0;
+    
+    /// set the foreground color
+    ///
+    /// @note this method may be overridden in a derived class.
+    ///
+    /// @param color is color to use for foreground drawing.
+    /// @returns error code.
+    ///
+    virtual RetCode_t foreground(color_t color) = 0;
+
+    /// set the background color
+    ///
+    /// @note this method may be overridden in a derived class.
+    ///
+    /// @param color is color to use for background drawing.
+    /// @returns error code.
+    ///
+    virtual RetCode_t background(color_t color) = 0;
     // putc (from Stream)
     // printf (from Stream)
 
@@ -75,8 +126,8 @@
     uint16_t _row;
 
     // colors
-    uint16_t _foreground;
-    uint16_t _background;
+    color_t _foreground;
+    color_t _background;
     char *_path;
 };