Caution: This version of this document is no longer maintained. For the latest documentation, see http://www.qnx.com/developers/docs.

PtTerminal

A window that emulates a character-mode terminal

Class hierarchy:

PtWidgetPtBasicPtContainerPtTerminal

Immediate subclasses:

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

PhAB icon:

PtTerminal button in PhAB

Public header:

<photon/PtTerm.h>

Description:

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


PtTerm


A PtTerminal widget.

You can send characters to the terminal by calling PtTerminalPutc(), PtTerminalPut() and PtTerminalPuts(). If you type in the terminal, the keyboard input is passed to the widget via the Pt_CB_TERM_INPUT callback.

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


Note: 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

Your application program can use Pt_ARG_TERM_FONT to set an explicit font name, or Pt_ARG_TERM_FONT_INDEX to choose a font from the list of supported fonts, Pt_ARG_TERM_FONT_LIST.

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

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

If you've set the Pt_TERM_OPFONT flag, you can use escape sequences to set the font:

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 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 ANSI mode, the internal character set can be used for the 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 devc-con in the QNX Neutrino Utilities Reference.

ANSI character set
What's used in 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 the 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). Your application can define an additional mapping; for example, you can 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

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

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:

Character Meaning
- The value is decreasing.
+ The value is increasing.
= The value didn't change (used only when the size or margin is changing).

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 adjusts the number of columns (xs) and the margin height (ym).

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

Adjusting the dimension is always successful, while adjusting the 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:

Size limits

Other resources that may affect geometry are the size limits:

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, you should set the limits before the size.

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

Console emulation

A PtSetResources() call for the Pt_ARG_TERM_CONSOLE writes data directly to the widget's screen buffer.

First, your application should fill a PtTerminalConsoleWrite_t structure:

void const *buffer
A pointer to the data to be written.
unsigned short offset
The offset into the widget's screen buffer at which to write the data.
unsigned short nbytes
The number of bytes to write.

Pass a pointer to the structure as the second argument to PtSetArg(). When you call PtSetResources(), the widget transfers the actual screen data from the buffer given by the application to the widget's screen buffer. Then the corresponding area of the widget is damaged in order to display the new data. PtSetResources() doesn't check to see if the offset and length given by your application exceed the size of the buffer.

If you call PtGetResources() to get Pt_ARG_TERM_CONSOLE, you're given a pointer to the buffer. If your 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 (see the Photon Library Reference). Color numbers are indexes into this array. The default array has 16 elements corresponding to 16 standard CGA colors.

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 too much from the default values.

Drawing and scrolling

The Pt_ARG_TERM_DRAW_MODES resource defines the widget's scrolling capability.

Scrolling optimization

If your application gives characters to PtTerminalPut() 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 Pt_ARG_BANDWIDTH_THRESHOLD (see PtBasic), Pt_ARG_TERM_SCROLL, and Pt_ARG_TERM_DRAW_MODES, 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.

Drag and Drop

If you select some text and hold down the Ctrl key, you can drag the selected text to a PtText, PtMultiText, PtTerminal, or PtTty widget.

New resources:

