API Reference

The following pages contain the complete API reference.

Terminal functions

zvt_term_set_blink

void zvt_term_set_blink (ZvtTerm * term, int state);

term A ZvtTerm widget.
state The blinking state. If TRUE, the cursor will blink.

Description

Use this to control the way the cursor is displayed (blinking/solid)

zvt_term_set_scroll_on_keystroke

void zvt_term_set_scroll_on_keystroke (ZvtTerm * term, int state);

term A ZvtTerm widget.
state Desired state.

Description

If state is TRUE, forces the terminal to jump out of the scrollback buffer whenever a keypress is received.

zvt_term_set_scroll_on_output

void zvt_term_set_scroll_on_output (ZvtTerm * term, int state);

term A ZvtTerm widget.
state Desired state.

Description

If state is TRUE, forces the terminal to scroll on output being generated by a child process or by zvt_term_feed().

zvt_term_set_wordclass

void zvt_term_set_wordclass (ZvtTerm * term, unsigned char * class);

term A ZvtTerm widget.
class A string of characters to consider a "word" character.

Description

Sets the list of characters (character class) that are considered part of a word, when selecting by word. The class is defined the same was as a regular expression character class (as normally defined using []'s, but without those included). A leading or trailing hypen (-) is used to include a hyphen in the character class.

Passing a NULL class restores the default behaviour of alphanumerics plus "_" (i.e. "A-Za-z0-9_").

zvt_term_new_with_size

GtkWidget* zvt_term_new_with_size (int cols, int rows);

cols Number of columns required.
rows Number of rows required.

Description

Creates a new ZVT Terminal widget of the given character dimentions. If the encompassing widget is resizable, then this size may change afterwards, but should be correct at realisation time.

Return Value

A pointer to a ZvtTerm widget is returned, or NULL on error.

zvt_term_new

GtkWidget* zvt_term_new ( void);

void -- undescribed --

Description

Creates a new ZVT Terminal widget. By default the terminal will be setup as 80 colmns x 24 rows, but it will size automatically to its encompassing widget, and may be smaller or larger upon realisation.

Return Value

A pointer to a ZvtTerm widget is returned, or NULL on error.

zvt_term_reset

void zvt_term_reset (ZvtTerm * term, int hard);

term A ZvtTerm widget.
hard If TRUE, then perform a HARD reset.

Description

Performs a complete reset on the terminal. Resets all attributes, and if hard is TRUE, also clears the screen.

zvt_term_set_color_scheme

void zvt_term_set_color_scheme (ZvtTerm * term, gushort * red, gushort * grn, gushort * blu);

term A ZvtTerm widget.
red pointer to a gushort array of 18 elements with red values.
grn pointer to a gushort array of 18 elements with green values.
blu pointer to a gushort array of 18 elements with blue values.

Description

This function sets the colour palette for the terminal term. Each pointer points to a gushort array of 18 elements. White is 0xffff in all elements.

The elements 0 trough 15 are the first 16 colours for the terminal, with element 16 and 17 the default foreground and background colour respectively.

zvt_term_set_default_color_scheme

void zvt_term_set_default_color_scheme (ZvtTerm * term);

term A ZvtTerm widget.

Description

Resets the color values to the default color scheme.

zvt_term_set_size

void zvt_term_set_size (ZvtTerm * term, guint width, guint height);

term A ZvtTerm widget.
width Width of terminal, in columns.
height Height of terminal, in rows.

Description

Causes the terminal to attempt to resize to the absolute character size of width rows by height columns.

zvt_term_show_pointer

void zvt_term_show_pointer (ZvtTerm * term);

term A ZvtTerm widget.

Description

Show the default I beam pointer.

zvt_term_hide_pointer

void zvt_term_hide_pointer (ZvtTerm * term);

term A ZvtTerm widget.

Description

Hide the pointer. In reality the pointer is changed to a single-pixel black dot.

zvt_term_set_scrollback

void zvt_term_set_scrollback (ZvtTerm * term, int lines);

term A ZvtTerm widget.
lines Number of lines desired for the scrollback buffer.

Description

Set the maximum number of scrollback lines for the widget term to lines lines.

zvt_term_set_fonts

void zvt_term_set_fonts (ZvtTerm * term, GdkFont * font, GdkFont * font_bold);

term A ZvtTerm widget.
font Font used for regular text.
font_bold Font used for bold text. May be null, in which case the bold font is rendered by over-striking.

Description

Load a set of fonts into the terminal.

These fonts should be the same size, otherwise it could get messy ...

zvt_term_set_font_name

void zvt_term_set_font_name (ZvtTerm * term, char * name);

term A ZvtTerm widget.
name A full X11 font name string.

Description

Set a font by name only. If font aliases such as 'fixed' or '10x20' are passed to this function, then both the bold and non-bold font will be identical. In colour mode bold fonts are always the top 8 colour scheme entries, and so bold is still rendered.

Tries to calculate bold font name from the base name. This only works with fonts where the names are alike.

zvt_term_writechild

int zvt_term_writechild (ZvtTerm * term, char * data, int len);

term A ZvtTerm widget.
data Data to write.
len Length of data to write.

Description

Writes len bytes of data, starting from data to the subordinate child process. If the child is unable to handle all of the data at once, then it will return, and asynchronously continue to feed the data to the child.

Return Value

The number of bytes written initially.

zvt_term_forkpty

int zvt_term_forkpty (ZvtTerm * term, int do_uwtmp_log);

term A ZvtTerm widget.
do_uwtmp_log If TRUE, then log the session in wtmp(4) and utmp(4).

Description

Fork a child process, with a master controlling terminal.

zvt_term_killchild

int zvt_term_killchild (ZvtTerm * term, int signal);

term A ZvtTerm widget.
signal A signal number.

Description

Send the signal signal to the child process. Note that a child process must have first been started using zvt_term_forkpty().

Return Value

See kill(2).

See Also

signal(5).

zvt_term_closepty

int zvt_term_closepty (ZvtTerm * term);

term A ZvtTerm widget.

Description

Close master pty to the child process. It is upto the child to recognise its pty has been closed, and to exit appropriately.

Note that a child process must have first been started using zvt_term_forkpty().

Return Value

See close(2).

zvt_term_match_add

int zvt_term_match_add (ZvtTerm * term, char * regex, uint32 highlight_mask, void * data);

term An initialised ZvtTerm.
regex A regular expression to match. It should be concise enough so that it doesn't match whole lines.
highlight_mask Mask of bits used to highlight the text as the mouse moves over it.
data User data.

Description

Add a new auto-match regular expression. The zvt_term_match_check() function can be used to check for matches using screen coordinates.

Each regular expression regex will be matched against each line in the visible buffer.

The highlight_mask is taken from the VTATTR_* bits, as defined in vt.h. These include VTATTR_BOLD, VTATTR_UNDERLINE, etc, but not the colours.

Return value

Returns -1 when the regular expression is invalid and cannot be compiled (see regcomp(3c)). Otherwise returns 0.

zvt_term_match_clear

void zvt_term_match_clear (ZvtTerm * term, char * regex);

term An initialised ZvtTerm.
regex A regular expression to remove, or NULL to remove all match strings.

Description

Remove a specific match string, or all match strings from the terminal term.

zvt_term_match_check

char * zvt_term_match_check (ZvtTerm * term, int x, int y, void ** user_data_ptr);

term An initialised ZvtTerm.
x X coordinate, in character coordinates.
y Y coordinate to check, in character coordinates.
user_data_ptr A pointer to a location to hold the user-data associated with this match. If NULL, then this is ignored.

Description

Check for a match at a given character location.

Return Values

Returns the string matched. If user_data_ptr is non-NULL, then it is set to the user_data associated with this match type. The return value is only guaranteed valid until the next iteration of the gtk main loop.

zvt_term_feed

void zvt_term_feed (ZvtTerm * term, char * text, int len);

term A ZvtTerm widget.
text The text to feed.
len The text length.

Description

This makes the terminal emulator process the stream of characters in text for len bytes. The text is interpreted by the terminal emulator as if it were generated by a child process.

This is used by code that needs a terminal emulator, but does not use a child process.

zvt_term_set_background

void zvt_term_set_background (ZvtTerm * terminal, char * pixmap_file, int transparent, int flags);

terminal A ZvtTerm widget.
pixmap_file file containing the pixmap image
transparent true if we want to run in transparent mode
flags A bitmask of background options: ZVT_BACKGROUND_SHADED, shade the transparency pixmap. ZVT_BACKGROUND_SCROLL, allow smart scrolling of the pixmap, ignored if transparency is requested.

Description

Sets the background of the terminal. If pixmap_file and transparent are NULL and FALSE, then a standard filled background is set.

zvt_term_set_del_key_swap

void zvt_term_set_del_key_swap (ZvtTerm * term, int state);

term A ZvtTerm widget.
state If true it swaps the del/backspace definitions

Description

Sets the mode for interpreting the DEL and Backspace keys.

zvt_term_set_bell

void zvt_term_set_bell (ZvtTerm * term, int state);

term A ZvtTerm widget.
state New bell state.

Description

Enable or disable the terminal bell. If state is TRUE, then the bell is enabled.

zvt_term_get_bell

gboolean zvt_term_get_bell (ZvtTerm * term);

term A ZvtTerm widget.

Description

get the terminal bell state. If the bell on then TRUE is returned, otherwise FALSE.

zvt_term_get_capabilities

guint32 zvt_term_get_capabilities (ZvtTerm * term);

term A ZvtTerm widget.

Description

Gets the compiled in capabilities of the terminal widget.

ZVT_TERM_PIXMAP_SUPPORT; Pixmaps can be loaded into the background using the background setting function.

ZVT_TERM_PIXMAPSCROLL_SUPPORT; The background scrolling flag of the background setting function is honoured.

ZVT_TERM_EMBOLDEN_SUPPORT; Bold fonts are autogenerated, and can be requested by setting the bold_font of the font setting function to NULL.

ZVT_TERM_MATCH_SUPPORT; The zvt_term_add_match() functions exist, and can be used to receive the match_clicked signal when the user clicks on matching text.

ZVT_TERM_TRANSPARENCY_SUPPORT; A transparent background can be requested on the current display.

Returns

a bitmask of the capabilities

zvt_term_get_buffer

char * zvt_term_get_buffer (ZvtTerm * term, int * len, int type, int sx, int sy, int ex, int ey);

term Valid ZvtTerm widget.
len Placeholder to store the length of text selected. May be NULL in which case the value is not returned.
type Type of selection. VT_SELTYPE_LINE, select by line, VT_SELTYPE_WORD, select by word, or VT_SELTYPE_CHAR, select by character.
sx Start of selection, horizontal.
sy Start of selection, vertical. 0 is the top of the visible screen, <0 is scrollback lines, >0 is visible lines (upto the height of the window).
ex End of selection, horizontal.
ey End of selection, vertical, as above.

Description

Convert the buffer memory into a contiguous array which may be saved or processed. Note that this is not gauranteed to match the order of characters processed by the terminal, only the order in which they were displayed. Tabs will normally be preserved in the output.

All inputs are range-checked first, so it is possible to fudge a full buffer grab.

Examples

Example 1.

data = zvt_term_get_buffer(term, NULL, VT_SELTYPE_LINE, -term->vx->vt.scrollbackmax, 0, term->vx->vt.height, 0); or, as a rule - data = zvt_term_get_buffer(term, NULL, VT_SELTYPE_LINE, -10000, 0, 10000, 0);

Will return the contents of the entire scrollback and on-screen buffers, remembering that all inputs are range-checked first.

data = zvt_term_get_buffer(term, NULL, VT_SELTYPE_CHAR, 0, 0, 5, 10);

Will return the first 5 lines of the visible screen, and the 6th line upto column 10.

Return value

A pointer to a NUL terminated buffer containing the raw text from the buffer. If memory could not be allocated, then returns NULL. Note that it is upto the caller to free the memory, using g_free(3c). If len was supplied, then the length of data is stored there.