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

EMSTATUS	TEXTDISPLAY_LfToCrLf (TEXTDISPLAY_Handle_t handle, bool on)
	Enable or disable LF to CR+LF conversion. More...

EMSTATUS	TEXTDISPLAY_New (TEXTDISPLAY_Config_t config, TEXTDISPLAY_Handle_t handle)
	Create a new text display device. More...

EMSTATUS	TEXTDISPLAY_WriteChar (TEXTDISPLAY_Handle_t handle, char c)
	Write a single character to a text display. More...

EMSTATUS	TEXTDISPLAY_WriteString (TEXTDISPLAY_Handle_t handle, const char *str)
	Write a string of characters to a text display. More...

Macro Definition Documentation

#define TEXTDISPLAY_EMSTATUS_ALREADY_INITIALIZED (TEXTDISPLAY_EMSTATUS_BASE | 3)

Device is already initialized.

Definition at line 46 of file textdisplay.h.

#define TEXTDISPLAY_EMSTATUS_INVALID_PARAM (TEXTDISPLAY_EMSTATUS_BASE | 1)

Invalid parameter.

Definition at line 44 of file textdisplay.h.

Referenced by TEXTDISPLAY_Delete().

#define TEXTDISPLAY_EMSTATUS_NOT_ENOUGH_MEMORY (TEXTDISPLAY_EMSTATUS_BASE | 5)

Not enough memory.

Definition at line 48 of file textdisplay.h.

Referenced by TEXTDISPLAY_New().

#define TEXTDISPLAY_EMSTATUS_NOT_INITIALIZED (TEXTDISPLAY_EMSTATUS_BASE | 6)

Device is not initialized.

Definition at line 49 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 47 of file textdisplay.h.

#define TEXTDISPLAY_EMSTATUS_OK (0)

EMSTATUS codes of the textdisplay module. Operation successful.

Definition at line 43 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 45 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 68 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 322 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 361 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.