Arduino openGLCD Library  Version v0.9.1a
gText Class Reference

Functions for Text Areas. More...

+ Inheritance diagram for gText:

List of all members.

Public Member Functions

CONSTRUCTORS

The following gText class constructors are available

 gText ()
 Constructor creates a default gText text area object with no font.
 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.
 gText (predefinedArea selection, gTextMode mode=DEFAULT_gTEXTMODE)
 Constructor creates a gText text area object by predefined area without font.
 gText (predefinedArea selection, Font_t font, gTextMode mode=DEFAULT_gTEXTMODE)
 Constructor creates a gText text area object by predefined area and font.
 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.
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.
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.
uint8_t DefineArea (predefinedArea selection, Font_t font, gTextMode mode=DEFAULT_gTEXTMODE)
 Define a predefined generic text area and font.
uint8_t DefineArea (predefinedArea selection, gTextMode mode=DEFAULT_gTEXTMODE)
 Define a predefined generic text area.
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 SetAreaMode (gTextMode mode)
 Set TextArea mode options.
void ClearAreaMode (gTextMode mode)
 Clear TextArea mode options.
int GetAreaProp (gTextProp_t)
 Get Text Area property.
void SelectFont (Font_t font, uint8_t fgcolor=BLACK, FontCallback callback=ReadPgmData)
 Select a Font and font color.
void SetFontColor (uint8_t fgcolor)
 Set a font foreground color.
int PutChar (uint8_t c)
 output a character
void Puts (const char *str)
 output a character string
void Puts (const String &str)
 output a String class string
void Puts_P (PGM_P str)
 output a program memory character string
void Puts (const __FlashStringHelper *str)
 output an Arduino Flash program memory character string
void DrawString (const char *str, int hpos, int vpos, eraseLine_t erase=eraseNONE)
 Output a NULL terminated character string with horizontal and vertical positioning.
void DrawString (String &str, int hpos, int vpos, eraseLine_t erase=eraseNONE)
 Output a String class string with horizontal and vertical positioning.
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.
void DrawString (const __FlashStringHelper *str, int hpos, int vpos, eraseLine_t erase=eraseNONE)
 Output an Arduino FLASH string with horizontal and vertical positioning.
void DrawString (FLASHSTRING str, int hpos, int vpos, eraseLine_t erase=eraseNONE)
 Output an GLCD FLASH string with horizontal and vertical positioning.
void write (uint8_t c)
 output a character to the text area
void CursorTo (uint8_t column, uint8_t row)
 Positions cursor to a character based column and row.
void CursorTo (int8_t column)
 Positions cursor to a character based column on the current row.
void CursorToXY (uint8_t x, uint8_t y)
 Positions cursor to a X,Y position.
uint8_t CharWidth (uint8_t c)
 Returns the pixel width of a character.
uint8_t CharHeight (uint8_t c)
 Returns the pixel height of a character.
uint16_t StringWidth (const char *str)
 Returns the pixel width of a string.
uint16_t StringWidth_P (PGM_P str)
 Returns the pixel width of a string.
uint16_t StringWidth (String &str)
 Returns the pixel width of a String class string.
uint16_t StringWidth (const __FlashStringHelper *str)
 Returns the pixel width of a FlashString.
void EraseTextLine (eraseLine_t type=eraseTO_EOL)
 Erase in Line.
void EraseTextLine (uint8_t row)
 Erase Text Line.
void PrintNumber (long n)
 Legacy function to print a number.
void printFlash (FLASHSTRING str)
 print a flash based string
void printFlashln (FLASHSTRING str)
 print a flash based string
void Printf (const char *format,...)
 print formatted data
void Printf (const __FlashStringHelper *format,...)
 print formatted data
void Printf_P (PGM_P format,...)
 print formatted data

Protected Member Functions

void GotoXY (uint8_t x, uint8_t y)
 set current x,y coordinate on display device
int Init (glcd_device_mode invert=NON_INVERTED)
 Low level h/w initialization of library and display.
int Off (void)
 Turn off the display & backlight.
int OffBacklight (void)
 Turn off the backlight.
int OffDisplay (void)
 Turn the display pixels off.
int On (void)
 Turn on the display & backlight.
int OnBacklight (void)
 Turn on the backlight.
int OnDisplay (void)
 Turn the display pixels on.
uint8_t ReadData (void)
 read a data byte from display device memory
int SetBacklight (int val)
 Set backlight brightness.
void SetDot (uint8_t x, uint8_t y, uint8_t color)
 set pixel at x,y to the given color
void SetPixels (uint8_t x, uint8_t y, uint8_t x1, uint8_t y1, uint8_t color)
 set an area of pixels
void WriteData (uint8_t data)
 Write a byte to display device memory.

Detailed Description

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.


Constructor & Destructor Documentation

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:

    // text area using full display
    gText textarea;
See also:
DefineArea()
ClearArea()
SetAreaMode() ClearAreaMode()
gTextMode
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.