Resource C type Pt type Default
Pt_ARG_TERM_ANSI_PROTOCOL int Boolean 1
Pt_ARG_TERM_APP PtTerminalAppState_t Struct See below
Pt_ARG_TERM_CHARSETS PtTerminalCsXlatData_t * Pointer See below
Pt_ARG_TERM_COLOR_MODE PtTerminalColorMode_t Struct Pt_TERM_COLOR_MODE
Pt_ARG_TERM_COLOR_TABLE PgColor_t, short Array CGA colors, 16
Pt_ARG_TERM_COLS short Scalar 80
Pt_ARG_TERM_CONSOLE PtTerminalConsoleWrite_t Complex N/A
Pt_ARG_TERM_CUR_COL short Scalar 0
Pt_ARG_TERM_CUR_POS PtTerminalRowCol_t Struct 0, 0
Pt_ARG_TERM_CUR_ROW short Scalar 0
Pt_ARG_TERM_CURSOR_FLAGS short Flag Pt_TERM_CURSOR_ON_FOCUS
Pt_ARG_TERM_DRAW_MODES unsigned char Flag Pt_TERM_SCROLL_RFSH
Pt_ARG_TERM_FONT char * String "pcterm14"
Pt_ARG_TERM_FONT_INDEX short Scalar -1
Pt_ARG_TERM_FONT_LIST char *, short Array NULL, 0
Pt_ARG_TERM_FONT_SIZE PhDim_t Struct Size of default font (read-only)
Pt_ARG_TERM_MARGINS PhRect_t Struct 0, 0, 0, 0 (read-only)
Pt_ARG_TERM_MAXCOLS short Scalar 1000
Pt_ARG_TERM_MAXROWS short Scalar 1000
Pt_ARG_TERM_MAXSIZE PtTerminalRowCol_t Struct 1000, 1000
Pt_ARG_TERM_MINCOLS short Scalar 1
Pt_ARG_TERM_MINROWS short Scalar 1
Pt_ARG_TERM_MINSIZE PtTerminalRowCol_t Struct 1, 1
Pt_ARG_TERM_OPTIONS unsigned long Flag 0x84380
Pt_ARG_TERM_OPTMASK unsigned long Flag ~0uL
Pt_ARG_TERM_RESIZE_FL unsigned short Flag All defined flags
Pt_ARG_TERM_RESIZE_FUN See below Pointer Pointer to static function
Pt_ARG_TERM_RESIZE_STR char * String "DF=sM:M=s"
Pt_ARG_TERM_ROWS short Scalar 25
Pt_ARG_TERM_SCRLBK_COUNT short Scalar 0
Pt_ARG_TERM_SCRLBK_LIMIT short Scalar 0
Pt_ARG_TERM_SCRLBK_POS short Scalar 0
Pt_ARG_TERM_SCROLL short Scalar Pt_TERM_MAX_ROWS
Pt_ARG_TERM_SELECTION PtTerminalSelection_t Struct 0
Pt_ARG_TERM_SIZE PtTerminalRowCol_t Struct 25, 80
Pt_ARG_TERM_VISUAL_BELL short Scalar 20
Pt_CB_TERM_APP PtCallback_t * Link NULL
Pt_CB_TERM_FONT PtCallback_t * Link NULL
Pt_CB_TERM_INPUT PtCallback_t * Link NULL
Pt_CB_TERM_OPTIONS PtCallback_t * Link NULL
Pt_CB_TERM_RESIZE PtCallback_t * Link NULL
Pt_CB_TERM_RESIZED PtCallback_t * Link NULL
Pt_CB_TERM_SCRLBK PtCallback_t * Link NULL

Pt_ARG_TERM_ANSI_PROTOCOL

C type Pt type Default
short Boolean 1

The protocol to use for the terminal:

0
QNX4
1
ANSI

Pt_ARG_TERM_APP

C type Pt type Default
PtTerminalAppState_t Struct See below

A structure containing the application window's state, which the protocol engine needs (see the Pt_CB_TERM_APP callback). This structure also contains some other information that a terminal emulator can use, 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 terminal emulators other than pterm, A text-mode program 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 are otherwise ignored. The only exception is titlepterm uses it to set its window title.

If you have a text-mode program that needs a terminal emulator other than pterm, 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 to display on the icon instead of the window title.

Pt_ARG_TERM_CHARSETS

C type Pt type Default
PtTerminalCsXlatData_t * Pointer See below

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.


Note: 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 or modify 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

C type Pt type Default
PtTerminalColorMode_t Struct Pt_TERM_COLOR_MODE

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

Pt_ARG_TERM_COLOR_TABLE

C type Pt type Default
PgColor_t, short Array CGA colors, 16

The color table used for the display. See PgColor_t in the Photon Library Reference.

This resource is used to convert 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:

Index Color
0 BLACK
1 BLUE
2 GREEN
3 CYAN
4 RED
5 MAGENTA
6 BROWN
7 WHITE (light grey)
8 BRIGHT BLACK (dark grey)
9 BRIGHT BLUE
10 BRIGHT GREEN
11 BRIGHT CYAN
12 BRIGHT RED
13 BRIGHT MAGENTA
14 BRIGHT BROWN (yellow)
15 BRIGHT WHITE

Pt_ARG_TERM_COLS

C type Pt type Default
short Scalar 80

The number of character columns.

Pt_ARG_TERM_CONSOLE

C type Pt type Default
PtTerminalConsoleWrite_t Complex N/A

You can use this resource to access the widget's “video memory” For more information, see Console emulation,” above.

Pt_ARG_TERM_CUR_COL

C type Pt type Default
short Scalar 0

The column number of the cursor's position.

Pt_ARG_TERM_CUR_POS

C type Pt type Default
PtTerminalRowCol_t Struct 0, 0

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

Pt_ARG_TERM_CUR_ROW

C type Pt type Default
short Scalar 0

The line number of the cursor's position.

Pt_ARG_TERM_CURSOR_FLAGS

C type Pt type Default
short Flag Pt_TERM_CURSOR_ON_FOCUS

Flags affecting the cursor timer. Possible values are:

Pt_ARG_TERM_DRAW_MODES

C type Pt type Default
unsigned char Flag Pt_TERM_SCROLL_RFSH

Flags that determine scrolling optimization:

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

Pt_ARG_TERM_FONT

