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