PtTerminal

A window that emulates a character-mode terminal

Class hierarchy:

PtWidget --> PtBasic --> PtContainer --> PtTerminal

For more information, see the diagram of the widget hierarchy.

PhAB icon:

Public header:

<photon/PtTerm.h>

Description:

The PtTerminal class provides a text window emulating a character terminal.

A PtTerminal widget.

Characters can be sent to the terminal with the PtTerminalPutc(), PtTerminalPut() and PtTerminalPuts() functions, and keyboard input to the terminal is available with the Pt_CB_TERM_INPUT callback.

Other convenience functions and callbacks support the following kinds of user interaction:

• resizing the terminal window
• changing the displayed font
• scrolling
• other activities permitted through escape sequences. For information about specific escape sequences, see Dev.con and Dev.ansi in the QNX Utilities Reference.

PtTerminal uses some Ctrl -Alt combinations for cutting and pasting, changing font sizes, and so on, but all Alt-key combinations that are defined for text mode are passed to your text-mode application, provided that the window manager lets PtTerminal see them. The window manager intercepts certain Alt-key combinations unless you set Ph_WM_STATE_ISALTKEY in the Pt_ARG_WINDOW_STATE resource of the PtWindow that contains the PtTerminal.

PtTerminal and PtTty

The main difference between PtTerminal and PtTty is that PtTerminal doesn't do any I/O for you. The only way to display characters in a PtTerminal is by giving them to one of the PtTerminalPut*() functions. Similarly, the only thing PtTerminal does with Photon input is translate function keys into text-mode compatible escape sequences and give the result to your Pt_CB_TERM_INPUT callback.

PtTty adds device I/O to that. The code that opens a pty, reads characters from it, and gives those characters to PtTerminalPut() is part of PtTty. Similarly, PtTty attaches a Pt_CB_TERM_INPUT callback that writes Photon keyboard input (translated by PtTerminal to text-mode compatible format) to the pty.

Another responsibility of PtTty is spawning a command for you and invoking the Pt_CB_TTY_TERMINATED callbacks when the command terminates.

Fonts

Application programs set the Pt_ARG_TERM_FONT resource to set an explicit font name or the Pt_ARG_TERM_FONT_INDEX resource to choose a font from the list of supported fonts, Pt_ARG_TERM_FONT_LIST.

If the Pt_TERM_KBFONT bit is set in Pt_ARG_TERM_RESIZE_FL, the user can select a font using the keyboard:

