Arduino GLCD Library: gText Class Reference

# gText Class Reference

Functions for Text Areas. More...

Inheritance diagram for gText:

List of all members.

## Public Member Functions

| gText (uint8_t x1, uint8_t y1, uint8_t columns, uint8_t rows, Font_t font, textMode mode=DEFAULT_SCROLLDIR)
| gText (predefinedArea selection, textMode mode=DEFAULT_SCROLLDIR)
| gText (uint8_t x1, uint8_t y1, uint8_t x2, uint8_t y2, textMode mode=DEFAULT_SCROLLDIR)
TEXT FUNCTIONS
The following text functions are available
uint8_t | CharWidth (uint8_t c)
void | ClearArea (void)
void | CursorTo (int8_t column)
void | CursorTo (uint8_t column, uint8_t row)
void | CursorToXY (uint8_t x, uint8_t y)
uint8_t | DefineArea (predefinedArea selection, textMode mode=DEFAULT_SCROLLDIR)
uint8_t | DefineArea (uint8_t x1, uint8_t y1, uint8_t columns, uint8_t rows, Font_t font, textMode mode=DEFAULT_SCROLLDIR)
uint8_t | DefineArea (uint8_t x1, uint8_t y1, uint8_t x2, uint8_t y2, textMode mode=DEFAULT_SCROLLDIR)
void | DrawString (char *str, uint8_t x, uint8_t y)
void | DrawString_P (PGM_P str, uint8_t x, uint8_t y)
void | EraseTextLine (uint8_t row)
void | EraseTextLine (eraseLine_t type=eraseTO_EOL)
void | Printf (const char *format,...)
void | Printf_P (const char *format,...)
void | printFlash (FLASHSTRING str)
void | printFlashln (FLASHSTRING str)
void | PrintNumber (long n)
int | PutChar (uint8_t c)
void | Puts (char *str)
void | Puts_P (PGM_P str)
void | SelectFont (Font_t font, uint8_t color=BLACK, FontCallback callback=ReadPgmData)
void | SetFontColor (uint8_t color)
void | SetTextMode (textMode mode)
uint16_t | StringWidth (const char *str)
uint16_t | StringWidth_P (PGM_P str)
void | write (uint8_t c)

## Protected Member Functions

void | GotoXY (uint8_t x, uint8_t y)
void | Init (uint8_t invert=false)
uint8_t | ReadData (void)
void | SetDot (uint8_t x, uint8_t y, uint8_t color)
void | SetPixels (uint8_t x, uint8_t y, uint8_t x1, uint8_t y1, uint8_t color)
void | WriteData (uint8_t data)

## Static Protected Attributes

static lcdCoord | Coord
static uint8_t | Inverted

## 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.

## Member Function Documentation

uint8_t CharWidth | ( | uint8_t | c | ) |

Returns the pixel width of a character

Parameters:

  | c | character 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.

See also:
  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 CursorTo | ( | int8_t | column | ) |

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

Parameters:

  | 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.

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 CursorTo | ( | uint8_t | column,
|  | uint8_t | row |
| ) |  |  |

Positions cursor to a character based column and row.

Parameters:

  | 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.

While intended for fixed width fonts, positioning will work for variable width fonts.

When variable width fonts are used, the column is based on assuming a width of the widest character.

See also:
  CursorToXY()

void CursorToXY | ( | uint8_t | x,
|  | uint8_t | y |
| ) |  |  |

Positions cursor to a X,Y position

Parameters:

  | 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.

See also:
  CursorTo()

uint8_t DefineArea | ( | predefinedArea | selection,
|  | textMode | mode = `DEFAULT_SCROLLDIR` |
| ) |  |  |

Define a predefined generic text area

Parameters:

  | selection | a value from predefinedArea
  | mode | constants SCROLL_DOWN and SCROLL_UP control scroll direction

Defines a text area using a selection form 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:
  returns true if successful.

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()
  predefinedArea

uint8_t DefineArea | ( | uint8_t | x,
|  | uint8_t | y,
|  | uint8_t | columns,
|  | uint8_t | rows,
|  | Font_t | font,
|  | textMode | mode = `DEFAULT_SCROLLDIR` |
| ) |  |  |

Define a Text area by columns and rows

Parameters:

  | 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 | constants SCROLL_DOWN and SCROLL_UP control scroll direction

Defines 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

Note:
  Upon defining the text area, the cursor position for the text area will be set to x,y

See also:
  ClearArea()

uint8_t DefineArea | ( | uint8_t | x1,
|  | uint8_t | y1,
|  | uint8_t | x2,
|  | uint8_t | y2,
|  | textMode | mode = `DEFAULT_SCROLLDIR` |
| ) |  |  |

Define a text area by absolute coordinates

Parameters:

  | 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 | constants SCROLL_DOWN and SCROLL_UP control scroll direction

Defines 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:
  true with the given area selected if all the coordinates are valid, otherwise returns returns false with the area set to the full display

Note:
  Upon creation of the text area, the cursor position for the text area will be set to x1, y1

See also:
  ClearArea()

void DrawString | ( | char * | str,
|  | uint8_t | x,
|  | uint8_t | y |
| ) |  |  |

output a character string at x,y coordinate

Parameters:

  | str | pointer to a null terminated character string
  | x | specifies the horizontal location
  | y | specifies the vertical location

Outputs all the characters in the string to the text area. X & Y are zero based pixel coordinates and are relative to the upper left corner of the text area.

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

See also:
  PutChar()
  Puts()
  Puts_P()
  DrawString_P()
  write()