Parameters:
x1X coordinate of upper left corner
y1Y coordinate of upper left corner
x2X coordinate of lower right corner
y2Y coordinate of lower right corner
modea value from gTextMode

Creates a gText area object and then calls DefineArea() with the same parameters to initalize it.

Examples:

    // upper left quardrant
    textarea.DefineArea(GLCD.Left, GLCD.Top, GLCD.CenterX, GLCD.CenterY);

    // Right half, reverse scroll
    textarea.DefineArea(GLCD.CenterX, GLCD.Top, GLCD.Right, GLCD.Bottom, gTextMode_SCROLLDOWN);
Note:
See also:
DefineArea()
ClearArea()
SetAreaMode() ClearAreaMode()
gTextMode
gText ( predefinedArea  selection,
gTextMode  mode = DEFAULT_gTEXTMODE 
)

Constructor creates a gText text area object by predefined area without font.

Parameters:
selectiona value from predefinedArea
modea 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:

    // right side of display
    textarea.DefineArea(textAreaRIGHT);

    // top half of display
    textarea.DefineArea(textAreaTOP);

    // upper left quadrant reverse scroll
    textarea.DefineArea(textAreaTOPLEFT, gTextMode_SCROLLDOWN);
See also:
DefineArea()
ClearArea()
SetAreaMode() ClearAreaMode()
gTextMode
gText ( predefinedArea  selection,
Font_t  font,
gTextMode  mode = DEFAULT_gTEXTMODE 
)

Constructor creates a gText text area object by predefined area and font.

Parameters:
selectiona value from predefinedArea
fonta font definition
modea value from gTextMode

Creates a gText area object and then calls DefineArea() with the same parameters to initalize it.

Examples:

    // right side of display
    textarea.DefineArea(textAreaRIGHT, System5x7);

    // top half of display
    textarea.DefineArea(textAreaTOP, System5x7);

    // upper left quadrant reverse scroll
    textarea.DefineArea(textAreaTOPLEFT, System5x7, gTextMode_SCROLLDOWN);
See also:
DefineArea()
ClearArea()
SetAreaMode() ClearAreaMode()
gTextMode
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.

Parameters:
xX coordinate of upper left corner
yY coordinate of upper left corner
columnsnumber of text columns
rowsnumber of text rows
fonta font definition
modea value from gTextMode

Creates a gText area object and then calls DefineArea() with the same parameters to initalize it.

Examples:

    // top of right side of display, 10 columns by 2 lines
    gText textarea(GLCD.CenterX, GLCD.Top, 10, 2, System5x7);

    // top of right side of display, 10 columns by 2 lines, reverse scroll
    gText textarea(GLCD.CenterX, GLCD.Top, 10, 2, System5x7, gTextMode_SCROLLDOWN);
See also:
DefineArea()
ClearArea()
SetAreaMode() ClearAreaMode()
gTextMode

Member Function Documentation

uint8_t CharHeight ( uint8_t  c)

Returns the pixel height of a character.

Parameters:
ccharacter to be sized. NULL can be used to size the first char in the font.
Returns:
The height in pixels of the given character font including any inter-character gap pixels below the character when the character is rendered on the display.
Note:
The font for the character is the most recently selected font and while individual characters may actually render different pixel heights, the returned value is actually the height of the font row. i.e a '.' (period) will return the same height as a '@' (at sign).

If there is no font selected, 0 will be returned.

See also:
CharWidth()
StringWidth()
StringWidth_P()
uint8_t CharWidth ( uint8_t  c)

Returns the pixel width of a character.

Parameters:
ccharacter to be sized
Returns:
The width in pixels of the given character including any inter-character gap pixels following the character when the character is rendered on the display.
Note:
The font for the character is the most recently selected font. If there is no font selected or if the character code does not have a valid definition in the selected font, 0 will be returned.
See also:
CharHeight()
StringWidth()
StringWidth_P()
void ClearArea ( void  )

Clear text area with the current font background color and home the cursor to upper left corner of the text area.

See also:
DefineArea()
void ClearAreaMode ( gTextMode  mode)

Clear TextArea mode options.

Parameters:
modea value from gTextMode

Examples:

 textarea.ClearAreaMode(gTextMode_SCROLLDOWN); // Disable reverse vertical scrolling
 textarea.ClearAreaMode(gTextMode_OVERSTRIKE); // Disable text overstrike mode
See also:
SetAreaMode()
SelectFont()
SetFontColor()
DefineArea()
gTextMode
void CursorTo ( uint8_t  column,
uint8_t  row 
)

Positions cursor to a character based column and row.

Parameters:
columnspecifies the horizontal position
rowspecifies 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:

 GLCD.CursorTo(0,0);     // position cursor to leftmost column, on top line of default text area
 GLCD.CursorTo(5,0);     // position cursor to column 5 , on top line of default text area
 textarea.CursorTo(10,2);// position cursor to column 10, line 2 in text area
 textarea.CursorTo(0,2); // position cursor to leftmost column, line 2 in text area
 textarea.CursorTo(0,0); // position cursor to leftmost column, on top line of text area
