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     ///     the stdio stream.
00036     ///
00037     TextDisplay(const char *name = NULL);
00038 
00039     /// destructor to clean up
00040     ///
00041     //~TextDisplay();
00042 
00043     /// output a character at the given position
00044     ///
00045     /// @note this method may be overridden in a derived class.
00046     ///
00047     /// @param[in] x position in pixels
00048     /// @param[in] y position in pixels
00049     /// @param[in] c the character to be written to the TextDisplay
00050     /// @returns number of pixels to advance the cursor which could be the cell width
00051     ///     for non-proportional characters, or the actual character width for
00052     ///     proportional characters.
00053     ///
00054     virtual int character(int x, int y, int c) = 0;
00055 
00056     /// return number of rows on TextDisplay
00057     ///
00058     /// @note this method may be overridden in a derived class.
00059     ///
00060     /// @returns number of text rows for the display for the currently 
00061     ///     active font.
00062     ///
00063     virtual int rows() = 0;
00064 
00065     /// return number if columns on TextDisplay
00066     ///
00067     /// @note this method may be overridden in a derived class.
00068     ///
00069     /// @returns number of text rows for the display for the currently
00070     ///     active font.
00071     ///
00072     virtual int columns() = 0;
00073 
00074     // functions that come for free, but can be overwritten
00075 
00076     /// redirect output from a stream (stoud, sterr) to  display
00077     ///
00078     /// @note this method may be overridden in a derived class.
00079     ///
00080     /// @param[in] stream that shall be redirected to the TextDisplay
00081     /// @returns true if the claim succeeded.
00082     ///
00083     virtual bool claim (FILE *stream);
00084 
00085     /// clear screen
00086     ///
00087     /// @note this method may be overridden in a derived class.
00088     ///
00089     /// @param[in] layers is ignored, but supports maintaining the same 
00090     ///     API for the graphics layer.
00091     /// @returns @ref RetCode_t value.
00092     ///
00093     virtual RetCode_t cls(uint16_t layers = 0) = 0;
00094     
00095     /// locate the cursor at a character position.
00096     ///
00097     /// Based on the currently active font, locate the cursor on screen.
00098     ///
00099     /// @note this method may be overridden in a derived class.
00100     ///
00101     /// @param[in] column is the horizontal offset from the left side.
00102     /// @param[in] row is the vertical offset from the top.
00103     /// @returns @ref RetCode_t value.
00104     ///
00105     virtual RetCode_t locate(textloc_t column, textloc_t row) = 0;
00106     
00107     /// set the foreground color
00108     ///
00109     /// @note this method may be overridden in a derived class.
00110     ///
00111     /// @param[in] color is color to use for foreground drawing.
00112     /// @returns @ref RetCode_t value.
00113     ///
00114     virtual RetCode_t foreground(color_t color) = 0;
00115 
00116     /// set the background color
00117     ///
00118     /// @note this method may be overridden in a derived class.
00119     ///
00120     /// @param[in] color is color to use for background drawing.
00121     /// @returns @ref RetCode_t value.
00122     ///
00123     virtual RetCode_t background(color_t color) = 0;
00124     // putc (from Stream)
00125     // printf (from Stream)
00126 
00127 protected:
00128     /// a method to put a character to the display.
00129     ///
00130     /// @param value is the character value to send to the display
00131     /// @returns the character that was sent.
00132     ///
00133     virtual int _putc(int value);
00134     
00135     /// a method to get a character from the stdin
00136     /// 
00137     /// @returns the fetched character.
00138     ///
00139     virtual int _getc();
00140 
00141     uint16_t _column;           ///< character column location
00142     uint16_t _row;              ///< character row location
00143 
00144     // colors
00145     color_t _foreground;        ///< presently set foreground color
00146     color_t _background;        ///< presently set background color
00147     char *_path;                ///< stream name when redirecting stdio
00148 };
00149 
00150 #endif