TextDisplay.h

00001 /// @page TextDisplay_Copyright Text Display Library Base Class
00002 ///
00003 /// mbed TextDisplay Library Base Class
00004 /// @copyright © 2007-2009 sford
00005 /// Released under the MIT License: http://mbed.org/license/mit
00006 ///
00007 /// A common base class for Text displays
00008 /// To port a new display, derive from this class and implement
00009 /// the constructor (setup the display), character (put a character
00010 /// at a location), rows and columns (number of rows/cols) functions.
00011 /// Everything else (locate, printf, putc, cls) will come for free
00012 ///
00013 /// The model is the display will wrap at the right and bottom, so you can
00014 /// keep writing and will always get valid characters. The location is
00015 /// maintained internally to the class to make this easy
00016 ///
00017 #ifndef MBED_TEXTDISPLAY_H
00018 #define MBED_TEXTDISPLAY_H
00019 
00020 #include "mbed.h"
00021 
00022 #include "DisplayDefs.h"
00023 
00024 /// A text display class that supports character based
00025 /// presentation.
00026 ///
00027 class TextDisplay : public Stream
00028 {
00029 public:
00030 
00031     // functions needing implementation in derived implementation class
00032     /// Create a TextDisplay interface
00033     ///
00034     /// @param name The name used in the path to access the display through
00035 
00036     ///     the stdio stream.
00037     ///
00038     TextDisplay(const char *name = NULL);
00039 
00040     /// destructor to clean up
00041     ///
00042     virtual ~TextDisplay();
00043 
00044     /// output a character at the given position
00045     ///
00046     /// @note this method may be overridden in a derived class.
00047     ///
00048     /// @param[in] x position in pixels
00049     /// @param[in] y position in pixels
00050     /// @param[in] c the character to be written to the TextDisplay
00051     /// @returns number of pixels to advance the cursor which could be the cell width
00052     ///     for non-proportional characters, or the actual character width for
00053     ///     proportional characters.
00054     ///
00055     virtual int character(int x, int y, int c) = 0;
00056 
00057     /// return number of rows on TextDisplay
00058     ///
00059     /// @note this method may be overridden in a derived class.
00060     ///
00061     /// @returns number of text rows for the display for the currently
00062 
00063     ///     active font.
00064     ///
00065     virtual int rows() = 0;
00066 
00067     /// return number if columns on TextDisplay
00068     ///
00069     /// @note this method may be overridden in a derived class.
00070     ///
00071     /// @returns number of text rows for the display for the currently
00072     ///     active font.
00073     ///
00074     virtual int columns() = 0;
00075 
00076     // functions that come for free, but can be overwritten
00077 
00078     /// redirect output from a stream (stoud, sterr) to  display
00079     ///
00080     /// @note this method may be overridden in a derived class.
00081     ///
00082     /// @param[in] stream that shall be redirected to the TextDisplay
00083     /// @returns true if the claim succeeded.
00084     ///
00085     virtual bool claim (FILE *stream);
00086 
00087     /// clear screen
00088     ///
00089     /// @note this method may be overridden in a derived class.
00090     ///
00091     /// @param[in] layers is ignored, but supports maintaining the same
00092 
00093     ///     API for the graphics layer.
00094     /// @returns @ref RetCode_t value.
00095     ///
00096     virtual RetCode_t cls(uint16_t layers = 0) = 0;
00097    
00098 
00099     /// locate the cursor at a character position.
00100     ///
00101     /// Based on the currently active font, locate the cursor on screen.
00102     ///
00103     /// @note this method may be overridden in a derived class.
00104     ///
00105     /// @param[in] column is the horizontal offset from the left side.
00106     /// @param[in] row is the vertical offset from the top.
00107     /// @returns @ref point_t value that was the last location.
00108     ///
00109     virtual point_t locate(textloc_t column, textloc_t row) = 0;
00110    
00111 
00112     /// set the foreground color
00113     ///
00114     /// @note this method may be overridden in a derived class.
00115     ///
00116     /// @param[in] color is color to use for foreground drawing.
00117     /// @returns @ref color_t value that was the previous color.
00118     ///
00119     virtual color_t foreground(color_t color) = 0;
00120 
00121     /// set the background color
00122     ///
00123     /// @note this method may be overridden in a derived class.
00124     ///
00125     /// @param[in] color is color to use for background drawing.
00126     /// @returns @ref color_t value that was the previous color.
00127     ///
00128     virtual color_t background(color_t color) = 0;
00129     // putc (from Stream)
00130     // printf (from Stream)
00131 
00132 protected:
00133     /// a method to put a character to the display.
00134     ///
00135     /// @param value is the character value to send to the display
00136     /// @returns the character that was sent.
00137     ///
00138     virtual int _putc(int value);
00139    
00140 
00141     /// a method to get a character from the stdin
00142     ///
00143 
00144     /// @returns the fetched character.
00145     ///
00146     virtual int _getc();
00147 
00148     uint16_t _column;           ///< character column location
00149     uint16_t _row;              ///< character row location
00150 
00151     // colors
00152     color_t _foreground;        ///< presently set foreground color
00153     color_t _background;        ///< presently set background color
00154     char *_path;                ///< stream name when redirecting stdio
00155 };
00156 
00157 #endif