Note:
When variable width fonts are used, the column is based on assuming a width of the widest character.
Warning:
If the column and row parameters create a position that is outside the bounds of the text area, then the position will be set to the home position of the text area.
See also:
CursorToXY()
void CursorTo ( int8_t  column)

Positions cursor to a character based column on the current row.

Parameters:
columnspecifies 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.

Warning:
While intended only for fixed width fonts, cursor repositioning will be done for variable width fonts. When variable width fonts are used, the column is based on assuming a width of the widest character in the font. Because the widest character is used for the amount of cursor movement, the amount of cursor movement when using relative positioning will often not be consistent with the number characters previously rendered. For example, if a letter "l" was written and the cursor was reposisitioned with a -1, the amount backed up will be much larger than the width of the "l".
See also:
CursorToXY()
void CursorToXY ( uint8_t  x,
uint8_t  y 
)

Positions cursor to a X,Y position.

Parameters:
xspecifies the horizontal location
yspecifies the vertical location

X & Y are zero based pixel coordinates and are relative to the upper left corner of the text area.

Examples:

 GLCD.CursorToXY(GLCD.CenterX, GLCD.CenterY); // position cursor to center of display
 GLCD.CursorToXY(5,8);     // position cursor 5 pixels from left, 8 pixels from top in default text area
 textarea.CursorToXY(10,2);// position cursor 10 pixels from left,2 pixels from top in text area
 textarea.CursorToXY(0,0); // position cursor upper left corner in text area
Note:
: For most uses, DrawString() is a better alternative to position text.
See also:
CursorTo()
DrawString()
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.

Parameters:
x1X coordinate of upper left corner
y1Y coordinate of upper left corner
x2X coordinate of lower right corner
y2Y coordinate of lower right corner
modea 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

Returns:
0 with the desired area defined if all the coordinates are valid, otherwise returns non zero error code with the area set to the full display

Examples:

    // upper left quardrant
    textarea.DefineArea(GLCD.Left, GLCD.Top, GLCD.CenterX, GLCD.CenterY);

    // Right half, reverse scroll
    textarea.DefineArea(GLCD.CenterX, GLCD.Top, GLCD.Right, GLCD.Bottom, gTextMode_SCROLLDOWN);
Note:
Upon creation of the text area, the cursor position for the text area will be set to x1, y1
See also:
ClearArea()
SetAreaMode()
ClearAreaMode()
gTextMode
gText()
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.

Parameters:
xX coordinate of upper left corner
yY coordinate of upper left corner
columnsnumber of text columns
rowsnumber of text rows
fonta font definition
modea 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

Returns:
0 with the desired area defined if all the coordinates are valid, otherwise returns non zero error code with the area set to the full display

Examples:

    // top of right side of display, 10 columns by 2 lines
    textarea.DefineArea(GLCD.CenterX, GLCD.Top, 10, 2, System5x7);

    // top of right side of display, 10 columns by 2 lines, reverse scrolling
    textarea.DefineArea(GLCD.CenterX, GLCD.Top, 10, 2, System5x7, gTextMode_SCROLLDOWN);
Note:
Upon defining the text area, the cursor position for the text area will be set to x,y
See also:
ClearArea()
SetAreaMode() ClearAreaMode()
gTextMode
gText()
uint8_t DefineArea ( predefinedArea  selection,
Font_t  font,
gTextMode  mode = DEFAULT_gTEXTMODE 
)

Define a predefined generic text area and font.

Parameters:
selectiona value from predefinedArea
fonta font definition
modea 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

Returns:
0 with the desired area defined if all the coordinates are valid, otherwise returns non zero error code with the area set to the full display

Examples:

    // right side of display
    textarea.DefineArea(textAreaRIGHT, System5x7);

    // top half of display
    textarea.DefineArea(textAreaTOP, System5x7);

    // upper left quadrant reverse scroll
    textarea.DefineArea(textAreaTOPLEFT, System5x7, gTextMode_SCROLLDOWN);
Note:
Upon defining the text area, the cursor position for the text area will be set to the upper left coordinate of the given predefined area
See also:
ClearArea()
SetAreaMode()
ClearAreaMode()
predefinedArea
gTextMode
uint8_t DefineArea ( predefinedArea  selection,
gTextMode  mode = DEFAULT_gTEXTMODE 
)

Define a predefined generic text area.

Parameters:
selectiona value from predefinedArea
modea 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

Returns:
0 with the desired area defined if all the coordinates are valid, otherwise returns non zero error code with the area set to the full display

Examples:

    // right side of display
    textarea.DefineArea(textAreaRIGHT);

 // top half of display
    textarea.DefineArea(textAreaTOP);

    // upper left quadrant reverse scroll
    textarea.DefineArea(textAreaTOPLEFT, gTextMode_SCROLLDOWN);
