Embedding applications

One may wish to embed an existing curses or simple text-based application within a prettier frame-work, and/or add extra macro or session functionality to simplify its use.

One such example of this is the Crescendo application, which embeds the TinyFuge mud client into a gnome-aware GUI application and provides some point-and-click functionality.

This is very easy to do using the ZvtTerm widget. All you have to do is instantiate the widget, and then execute the controlled program in the appropriate environment. The and functions are used for this purpose.

Further information can be found in the section called Terminal input and output about how to interact with the subordinate application.

Creating an appropriate widget

Typically applications such as these are designed to run in a 80x24 character-mode terminal, you should use zvt_term_new_with_size() to create the initial 80x24 terminal.

You may also need to force the application window not to be resized, if the embedded application cannot handle it. This can be done using the normal GDK/GTK+ window hints mechanism.

Creating an appropriate execution environment

The function should be used to create the child process required to execute the program in. It works just like fork(2) with some additional features.

This will setup the pseudo tty (pty) for the subordinate program, and register the login session if required. ZvtTerm uses a secure set-uid helper application to register the session, so applications need not (and should not!) be run as a privileged user to register login sessions.

The environment must also be setup appropriately if any curses/nurses or similar application is to be run within the terminal. The following environmental variables should be modified/set as shown:

TERM: Should be set to xterm, as the ZvtTerm widget tries to emulate an xterm. vt100 or vt220 may also work if xterm is not understood by the application.
COLORTERM: Can be set to anything, including the name of the application. Although it may be appropriate to set it to the value "zterm". This will enable color rendering in a modern color-capable curses, like ncurses.
COLUMNS & ROWS: These variables should be removed from the environment passed to the child process. However it may be necessary to initialize it to the size of the terminal, if it will not change. The terminal size is always set properly on the pseudo-tty.

These should only be set in the child process (that which received a 0 return value from zvt_term_forkpty()). The program should then be executed using execle(2), execpe(2) or similar. If these environment variables are not set, the terminal will still function, but any embedded application may not properly display.

Setting up an exit handler

The widget will generate a "child_died" signal when the child process terminates. This signal should be caught if you wish to detect when the subordinate process exits.