• Pressing Ctrl -Alt -< or Ctrl -Alt -[ decrements the value of Pt_ARG_TERM_FONT_INDEX by one (unless it's already at 0) or sets it to the maximum value (if the current value is -1).
• Pressing Ctrl -Alt -> or Ctrl -Alt -] increments the value of Pt_ARG_TERM_FONT_INDEX by one (unless it's already at the maximum value).

The Pt_TERM_KBFORCE flag affects any resizing that occurs when the above keychords are used:

• If this flag isn't set, the above keystrokes simply set the Pt_ARG_TERM_FONT_INDEX resource.
• If the flag is set, the [ and ] keys adjust the window size to keep the terminal size (rows/columns) while the < and > keys attempt to adjust the terminal size within the current window size.

If the Pt_TERM_OPFONT flag is set, the font can be changed by escape sequences:

• If the font is set using the Pt_ARG_TERM_FONT resource and the new font name is equal to one of the names on the current font list, the Pt_ARG_TERM_FONT_INDEX resource is set to the index of that list item. When the Pt_ARG_TERM_FONT_LIST resource is set, the widget also attempts to find the current font name on the list and set the index.
• If the font list contains an invalid font name, the Pt_ARG_TERM_FONT_INDEX resource can be set to its index but the current font isn't changed.

Character sets

PtTerminal uses two 8-bit character sets:

Internal character set

What the widget uses to store characters internally. This character set is also used in the QNX mode as the "text-mode character set" (i.e. anything that you pass to PtTerminalPut() is assumed to use this character set, and Photon key events get translated to this character set before being passed to the Pt_CB_TERM_INPUT callback).

In the ANSI mode, the internal character set can be used for display by setting one of the G0...G3 character sets to "the PC character set." The escape sequences that do it are:

ESC ( U 
ESC ) U 
ESC * U
ESC + U
    

See the documentation for Dev.ansi in the QNX Utilities Reference.

ANSI character set

What's used in the ANSI mode. It's the default setting for the G2 character set (which is used by default for characters above 0x9F). It's also the character set to which Photon key events get translated in the ANSI mode.

By default, the internal character set is the PC character set ("IBM code page 437") and the ANSI character set is ISO 8859-1. PtTerminal lets you choose any 8-bit character sets - the only requirement is that they must be supersets of ASCII: PtTerminal translates only codes above 0x7F.

By default, PtTerminal assumes that the Photon font used for display is encoded using the internal character set (in particular, all the terminal fonts shipped with Photon use the PC character set rather than Unicode). The application can define an additional mapping; for example, it's possible to use a Unicode font to display any character sets in PtTerminal.

The Pt_ARG_TERM_CHARSETS resource stores the current character sets.

Resource changes and function reentrancy

When the PtTerminalPut*() functions parse the output stream, certain escape sequences contained in the stream may cause resource changes that invoke callback functions. The callback functions shouldn't call any of the PtTerminalPut*() functions to output text to the same terminal widget that invoked the callback because the protocol engine function isn't reentrant. Recursion is allowed, but only when each of the nested calls outputs data to a different terminal widget. Otherwise, the PtTerminalPut*() functions return -1 to indicate an illegal call.

Geometry

There are four groups of resources that affect a terminal widget's geometry:

Dimensions

Pt_ARG_DIM and Pt_ARG_AREA (see PtWidget)

Margins

Pt_ARG_MARGIN_HEIGHT, Pt_ARG_MARGIN_WIDTH (see PtBasic), and Pt_ARG_TERM_MARGINS

Terminal size

Pt_ARG_TERM_SIZE, Pt_ARG_TERM_ROWS, and Pt_ARG_TERM_COLS

Font

Pt_ARG_TERM_FONT and Pt_ARG_TERM_FONT_INDEX

Resizing

A widget's dimensions can be calculated as long as terminal size, font size, and margins are known. Thus, whenever one of these resources is changed, another resource - or sometimes even two resources - must be adjusted too.

The return value of the function attached to the Pt_ARG_TERM_RESIZE_FUN resource (known as the resize function) determines how the widget is resized. The function is called with two output arguments: the first is a pointer to a string that describes which resource is changing and how, and the second is the value of widget's Pt_ARG_TERM_RESIZE_STR resource.

Each character in the string has a specific meaning. The first character is a resource identifier that describes which resource is changing:

D (dimension)

Change Pt_ARG_DIM and Pt_ARG_AREA.

M (margin)

Change Pt_ARG_MARGIN_WIDTH and Pt_ARG_MARGIN_HEIGHT.

S (size)

Change Pt_ARG_TERM_SIZE, Pt_ARG_TERM_ROWS, and Pt_ARG_TERM_COLS.

F (font)

Change Pt_ARG_TERM_FONT.

The next series of characters provide the details, starting with the character x or y to specify direction (horizontal or vertical). The next character can be one of the following:

Additional characters can be given to indicate resources that aren't sufficient alone to adjust the widget because these resources have limited values. An m means that the adjustment must involve a resource other than the margins, and an s means that the adjustment must involve a resource other than the terminal size.

Adjusting after a resize

The result of the "resize function" is a string specifying the order of the resources used in the adjustment process. The adjustment can be performed in both directions, but if the original resource change doesn't affect horizontal or vertical dimensions, only the affected direction is adjusted.

The resize function may either return a static string or use the buffer passed in the first argument. The buffer size is at least 10 bytes. A NULL pointer is equivalent to an empty string.

Each character in the adjustment string has a specific meaning:

x

Perform a horizontal adjustment on the following characters.

y

Perform a vertical adjustment on the following characters.

d

Adjust the Pt_ARG_DIM resource.

s

Adjust the Pt_ARG_TERM_SIZE resource.

m

Adjust the Pt_ARG_MARGIN_WIDTH and/or Pt_ARG_MARGIN_HEIGHT resource and copy the new value to the Pt_ARG_TERM_MARGINS resource.

M

Adjust the Pt_ARG_TERM_MARGINS resource.

For example, xsym would adjust the number of columns (xs) and the margin height (ym).

Before any adjustments specified by the string are done, Pt_ARG_TERM_MARGINS resource is reset to the Pt_ARG_MARGIN_HEIGHT and/or Pt_ARG_MARGIN_WIDTH values.

Adjusting the dimension is always successful, while adjusting size or margin isn't always sufficient - size is limited and must be a multiple of the font size, and margin must be nonnegative.

After the adjustments specified by the string are done, the dimension is adjusted to make sure that the new values are coherent. Thus, specifying a d is always superfluous and specifying anything after a d has no effect unless it specifies a different direction.

The default resize function

The default function uses only the resource identifier (i.e. D, M, S or F) given in the first argument. The function assumes that the Pt_ARG_TERM_RESIZE_STR resource string given in the second argument consists of segments delimited by colons.

Each of the segments consists of a list of letters that define resources, an equality symbol (=), and the string that's returned if the resource identifier matches one of the letters in the list.

The default value of the Pt_ARG_TERM_RESIZE_STR resource is D=sM:M=s, which means:

• If the dimension has changed (D), sM is returned. The size and margin of the widget are adjusted. If the sizes couldn't be matched (that is, the new dimensions are smaller than the minimum size), the dimension is readjusted.
• If a margin is changed (M), s is returned, and the widget attempts to adjust the appropriate size component (rows or columns), after which the dimension is adjusted to fit the exact margin width or height.
• If font (F) or size (S) is changed, the corresponding resource identifier isn't found on the default list and an empty string is returned. The terminal's margin is set according to the margin width and height resources, and then the dimension is recalculated.

Size limits

Other resources that may affect geometry are the size limits:

• Pt_ARG_TERM_MINSIZE
• Pt_ARG_TERM_MINROWS
• Pt_ARG_TERM_MINCOLS
• Pt_ARG_TERM_MAXSIZE
• Pt_ARG_TERM_MAXROWS
• Pt_ARG_TERM_MAXCOLS

When a limit is being set to a value that makes the current size invalid, the current size is adjusted. If a minimum is set to a value larger than the corresponding maximum, then both the maximum and the current size are also set to this value.

The opposite is also true: if a maximum is changed, the corresponding minimum may be adjusted. This means that if you want to set the limits and size to arbitrary values regardless of their current values, the limits should be set before the size.

The minimum size (together with font and margins) determines also minimal values for the Pt_ARG_DIM resource. There is no upper limit for the dimensions because there is no upper limit for the Pt_ARG_TERM_MARGINS resource.

Console emulation

A PtSetResources() call for the Pt_ARG_TERM_CONSOLE resource works in a manner similar to the console_write() function.

First, the application should fill a PtTerminalConsoleWrite_t structure with data corresponding to arguments of the console_write() function. The pointer to the structure is the argument of the PtSetArg() macro. The PtSetResources() function transfers actual screen data from the buffer given by the application to the widget's screen buffer. Then a damage event is generated in order to display the new data. The function doesn't check whether offset and length given by the application don't exceed the size of the buffer.

A PtGetResources() call for the Pt_ARG_TERM_CONSOLE resource directly returns a pointer to the buffer. If the application wishes to get the contents of a specific fragment of the screen, it must calculate the offset to the desired position in the buffer and copy the data.

Color coding

The Pt_ARG_TERM_COLOR_TABLE resource is an array used by the widget for mapping color numbers into Photon PgColor_t color values. Color numbers are indexes into this array. The default array has 16 elements corresponding to 16 standard CGA colors.

The Pt_ARG_FILL_COLOR (see PtBasic) defines the color of the margins.

The background color of the terminal defaults to black - or whatever the Pt_ARG_TERM_COLOR_TABLE resource defines as entry 0. If you want a different background color, you can either change the color table or set the background color by sending appropriate escape sequences to the terminal using PtTerminalPut() The latter is probably safer if the widget is a PtTty that will be running arbitrary programs in it; programs that use color might look odd if the colors in the color table differ from the default values too much.

Drawing and scrolling

The Pt_ARG_TERM_DRAW_MODES resource defines the widget's scrolling capability.

Scrolling optimization

If characters are given to the PtTerminalPut() function in a large portion that consists of many lines that scroll through the terminal, the widget may attempt to optimize drawing speed.

Instead of blitting h-1 lines (where h is the height of the terminal in lines) and drawing the bottom line on each scroll, the widget blits h-n lines (if h-n is positive) and draws min(h,n) lines every n scrolls.

The limit for the actual value of n is determined by the Pt_ARG_BANDWIDTH_THRESHOLD (see PtBasic), Pt_ARG_TERM_SCROLL, and Pt_ARG_TERM_DRAW_MODES resources and by the current graphics bandwidth (see PhQuerySystemInfo() in the Photon Library Reference). If the connection is slow and the Pt_TERM_SCROLL_NOSPEEDCHK bit in Pt_ARG_TERM_CURSOR_FLAGS is clear, there's no limit for n. Otherwise, the maximal value of n is the value of the Pt_ARG_TERM_SCROLL resource.

New resources:

Pt_ARG_TERM_APP

A structure containing the application window state, which is needed by the protocol engine (see the Pt_CB_TERM_APP callback). This structure also contains some other information that can be used by a terminal emulator, such as the window title, size, and position.

The PtTerminalAppState_t structure is defined as:

typedef struct Pt_terminal_app_state {
    struct PtTerminal_app_state_bins {
        /* Binary part - memcmp can be used for comparing */
        unsigned version;
        PhArea_t area;
        PtTerminalRowCol_t size;
        unsigned iconic: 1, infront: 1;
        }
            b;
    /* Strings - guaranteed to never contain garbage after '\0' */
    char title[ Pt_TERM_WSTRING_MAX + 1 ];
    char l_msg[ Pt_TERM_WSTRING_MAX + 1 ];
    char icon[ Pt_TERM_WSTRING_MAX + 1 ];
    char reserved;
    }
        PtTerminalAppState_t;

Most of the members of this structure are present mainly for compatibility with QNX Windows. A text-mode program written for QNX Windows might use certain special escape sequences to set those values, and other special escape sequences to query those values. In pterm, the values are preserved (so your text-mode program sees the expected responses to escape sequences), but otherwise ignored because their original meaning is too specific to QNX Windows). The only exception is title - pterm uses it to set its window title.

If you have a text-mode program that needs more compatibility with the QNX Windows terminal emulator than pterm offers, you'll need to use the Pt_ARG_TERM_APP resource and the Pt_CB_TERM_APP callback.

The members are:

b.version

The version number, which is initialized to 100, can be queried by an escape sequence. It's useful if you want to write a terminal emulator that recognizes additional escape sequences and you want your text-mode programs to be able to detect whether they're running in a pterm (version=100) or in your emulator (version=something else).

b.area

The area of the PtTerminal widget.

b.size

The terminal's size, in rows and columns.

b.iconic

A bit that indicates whether or not the application is iconified (minimized).

b.infront

A bit that indicates whether or not the application is in front of all other windows.

title

The first part of the window's title.

l_msg

The second part of the window's title.

icon

The string that QNX Windows would display on the icon instead of the window title.

Pt_ARG_TERM_CHARSETS

This resource handles the character set translation. It's a pointer to translation tables stored in a PtTerminalCsXlatData_t structure. The contents of the structure aren't defined in a public header - the only way to create a PtTerminalCsXlatData_t structure is by calling PtTerminalCreateCsXlat().

If you set Pt_ARG_TERM_CHARSETS to NULL, the widget calls PtTerminalCreateCsXlat() to create its own copy of the default translation tables. This copy is freed when you destroy the widget or set its Pt_ARG_TERM_CHARSETS resource to a non-NULL value.

PtTerminalCreateCsXlat() doesn't make a copy of the PtTerminalCharsets_t structure passed to it, and PtTerminal doesn't make a copy of the PtTerminalCsXlatData_t structure when you set Pt_ARG_TERM_CHARSETS. Don't free these structures until they're no longer needed by any widget. The PtTerminalCsXlatData_t structure created by PtTerminalCreateCsXlat() is placed in a single allocated block of memory. When it's no longer needed, you can simply free() it.

Pt_ARG_TERM_COLOR_MODE

A set of pointers to conversion functions, used internally by the widget.

Pt_ARG_TERM_COLOR_TABLE

Color table used for display. Converts color numbers used internally to actual Photon color values. Color numbers are indexes into this array. The default array has 16 elements corresponding to 16 standard CGA colors:

Pt_ARG_TERM_COLS

The number of character columns.

Pt_ARG_TERM_CONSOLE

This resource can be used for accessing the "video memory" of the widget. For more information, see the "Console emulation" part of the "Description" section above.

Pt_ARG_TERM_CUR_COL

The column number of cursor position.

Pt_ARG_TERM_CUR_POS

The cursor position. The PtTerminalRowCol_t structure contains the following members:

• short r
• short c

Pt_ARG_TERM_CUR_ROW

The line number of cursor position.

Pt_ARG_TERM_CURSOR_FLAGS

Flags affecting the cursor timer. Possible values are:

• Pt_TERM_CURSOR_ON_FOCUS - the cursor blinks when the widget has focus.
• Pt_TERM_CURSOR_ALWAYS - the cursor always blinks.
• Pt_TERM_CURSOR_NEVER (zero) - the cursor never blinks.
• Pt_TERM_CURSOR_TIMER - the timer is activated even if not needed. This may be useful for getting a raw callback periodically. Note that this timer only runs when the widget is realized.
• Pt_TERM_CURSOR_NOSPEEDCHK - if this flag isn't set, the cursor won't blink if the connection to Photon is slow. See also Pt_ARG_BANDWIDTH_THRESHOLD.

Pt_ARG_TERM_DRAW_MODES

The flags that determine scrolling optimization.

• Pt_TERM_SCROLL_NOBLIT - always redraw instead of blitting.
• Pt_TERM_SCROLL_NOHWCHK - attempt to blit even if blitting isn't supported by hardware.
• Pt_TERM_SCROLL_RFSH - redraw the screen on the first scroll even if the PhBlit() function won't be used.
• Pt_TERM_SCROLL_NOVISCHK - always assume that the widget isn't clipped or obscured by other widgets. (Normally, the widget checks whether it isn't obscured or clipped by other widgets in such a way that the PhBlit() function would move parts of another widget.)
• Pt_TERM_SCROLL_NOSPEEDCHK - don't check the bandwidth. If this flag isn't set and the bandwidth isn't greater than the value of the Pt_ARG_BANDWIDTH_THRESHOLD resource, the widget behaves as if the Pt_TERM_SCROLL_NOBLIT, Pt_TERM_SCROLL_NOHWCHK, and Pt_TERM_SCROLL_RFSH flags are clear and the Pt_ARG_TERM_SCROLL resource has a huge value.