Note:
Upon defining the text area, the cursor position for the text area will be set to the upper left coordinate of the given predefined area
See also:
ClearArea()
SetAreaMode()
ClearAreaMode()
predefinedArea
gTextMode
gText()
void DrawString ( const char *  str,
int  hpos,
int  vpos,
eraseLine_t  erase = eraseNONE 
)

Output a NULL terminated character string with horizontal and vertical positioning.

Parameters:
strcharacter string
hposspecifies the horizontal positioning.
vposspecifies the vertical positioning.
eraseoptional 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:

  • an x/y pixel position relative to the upper left corner of the text area
  • a formatting type from gTextfmt_t
  • the type gTextfmt_col(col) to specify a text column relative to the left of the text area
  • the type gTextfmt_row(row) to specify a text row/line relative the top of the text area

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:

    GLCD.DrawString("Hello", 20, 10, eraseFULL_LINE);           // print at pixel coordinate x=20, y=10 relative to top left corner of text area
    GLCD.DrawString("Hello", gTextfmt_left, gTextfmt_row(2), eraseFULL_LINE);       // left adjust on row=2 (3rd line from top) 
    GLCD.DrawString("Hello", gTextfmt_col(20), gTextfmt_row(2), eraseFULL_LINE);    // text column=20, row=2
    GLCD.DrawString("Hello", gTextfmt_col(col), gTextfmt_row(row), eraseFULL_LINE);     // text column=col, row=row
    GLCD.DrawString("Hello", gTextfmt_center, gTextfmt_center);                 // center on display
    GLCD.DrawString("Hello", gTextfmt_center, gTextfmt_bottom);                 // center on bottom line of display
    GLCD.DrawString("Hello", gTextfmt_right, gTextfmt_top);                     // right adjust on top line of display
    GLCD.DrawString(F("Hello"), gTextfmt_right, gTextfmt_top);                  // right adjust on top line of display
    GLCD.DrawString_P(PSTR("Hello"), gTextfmt_right, gTextfmt_top);             // right adjust on top line of display
    textarea.DrawString(F("Hello"), gTextfmt_right, gTextfmt_top);              // right adjust on top line of display

See PutChar() for a full description of how characters are written to the text area.

Note:
Because DrawString() allows alignment at the pixel level in addition to the row and column, it is possible that the renderered text does not line up with a normal text area row and column. This is likely to occur when using formatting type gTextfmt_center
See also:
PutChar()
Puts()
Puts_P()
DrawString_P()
write()
void DrawString ( String &  str,
int  hpos,
int  vpos,
eraseLine_t  erase = eraseNONE 
)

Output a String class string with horizontal and vertical positioning.

Parameters:
strcharacter string
hposspecifies the horizontal positioning.
vposspecifies the vertical positioning.
eraseoptional 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:

  • an x/y pixel position relative to the upper left corner of the text area
  • a formatting type from gTextfmt_t
  • the type gTextfmt_col(col) to specify a text column relative to the left of the text area
  • the type gTextfmt_row(row) to specify a text row/line relative the top of the text area

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:

    GLCD.DrawString("Hello", 20, 10, eraseFULL_LINE);           // print at pixel coordinate x=20, y=10 relative to top left corner of text area
    GLCD.DrawString("Hello", gTextfmt_left, gTextfmt_row(2), eraseFULL_LINE);       // left adjust on row=2 (3rd line from top) 
    GLCD.DrawString("Hello", gTextfmt_col(20), gTextfmt_row(2), eraseFULL_LINE);    // text column=20, row=2
    GLCD.DrawString("Hello", gTextfmt_col(col), gTextfmt_row(row), eraseFULL_LINE);     // text column=col, row=row
    GLCD.DrawString("Hello", gTextfmt_center, gTextfmt_center);                 // center on display
    GLCD.DrawString("Hello", gTextfmt_center, gTextfmt_bottom);                 // center on bottom line of display
    GLCD.DrawString("Hello", gTextfmt_right, gTextfmt_top);                     // right adjust on top line of display
    GLCD.DrawString(F("Hello"), gTextfmt_right, gTextfmt_top);                  // right adjust on top line of display
    GLCD.DrawString_P(PSTR("Hello"), gTextfmt_right, gTextfmt_top);             // right adjust on top line of display
    textarea.DrawString(F("Hello"), gTextfmt_right, gTextfmt_top);              // right adjust on top line of display

See PutChar() for a full description of how characters are written to the text area.

Note:
Because DrawString() allows alignment at the pixel level in addition to the row and column, it is possible that the renderered text does not line up with a normal text area row and column. This is likely to occur when using formatting type gTextfmt_center
See also:
PutChar()
Puts()
Puts_P()
DrawString_P()
write()
void DrawString ( const __FlashStringHelper *  str,
int  hpos,
int  vpos,
eraseLine_t  erase = eraseNONE 
)

Output an Arduino FLASH string with horizontal and vertical positioning.

