TextDisplay.h

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