C type Pt type Default
char * String "pcterm14"

The name of the font used for the display. For more information, see Fonts,” above.


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

Pt_ARG_TERM_FONT_INDEX

C type Pt type Default
short Scalar -1

The position of the current font in the font list, or -1 if the current font isn't in the list. You can use this resource to choose a font from the list, but you can't explicitly set it to -1.

Pt_ARG_TERM_FONT_LIST

C type Pt type Default
char *, short Array NULL, 0

The list of fonts (an array of pointers to strings).

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

Pt_ARG_TERM_FONT_SIZE (read-only)

C type Pt type Default
PhDim_t Struct Size of default font

A PhDim_t structure (see the Photon Library Reference) that defines the dimensions of the font used for the display.

Pt_ARG_TERM_MARGINS (read-only)

C type Pt type Default
PhRect_t Struct 0, 0, 0, 0

A PhRect_t structure (see the Photon Library Reference) that contains 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 Geometry,” above.

Pt_ARG_TERM_MAXCOLS

C type Pt type Default
short Scalar 1000

The maximum number of character columns.

Pt_ARG_TERM_MAXROWS

C type Pt type Default
short Scalar 1000

The maximum number of character rows.

Pt_ARG_TERM_MAXSIZE

C type Pt type Default
PtTerminalRowCol_t Struct 1000, 1000

The maximum screen size, in character rows and columns. The PtTerminalRowCol_t structure contains the following members:

Pt_ARG_TERM_MINCOLS

C type Pt type Default
short Scalar 1

The minimum number of character columns.

Pt_ARG_TERM_MINROWS

C type Pt type Default
short Scalar 1

The minimum number of character rows.

Pt_ARG_TERM_MINSIZE

C type Pt type Default
PtTerminalRowCol_t Struct 1, 1

The minimum screen size, in character rows and columns. The PtTerminalRowCol_t structure contains the following members:

Pt_ARG_TERM_OPTIONS

C type Pt type Default
unsigned long Flag 0x84380

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>). The widget handles some of them, and your application can handle some others.

Pt_ARG_TERM_OPTMASK

C type Pt type Default
unsigned long Flag ~0uL

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_RESIZE_FL

C type Pt type Default
unsigned short Flag All defined flags

Flags that affect the resizing of the terminal widget. Any combination of:

Pt_ARG_TERM_RESIZE_FUN

C type Pt type Default
See below Pointer Pointer to static function

A pointer to a function to be used in geometry adjustments. The prototype is:

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

For more information, see Geometry,” above.

Pt_ARG_TERM_RESIZE_STR

C type Pt type Default
char * String "DF=sM:M=s"

A hint for the function used in geometry adjustments. For more information, see Geometry,” above.

Pt_ARG_TERM_ROWS

C type Pt type Default
short Scalar 25

The number of character rows.

Pt_ARG_TERM_SCRLBK_COUNT

C type Pt type Default
short Scalar 0

The current number of lines saved in the scrollback buffer.

Pt_ARG_TERM_SCRLBK_LIMIT

C type Pt type Default
short Scalar 0

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

Pt_ARG_TERM_SCRLBK_POS

C type Pt type Default
short Scalar 0

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

Pt_ARG_TERM_SCROLL

C type Pt type Default
short Scalar Pt_TERM_MAX_ROWS

The maximum number of scrolls that will be delayed. For more information, see Scrolling optimization,” above.

Pt_ARG_TERM_SELECTION

C type Pt type Default
PtTerminalSelection_t Struct 0

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:
old_type
The last value of type that differed from Pt_TERM_SELECTION_NONE.
flags
Valid flags are:

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:

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:

Pt_ARG_TERM_SIZE

C type Pt type Default
PtTerminalRowCol_t Struct 25, 80

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

Pt_ARG_TERM_VISUAL_BELL

C type Pt type Default
short Scalar 20

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

Pt_CB_TERM_APP

C type Pt type Default
PtCallback_t * Link NULL

A list of PtCallback_t structures that define the 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

C type Pt type Default
PtCallback_t * Link NULL

A list of PtCallback_t structures that define the 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

C type Pt type Default
PtCallback_t * Link NULL

A list of PtCallback_t structures that define the 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:
event
A pointer to a PhEvent_t structure that describes the event that caused the callback to be invoked, 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 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

C type Pt type Default
PtCallback_t * Link NULL

A list of PtCallback_t structures that define the 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

C type Pt type Default
PtCallback_t * Link NULL

