TextdisplayKit Drivers
Detailed Description
Line based text output terminal interface on top of the DISPLAY device driver stack. See TextDisplay Library for more information.
TextDisplay Library
The source code of the TEXTDISPLAY module is implemented in kits/common/drivers/textdisplay.c and
textdisplay.h
.
Introduction
The TEXTDISPLAY library implements a line based text output terminal on top of the DISPLAY device driver stack. It exports a set of functions that enables the user to print text on any of the display devices that are available via the DISPLAY device driver interface. Additionally the retargettextdisplay module ( Retarget TextDisplay Module ) retargets the stdout interface to a textdisplay device in order for the user to print text by calling standard C language functions (like printf) that prints text to stdout.
TEXTDISPLAY Configuration.
This section contains a description of the configuration parameters of the TEXTDISPLAY Library.
In order to enable the TEXTDISPLAY module the user must define INCLUDE_TEXTDISPLAY_SUPPORT (typically in displayconfigapp.h).
The user can select one out of a few different fonts, and the display will be organized in a number of lines and columns to fit the maximum number of characters depending on the font size. Currently the available fonts are:
#define TEXTDISPLAY_FONT_6x8 Select a font which is 6 pixels wide and 8 pixels high, resulting in 21 column and 16 lines on a 128x128 display. #define TEXTDISPLAY_FONT_8x8 Select a font which is 8 pixels wide and 8 pixels high, resulting in 16 column and 16 lines on a 128x128 display. #define TEXTDISPLAY_NUMBER_FONT_16x20 Select a _NUMBERS_ONLY_ font which is 16 pixels wide and 20 pixels high, resulting in 8 column and 6 lines on a 128x128 display. Note that this font does not include letters. It includes only the number characters 0,1,2,3,4,5,6,7,8,9 and additionally the colon ':' sign. This font is used by the digital clock mode in the clock example on the Zero Gecko starting kit (EFM32ZG_STK3200).
The TEXTDISPLAY module may supports scroll mode which may be enabled via the input parameter to the TEXTDISPLAY_New function during initialization, or by defining RETARGETTEXTDISPLAY_SCROLL_MODE to 'true' which enables scroll mode when using the retargettextdisplay module to retarget stdout to a TEXTDISPLAY device.
The user can select whether the LINE FEED (LF) character should be automatically accompanied by a CARRIAGE RETURN (CR) in order to bring the cursor position to the leftmost column on the display when a LF is printed. This can be enabled via the input parameter to the TEXTDISPLAY_New function during initialization, or by defining RETARGETTEXTDISPLAY_LINE_FEED_MODE to 'true' which enables LF+CR when using the retargettextdisplay module to retarget stdout to a TEXTDISPLAY device.
The TEXTDISPLAY module supports some standard VT52/VT100 escape sequences in order to move the cursor around the screen without clearing the existing characters. Please refer to the
textdisplay.h
file for a list of supported escape sequence codes. The user must define INCLUDE_VIDEO_TERMINAL_ESCAPE_SEQUENCE_SUPPORT (typically in displayconfigapp.h) in order to include support for escape sequences.
TEXTDISPLAY Kit Configuration
This section lists and describes the configuration parameters defined to default values in kits/kit_name/config/textdisplayconfig.h. The user may need or want to override some of these configuration parameters in displayconfigapp.h.
#define TEXTDISPLAY_DEVICES_MAX Maximum number of text display devices the display module is configured to support. This number may be increased if the system includes more than one display device. #define TEXTDISPLAY_DEVICE_0_LINES (DISPLAY0_HEIGHT / FONT_HEIGHT) #define TEXTDISPLAY_DEVICE_0_COLUMNS (DISPLAY0_WIDTH / FONT_WIDTH) Specify the number of lines and columns of the textdisplay devices. The default values are the maximal possible and utilizes the full width and height of the display. The user should not increase the values above the maximal values, however the values may be reduced. These constants are used for static memory allocation in the textdisplay driver.
Data Structures |
|
struct | TEXTDISPLAY_Config_t |
Macros |
|
#define |
TEXTDISPLAY_EMSTATUS_ALREADY_INITIALIZED
(
TEXTDISPLAY_EMSTATUS_BASE
| 3)
|
#define |
TEXTDISPLAY_EMSTATUS_INVALID_PARAM
(
TEXTDISPLAY_EMSTATUS_BASE
| 1)
|
#define |
TEXTDISPLAY_EMSTATUS_NOT_ENOUGH_MEMORY
(
TEXTDISPLAY_EMSTATUS_BASE
| 5)
|
#define |
TEXTDISPLAY_EMSTATUS_NOT_INITIALIZED
(
TEXTDISPLAY_EMSTATUS_BASE
| 6)
|
#define |
TEXTDISPLAY_EMSTATUS_NOT_SUPPORTED
(
TEXTDISPLAY_EMSTATUS_BASE
| 4)
|
#define | TEXTDISPLAY_EMSTATUS_OK (0) |
#define |
TEXTDISPLAY_EMSTATUS_OUT_OF_RANGE
(
TEXTDISPLAY_EMSTATUS_BASE
| 2)
|
Typedefs |
|
typedef struct TEXTDISPLAY_Config_t | TEXTDISPLAY_Config_t |
typedef void * | TEXTDISPLAY_Handle_t |
Functions |
|
EMSTATUS | TEXTDISPLAY_Delete ( TEXTDISPLAY_Handle_t handle) |
Delete a text display device.
|
|
EMSTATUS | TEXTDISPLAY_LfToCrLf ( TEXTDISPLAY_Handle_t handle, bool on) |
Enable or disable LF to CR+LF conversion.
|
|
EMSTATUS | TEXTDISPLAY_New ( TEXTDISPLAY_Config_t *config, TEXTDISPLAY_Handle_t *handle) |
Create a new text display device.
|
|
EMSTATUS | TEXTDISPLAY_WriteChar ( TEXTDISPLAY_Handle_t handle, char c) |
Write a single character to a text display.
|
|
EMSTATUS | TEXTDISPLAY_WriteString ( TEXTDISPLAY_Handle_t handle, const char *str) |
Write a string of characters to a text display.
|
|
Macro Definition Documentation
#define TEXTDISPLAY_EMSTATUS_ALREADY_INITIALIZED (
TEXTDISPLAY_EMSTATUS_BASE
| 3)
|
Device is already initialized.
Definition at line
44
of file
textdisplay.h
.
#define TEXTDISPLAY_EMSTATUS_INVALID_PARAM (
TEXTDISPLAY_EMSTATUS_BASE
| 1)
|
Invalid parameter.
Definition at line
42
of file
textdisplay.h
.
Referenced by TEXTDISPLAY_Delete() .
#define TEXTDISPLAY_EMSTATUS_NOT_ENOUGH_MEMORY (
TEXTDISPLAY_EMSTATUS_BASE
| 5)
|
#define TEXTDISPLAY_EMSTATUS_NOT_INITIALIZED (
TEXTDISPLAY_EMSTATUS_BASE
| 6)
|
Device is not initialized.
Definition at line
47
of file
textdisplay.h
.
Referenced by RETARGET_WriteString() , TEXTDISPLAY_WriteChar() , and TEXTDISPLAY_WriteString() .
#define TEXTDISPLAY_EMSTATUS_NOT_SUPPORTED (
TEXTDISPLAY_EMSTATUS_BASE
| 4)
|
Feature/option not supported.
Definition at line
45
of file
textdisplay.h
.
#define TEXTDISPLAY_EMSTATUS_OK (0) |
EMSTATUS codes of the textdisplay module. Operation successful.
Definition at line
41
of file
textdisplay.h
.
Referenced by RETARGET_TextDisplayInit() , TEXTDISPLAY_Delete() , TEXTDISPLAY_LfToCrLf() , TEXTDISPLAY_New() , TEXTDISPLAY_WriteChar() , and TEXTDISPLAY_WriteString() .
#define TEXTDISPLAY_EMSTATUS_OUT_OF_RANGE (
TEXTDISPLAY_EMSTATUS_BASE
| 2)
|
Parameters out of range.
Definition at line
43
of file
textdisplay.h
.
Referenced by TEXTDISPLAY_New() .
Typedef Documentation
typedef struct TEXTDISPLAY_Config_t TEXTDISPLAY_Config_t |
Initialization data structure for text display devices.
typedef void* TEXTDISPLAY_Handle_t |
VT52/VT100 Escape Sequence codes supported by TEXTDISPLAY: Handle for text display device.
Definition at line
64
of file
textdisplay.h
.
Function Documentation
EMSTATUS TEXTDISPLAY_Delete | ( | TEXTDISPLAY_Handle_t |
handle
|
) |
Delete a text display device.
Delete a text display device and release all resources associataed with the text display device.
- Parameters
-
[in] handle
Handle to the text display device to delete.
- Returns
- EMSTATUS code of the operation.
Definition at line
312
of file
textdisplay.c
.
References TEXTDISPLAY_EMSTATUS_INVALID_PARAM , and TEXTDISPLAY_EMSTATUS_OK .
EMSTATUS TEXTDISPLAY_LfToCrLf | ( | TEXTDISPLAY_Handle_t |
handle,
|
bool |
on
|
||
) |
Enable or disable LF to CR+LF conversion.
- Parameters
-
[in] handle
Text display handle associated with the text display to write the character on. [in] on
If true, automatic LF to CRLF conversion will be enabled. If false, LF will only result in a line feed on the terminal.
- Returns
- EMSTATUS code of the operation.
Definition at line
348
of file
textdisplay.c
.
References TEXTDISPLAY_EMSTATUS_OK .
EMSTATUS TEXTDISPLAY_New | ( | TEXTDISPLAY_Config_t * |
config,
|
TEXTDISPLAY_Handle_t * |
handle
|
||
) |
Create a new text display device.
- Parameters
-
[in] config
Configuration data structure for the text display device to create. [out] handle
Pointer to text display handle which will be returned if the function is successful.
- Returns
- EMSTATUS code of the operation.
Definition at line
201
of file
textdisplay.c
.
References DISPLAY_ADDRESSING_BY_ROWS_ONLY , DISPLAY_DeviceGet() , DISPLAY_EMSTATUS_OK , TEXTDISPLAY_Config_t::displayDeviceNo , initialized , TEXTDISPLAY_Config_t::lfToCrLf , TEXTDISPLAY_Config_t::scrollEnable , TEXTDISPLAY_EMSTATUS_NOT_ENOUGH_MEMORY , TEXTDISPLAY_EMSTATUS_OK , and TEXTDISPLAY_EMSTATUS_OUT_OF_RANGE .
Referenced by RETARGET_TextDisplayInit() .
EMSTATUS TEXTDISPLAY_WriteChar | ( | TEXTDISPLAY_Handle_t |
handle,
|
char |
c
|
||
) |
Write a single character to a text display.
- Parameters
-
[in] handle
Text display handle associated with the text display to write the character on. [in] c
Character to write.
- Returns
- EMSTATUS code of the operation.
Definition at line
367
of file
textdisplay.c
.
References DISPLAY_ADDRESSING_BY_ROWS_ONLY , TEXTDISPLAY_EMSTATUS_NOT_INITIALIZED , and TEXTDISPLAY_EMSTATUS_OK .
Referenced by RETARGET_WriteChar() .
EMSTATUS TEXTDISPLAY_WriteString | ( | TEXTDISPLAY_Handle_t |
handle,
|
const char * |
str
|
||
) |
Write a string of characters to a text display.
- Parameters
-
[in] handle
Text display handle associated with the text display to write the character string on. [in] str
String to write.
- Returns
- EMSTATUS code of the operation.
Definition at line
429
of file
textdisplay.c
.
References DISPLAY_ADDRESSING_BY_ROWS_ONLY , TEXTDISPLAY_EMSTATUS_NOT_INITIALIZED , and TEXTDISPLAY_EMSTATUS_OK .
Referenced by RETARGET_WriteString() .