For more information, see the "Drawing and scrolling" part of the "Description" section above.

Pt_ARG_TERM_FONT

The name of the font used for display. For more information, see the "Fonts" part of the "Description" section above.

PtTerminal works only with fixed-width fonts. It ignores any attempts to change to a proportional font.

Pt_ARG_TERM_FONT_INDEX

Position of the current font on the font list, or -1 if the current font isn't on the list. Can be used to choose a font from the list, but cannot be explicitly set to -1.

Pt_ARG_TERM_FONT_LIST

List of fonts (an array of pointers to strings).

When this resource is being set, the meaning of the value argument of the PtSetArg() macro depends on whether the len argument is zero or nonzero:

• If len is nonzero, value should be a pointer to an array of pointers to font names, and len should be the number of pointers in the array. The widget replaces the current font list with a copy of the given list.
• If len is zero, value should be either NULL or a pointer to string. If value is NULL, the font list is removed. Otherwise, the given string is appended to the current list. For more information, see the "Fonts" part of the "Description" section above.

Pt_ARG_TERM_FONT_SIZE (read-only)

The dimensions of the font used for display.

Pt_ARG_TERM_MARGINS (read-only)

The actual width and height of the widget's margins. These values are equal to or greater than values of Pt_ARG_MARGIN_WIDTH and Pt_ARG_MARGIN_HEIGHT resources. For more information, see the "Geometry" part of the "Description" section above.