Parameters:
strcharacter string
hposspecifies the horizontal positioning.
vposspecifies the vertical positioning.
eraseoptional 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:

  • an x/y pixel position relative to the upper left corner of the text area
  • a formatting type from gTextfmt_t
  • the type gTextfmt_col(col) to specify a text column relative to the left of the text area
  • the type gTextfmt_row(row) to specify a text row/line relative the top of the text area

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:

    GLCD.DrawString("Hello", 20, 10, eraseFULL_LINE);           // print at pixel coordinate x=20, y=10 relative to top left corner of text area
    GLCD.DrawString("Hello", gTextfmt_left, gTextfmt_row(2), eraseFULL_LINE);       // left adjust on row=2 (3rd line from top) 
    GLCD.DrawString("Hello", gTextfmt_col(20), gTextfmt_row(2), eraseFULL_LINE);    // text column=20, row=2
    GLCD.DrawString("Hello", gTextfmt_col(col), gTextfmt_row(row), eraseFULL_LINE);     // text column=col, row=row
    GLCD.DrawString("Hello", gTextfmt_center, gTextfmt_center);                 // center on display
    GLCD.DrawString("Hello", gTextfmt_center, gTextfmt_bottom);                 // center on bottom line of display
    GLCD.DrawString("Hello", gTextfmt_right, gTextfmt_top);                     // right adjust on top line of display
    GLCD.DrawString(F("Hello"), gTextfmt_right, gTextfmt_top);                  // right adjust on top line of display
    GLCD.DrawString_P(PSTR("Hello"), gTextfmt_right, gTextfmt_top);             // right adjust on top line of display
    textarea.DrawString(F("Hello"), gTextfmt_right, gTextfmt_top);              // right adjust on top line of display

See PutChar() for a full description of how characters are written to the text area.

Note:
Because DrawString() allows alignment at the pixel level in addition to the row and column, it is possible that the renderered text does not line up with a normal text area row and column. This is likely to occur when using formatting type gTextfmt_center
See also:
PutChar()
Puts()
Puts_P()
DrawString_P()
write()
void DrawString ( FLASHSTRING  str,
int  hpos,
int  vpos,
eraseLine_t  erase = eraseNONE 
)

Output an GLCD FLASH string with horizontal and vertical positioning.

Parameters:
strcharacter string
hposspecifies the horizontal positioning.
vposspecifies the vertical positioning.
eraseoptional 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:

  • an x/y pixel position relative to the upper left corner of the text area
  • a formatting type from gTextfmt_t
  • the type gTextfmt_col(col) to specify a text column relative to the left of the text area
  • the type gTextfmt_row(row) to specify a text row/line relative the top of the text area

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:

    GLCD.DrawString("Hello", 20, 10, eraseFULL_LINE);           // print at pixel coordinate x=20, y=10 relative to top left corner of text area
    GLCD.DrawString("Hello", gTextfmt_left, gTextfmt_row(2), eraseFULL_LINE);       // left adjust on row=2 (3rd line from top) 
    GLCD.DrawString("Hello", gTextfmt_col(20), gTextfmt_row(2), eraseFULL_LINE);    // text column=20, row=2
    GLCD.DrawString("Hello", gTextfmt_col(col), gTextfmt_row(row), eraseFULL_LINE);     // text column=col, row=row
    GLCD.DrawString("Hello", gTextfmt_center, gTextfmt_center);                 // center on display
    GLCD.DrawString("Hello", gTextfmt_center, gTextfmt_bottom);                 // center on bottom line of display
    GLCD.DrawString("Hello", gTextfmt_right, gTextfmt_top);                     // right adjust on top line of display
    GLCD.DrawString(F("Hello"), gTextfmt_right, gTextfmt_top);                  // right adjust on top line of display
    GLCD.DrawString_P(PSTR("Hello"), gTextfmt_right, gTextfmt_top);             // right adjust on top line of display
    textarea.DrawString(F("Hello"), gTextfmt_right, gTextfmt_top);              // right adjust on top line of display

See PutChar() for a full description of how characters are written to the text area.

Note:
Because DrawString() allows alignment at the pixel level in addition to the row and column, it is possible that the renderered text does not line up with a normal text area row and column. This is likely to occur when using formatting type gTextfmt_center
See also:
PutChar()
Puts()
Puts_P()
DrawString_P()
write()
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.

Parameters:
strcharacter string
hposspecifies the horizontal positioning.
vposspecifies the vertical positioning.
eraseoptional 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:

  • an x/y pixel position relative to the upper left corner of the text area
  • a formatting type from gTextfmt_t
  • the type gTextfmt_col(col) to specify a text column relative to the left of the text area
  • the type gTextfmt_row(row) to specify a text row/line relative the top of the text area

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:

    GLCD.DrawString("Hello", 20, 10, eraseFULL_LINE);           // print at pixel coordinate x=20, y=10 relative to top left corner of text area
    GLCD.DrawString("Hello", gTextfmt_left, gTextfmt_row(2), eraseFULL_LINE);       // left adjust on row=2 (3rd line from top) 
    GLCD.DrawString("Hello", gTextfmt_col(20), gTextfmt_row(2), eraseFULL_LINE);    // text column=20, row=2
    GLCD.DrawString("Hello", gTextfmt_col(col), gTextfmt_row(row), eraseFULL_LINE);     // text column=col, row=row
    GLCD.DrawString("Hello", gTextfmt_center, gTextfmt_center);                 // center on display
    GLCD.DrawString("Hello", gTextfmt_center, gTextfmt_bottom);                 // center on bottom line of display
    GLCD.DrawString("Hello", gTextfmt_right, gTextfmt_top);                     // right adjust on top line of display
    GLCD.DrawString(F("Hello"), gTextfmt_right, gTextfmt_top);                  // right adjust on top line of display
    GLCD.DrawString_P(PSTR("Hello"), gTextfmt_right, gTextfmt_top);             // right adjust on top line of display
    textarea.DrawString(F("Hello"), gTextfmt_right, gTextfmt_top);              // right adjust on top line of display

