Keypad/Display Forth Glossary

This glossary defines important constants and functions from the Keypad Display Wildcard driver code. This Wildcard is useful your instrumentation requires human interaction or control.

?KEYPAD ( -- [n\TRUE] or [FALSE] | 0 < = n < = 39 )

Scans keypad or touchscreen having up to 8 rows and 5 columns. If a key is being depressed, PAUSEs and waits until the key is released, then returns the key number under a true flag. If no key is depressed, returns a false flag. Consult the KEYPAD glossary entry for a detailed description of keypad orientation. Disables interrupts for up to 12 µseconds each time a row is scanned.

See also ?KEYPRESS and KEYPAD
Pronunciation: "question-keypad"

?KEYPRESS ( -- [n\TRUE] or [FALSE] | 0 < = n < = 39 )

Scans keypad or touchscreen having up to 8 rows and 5 columns. If a key is being depressed, returns the key number under a true flag; unlike ?KEYPAD, ?KEYPRESS does not wait for the key to be released. If no key is depressed, returns a false flag. When using this function, make sure that multiple calls to your program do not misinterpret a single keystroke as multiple entries from the keypad. Consult the KEYPAD glossary entry for a detailed description of keypad orientation. Disables interrupts for 12 microseconds each time a row is scanned.

See also ?KEYPAD and KEYPAD
Pronunciation: "question-keypress"