Pt_ARG_TERM_MAXCOLS

The maximum number of character columns.

Pt_ARG_TERM_MAXROWS

The maximum number of character rows.

Pt_ARG_TERM_MAXSIZE

Maximum screen size. The PtTerminalRowCol_t structure contains the following members:

• short r
• short c

Pt_ARG_TERM_MINCOLS

The minimum number of character columns.

Pt_ARG_TERM_MINROWS

The minimum number of character rows.

Pt_ARG_TERM_MINSIZE

Minimum screen size. The PtTerminalRowCol_t structure contains the following members:

• short r
• short c

Pt_ARG_TERM_OPTIONS

A set of flags that can be set or cleared by escape sequences. The flags are numbered from 1 to 32 (see <photon/PtTerm.h>). Some of them are handled by the widget, some others can be handled by the application.

Pt_ARG_TERM_OPTMASK

A set of bits that correspond to those in Pt_ARG_TERM_OPTIONS. Clearing a bit in Pt_ARG_TERM_OPTMASK disables the escape sequence for the corresponding bit in Pt_ARG_TERM_OPTIONS

Pt_ARG_TERM_PROTOCOL

The protocol:

0

QNX4

1

ANSI

Pt_ARG_TERM_RESIZE_FL

Bit flags that affect terminal widget's resizing. Valid values are:

• Pt_TERM_OPFONT - FONT can be set with escape sequences.
• Pt_TERM_KBFONT - FONT can be set with keyboard.
• Pt_TERM_KBFORCE - when FONT is set with keyboard, keep the widget's SIZE or DIM (depending on the key sequence).
• Pt_TERM_ANCHOR_PARENT_WIDTH - resize the parent widget's width if the terminal's right edge is anchored to the parent's right edge.
• Pt_TERM_ANCHOR_PARENT_HEIGHT - resize the parent widget's height if the terminal's bottom edge is anchored to the parent's bottom edge.
• Pt_TERM_ANCHOR_WINDOWS_ONLY - don't resize the parent unless it's a window.

Pt_ARG_TERM_RESIZE_FUN

Pointer to a function used in geometry adjustments. The prototype is:

const char*(*)(char*, const char*)
  

For more information, see the "Geometry" part of the "Description" section above.

Pt_ARG_TERM_RESIZE_STR

A hint for the function used in geometry adjustments. For more information, see the "Geometry" part of the "Description" section above.

Pt_ARG_TERM_ROWS

The number of character rows.

Pt_ARG_TERM_SCRLBK_COUNT

The current number of lines saved in the scrollback buffer.

Pt_ARG_TERM_SCRLBK_LIMIT