See PutChar() for a full description of how characters are written to the text area.

Note:
Because DrawString() allows alignment at the pixel level in addition to the row and column, it is possible that the renderered text does not line up with a normal text area row and column. This is likely to occur when using formatting type gTextfmt_center
See also:
PutChar()
Puts()
Puts_P()
DrawString_P()
write()

Erase in Line.

Parameters:
typetype 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.

See also:
ClearArea()
eraseLine_t
void EraseTextLine ( uint8_t  row)

Erase Text Line.

Parameters:
rowrow # 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.

See also:
ClearArea()
int GetAreaProp ( gTextProp_t  property)

Get Text Area property.

Parameters:
propertya value from gTextProp_t Get Text Area property
Returns:
the value of the specified text area property.

Examples:

 height = GLCD.GetAreaProp(gTextProp_FontHeight);   // font rendered height
   cols = GLCD.GetAreaProp(gTextProp_cols);         // text columns
   rows = GLCD.GetAreaProp(gTextProp_rows);         // text rows
   cols = textarea.GetAreaProp(gTextProp_cols);     // text columns
   rows = textarea.GetAreaProp(gTextProp_rows);     // text rows
    x1  = textarea.GetAreaProp(gTextProp_x1);       // upper left x coordinate
    y1  = textarea.GetAreaProp(gTextProp_y1);       // upper left y coordinate
    x2  = textarea.GetAreaProp(gTextProp_x2);       // lower right x coordinate
    y2  = textarea.GetAreaProp(gTextProp_y2);       // lower right y coordinate
 width  = textarea.GetAreaProp(gTextProp_FontWidth);// font rendered fixed width
Note:
The value returned for gTextProp_cols is based on the fixed width maximum size of the font. If a variable font is used, the true number of actual columns possible will vary depending on the characters rendered.

gTextProp_FontWidth and gTextProp_FontHeight return rendered sizes in pixels which include any inter character padding pixels.

See also:
DefineArea()
CharHeight()
CharWidth()
void GotoXY ( uint8_t  x,
uint8_t  y 
) [protected, inherited]

set current x,y coordinate on display device

Parameters:
xX coordinate
yY 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.

Reimplemented in glcd.

int Init ( glcd_device_mode  invert = NON_INVERTED) [protected, inherited]

Low level h/w initialization of library and display.

Parameters:
invertspecifices 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:

  • the display pixels will be enabled
  • the backlight will be turned on (if configured)
  • the entire display will be cleared
  • the x,y postion will be set to 0,0
Returns:
0 or GLCD_NOERR when successful or non zero error code when unsucessful
Note:
This function can also be called to re-initliaze the display hardware.

Reimplemented in glcd.

int Off ( void  ) [protected, inherited]

Turn off the display & backlight.

Turns off the display's pixels and backlight

See also:
On()
OffDisplay()
OffBacklight()

Reimplemented in glcd.

int OffBacklight ( void  ) [protected, inherited]

Turn off the backlight.

Returns:
0 or GLCD_NOERR when successful or non zero error code when unsucessful
See also:
OnBacklight()
OffDisplay()
Off()

Reimplemented in glcd.

int OffDisplay ( void  ) [protected, inherited]

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.

Returns:
0 or GLCD_NOERR when successful or non zero error code when unsucessful
See also:
OnDisplay()
OffBacklight()
Off()

Reimplemented in glcd.

int On ( void  ) [protected, inherited]

Turn on the display & backlight.

Turns on the display's pixels and backlight

Note:
The backlight will be turned on at full intensity
See also:
Off()
OnDisplay()
OnBacklight()

Reimplemented in glcd.

int OnBacklight ( void  ) [protected, inherited]

Turn on the backlight.

Returns:
0 or GLCD_NOERR when successful or non zero error code when unsucessful
See also:
OffBacklight()
OnDisplay()
On()

Reimplemented in glcd.

int OnDisplay ( void  ) [protected, inherited]

Turn the display pixels on.

Turns on the display pixels. It does not alter or modify the backlight setting.

Returns:
0 or GLCD_NOERR when successful or non zero error code when unsucessful
See also:
OffDisplay()
OnBacklight()
On()

