Actions

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.