The maximum of number of lines saved in the scrollback buffer.

Pt_ARG_TERM_SCRLBK_POS

The current position in the scrollback buffer (reset to zero on any output, including the Pt_ARG_TERM_CONSOLE resource).

Pt_ARG_TERM_SCROLL

The maximum number of scrolls that will be delayed. For more information, see the "Scrolling optimization" part of the "Description" section above.

Pt_ARG_TERM_SELECTION

The PtTerminalSelection_t structure contains at least the following members:

unsigned char type;
unsigned char old_type;
unsigned short flags;
PtTerminalRowCol_t first, last;

where:

type

Can be one of:

• Pt_TERM_SELECTION_NONE - no selection.
• Pt_TERM_SELECTION_BLOCK - a block is selected.
• Pt_TERM_SELECTION_STREAM - a stream is selected.

old_type

The last value of type that differed from Pt_TERM_SELECTION_NONE.

flags

Valid flags are:

• Pt_TERM_SELECTION_ALWAYS - mouse always selects text.
• Pt_TERM_SELECTION_NEVER - mouse never selects text.
• Pt_TERM_SELECTING (read_only) - something is being selected.

The following flags aren't stored in the widget but they tell the widget that the corresponding member of the structure shouldn't be modified:

• Pt_TERM_SELECTION_TYPE_KEEP - don't modify type.
• Pt_TERM_SELECTION_FIRST_KEEP - don't modify first.
• Pt_TERM_SELECTION_LAST_KEEP - don't modify last.
• Pt_TERM_SELECTION_FLAGS_KEEP - don't modify flags.

first, last

Two positions that define the selected area. If selected by the mouse, first is the position of the press and last is the position of the release. The PtTerminalRowCol_t structure contains the following members:

• short r
• short c

Pt_ARG_TERM_SIZE

Screen size, measured in characters. The PtTerminalRowCol_t structure contains the following members:

• short r
• short c

Pt_ARG_TERM_VISUAL_BELL

Time, in milliseconds, of the screen flash when the ASCII BEL character ( Ctrl -G ) is received.

Pt_CB_TERM_APP

A list of callbacks invoked whenever the Pt_ARG_TERM_APP resource changes, or a private escape sequence is received.

