Functions for Text Areas. More...
Public Member Functions | |
CONSTRUCTORS | |
The following gText class constructors are available | |
gText () | |
Constructor creates a default gText text area object with no font. More... | |
gText (uint8_t x1, uint8_t y1, uint8_t x2, uint8_t y2, gTextMode mode=DEFAULT_gTEXTMODE) | |
Constructor creates a gText text area object by coordinates. More... | |
gText (predefinedArea selection, gTextMode mode=DEFAULT_gTEXTMODE) | |
Constructor creates a gText text area object by predefined area without font. More... | |
gText (predefinedArea selection, Font_t font, gTextMode mode=DEFAULT_gTEXTMODE) | |
Constructor creates a gText text area object by predefined area and font. More... | |
gText (uint8_t x1, uint8_t y1, uint8_t columns, uint8_t rows, Font_t font, gTextMode mode=DEFAULT_gTEXTMODE) | |
Constructor creates a gText text area object by columns and rows. More... | |
TEXT FUNCTIONS | |
The following text functions are available | |
uint8_t | DefineArea (uint8_t x1, uint8_t y1, uint8_t x2, uint8_t y2, gTextMode mode=DEFAULT_gTEXTMODE) |
Define a text area by absolute coordinates. More... | |
uint8_t | DefineArea (uint8_t x, uint8_t y, uint8_t columns, uint8_t rows, Font_t font, gTextMode mode=DEFAULT_gTEXTMODE) |
Define a Text area by columns and rows. More... | |
uint8_t | DefineArea (predefinedArea selection, Font_t font, gTextMode mode=DEFAULT_gTEXTMODE) |
Define a predefined generic text area and font. More... | |
uint8_t | DefineArea (predefinedArea selection, gTextMode mode=DEFAULT_gTEXTMODE) |
Define a predefined generic text area. More... | |
void | ClearArea (void) |
Clear text area with the current font background color and home the cursor to upper left corner of the text area. More... | |
void | SetAreaMode (gTextMode mode) |
Set TextArea mode options. More... | |
void | ClearAreaMode (gTextMode mode) |
Clear TextArea mode options. More... | |
int | GetAreaProp (gTextProp_t) |
Get Text Area property. More... | |
void | SelectFont (Font_t font, uint8_t fgcolor=BLACK, FontCallback callback=ReadPgmData) |
Select a Font and font color. More... | |
void | SetFontColor (uint8_t fgcolor) |
Set a font foreground color. More... | |
int | PutChar (uint8_t c) |
output a character More... | |
void | Puts (const char *str) |
output a character string More... | |
void | Puts (const String &str) |
output a String class string More... | |
void | Puts_P (PGM_P str) |
output a program memory character string More... | |
void | DrawString (const char *str, int hpos, int vpos, eraseLine_t erase=eraseNONE) |
Output a NULL terminated character string with horizontal and vertical positioning. More... | |
void | DrawString (String &str, int hpos, int vpos, eraseLine_t erase=eraseNONE) |
Output a String class string with horizontal and vertical positioning. More... | |
void | DrawString_P (PGM_P str, int hpos, int vpos, eraseLine_t erase=eraseNONE) |
Output a program memory character string with horizontal and vertical positioning. More... | |
void | DrawString (FLASHSTRING str, int hpos, int vpos, eraseLine_t erase=eraseNONE) |
Output an GLCD FLASH string with horizontal and vertical positioning. More... | |
size_t | write (uint8_t c) |
output a character to the text area More... | |
size_t | writeUTF8 (wchar_t utfc) |
output a UTF8 encoded character to the text area More... | |
void | CursorTo (uint8_t column, uint8_t row) |
Positions cursor to a character based column and row. More... | |
void | CursorTo (int8_t column) |
Positions cursor to a character based column on the current row. More... | |
void | CursorToXY (uint8_t x, uint8_t y) |
Positions cursor to a X,Y position. More... | |
uint8_t | CharWidth (uint8_t c) |
Returns the pixel width of a character. More... | |
uint8_t | CharHeight (uint8_t c) |
Returns the pixel height of a character. More... | |
uint16_t | StringWidth (const char *str) |
Returns the pixel width of a string. More... | |
uint16_t | StringWidth_P (PGM_P str) |
Returns the pixel width of a string. More... | |
uint16_t | StringWidth (String &str) |
Returns the pixel width of a String class string. More... | |
void | EraseTextLine (eraseLine_t type=eraseTO_EOL) |
Erase in Line. More... | |
void | EraseTextLine (uint8_t row) |
Erase Text Line. More... | |
void | PrintNumber (long n) |
Legacy function to print a number. More... | |
void | printFlash (FLASHSTRING str) |
print a flash based string More... | |
void | printFlashln (FLASHSTRING str) |
print a flash based string More... | |
void | Printf (const char *format,...) |
print formatted data More... | |
void | Printf (const __FlashStringHelper *format,...) |
print formatted data More... | |
void | Printf_P (PGM_P format,...) |
print formatted data More... | |
Protected Member Functions | |
void | GotoXY (uint8_t x, uint8_t y) |
set current x,y coordinate on display device More... | |
int | Init (glcd_device_mode invert=NON_INVERTED) |
Low level h/w initialization of library and display. More... | |
int | Off (void) |
Turn off the display & backlight. More... | |
int | OffBacklight (void) |
Turn off the backlight. More... | |
int | OffDisplay (void) |
Turn the display pixels off. More... | |
int | On (void) |
Turn on the display & backlight. More... | |
int | OnBacklight (void) |
Turn on the backlight. More... | |
int | OnDisplay (void) |
Turn the display pixels on. More... | |
uint8_t | ReadData (void) |
read a data byte from display device memory More... | |
int | SetBacklight (int val) |
Set backlight brightness. More... | |
void | SetDot (uint8_t x, uint8_t y, uint8_t color) |
set pixel at x,y to the given color More... | |
void | SetPixels (uint8_t x, uint8_t y, uint8_t x1, uint8_t y1, uint8_t color) |
set an area of pixels More... | |
void | WriteData (uint8_t data) |
Write a byte to display device memory. More... | |
Functions for Text Areas.
A text area acts like a terminal monitor and text output is displayed within the confines of a rectangle given in the DefineArea command. All of the following text area functions operate on a user defined text area.
gText | ( | ) |
Constructor creates a default gText text area object with no font.
Constructor creates a text area using the entire display but does not assign any font to it. SelectFont() must be used to select a font for the area before any text can be output to the display.
Examples:
Constructor creates a gText text area object by coordinates.
x1 | X coordinate of upper left corner |
y1 | Y coordinate of upper left corner |
x2 | X coordinate of lower right corner |
y2 | Y coordinate of lower right corner |
mode | a value from gTextMode |
Creates a gText area object and then calls DefineArea() with the same parameters to initalize it.
Examples:
gText | ( | predefinedArea | selection, |
gTextMode | mode = DEFAULT_gTEXTMODE |
||
) |
Constructor creates a gText text area object by predefined area without font.
selection | a value from predefinedArea |
mode | a value from gTextMode |
Creates a gText area object and then calls DefineArea() with the same parameters to initalize it. Constructor does not assign any font to it. SelectFont() must be used to select a font for the area before any text can be output to the display.
Examples:
gText | ( | predefinedArea | selection, |
Font_t | font, | ||
gTextMode | mode = DEFAULT_gTEXTMODE |
||
) |
Constructor creates a gText text area object by predefined area and font.
selection | a value from predefinedArea |
font | a font definition |
mode | a value from gTextMode |
Creates a gText area object and then calls DefineArea() with the same parameters to initalize it.
Examples:
gText | ( | uint8_t | x, |
uint8_t | y, | ||
uint8_t | columns, | ||
uint8_t | rows, | ||
Font_t | font, | ||
gTextMode | mode = DEFAULT_gTEXTMODE |
||
) |
Constructor creates a gText text area object by columns and rows.
x | X coordinate of upper left corner |
y | Y coordinate of upper left corner |
columns | number of text columns |
rows | number of text rows |
font | a font definition |
mode | a value from gTextMode |
Creates a gText area object and then calls DefineArea() with the same parameters to initalize it.
Examples:
uint8_t CharHeight | ( | uint8_t | c | ) |
Returns the pixel height of a character.
c | character to be sized. NULL can be used to size the first char in the font. |
If there is no font selected, 0 will be returned.
uint8_t CharWidth | ( | uint8_t | c | ) |
Returns the pixel width of a character.
c | character to be sized |
void ClearArea | ( | void | ) |
Clear text area with the current font background color and home the cursor to upper left corner of the text area.
void ClearAreaMode | ( | gTextMode | mode | ) |
void CursorTo | ( | uint8_t | column, |
uint8_t | row | ||
) |
Positions cursor to a character based column and row.
column | specifies the horizontal position |
row | specifies the vertical position |
Column and Row are zero based character positions and are relative the the upper left corner of the text area base on the size of the currently selected font.
This is intended for fixed width fonts
Examples:
void CursorTo | ( | int8_t | column | ) |
Positions cursor to a character based column on the current row.
column | specifies the horizontal position |
Column is a 0 based character position based on the size of the currently selected font.
If column is negative then the column position is relative to the current cursor position.
void CursorToXY | ( | uint8_t | x, |
uint8_t | y | ||
) |
Positions cursor to a X,Y position.
x | specifies the horizontal location |
y | specifies the vertical location |
X & Y are zero based pixel coordinates and are relative to the upper left corner of the text area.
Examples:
uint8_t DefineArea | ( | uint8_t | x1, |
uint8_t | y1, | ||
uint8_t | x2, | ||
uint8_t | y2, | ||
gTextMode | mode = DEFAULT_gTEXTMODE |
||
) |
Define a text area by absolute coordinates.
x1 | X coordinate of upper left corner |
y1 | Y coordinate of upper left corner |
x2 | X coordinate of lower right corner |
y2 | Y coordinate of lower right corner |
mode | a value from gTextMode |
Define a text area based on absolute coordinates. The pixel coordinates for the text area are inclusive so x2,y2 is the lower right pixel of the text area.
x1,y1 and x2,y2 are an absolute coordinates and are relateive to the 0,0 origin of the display.
The area within the newly defined text area is intentionally not cleared.
mode is an optional parameter and defaults to normal/up scrolling
Examples:
uint8_t DefineArea | ( | uint8_t | x, |
uint8_t | y, | ||
uint8_t | columns, | ||
uint8_t | rows, | ||
Font_t | font, | ||
gTextMode | mode = DEFAULT_gTEXTMODE |
||
) |
Define a Text area by columns and rows.
x | X coordinate of upper left corner |
y | Y coordinate of upper left corner |
columns | number of text columns |
rows | number of text rows |
font | a font definition |
mode | a value from gTextMode |
Define a text area sized to hold columns characters across and rows characters tall. It is properly sized for the specified font.
The area within the newly defined text area is intentionally not cleared.
While intended for fixed width fonts, sizing will work for variable width fonts.
When variable width fonts are used, the column is based on assuming a width of the widest character.
x,y is an absolute coordinate and is relateive to the 0,0 origin of the display.
mode is an optional parameter and defaults to normal/up scrolling
Examples:
uint8_t DefineArea | ( | predefinedArea | selection, |
Font_t | font, | ||
gTextMode | mode = DEFAULT_gTEXTMODE |
||
) |
Define a predefined generic text area and font.
selection | a value from predefinedArea |
font | a font definition |
mode | a value from gTextMode |
Define a text area using a selection from a set of predefined areas.
The area within the newly defined text area is intentionally not cleared.
mode is an optional parameter and defaults to normal/up scrolling
Examples:
uint8_t DefineArea | ( | predefinedArea | selection, |
gTextMode | mode = DEFAULT_gTEXTMODE |
||
) |
Define a predefined generic text area.
selection | a value from predefinedArea |
mode | a value from gTextMode |
Define a text area using a selection form a set of predefined areas without setting or altering the area's font.
The area within the newly defined text area is intentionally not cleared.
mode is an optional parameter and defaults to normal/up scrolling
Examples:
void DrawString | ( | const char * | str, |
int | hpos, | ||
int | vpos, | ||
eraseLine_t | erase = eraseNONE |
||
) |
Output a NULL terminated character string with horizontal and vertical positioning.
str | character string |
hpos | specifies the horizontal positioning. |
vpos | specifies the vertical positioning. |
erase | optional parameter that specifies which of the remaing pixels on the text line will be erased before the characters are rendered. It is one of the values from eraseLine_t and defaults to eraseNONE |
Outputs the characters in the string to the text area.
hpos/vpos can specify:
When hpos & vpos are not a formatting type, the value is a zero based pixel coordinate relative to the upper left corner of the text area.
Examples:
See PutChar() for a full description of how characters are written to the text area.
void DrawString | ( | String & | str, |
int | hpos, | ||
int | vpos, | ||
eraseLine_t | erase = eraseNONE |
||
) |
Output a String class string with horizontal and vertical positioning.
str | character string |
hpos | specifies the horizontal positioning. |
vpos | specifies the vertical positioning. |
erase | optional parameter that specifies which of the remaing pixels on the text line will be erased before the characters are rendered. It is one of the values from eraseLine_t and defaults to eraseNONE |
Outputs the characters in the string to the text area.
hpos/vpos can specify:
When hpos & vpos are not a formatting type, the value is a zero based pixel coordinate relative to the upper left corner of the text area.
Examples:
See PutChar() for a full description of how characters are written to the text area.
void DrawString | ( | FLASHSTRING | str, |
int | hpos, | ||
int | vpos, | ||
eraseLine_t | erase = eraseNONE |
||
) |
Output an GLCD FLASH string with horizontal and vertical positioning.
str | character string |
hpos | specifies the horizontal positioning. |
vpos | specifies the vertical positioning. |
erase | optional parameter that specifies which of the remaing pixels on the text line will be erased before the characters are rendered. It is one of the values from eraseLine_t and defaults to eraseNONE |
Outputs the characters in the string to the text area.
hpos/vpos can specify:
When hpos & vpos are not a formatting type, the value is a zero based pixel coordinate relative to the upper left corner of the text area.
Examples:
See PutChar() for a full description of how characters are written to the text area.
void DrawString_P | ( | PGM_P | str, |
int | hpos, | ||
int | vpos, | ||
eraseLine_t | erase = eraseNONE |
||
) |
Output a program memory character string with horizontal and vertical positioning.
str | character string |
hpos | specifies the horizontal positioning. |
vpos | specifies the vertical positioning. |
erase | optional parameter that specifies which of the remaing pixels on the text line will be erased before the characters are rendered. It is one of the values from eraseLine_t and defaults to eraseNONE |
Outputs the characters in the string to the text area.
hpos/vpos can specify:
When hpos & vpos are not a formatting type, the value is a zero based pixel coordinate relative to the upper left corner of the text area.
Examples:
See PutChar() for a full description of how characters are written to the text area.
void EraseTextLine | ( | eraseLine_t | type = eraseTO_EOL | ) |
Erase in Line.
type | type of line erase |
Erases all or part of a line of text depending on the type of erase specified.
If type is not specified it is assumed to be eraseTO_EOL
The cursor position does not change.
void EraseTextLine | ( | uint8_t | row | ) |
Erase Text Line.
row | row # of text to earase |
Erases a line of text and moves the cursor to the begining of the line. Rows are zero based so the top line/row of a text area is 0.
int GetAreaProp | ( | gTextProp_t | property | ) |
Get Text Area property.
property | a value from gTextProp_t Get Text Area property |
Examples:
gTextProp_FontWidth and gTextProp_FontHeight return rendered sizes in pixels which include any inter character padding pixels.
|
protectedinherited |
set current x,y coordinate on display device
x | X coordinate |
y | Y coordinate |
Sets the current pixel location to x,y. x and y are relative to the 0,0 origin of the display which is the upper left most pixel on the display.
|
protectedinherited |
Low level h/w initialization of library and display.
invert | specifices whether display is in normal mode or inverted mode. |
This should be called prior to any other graphic library function. It does all the needed initializations including taking care of the low level hardware initalization of the display device.
The optional invert parameter specifies if the display should be run in a normal mode, or inverted mode.
It does not refer to whether the display uses light or darg pixels.
In "normal" or NON_INVERTED mode, pixels are turned on for PIXEL_ON or BLACK and turned off for PIXEL_OFF or WHITE.
In "inverted" or INVERTED mode, pixels are turned off for PIXEL_ON or BLACK and turned on for PIXEL_OFF or WHITE.
NON_INVERTED mode clears the display with all pixels off and drawing with PIXEL_ON or BLACK will turn on pixels.
INVERTED mode clears the display with all pixels on and drawing with PIXEL_OFF or WHITE will turn on pixels.
The terminology of BLACK and WHITE is from the perspective of a display that uses black pixels on a light background. For example, if a pixel is set to BLACK and used on a black pixel on light background display, you get a black pixel.
However, if the display is a white pixel on dark background display, then setting a pixel to BLACK turns on a white pixel on the display.
Because of this, it can be less confusing to use PIXEL_ON and PIXEL_OFF vs BLACK and WHITE.
Upon successful completion of the initialization:
|
protectedinherited |
Turn off the display & backlight.
Turns off the display's pixels and backlight
|
protectedinherited |
Turn off the backlight.
|
protectedinherited |
Turn the display pixels off.
Turns off the display pixels. It does not alter or modify the backlight setting. If the display backlight is on, it will remain on.
|
protectedinherited |
Turn on the display & backlight.
Turns on the display's pixels and backlight
|
protectedinherited |
Turn on the backlight.
|
protectedinherited |
Turn the display pixels on.
Turns on the display pixels. It does not alter or modify the backlight setting.
void Printf | ( | const char * | format, |
... | |||
) |
print formatted data
format | string that contains text or optional embedded format tags |
... | Depending on the format string, the function may expect a sequence of additional arguments. |
Writes a sequence of data formatted as the format argument specifies. After the format parameter, the function expects at least as many additional arguments as specified in format. The format string supports all standard printf() formating % tags.
Examples:
void Printf | ( | const __FlashStringHelper * | format, |
... | |||
) |
print formatted data
format | string that contains text or optional embedded format tags |
... | Depending on the format string, the function may expect a sequence of additional arguments. |
Writes a sequence of data formatted as the format argument specifies. After the format parameter, the function expects at least as many additional arguments as specified in format. The format string supports all standard printf() formating % tags.
Examples:
void Printf_P | ( | PGM_P | format, |
... | |||
) |
print formatted data
format | string in AVR progmem that contains text or optional embedded format tags |
... | Depending on the format string, the function may expect a sequence of additional arguments. |
See gText::Printf() for full details.
void printFlash | ( | FLASHSTRING | str | ) |
print a flash based string
str | pointer to a null terminated character string stored in program memory |
void printFlashln | ( | FLASHSTRING | str | ) |
print a flash based string
str | pointer to a null terminated character string stored in program memory |
The string is output followed by a newline.
void PrintNumber | ( | long | n | ) |
Legacy function to print a number.
n | is the number to print |
int PutChar | ( | uint8_t | c | ) |
output a character
c | the character to output |
If the character will not fit on the current text line inside the text area, the text position is wrapped to the next line. This might be the next lower or the next higher line depending on the scroll direction.
If there is not enough room to fit a full line of new text after wrapping, the entire text area will be scrolled to make room for a new line of text. The scroll direction will be up or down depending on the scroll direction for the text area.
If there is an attempt to output a character that has no definition i.e. its width is zero in the font data, then no character will be rendered. This occurs if the font is a "sparse" font, that does not define all the characters within the font range. To save room a "sparse" font will set the width of the undefined characters to zero.
void Puts | ( | const char * | str | ) |
output a character string
str | pointer to a null terminated character string. |
Outputs all the characters in the string to the text area.
Examples:
See PutChar() for a full description of how characters are written to the text area.
void Puts | ( | const String & | str | ) |
output a String class string
str | String class string |
Outputs all the characters in the string to the text area. See PutChar() for a full description of how characters are written to the text area.
void Puts_P | ( | PGM_P | str | ) |
output a program memory character string
str | pointer to a null terminated character string stored in program memory |
Outputs all the characters in the string to the text area.
Examples:
See PutChar() for a full description of how characters are written to the text area.
|
protectedinherited |
read a data byte from display device memory
void SelectFont | ( | Font_t | font, |
uint8_t | fgcolor = BLACK , |
||
FontCallback | callback = ReadPgmData |
||
) |
Select a Font and font color.
font | a font definition |
fgcolor | foreground font color |
callback | optional font read routine |
Selects the font definition as the current font for the text area.
All subsequent printing functions will use this font.
Font definitions stored in program memory. You can have as many fonts defines as will fit in program memory can switch between them with this function.
fgcolor PIXEL_ON or BLACK renders "on" pixels on a "off" background, i.e. it turns on the pixels on the LCD for the pixels in the character glpyh and turns off all the background pixels.
fgcolor PIXEL_OFF or WHITE renders "off" pixels on a "on" background; i.e. it turns off the pixels on the LCD for the pixels in the character glpyh and turns on all the background pixels.
If the optional callback argument is ommitted, a default routine is selected that assumes that the font is in program memory (flash).
Examples:
void SetAreaMode | ( | gTextMode | mode | ) |
|
protectedinherited |
Set backlight brightness.
val | backlight brightness (0-255) |
If the display circuitry only has the option to turn the backlight on and off then any non zero value will turn the display on with maximum brightness The value HIGH should not be used to turn the backlight on since this function is used to control backlight intensity and not for on / off control. A value of HIGH is typically 1 which would be a very dim backlight.
|
protectedinherited |
set pixel at x,y to the given color
x | X coordinate, a value from 0 to GLCD.Width-1 |
y | Y coordinate, a value from 0 to GLCD.Heigh-1 |
color | Sets the pixel at location x,y to the specified color. x and y are relative to the 0,0 origin of the display which is the upper left corner. Requests to set pixels outside the range of the display will be ignored. |
void SetFontColor | ( | uint8_t | fgcolor | ) |
Set a font foreground color.
fgcolor | foreground font color |
Set the font foreground color for the text area.
fgcolor PIXEL_ON or BLACK renders "on" pixels on a "off" background, i.e. it turns on the pixels on the LCD for the pixels in the character glpyh and turns off all the background pixels.
fgcolor PIXEL_OFF or WHITE renders "off" pixels on a "on" background; i.e. it turns off the pixels on the LCD for the pixels in the character glpyh and turns on all the background pixels.
Examples:
|
protectedinherited |
set an area of pixels
x | X coordinate of upper left corner |
y | Y coordinate of upper left corner |
x2 | X coordinate of lower right corner |
y2 | Y coordinate of lower right corner |
color | sets the pixels an area bounded by x,y to x2,y2 inclusive to the specified color. x,y is the upper left corner and x2,y2 is the lower left corner. |
The width of the area is x2-x + 1. The height of the area is y2-y+1
uint16_t StringWidth | ( | const char * | str | ) |
Returns the pixel width of a string.
str | pointer to string stored in RAM |
uint16_t StringWidth | ( | String & | str | ) |
Returns the pixel width of a String class string.
str | String class string |
uint16_t StringWidth_P | ( | PGM_P | str | ) |
Returns the pixel width of a string.
str | pointer to string stored in program memory |
size_t write | ( | uint8_t | c | ) |
output a character to the text area
c | the character to output |
This method is needed for the Print base class
|
protectedinherited |
Write a byte to display device memory.
data | date byte to write to memory |
The data specified is written to glcd memory at the current x,y position. If the y location is not on a byte boundary, the write is fragemented up into multiple writes.
size_t writeUTF8 | ( | wchar_t | utfc | ) |
output a UTF8 encoded character to the text area
utfc | the UTF8 character to output |
used to output UTF8 encoded characters including multibyte wide UTF8 character codes.
The UTF character codes are limited to 0-255. To go beyond 255 is a BIG deal since the font header currently only supports up to 256 characters. (it is only an 8 bit field)
Also by only supporting 0-255 codes, when UTF8 processing is enabled, raw code processing can also be supported for characters above 0x7f with the exception that codes 0xc2 and 0xc3 will be lost.