Reimplemented in glcd.

void Printf ( const char *  format,
  ... 
)

print formatted data

Parameters:
formatstring 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:

 GLCD.Printf("Hello World");
 GLCD.Printf(F("Hello World")); // put string in flash memory
 textarea.Printf("Hello World");
 GLCD.Printf("x=%02d", x);      // 2 digits decimal with zero fill
 GLCD.Printf("x=%2d", x);       // 2 digits decimal with <space> fill
 GLCD.Printf("hexval=%02x", x); // 2 hex digits with zero fill
 GLCD.Printf("val=%d", val);    // decimal number
 GLCD.Printf(F("val=%d"), val); // decimal number with format string in flash
Note:
By default the xxprintf() routines, which Printf() uses, have no floating point support in AVR enviornments. (Works for ARM and PIC32 by default) In order to enable floating point support for AVR, a linker option must be changed. Currently, the Arduino IDE does not support modifying the linker options.
See also:
Printf_P()
void Printf ( const __FlashStringHelper *  format,
  ... 
)

print formatted data

Parameters:
formatstring 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:

 GLCD.Printf("Hello World");
 GLCD.Printf(F("Hello World")); // put string in flash memory
 textarea.Printf("Hello World");
 GLCD.Printf("x=%02d", x);      // 2 digits decimal with zero fill
 GLCD.Printf("x=%2d", x);       // 2 digits decimal with <space> fill
 GLCD.Printf("hexval=%02x", x); // 2 hex digits with zero fill
 GLCD.Printf("val=%d", val);    // decimal number
 GLCD.Printf(F("val=%d"), val); // decimal number with format string in flash
Note:
By default the xxprintf() routines, which Printf() uses, have no floating point support in AVR enviornments. (Works for ARM and PIC32 by default) In order to enable floating point support for AVR, a linker option must be changed. Currently, the Arduino IDE does not support modifying the linker options.
See also:
Printf_P()
(const char *format, ...)

void Printf_P ( PGM_P  format,
  ... 
)

print formatted data

Parameters:
formatstring 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.

See also:
Printf()
void printFlash ( FLASHSTRING  str)

print a flash based string

Parameters:
strpointer to a null terminated character string stored in program memory
See also:
printFlashln()
Puts_P()
void printFlashln ( FLASHSTRING  str)

print a flash based string

Parameters:
strpointer to a null terminated character string stored in program memory

The string is output followed by a newline.

See also:
printFlash()
Puts_P()
void PrintNumber ( long  n)

Legacy function to print a number.

Parameters:
nis the number to print
See also:
print(n)
int PutChar ( uint8_t  c)

output a character

Parameters:
cthe 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.

Returns:
1 if a character was rendered, 0 if a character was not rendered
See also:
Puts()
Puts_P()
write()
void Puts ( const char *  str)

output a character string

Parameters:
strpointer to a null terminated character string.

Outputs all the characters in the string to the text area.

Examples:

 GLCD.Puts("Hello World");
 textarea.Puts("Hello World");

See PutChar() for a full description of how characters are written to the text area.

See also:
PutChar()
Puts_P()
DrawString()
DrawString_P()
write()
void Puts ( const String &  str)

output a String class string

Parameters:
strString 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.

See also:
PutChar()
Puts_P()
DrawString()
DrawString_P()
write()
void Puts ( const __FlashStringHelper *  str)

output an Arduino Flash program memory character string

Parameters:
strpointer to a null terminated character string stored in program memory declared using F() macro

Outputs all the characters in the string to the text area.

Examples:

 GLCD.Puts(F("Hello World"));
 textarea.Puts(F("Hello World"));

See PutChar() for a full description of how characters are written to the text area.

See also:
PutChar()
Puts()
DrawString()
DrawString_P()
write()
void Puts_P ( PGM_P  str)

output a program memory character string

Parameters:
strpointer to a null terminated character string stored in program memory

Outputs all the characters in the string to the text area.

Examples:

 GLCD.Puts_P(PSTR("Hello World"));
 textarea.Puts_P(PSTR("Hello World"));

See PutChar() for a full description of how characters are written to the text area.

See also:
PutChar()
Puts()
DrawString()
DrawString_P()
write()
uint8_t ReadData ( void  ) [protected, inherited]

read a data byte from display device memory

Returns:
the data byte at the current x,y position
Note:
the current x,y location is not modified by the routine. This allows a read/modify/write operation. Code can call ReadData() modify the data then call WriteData() and update the same location.
See also:
WriteData()

Reimplemented in glcd.

void SelectFont ( Font_t  font,
uint8_t  fgcolor = BLACK,
FontCallback  callback = ReadPgmData 
)

Select a Font and font color.