Each callback is passed a PtCallbackInfo_t structure that contains at least the following members:

reason

Pt_CB_TERM_APP

reason_subtype

The character or number defining the type of escape sequence.

event

NULL

cbdata

Either a NULL pointer, or the string contained in the escape sequence.

There are four general sources of the Pt_CB_TERM_APP callback. They can be recognized by the values of the reason_subtype and cbdata fields:

reason_subtype=0, cbdata=NULL

A change of terminal's size or font. Before issuing this callback, the widget sets the area and size fields of the Pt_ARG_TERM_APP resource to the values of the widget's Pt_ARG_AREA and Pt_ARG_TERM_SIZE resources so that even if a terminal emulator program doesn't modify the Pt_ARG_TERM_APP resource, the terminal responds properly to escape sequences that query terminal parameters.

reason_subtype=0, cbdata=""

An explicit change of the Pt_ARG_TERM_APP resource.

reason_subtype=nonzero, cbdata=NULL

An escape sequence that set some of the data stored in the "binary" part of the Pt_ARG_TERM_APP resource. The reason_subtype field indicates the first parameter of the escape sequence.

reason_subtype=nonzero, cbdata=string

An escape sequence that changed one of the strings stored in the Pt_ARG_TERM_APP resource.

The value of the reason_subtype field is the ASCII code of the character that indicates the escape sequence type, and the cbdata field points to the <string>.

These callbacks should return Pt_CONTINUE.

Pt_CB_TERM_FONT

A list of callbacks invoked after the font is changed. Each callback is passed a PtCallbackInfo_t structure that contains at least the following members:

reason

Pt_CB_TERM_FONT

event

NULL

cbdata

A pointer to a PtTerminalFontChange_t structure that contains at least the following members:

const char * old_font;

Defines the previous font.

const char * new_font;

Defines the new font.

These callbacks should return Pt_CONTINUE.

Pt_CB_TERM_INPUT

A list of callbacks invoked when keyboard or mouse input is delivered to the widget. Each callback is passed a PtCallbackInfo_t structure that contains at least the following members:

reason

Pt_CB_TERM_INPUT

reason_subtype

Can be one of:

• Pt_TERM_KEYBOARD_INPUT - for key events other than the Break key.
• Pt_TERM_MOUSE_INPUT - for mouse events.
• Pt_TERM_CTRLBRK_INPUT - for the Break key.
• Pt_TERM_PROTOCOL_INPUT - for responses to an escape sequence.
• Pt_TERM_PASTE_INPUT - for pasting from the clipboard.
• Pt_TERM_PASTE_NF_INPUT - for pasting from the clipboard.

event

A pointer to a PhEvent_t structure or NULL if the characters are a reply to an escape sequence rather than reaction to a keyboard or mouse event.

cbdata

A pointer to a PtTerminalInput_t structure that contains at least the following members:

unsigned short length;