A list of PtCallback_t structures that define the callbacks invoked when the terminal is about to change its size (i.e the 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;
The current size of the terminal.
PtTerminalRowCol_t new_size;
The new size.

The PtTerminalRowCol_t structure contains the following members:

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 your application calls PtSetResources() 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

C type Pt type Default
PtCallback_t * Link NULL

A list of PtCallback_t structures that define the 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;
The previous size of the terminal.
PtTerminalRowCol_t new_size;
The current size.

The PtTerminalRowCol_t structure contains the following members:

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.

These callbacks should return Pt_CONTINUE.

Pt_CB_TERM_SCRLBK

C type Pt type Default
PtCallback_t * Link NULL

A list of PtCallback_t structures that define the 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;
The previous value of the line count
short old_pos;
The previous value of the line position.
short new_count;
The new line count.
short new_pos;
The new line position.

Note: 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.

Resource Inherited from Default override
Pt_ARG_ANCHOR_FLAGS PtWidget
Pt_ARG_ANCHOR_OFFSETS PtWidget
Pt_ARG_AREA PtWidget
Pt_ARG_BANDWIDTH_THRESHOLD PtBasic Ph_BAUD_SLOW (see below)
Pt_ARG_BASIC_FLAGS PtBasic
Pt_ARG_BEVEL_WIDTH PtWidget
Pt_ARG_BITMAP_CURSOR PtWidget
Pt_ARG_BEVEL_COLOR PtBasic
Pt_ARG_BEVEL_CONTRAST PtBasic
Pt_ARG_COLOR PtBasic
Pt_ARG_CONTAINER_FLAGS PtContainer
Pt_ARG_CONTRAST PtBasic
Pt_ARG_CURSOR_COLOR PtWidget
Pt_ARG_CURSOR_OVERRIDE PtContainer
Pt_ARG_CURSOR_TYPE PtWidget
Pt_ARG_DARK_BEVEL_COLOR PtBasic
Pt_ARG_DARK_FILL_COLOR PtBasic
Pt_ARG_DATA PtWidget
Pt_ARG_DIM PtWidget
Pt_ARG_EFLAGS PtWidget
Pt_ARG_EXTENT PtWidget
Pt_ARG_FILL_COLOR PtBasic Pt_INHERIT_COLOR (see below)
Pt_ARG_FILL_PATTERN PtBasic
Pt_ARG_FLAGS PtWidget
Pt_ARG_GRID_LAYOUT_DATA PtWidget
Pt_ARG_HEIGHT PtWidget
Pt_ARG_HELP_TOPIC PtWidget
Pt_ARG_HIGHLIGHT_ROUNDNESS PtBasic
Pt_ARG_INLINE_COLOR PtBasic
Pt_ARG_LAYOUT_DATA PtWidget
Pt_ARG_LIGHT_BEVEL_COLOR PtBasic
Pt_ARG_LIGHT_FILL_COLOR PtBasic
Pt_ARG_MARGIN_HEIGHT PtBasic
Pt_ARG_MARGIN_WIDTH PtBasic
Pt_ARG_MAXIMUM_DIM PtWidget
Pt_ARG_MINIMUM_DIM PtWidget
Pt_ARG_OUTLINE_COLOR PtBasic
Pt_ARG_POINTER PtWidget
Pt_ARG_POS PtWidget
Pt_ARG_RESIZE_FLAGS PtWidget 0
Pt_ARG_ROW_LAYOUT_DATA PtWidget
Pt_ARG_STYLE PtBasic
Pt_ARG_TITLE PtContainer
Pt_ARG_TITLE_FONT PtContainer
Pt_ARG_TRANS_PATTERN PtBasic
Pt_ARG_USER_DATA PtWidget
Pt_ARG_WIDTH PtWidget
Pt_CB_ACTIVATE PtBasic
Pt_CB_ARM PtBasic
Pt_CB_BALLOONS PtContainer
Pt_CB_BLOCKED PtWidget
Pt_CB_CHILD_ADDED_REMOVED PtContainer
Pt_CB_CHILD_GETTING_FOCUS PtContainer
Pt_CB_CHILD_LOSING_FOCUS PtContainer
Pt_CB_DESTROYED PtWidget
Pt_CB_DISARM PtBasic
Pt_CB_DND PtWidget
Pt_CB_FILTER PtWidget
Pt_CB_GOT_FOCUS PtBasic
Pt_CB_HOTKEY PtWidget
Pt_CB_IS_DESTROYED PtWidget
Pt_CB_LOST_FOCUS PtBasic
Pt_CB_MENU PtBasic
Pt_CB_OUTBOUND PtWidget
Pt_CB_RAW PtWidget
Pt_CB_REALIZED PtWidget
Pt_CB_REPEAT PtBasic
Pt_CB_RESIZE PtContainer
Pt_CB_UNREALIZED PtWidget

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 Scrolling optimization,” above.

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 the following convenience functions and data structures that make it easier to use the terminal once it's been created:

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.
PtTerminalFontInfo()
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.