PtTerminalCharset_t, PtTerminalCharsets_t

Character sets used by PtTerminal

Synopsis:

typedef struct {
    const wchar_t *table;
    unsigned char first, last;
    ...
    } PtTerminalCharset_t;

typedef struct {
    PtTerminalCharset_t const *AnsiCharset;
    PtTerminalCharset_t const *InternalCharset;
    PtTerminalCharset_t const *FontTranslation;
    ...
    } PtTerminalCharsets_t;

Description:

The PtTerminalCharset_t and PtTerminalCharsets_t structures define character sets used internally and externally by PtTerminal.

Both structures have some undocumented members at the end, reserved for future extensions. To be safe, make sure that they're filled with zeros. The order of the documented members will stay the same - it's safe to initialize these structures statically.

A PtTerminalCharset_t structure defines an 8-bit character set by defining its mapping to Unicode. This is how this mapping can be expressed in C:

wchar_t unicode_value( unsigned char ch, 
                       PtTerminalCharset_t const *cs ) {
wchar_t result;

if ( ch < 0x80 )
   return ch; /* ch is an ASCII character */
else {
   if ( ch >= cs->first && ch <= cs->last
        && ( result = cs->table[ cs - cs->first ] ) != L'\0' )
      /* ch is mapped to a Unicode value */
      return result;
   else
      /* ch is an illegal value */
      return NO_MAPPING_DEFINED;
   }
}

If a character set contains "illegal values", they're displayed as blanks and are never generated from a key event. But in general, it's a good idea to avoid having illegal values in a character set - preferably, the internal character set should define all values from 0x80 to 0xFF and the ANSI character set should define all values from 0xA0 to 0xFF.

You can set AnsiCharset or InternalCharset (or both) to NULL; the function then uses the defaults (8859-1 for AnsiCharset and PC character set for InternalCharset). It's also possible to get to the actual tables that define the defaults by calling PtTerminalDefaultCharsets():

const PtTerminalCharsets_t *PtTerminalDefaultCharsets( void );

The FontTranslation defines the mapping from the internal character set to whatever character set your Photon font is using. In other words, if FontTranslation isn't NULL, PtTerminal uses the 16-bit code returned by:

unicode_value( internal_char, FontTranslation )

to display the 8-bit internal code internal_char. Note that if you want the widget to use Unicode, FontTranslation should point to the same character set as InternalCharset.

If FontTranslation is NULL, the font is assumed to be compatible with the internal character set, and no mapping is used.

Classification:

Photon

See also:

PtTerminal, PtTerminalDefaultCharsets():