\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 may be used to fetch
the result of the last Tcl command.
In contrast, the function may be used
to set the result of a Tcl command, when this
command is defined in C++ (as may be done with ).
The function evaluate provides a shorthand for
combining eval and .
The function source may be used to read in
a file containing a Tcl script.
}
\c{
Also, we have the 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 and , 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.
}