ZVT Terminal Widget Reference Guide
<<< Previous Page | Home | Up | Next Page >>>

# ZvtTerm widget API description.

## Name

ZvtTerm widget API description. -- The API description for the ZvtTerm Gtk widget.

## Synopsis

    #define     ZVT_TERM                        (obj)
    #define     ZVT_TERM_CLASS                  (klass)
    #define     ZVT_IS_TERM                     (obj)
    struct      ZvtTerm;
    struct      ZvtTermClass;
    #define     ZVT_TERM_DO_UTMP_LOG
    #define     ZVT_TERM_DO_WTMP_LOG
    GtkWidget*  zvt_term_new                    (void);
    GtkWidget*  zvt_term_new_with_size          (int cols,
                                                 int rows);
    void        zvt_term_feed                   (ZvtTerm *term,
                                                 char *text,
                                                 int len);
    int         zvt_term_forkpty                (ZvtTerm *term,
                                                 int do_uwtmp_log);
    int         zvt_term_closepty               (ZvtTerm *term);
    int         zvt_term_killchild              (ZvtTerm *term,
                                                 int signal);
    void        zvt_term_bell                   (void *zvt_term);
    guint       zvt_term_get_type               (void);
    void        zvt_term_set_scrollback         (ZvtTerm *term,
                                                 int lines);
    char*       zvt_term_get_buffer             (ZvtTerm *term,
                                                 int *len,
                                                 int type,
                                                 int sx,
                                                 int sy,
                                                 int ex,
                                                 int ey);
    void        zvt_term_set_font_name          (ZvtTerm *term,
                                                 char *name);
    void        zvt_term_set_fonts              (ZvtTerm *term,
                                                 GdkFont *font,
                                                 GdkFont *font_bold);
    void        zvt_term_hide_pointer           (ZvtTerm *term);
    void        zvt_term_show_pointer           (ZvtTerm *term);
    void        zvt_term_set_bell               (ZvtTerm *term,
                                                 int state);
    gboolean    zvt_term_get_bell               (ZvtTerm *term);
    void        zvt_term_set_blink              (ZvtTerm *term,
                                                 int state);
    void        zvt_term_set_scroll_on_keystroke
                                                (ZvtTerm *term,
                                                 int state);
    void        zvt_term_set_scroll_on_output   (ZvtTerm *term,
                                                 int state);
    void        zvt_term_set_color_scheme       (ZvtTerm *term,
                                                 gushort *red,
                                                 gushort *grn,
                                                 gushort *blu);
    void        zvt_term_set_default_color_scheme
                                                (ZvtTerm *term);
    void        zvt_term_set_del_key_swap       (ZvtTerm *term,
                                                 int state);
    void        zvt_term_set_wordclass          (ZvtTerm *term,
                                                 unsigned char *klass);
    void        zvt_term_set_background         (ZvtTerm *terminal,
                                                 char *pixmap_file,
                                                 int transparent,
                                                 int flags);
    void        zvt_term_set_shadow_type        (ZvtTerm *term,
                                                 GtkShadowType type);
    void        zvt_term_set_size               (ZvtTerm *term,
                                                 guint width,
                                                 guint height);
    guint32     zvt_term_get_capabilities       (ZvtTerm *term);
    GtkAdjustment* zvt_term_get_adjustment      (ZvtTerm *terminal);
    void        zvk_term_set_adjustment         (ZvtTerm *dial,
                                                 GtkAdjustment *adjustment);

## Description

Here is the API decription of the Zvt Widget.

## Details

### ZVT_TERM()

    #define ZVT_TERM(obj)          GTK_CHECK_CAST (obj, zvt_term_get_type (), ZvtTerm)

Casts the `obj` GtkObject into a ZvtTerm object class.

`obj` : | A GtkObject

### ZVT_TERM_CLASS()

    #define ZVT_TERM_CLASS(klass)  GTK_CHECK_CLASS_CAST (klass, zvt_term_get_type (), ZvtTermClass)

Casts the `klass` GtkObjectClass into a ZvtTermClass class.

`klass` : | A GtkClass

### ZVT_IS_TERM()

    #define ZVT_IS_TERM(obj)       GTK_CHECK_TYPE (obj, zvt_term_get_type ())

Returns TRUE if the `obj` argument is a GtkObject of type ZvtTerm.

`obj` : | A Gtk Object.

### struct ZvtTerm

    struct ZvtTerm;

### struct ZvtTermClass

    struct ZvtTermClass
    {
      GtkWidgetClass parent_class;

      void (* child_died) (ZvtTerm *term);
      void (* title_changed) (ZvtTerm *term, VTTITLE_TYPE type, char *newtitle);
    };

### ZVT_TERM_DO_UTMP_LOG

    #define ZVT_TERM_DO_UTMP_LOG 1

### ZVT_TERM_DO_WTMP_LOG

    #define ZVT_TERM_DO_WTMP_LOG 2

### zvt_term_new ()

    GtkWidget*  zvt_term_new                    (void);

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.

Returns : | A pointer to a &ZvtTerm widget is returned, or `NULL` on error.

