Handler objects will be activated only
when a binding has been defined,
by using kit::action
or implicitly by employing
widget::bind or $widget::handler$.
Such bindings may also be defined
by kit::after or $item::bind$ and
item::handler.
Implicit binding results in the creation of
an anonymous action.
Actions, as characterized by the class action,
provide the actual means to bind C++
code to Tcl commands.
Actions may be defined either, trivially,
by a Tcl command,
by a C/C++ command function,
or by handler objects.
In effect, defining an action by means
of a handler object amounts, implicitly,
to defining a command function with a
privileged client for which, by convention,
the dispatch function is invoked.
For completeness, a brief description of
the other means to define actions is given
here as well.
Client
\zline{\fbox{client}}
class client { }; /// empty class
Command
\zline{\fbox{command}}
typedef command(client*, kit*, int, char*[]);
typedef tcl_command(ClientData, Tcl_Tnterp*, int, char*[]);
Data passed to a command function must be of type
client, which is defined by an empty
class introduced only to please the compiler.
In \ref{class-client} the type definition of command is given.
Apart from the client* parameter, a command
function must also declare a kit* parameter
and an argc and $argv$ parameter, similar as for $main$.
The client* data of a command (and similar for
the clientdata parameter of a $tclcommand$)
can be any kind of class.
However, it is to be preferred that such classes
are made a subclass of client.
The client data pointer is declared when creating
an action and passed to the command function when the actual call
is made.
The other parameters (argc and $argv$) depend
on the actual call.
The use of argc and $argv$ comes from the original
C interface of Tcl.
It proves to be a very flexible way of
communicating data, especially in string-oriented
applications.
interface action { /// \fbox{action}
action(char* name);
action(char* name, handler* h);
action(char* name, command f, client* data = 0);
action(char* name, tcl_command f, ClientData data = 0);
action( handler* h); /// anonymous
action( command f, client* data = 0);
action( tcl_command f, ClientData data = 0);
char* name(); /// returns the name of an action
};
The class action offers no less than seven
constructors.
The first constructor, which takes a (char*)
string as a parameter, is merely
for convenience.
It may be used to convert the name of a Tcl script command
into an action.
The following three constructors differ from the last
three constructors only by their first string parameter
which serves to define the name under which the
action will be known by the Tcl script interpreter.
The last three constructors, in contrast,
create anonymous actions, of which the user, however,
can ask its name by invoking the function name.
The preferred form of creating an action is by giving it
(apart from a name) a handler as parameter.
As already noted,
handler objects offer a type-secure way of dealing with client
information.
In contrast, the second constructor of this group,
which takes a command function and possibly a pointer
to client data as parameters, may make (type-insecure) conversions
of the client data necessary.
The constructor taking a tcl_command and ClientData as parameters
is incorporated for compatibility reasons only.
When using any of the last six constructors,
as a side-effect an association is created between
the name of the action and a Tcl command.
If such a Tcl command already exists,
the previous association will be overwritten.
This is also the case if it has been defined
as a Tcl script command.