Parameters:
fonta font definition
fgcolorforeground font color
callbackoptional 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:

    GLCD.SelectFont(System5x7);            // fg pixels on, bg pixels off
    GLCD.SelectFont(System5x7, PIXEL_ON);  // fg pixels on, bg pixels off
    GLCD.SelectFont(System5x7, BLACK);     // fg pixels on, bg pixels off
    GLCD.SelectFont(System5x7, PIXEL_OFF); // fg pixels off, bg pixels on
    GLCD.SelectFont(System5x7, WHITE);     // fg pixels off, bg pixels on
    GLCD.SelectFont(Arial14);
    textarea.SelectFont(fixednums7x15, PIXEL_OFF);
Note:
When the display is initilized in INVERTED mode, the colors are reversed.
AVR systems require fonts to fit in lower 64k of program memory
See also:
SetFontColor()
SetAreaMode()
void SetAreaMode ( gTextMode  mode)

Set TextArea mode options.

Parameters:
modea value from gTextMode

Examples:

 textarea.SetAreaMode(gTextMode_SCROLLDOWN); // enable reverse vertical scrolling
 textarea.SetAreaMode(gTextMode_VARasFIXED); // render variable font as fixedwidth
 textarea.SetAreaMode(gTextMode_OVERSTRIKE); // enable text overstrike
See also:
ClearAreaMode()
SelectFont()
SetFontColor()
DefineArea()
gTextMode
int SetBacklight ( int  val) [protected, inherited]

Set backlight brightness.

Parameters:
valbacklight 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.

Returns:
0 or GLCD_NOERR when successful or non zero error code when unsucessful
See also:
OnBacklight() OffBacklight()
Note:
Currently dimming is not yet supported.

Reimplemented in glcd.

void SetDot ( uint8_t  x,
uint8_t  y,
uint8_t  color 
) [protected, inherited]

set pixel at x,y to the given color

Parameters:
xX coordinate, a value from 0 to GLCD.Width-1
yY coordinate, a value from 0 to GLCD.Heigh-1
colorSets 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.
Note:
If the display has been set to INVERTED mode then the color will be automically reversed.

Reimplemented in glcd.

void SetFontColor ( uint8_t  fgcolor)

Set a font foreground color.

Parameters:
fgcolorforeground 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:

    GLCD.SetFontColor(PIXEL_ON);  // fg pixels on, bg pixels off
    GLCD.SetFontColor(BLACK);     // fg pixels on, bg pixels off
    GLCD.SetFontColor(PIXEL_OFF); // fg pixels off, bg pixels on
    GLCD.SetFontColor(WHITE);     // fg pixels off, bg pixels on
    textarea.SetFontColor(PIXEL_OFF);
Note:
The color becomes effective for all future text operations but does not alter the area, including any existing text in the area. This allows switching colors as printing is done within the area. If a ClearScreen() is done, then the area is cleared according to the color.
See also:
SelectFont()
SetAreaMode()
void SetPixels ( uint8_t  x,
uint8_t  y,
uint8_t  x2,
uint8_t  y2,
uint8_t  color 
) [protected, inherited]

set an area of pixels

Parameters:
xX coordinate of upper left corner
yY coordinate of upper left corner
x2X coordinate of lower right corner
y2Y coordinate of lower right corner
colorsets 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

Reimplemented in glcd.

uint16_t StringWidth ( const char *  str)

Returns the pixel width of a string.

Parameters:
strpointer to string stored in RAM
Returns:
the width in pixels of the sum of all the characters in the the string pointed to by str.
See also:
CharWidth()
CharHeight()
StringWidth_P()
uint16_t StringWidth ( String &  str)

Returns the pixel width of a String class string.

Parameters:
strString class string
Returns:
the width in pixels of the sum of all the characters in the the string pointed to by str.
See also:
CharWidth()
CharHeight()
StringWidth()
uint16_t StringWidth ( const __FlashStringHelper *  str)

Returns the pixel width of a FlashString.

Parameters:
strstring declared with F() macro
Returns:
the width in pixels of the sum of all the characters in the the string pointed to by str.
See also:
CharWidth()
CharHeight()
StringWidth()
uint16_t StringWidth_P ( PGM_P  str)

Returns the pixel width of a string.

Parameters:
strpointer to string stored in program memory
Returns:
the width in pixels of the sum of all the characters in the the string pointed to by str.
See also:
CharWidth()
CharHeight()
StringWidth()
void write ( uint8_t  c)

output a character to the text area

Parameters:
cthe character to output

This method is needed for the Print base class

Warning:
Carriage returns are swallowed to prevent println() from printing the 0xd character if the font contains this character. To actually print the 0xd character use PutChar().
See also:
PutChar()
void WriteData ( uint8_t  data) [protected, inherited]

Write a byte to display device memory.

Parameters:
datadate 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.

Note:
the full behavior of this during split byte writes currently varies depending on a compile time define. The code can be configured to either OR in 1 data bits or set all the data bits. TRUE_WRITE controls this behavior.
the x,y address will not be the same as it was prior to this call. The y address will remain the aame but the x address will advance by one. This allows back to writes to write sequentially through memory without having to do additional x,y positioning.
See also:
ReadData()

Reimplemented in glcd.


The documentation for this class was generated from the following files:
 All Classes Functions Variables