### zvt_term_new_with_size ()

    GtkWidget*  zvt_term_new_with_size          (int cols,
                                                 int rows);

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.

`cols` : | Number of columns required.
`rows` : | Number of rows required.
Returns : | A pointer to a &ZvtTerm widget is returned, or `NULL` on error.

### zvt_term_feed ()

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

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.

`term` : | A &ZvtTerm widget.
`text` : | The text to feed.
`len` : | The text length.

### zvt_term_forkpty ()

    int         zvt_term_forkpty                (ZvtTerm *term,
                                                 int do_uwtmp_log);

Fork a child process, with a master controlling terminal.

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

### zvt_term_closepty ()

    int         zvt_term_closepty               (ZvtTerm *term);

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

`term` : | A &ZvtTerm widget.
Returns : | See close(2).

### zvt_term_killchild ()

    int         zvt_term_killchild              (ZvtTerm *term,
                                                 int signal);

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

`term` : | A &ZvtTerm widget.
`signal` : | A signal number.
Returns : | See kill(2). See Also: signal(5).

### zvt_term_bell ()

    void        zvt_term_bell                   (void *zvt_term);

`zvt_term` : |

### zvt_term_get_type ()

    guint       zvt_term_get_type               (void);

Returns : |

### zvt_term_set_scrollback ()

    void        zvt_term_set_scrollback         (ZvtTerm *term,
                                                 int lines);

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

`term` : | A &ZvtTerm widget.
`lines` : | Number of lines desired for the scrollback buffer.

### zvt_term_get_buffer ()

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

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

`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.
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.

### zvt_term_set_font_name ()

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

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.

`term` : | A &ZvtTerm widget.
`name` : | A full X11 font name string.

### zvt_term_set_fonts ()

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

Load a set of fonts into the terminal.

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

`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.

### zvt_term_hide_pointer ()

    void        zvt_term_hide_pointer           (ZvtTerm *term);

`term` : |

### zvt_term_show_pointer ()

    void        zvt_term_show_pointer           (ZvtTerm *term);

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

`term` : | A &ZvtTerm widget.

### zvt_term_set_bell ()

    void        zvt_term_set_bell               (ZvtTerm *term,
                                                 int state);

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

`term` : | A &ZvtTerm widget.
`state` : | New bell state.

### zvt_term_get_bell ()

    gboolean    zvt_term_get_bell               (ZvtTerm *term);

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

`term` : | A &ZvtTerm widget.
Returns : |

### zvt_term_set_blink ()

    void        zvt_term_set_blink              (ZvtTerm *term,
                                                 int state);

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

`term` : | A &ZvtTerm widget.
`state` : | The blinking state. If `TRUE`, the cursor will blink.

### zvt_term_set_scroll_on_keystroke ()

    void        zvt_term_set_scroll_on_keystroke
                                                (ZvtTerm *term,
                                                 int state);

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

`term` : | A &ZvtTerm widget.
`state` : | Desired state.

### zvt_term_set_scroll_on_output ()

    void        zvt_term_set_scroll_on_output   (ZvtTerm *term,
                                                 int state);

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

`term` : | A &ZvtTerm widget.
`state` : | Desired state.

### zvt_term_set_color_scheme ()

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

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.

`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.

### zvt_term_set_default_color_scheme ()

    void        zvt_term_set_default_color_scheme
                                                (ZvtTerm *term);

Resets the color values to the default color scheme.

`term` : | A &ZvtTerm widget.

### zvt_term_set_del_key_swap ()

    void        zvt_term_set_del_key_swap       (ZvtTerm *term,
                                                 int state);

Sets the mode for interpreting the DEL and Backspace keys.

`term` : | A &ZvtTerm widget.
`state` : | If true it swaps the del/backspace definitions

### zvt_term_set_wordclass ()

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

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_").

`term` : | A &ZvtTerm widget.
`klass` : |

### zvt_term_set_background ()

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

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

`terminal` : | A &ZvtTerm widget.
`pixmap_file` : | file containing the pixmap image
`transparent` : | true if we want to run in transparent mode
`shaded` : |

### zvt_term_set_shadow_type ()

    void        zvt_term_set_shadow_type        (ZvtTerm *term,
                                                 GtkShadowType type);

`term` : |
`type` : |

### zvt_term_set_size ()

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

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

`term` : | A &ZvtTerm widget.
`width` : | Width of terminal, in columns.
`height` : | Height of terminal, in rows.

### zvt_term_get_capabilities ()

    guint32     zvt_term_get_capabilities       (ZvtTerm *term);

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.

`term` : | A &ZvtTerm widget.
Returns : | a bitmask of the capabilities

### zvt_term_get_adjustment ()

    GtkAdjustment* zvt_term_get_adjustment      (ZvtTerm *terminal);

`terminal` : |
Returns : |

### zvk_term_set_adjustment ()

    void        zvk_term_set_adjustment         (ZvtTerm *dial,
                                                 GtkAdjustment *adjustment);

`dial` : |
`adjustment` : |

<<< Previous Page | Home | Up | Next Page >>>
API Reference | Implementation notes