$>DISPLAY ( x$addr\n1\n2 -- | n1 = line#, n2 = character# )

Moves the contents of the counted string specified by x$addr to the location in DISPLAY.BUFFER starting at the specified character number n2 on the specified line number n1. Does not move the count of x$addr. Confines the string to the specified line in DISPLAY.BUFFER by clamping the number of characters moved to a maximum equal to the number of character positions remaining after the specified position on the specified line. The line number n1 should be less than LINES/DISPLAY, and the character number n2 should be less than CHARS/DISPLAY.LINE. If the most significant byte of the page in x$addr equals 0xFF, $>DISPLAY accepts a null-terminated (C-style) string. $>DISPLAY does not modify the contents of the LCD display; this will occur upon the next execution of UPDATE.DISPLAY.LINE or UPDATE.DISPLAY or (UPDATE.DISPLAY).
Pronunciation: "string-to-display"

(UPDATE.DISPLAY) ( -- )

Writes the contents of the DISPLAY.BUFFER to the LCD display, but does not re-home the cursor/display RAM pointer to the default upper left position. This facilitates "scrolling" the contents of a graphics display when used in conjunction with the IS.DISPLAY.ADDRESS routine. For character displays, the cursor is turned off during the write to the display and is restored to its prior state after the update is complete, thus avoiding "flickering" of the cursor. Intermittently disables interrupts for up to 7 microseconds per byte.

See also UPDATE.DISPLAY and UPDATE.DISPLAY.LINE

Backlight_Off ( -- )

Turns off the LED backlight on the Keypad/Display Wildcard.

See also Backlight_On.

Backlight_On( -- )

Turns on the LED backlight on the Keypad/Display Wildcard.

See also Backlight_Off.

BUFFER.POSITION ( n1\n2 -- n3 | n1 = line#, n2 = char#, n3 = buffer.offset )

Given the specified LCD display line number n1 (0 ≤ n1 < LINES/DISPLAY) and the specified character position in the display line (0 ≤ n2 < CHARS/DISPLAY.LINE), calculates the offset n3 of the specified position relative to the extended base address returned by DISPLAY.BUFFER. Clamps n3 to ensure that the buffer.offset is not greater than the size of the buffer. Note that for a graphics-style display the line# n1 is interpreted differently depending on whether the display is being used in "text mode" or "graphics mode". In text mode, n1 corresponds to the character line#; in graphics mode, n1 corresponds to the pixel line#.

See also LINES/DISPLAY.

IsDisplay( -- )

This function configures the software for the standard 4-line by 20 character text-mode (alphanumeric/Hitachi-style) display. Saves the display configuration in EEPROM so that the LCD display is properly initialized upon subsequent restarts and resets by the INIT.DISPLAY routine. The encoded information is accessible via the routines CHARS/DISPLAY.LINE and LINES/DISPLAY. Note that because this routine saves the configuration information in EEPROM, you need not execute it each time the board starts up (but doing so has no adverse effects).

CHAR>DISPLAY ( char -- )

Writes the specified data byte char to the LCD display. Does not write to the Display Buffer. If an alphanumeric (character) display is being used, this command writes the specified ascii character at the current cursor position and increments the cursor position. (Caution: the cursor does not always follow a contiguous path as it is incremented; there may be discontinuities at the ends of lines.) Intermittently disables interrupts for up to 7 microseconds per byte written to the display.

See also COMMAND>DISPLAY and UPDATE.DISPLAY
Pronunciation: "char-to-display"

CHARS/DISPLAY.LINE ( -- n )

Returns the number of characters per line in the LCD display as specified by the last execution of Character_4x20 or IS.DISPLAY. The result returned by this routine is used by BUFFER.POSITION, PUT.CURSOR, UPDATE.DISPLAY, and UPDATE.DISPLAY.LINE.
Pronunciation: "chars-per-display-line"

Chirp ( u -- )

Activates the beeper on the Keypad/Display Wildcard for a time period specified by u in microseconds, which can be in the range from 1 to 65535 microseconds. Very short durations may not be audible. Specifying decimal 1000 microseconds (1 millisecond) produces a click that provides good audible feedback after a keypress. Longer durations produce a more tonal beep.

CLEAR.DISPLAY ( -- )

Clears (blanks) the LCD display, moves the cursor to home position (at the start of line 0). If a character display is in use (as specified by Character_4x20 or IS.DISPLAY), fills the 80 character DISPLAY.BUFFER with ascii blank characters. If a graphics display is being used in text mode, fills the heap-based buffer with ascii blanks. If a graphics display is being used in graphics mode, erases (zeros) the heap-based buffer. Intermittently disables interrupts for up to 7 microseconds per byte written to the display.

See also INIT.DISPLAY

COMMAND>DISPLAY ( byte -- )

Writes the specified byte to the LCD display as a command (as opposed to a character to be displayed). Does not modify the contents of the DISPLAY.BUFFER. Intermittently disables interrupts for up to 7 microseconds per command byte written to the display.

See also CHAR>DISPLAY.
Pronunciation: "command-to-display"

DISPLAY.BUFFER ( -- xaddr )

Returns the extended base address of the buffer that holds the display data. UPDATE.DISPLAY.LINE and UPDATE.DISPLAY write the contents of this buffer to the LCD display. If a character display is in use, xaddr is the base address of an 80 character buffer in the system RAM. If a graphics display is in use, xaddr is the starting address of a heap-based array. Each byte in this buffer represents a character position or graphical byte on the LCD display. To display characters on the LCD display, simply write the desired ascii characters or graphical data into this buffer and execute UPDATE.DISPLAY.LINE or UPDATE.DISPLAY. UPDATE.DISPLAY.LINE causes the contents of a specified line in DISPLAY.BUFFER to be written to the corresponding line of the display. UPDATE.DISPLAY causes the contents of all lines in DISPLAY.BUFFER to be written to the corresponding lines of the display.

See also $>DISPLAY and BUFFER.POSITION.

DISPLAY.OPTIONS ( flag1\flag2\flag3\flag4 -- )

Sets the display and cursor options on the LCD display. The meanings of the input flags are as follows:

flag1 = display.enabled?
flag2 = cursor.on?
flag3 = cursor.blinking?
flag4 = text.mode?

If flag1 is true, the contents of the display are visible; if false, the display appears blank. If flag2 is true, the cursor is on (typically an underscore character); if false, the cursor is off. If flag3 is true, the cursor blinks (typically a flashing box the size of a single character); if false, the cursor blink is turned off. If flag4 is true, the display is operating in "text mode"; if false, it is operating in "graphics mode". (If a Toshiba graphics display is in use, flag4 can take on the additional value 1, meaning that both text and graphics modes are enabled. In this case, you must set different home locations for the text and graphics regions.) Note that graphics mode should only be specified if a graphics display is in use. Note also that the cursor is never visible in graphics mode. INIT.DISPLAY leaves the display enabled with the cursor off and cursor blink off and the "home" location in the upper left corner at display ram address 0. Implementation detail: In addition to writing the appropriate command byte to the display, DISPLAY.OPTIONS stores the command byte in an system variable. This variable is referenced by UPDATE.DISPLAY.LINE and UPDATE.DISPLAY to blank the cursor during updates to character displays (to prevent annoying flickering) and restore it to its prior state after the update is complete. It is also used by LINES/DISPLAY to infer whether the display is being operated in text mode or graphics mode, which in turn determines whether LINES/DISPLAY reports the number of character lines or the number of pixel lines in the display. This routine intermittently disables interrupts for up to 7 microseconds per command byte written to the display.

INIT.DISPLAY ( -- )

Initializes the liquid crystal display (LCD) interface. If a graphics-style display has been specified by IS.DISPLAY, initializes an array in the heap; the base address of this array is returned by DISPLAY.BUFFER. If a character-style (alphanumeric) display has been specified by Character_4x20 or IS.DISPLAY, then the display buffer is located in the system RAM. INIT.DISPLAY calls CLEAR.DISPLAY to clear the DISPLAY.BUFFER and write the blank data (ascii blanks for character displays, binary zeros for graphics displays) to the LCD display. Homes the cursor to the start of line 0, and leaves the display enabled with the cursor off and not blinking. Intermittently disables interrupts for up to 7 microseconds per byte transmitted to the display.

See also CLEAR.DISPLAY

IS.DISPLAY ( #rows\#cols\text.mode?\char.display?\hitachi? -- )

This primitive is typically not used; the high level routine Character_4x20 is recommended when using the standard 4-line by 20 character text-mode display. IS.DISPLAY is used only for non-standard displays. Based on the specified number of rows, number of columns, and flags that indicate text or graphics mode, character versus graphics display, and Hitachi versus Toshiba graphics controller chip, this routine saves the display configuration in EEPROM so that the LCD display is properly initialized upon subsequent restarts and resets by the INIT.DISPLAY routine. The encoded information is accessible via the routines CHARS/DISPLAY.LINE and LINES/DISPLAY. When IS.DISPLAY is executed, #Rows and #cols should be expressed as the number of 8x6- or 8x8-pixel characters that the screen can accommodate. The standard width font for Toshiba graphics displays is set by hardware inputs on the display module to either 6 or 8 pixels wide. The standard width font for Hitachi graphics displays is 8 pixels in graphics mode, and can be set to either 6 pixels or 8 pixels wide in text mode. The allowed values of numRows are 2, 4, 8 or 16 lines per display. The allowed values of numCols are 8, 12, 16, 20, 24, 30, and 40 characters or bytes per line. The textMode input parameter selects between text mode (if textMode is true/non-zero) and graphics mode (if textMode is false/zero) for graphics displays; character displays always operate in text mode. The charDisplay input parameter selects between a strictly alphanumeric character display if charDisplay is true, and a graphics display if the charDisplay is false. The hitachi input parameter specifies the type of controller that drives the graphics display module. If hitachi is true, a Hitachi 61830 controller chip is assumed; if hitachi is false, we assume a Toshiba 6963 graphics controller chip. NOTE that if a graphics display is specified (char.display? is false) but the text mode is specified (text.mode? is true), the data buffer created by INIT.DISPLAY will be too small to accommodate graphical data. Thus if you want to use both the text and graphics modes of a graphics display, declare a graphics mode display (i.e., with a false text.mode flag), and use the DISPLAY.OPTIONS routine to convert to and from text mode. Then the dimensioned buffer will be large enough for either character or graphical data. To declare a 4x20 character display, use:

  IsDisplay( 4,20,-1,-1,-1 );

The 4x20 character display is the default type. Remember to execute INIT.DISPLAY after executing IS.DISPLAY. Note that because IS.DISPLAY saves the configuration information in EEPROM, you need not execute it each time the board starts up. See Character_4x20.

IS.DISPLAY.ADDRESS ( addr -- )

Configures a graphics display so that the next data write will occur at the specified RamAddress in the display RAM. This routine can be used in conjunction with (UPDATE.DISPLAY) to write data to the "off-screen" RAM that is typically present on a graphics display module. Then modifying the "home address" (upper left location) of the display allows scrolling of data across the display; consult the source code of the graphics extension source code file for more details. IsDisplayAddress has no effect if a character display is installed.

See also PUT.CURSOR

LINES/DISPLAY ( -- n )

Returns the number of lines in the LCD display. For character displays and for graphics displays being operated in "text mode", the result n equals the number of character lines (rows) in the display (the allowed values are 2, 4, 8 or 16 lines per display). For graphics displays being operated in "graphics mode", the result n equals the number of horizontal pixels on the display (which in turn is 8 times the number of character lines on the display). The type of display and the display mode (text mode vs. graphics mode) are determined by the most recent execution of DISPLAY.OPTIONS or INIT.DISPLAY (which implements the configuration specified by Character_4x20 or IS.DISPLAY). The result returned by this routine is used by BUFFER.POSITION, PUT.CURSOR, UPDATE.DISPLAY, and UPDATE.DISPLAY.LINE.
Pronunciation: "lines-per-display"

PUT.CURSOR ( n1\n2 -- | n1 = line#, n2 = character# )

Positions the LCD display cursor at the line number specified by n1 and the character number specified by n2. For all character and Hitachi graphics displays, the next character or graphical byte sent to the display by the CHAR>DISPLAY routine will appear at the specified cursor position, and then the cursor position will automatically increment. (Note that for Toshiba graphics displays, PUT.CURSOR affects only the cursor in text mode, and you must use IS.DISPLAY.ADDRESS to specify the location of the next graphical data byte.) n1 and n2 are 0 based (that is, the top line on the display is line#0, and the left-most character on each line is character#0). PUT.CURSOR clamps n1 to one less than LINES/DISPLAY, and clamps n2 to one less than CHARS/DISPLAY.LINE. The line# n1 follows the same rules explained in the description of BUFFER.POSITION: for a graphics-style display the line# n1 is interpreted differently depending on whether the display is being used in "text mode" or "graphics mode". In text mode, n1 corresponds to the character line#; in graphics mode, n1 corresponds to the pixel line#. Note that the cursor may not be visible, and is never visible in graphics mode (see DISPLAY.OPTIONS). Also note that after the cursor reaches the end of a line it may skip to the start of a line elsewhere on the display. Finally, consider using (UPDATE.DISPLAY) instead of UPDATE.DISPLAY to avoid re-homing the cursor after executing PUT.CURSOR. This routine intermittently disables interrupts for up to 7 microseconds per command byte.

See also DISPLAY.OPTIONS

Read_Extra_IO( -- byte )

Returns a value representing the current logic levels on the Extra IO port on the Keypad/Display Wildcard (1 = high, 0 = low). These eight digital I/O lines are arranged as a single byte comprising two nibbles of four lines each. The lower nibble named DIO_0 through DIO_3 is group-configurable as either inputs or outputs, and the upper nibble lines, DI_4 through DI_7, are always inputs. See Set_Extra_IO_Direction and Write_Extra_IO. Implementation detail: Reads the byte at offset 0x0D from the Wildcard base.

Set_Display_Modulenum( modulenum -- )

Declares the module number of the Keypad/Display Wildcard and stores it in a reserved EEPROM location. On the QCard platform, module number 0 must be used, and Set_Display_Modulenum prints a warning if a non-zero module number is specified. On the PDQ Board platform, any module number in the range 0 to 7 can be specified using Set_Display_Modulenum. In all cases, the hardware jumpers J1 and J2 must be set to correspond to the declared module number.

Set_Extra_IO_Direction( output? -- )

If the parameter named output? passed to this function is true, configures the lower nibble DIO_0 through DIO_3 of "extra IO" on the Keypad/Display Wildcard as outputs. If the parameter named output? passed to this function is false, configures the lower nibble DIO_0 through DIO_3 as inputs (the default at power-up). See Read_Extra_IO_Direction and Write_Extra_IO. Implementation detail: Writes to bit 0 at offset 0x0E from the Wildcard base (1=output, 0 = input).

UPDATE.DISPLAY ( -- )

Writes the contents of the DISPLAY.BUFFER to the LCD display. When finished, leaves the display cursor pointing at the first position in the first line. For character displays, the cursor is turned off during the write to the display and is restored to its prior state after the update is complete, thus avoiding "flickering" of the cursor. Intermittently disables interrupts up to 7 microseconds per byte.

See also (UPDATE.DISPLAY) and UPDATE.DISPLAY.LINE

UPDATE.DISPLAY.LINE ( n -- )

Writes the contents of the specified line number n in the DISPLAY.BUFFER to the LCD display. n is zero-based, and is clamped to a maximum of 1 less than LINES/DISPLAY. Writes CHARS/DISPLAY.LINE characters to the display. When finished, leaves the display cursor pointing at the first position in the line following n. For character displays, the cursor is blanked during the write to the display and is restored to its prior state after the update is complete, thus avoiding "flickering" of the cursor. The line# n follows the same rules explained in the description of BUFFER.POSITION: for a graphics-style display the line# n is interpreted differently depending on whether the display is being used in "text mode" or "graphics mode". In text mode, n corresponds to the character line#; in graphics mode, n corresponds to the pixel line#. Intermittently disables interrupts for up to 7 microseconds per byte.

Write_Extra_IO( byte -- )

Writes the specified byte to the extra IO port on the Keypad/Display Wildcard (1 = high, 0 = low). These eight digital I/O lines are arranged as a single byte comprising two nibbles of four lines each. The lower nibble named DIO_0 through DIO_3 is group-configurable as either inputs or outputs, and the upper nibble lines, DI_4 through DI_7, are always inputs. This routine will affect only those lines that are configured as outputs. See Set_Extra_IO_Direction and Read_Extra_IO. Implementation detail: Writes to the byte at offset 0x0D from the Wildcard base.

See also → Keypad/Display Wildcard
Compatible Controllers