void DrawString_P | ( | PGM_P | str,
|  | uint8_t | x,
|  | uint8_t | y |
| ) |  |  |

output a program memory character string at x,y coordinate

Parameters:

  | str | pointer to a null terminated character string stored in program memory
  | x | specifies the horizontal location
  | y | specifies the vertical location

Outputs all the characters in the string to the text area. X & Y are zero based pixel coordinates and are relative to the upper left corner of the text area.

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

See also:
  PutChar()
  Puts()
  Puts_P()
  DrawString()
  write()

void EraseTextLine | ( | uint8_t | row | ) |

Erase Text Line

Parameters:

  | 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.

See also:
  ClearArea()

void EraseTextLine | ( | eraseLine_t | type = `eraseTO_EOL` | ) |

Erase in Line

Parameters:

  | type | type of line erase

- eraseTO_EOL Erase from cursor to end of line
- eraseFROM_BOL Erase from beginning of line to cursor
- eraseFULL_LINE Erase entire line

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 GotoXY | ( | uint8_t | x,
|  | uint8_t | y |
| ) |  |  | `[protected, inherited]`

set current x,y coordinate on display device

Parameters:

  | 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.

Reimplemented in glcd.

void Init | ( | uint8_t | invert = `false` | ) | `[protected, inherited]`

Low level h/w initialization of display and AVR pins

Parameters:

  | invert | specifices whether display is in normal mode or inverted mode.

This should only be called by other library code.

It does all the low level hardware initalization of the display device.

The optional invert parameter specifies if the display should be run in a normal mode, dark pixels on light background or inverted, light pixels on a dark background.

To specify dark pixels use the define NON-INVERTED and to use light pixels use the define INVERTED

Upon completion of the initialization, the entire display will be cleared and the x,y postion will be set to 0,0

Reimplemented in glcd.

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

print formatted data

Parameters:

  | 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.

Note:
  By default printf() has no floating support in AVR enviornments. In order to enable this, a linker option must be changed. Currenly, the Arduino IDE does not support modifying the linker options.

See also:
  Printf_P()

void Printf_P | ( | const char * | format,
|  |  | ... |
| ) |  |  |

print formatted data

Parameters:

  | 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.

See also:
  Printf()

void printFlash | ( | FLASHSTRING | str | ) |

print a flash based string

Parameters:

  | str | pointer to a null terminated character string stored in program memory

See also:
  Puts_P()

void printFlashln | ( | FLASHSTRING | str | ) |

print a flash based string

Parameters:

  | str | pointer to a null terminated character string stored in program memory

The string is output followed by a newline.

See also:
  Puts_P()

void PrintNumber | ( | long | n | ) |

Legacy function to print a number

Parameters:

  | n | is the number to print

See also:
  print(n)

int PutChar | ( | uint8_t | c | ) |

output a character

Parameters:

  | 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.

See also:
  Puts()
  Puts_P()
  write()

void Puts | ( | char * | str | ) |

output a character string

Parameters:

  | str | pointer to a null terminated character 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_P | ( | PGM_P | str | ) |

output a program memory character string

Parameters:

  | str | pointer to a null terminated character string stored in program memory

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()
  DrawString()
  DrawString_P()
  write()

uint8_t ReadData | ( | void |  | ) | `[inline, 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 | color = `BLACK`,
|  | FontCallback | callback = `ReadPgmData` |
| ) |  |  |

Select a Font and font color

Parameters:

  | font | a font definition
  | color | can be WHITE or BLACK and defaults to black
  | 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 from included font definition files are stored in program memory You can have as many fonts defines as will fit in program memory up to 64k and can switch between them with this function.

If the optional callback argument is ommitted, a default routine is selected that assumes that the font is in program memory (flash).

Note:
  When the display is initilized in normal mode, BLACK renders dark pixels on a white background and WHITE renders white pixels on black background; however, if the display is set to INVERTED mode all colors are inverted.

See also:
  SetFontColor()
  SetTextMode()

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

set pixel at x,y to the given color

Parameters:

  | x | X coordinate, a value from 0 to GLCD.Width-1
  | y | Y coordinate, a value from 0 to GLCD.Heigh-1
  | color | WHITE or BLACK

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.

Note:
  If the display has been set to INVERTED mode then the colors will be automically reversed.

Reimplemented in glcd.

void SetFontColor | ( | uint8_t | color | ) |

Select a font color

Parameters:

  | color | can be WHITE or BLACK

See also:
  SelectFont()
  SetTextMode()

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:

  | 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.

The width of the area is x2-x + 1. The height of the area is y2-y+1

Reimplemented in glcd.

void SetTextMode | ( | textMode | mode | ) |

Select a font color

Parameters:

  | mode | text area mode

Currently mode is a scroll direction

- SCROLL_UP
- SCROLL_DOWN

See also:
  SelectFont()
  SetFontColor()

uint16_t StringWidth | ( | const char * | str | ) |

Returns the pixel width of a string

Parameters:

  | str | pointer 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()
  StringWidth_P()

uint16_t StringWidth_P | ( | PGM_P | str | ) |

Returns the pixel width of a character

Parameters:

  | str | pointer 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()
  StringWidth()

void write | ( | uint8_t | c | ) |

output a character to the text area

Parameters:

  | c | the character to output

This method is needed for the Print base class

See also:
  PutChar()

Reimplemented from glcd_Device.

void WriteData | ( | uint8_t | data | ) | `[protected, inherited]`

Write a byte to display device memory

Parameters:

  | 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.

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:

- gText.h
- gText.cpp