The number of characters the key generates (may be zero if a key was pressed that doesn't generate characters).

const char * string;

A pointer to the buffer containing the characters.

PtTerminalRowCol_t position;

In the case of a pointer event, the current mouse position. In all other cases, the current cursor position. The PtTerminalRowCol_t structure contains the following members:

• short r
• short c

The widget issues this callback on every keystroke unless both Ctrl and Alt modifiers are pressed.

When text is being pasted from the clipboard, the callback subtype is set to Pt_TERM_PASTE_INPUT if the buffer has been allocated with the malloc() function. A callback function can take over the responsibility for freeing the buffer by changing the subtype to Pt_TERM_PASTE_NF_INPUT.

These callbacks should return Pt_CONTINUE.

Pt_CB_TERM_OPTIONS

A list of callbacks invoked whenever the Pt_ARG_TERM_OPTIONS resource changes. Each callback is passed a PtCallbackInfo_t structure that contains at least the following members:

reason

Pt_CB_TERM_OPTIONS

reason_subtype

0 if options have been changed via widget resources, or 1 if options have been changed by an escape sequence.

event

NULL

cbdata

A pointer to a PtTerminalOptionChange_t structure that contains at least the following members:

unsigned long old_opts;

The previous value of the options.

unsigned long new_opts;

The new value of the options.

These callbacks should return Pt_CONTINUE.

Pt_CB_TERM_RESIZE

A list of callbacks invoked when the terminal is about to change its size (number of rows and/or columns).

Each callback is passed a PtCallbackInfo_t structure that contains at least the following members:

reason

Pt_CB_TERM_RESIZE

event

NULL

cbdata

A pointer to a PtTerminalSizeChange_t structure that contains at least the following members:

PtTerminalRowCol_t old_size;

Current size of the terminal.

PtTerminalRowCol_t new_size;

New size.

The PtTerminalRowCol_t structure contains the following members:

• short r
• short c

This callback is issued whenever one of the Pt_ARG_TERM_SIZE, Pt_ARG_TERM_ROWS, or Pt_ARG_TERM_COLS resources is set, even if the new value is equal to the old value.

However, if a PtSetResources() call is issued with invalid size values (outside of limits defined by Pt_ARG_TERM_MINSIZE and Pt_ARG_TERM_MAXSIZE resources), the new size is validated before issuing the callback.

These callbacks should return Pt_CONTINUE.

Pt_CB_TERM_RESIZED

A list of callbacks invoked after the size is changed.

Each callback is passed a PtCallbackInfo_t structure that contains at least the following members:

reason

Pt_CB_TERM_RESIZED

event

NULL

cbdata

A pointer to a PtTerminalSizeChange_t structure that contains at least the following members:

PtTerminalRowCol_t old_size;

Previous size of the terminal.

PtTerminalRowCol_t new_size;

Current size.

The PtTerminalRowCol_t structure contains the following members:

• short r
• short c

This callback is issued whenever one of the Pt_ARG_TERM_SIZE, Pt_ARG_TERM_ROWS, or Pt_ARG_TERM_COLS resources is set, even if the new value is equal to the old value.

After an unsuccessful attempt to resize the terminal, the callback is issued with cbdata set to NULL.

This callback should return Pt_CONTINUE.

Pt_CB_TERM_SCRLBK

A list of callbacks invoked whenever the Pt_ARG_TERM_SCRLBK_POS resource or the number of saved lines in the widget's buffer changes. Each callback is passed a PtCallbackInfo_t structure that contains at least the following members:

reason

Pt_CB_TERM_SCRLBK

reason_subtype

0

event

NULL

cbdata

A pointer to a PtTerminalScrlbkCb_t structure that contains at least the following members:

short old_count;

Previous value of the line count

short old_pos;

Previous value of the line position.

short new_count;

New line count.

short new_pos;

New line position.

Functions invoked by this callback shouldn't set any of the widget's resources.

These callbacks should return Pt_CONTINUE.

Inherited resources:

If the widget modifies an inherited resource, the "Default override" column indicates the new value. This modification affects any subclasses of the widget.

Pt_ARG_BANDWIDTH_THRESHOLD

The threshold value for graphics bandwidth (as reported by PhQuerySystemInfo()) that defines a slow connection. For more information, see Pt_ARG_TERM_CURSOR_FLAGS and the "Scrolling optimization" part of the "Description" section.

Pt_ARG_FILL_COLOR

The color of widget's margins. When set to Pt_INHERIT_COLOR, the widget draws margins using the "saved" fill color, which can be set to the current fill color using an escape sequence:

In QNX mode:

ESC S

In ANSI mode:

ESC [ 8 ]

Convenience functions:

The PtTerminal widget defines several convenience functions and data structures that make it easier to use the terminal once it's been created. Here's a brief overview:

PtTerminalCharset_t, PtTerminalCharsets_t

Character sets used by PtTerminal

PtTerminalCopy()

Copy the current selection to the clipboard.

PtTerminalCreateCsXlat().

Create a translation table for PtTerminal's character sets.

PtTerminalDefaultCharsets():

Get the default character sets used by PtTerminal.

PtTerminalFont()

Examine a font.

PtTerminalGetKeys()

Get the terminal line-editing keys.

PtTerminalGetSelection()

Get a copy of the current selection.

PtTerminalName()

Get the terminal's termcap/terminfo name.

PtTerminalPasteClipboard()

Paste the contents of the clipboard into the terminal.

PtTerminalPasteSelection()

Paste the current selection into the terminal.

PtTerminalPut(), PtTerminalPutc(), PtTerminalPuts()

Output text to the terminal.

PtTerminalSelectWord()

Select a word.