\c{

The {\em kit} class

Hush is meant to provide a parsimonious C++ interface to Tcl/Tk. Nevertheless, as with many a toolkit, some kind of API shock seems to be unavoidable. This is especially true for the widget class (covered in section hush-widget) and the class kit defining the C++ interface with the embedded Tcl interpreter. The functionality of kit can only be completely understood after reading this section. However, since an instance of kit is used in almost any other object (class), it is presented here first. See slide class-kit. The reader will undoubtly gradually learn the functionality of kit by studying the examples. } \c{ To understand why a kit class is needed, recall that each hush program contains an embedded Tcl interpreter. The kit class encapsulates this interpreter and provides a collection of member functions to interact with the embedded interpreter. } \nop{ The kit class is derived from the class hcl which provides access to the lower level details of (an extended version of) Tcl. \nop{Consult the reference manual.} } \c{ The first group of functions (eval, result, evaluate and source) may be used to execute commands in the Tcl scripting language directly. A Tcl command is simply a string conforming to certain syntactic requirements. The function eval evaluates a Tcl command. The function result() may be used to fetch the result of the last Tcl command. In contrast, the function result(char*) may be used to set the result of a Tcl command, when this command is defined in C++ (as may be done with kit::action). The function evaluate provides a shorthand for combining eval and result(). The function source may be used to read in a file containing a Tcl script. } \c{ Also, we have the kit::action function that may be used to associate a Tcl command with a handler object. In section action, alternative ways of defining an action are discussed. } \nop{ The function after may be used to have a Tcl command evaluated after n milliseconds. (It makes use of X timer callbacks). The function send may be used to evaluate a command in a different application. An application may be given a name when creating the session object. The function selection delivers the current X selection. The function update may be used to process any pending events. These functions are only for experienced users. See section tcl. } \c{ The next group of functions is related to widgets and events that may occur to widgets. The event function delivers the latest event. It may only be used in a command that is bound to some particular event. See section hush-events. When other events occur before accessing the event object, the information it contains may be obsolete. } .so sli-kit \c{ The function root gives access to the toplevel root widget associated with that particular instance of the kit. The function pack may be used to append widgets to the root widget, in order to map them to the screen. Widgets may be identified either by a pointer to a widget object or by their path name, which is a string. See section widget. } \c{ Next, we have a group of functions related to the X environment. The function selection delivers the current X selection. The function after may be used to set a timer callback for a handler. Setting a timer callback means that the handler object will be invoked after the number of milliseconds given as the first argument to after. The function update may be used to ensure that all pending events are processed. For example, when moving items on a canvas, an update may be needed to make the changes visible. Also, we have a send function that may be used to communicate with other Tcl/Tk applications. The first argument of send must be the name of an application, which may be set when creating a session. } \nop{ The function action may be used to associate a Tcl command to a command function or handler written in C++. See section action for details. } \nop{ A kit object, which may be only created by session(), provides an interface to the tcl interpreter and the global properties of the system. The function eval() may be used to execute commands in tcl and to retrieve the result. The function event delivers the latest event. When other events occur before accessing a particular event object, the information gotten will be obsolete. } \c{ Further, we have the functions trace() and notrace(), which may be used to turn on, respectively off, tracing. The level indicates at what detail information will be given. Trace level zero is equivalent to notrace(). Finally, the function quit may be used to terminate the main event loop. }