PtTerminalCharset_t, PtTerminalCharsets_t

Character sets used by PtTerminal

Synopsis:

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

typedef struct {
    unsigned short from, to;
    } PtTerminalCharSubst_t;

typedef struct {
    PtTerminalCharset_t const *AnsiCharset;
    PtTerminalCharset_t const *InternalCharset;
    PtTerminalCharset_t const *FontTranslation;
    PtTerminalCharSubst_t const *Subst;
    unsigned short NumSubst;
    ...
    } 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.

The Subst field points to an array that lists character substitutions that the widget uses when a character is missing from the character set that it needs to be translated to. The array must be sorted with the respect to the from field. NumSubst defines the length of the array.

The situations where the substitutions are performed are:

• When the widget receives a key event containing a Unicode symbol that doesn't exist in the current text-mode character set (i.e. either the ANSI character set or the internal character set, depending on the current terminal emulation), the widget searches the Subst array for an entry where from is the character in the event and to is a character that exists in the text-mode character set. If such an entry exists, the to character is used instead of the symbol in the event. If multiple matching entries exist in the table, the first one is used. If none exists, the event doesn't generate any terminal input.
• In the ANSI mode, characters written to the terminal must be converted from the ANSI character set to the internal character set before they can be displayed. If the ANSI character set contains characters that the internal character set doesn't contain, the Subst array is searched for a replacement character. If none is found, the character is displayed as a space.

Classification:

Photon

See also:

PtTerminal, PtTerminalDefaultCharsets()