Program structure

    // Initial declarations
    
    #include "hush.h"
    
    double newton(double arg);    // declare the function
    
    char* ftoa( double f);        // to convert float to char*
    
    // The generator (handler) class gives access to the widgets
    
    class generator : public handler {   
    public:
      
      generator() {                        // access to Tcl widgets
      	s = (scale*) new widget(".s");
      	m = (message*) new widget(".m");
      }
      
      ~generator() {
      	s->destroy(); m->destroy(); // to destroy widgets
      	delete s; delete m;       // to reclaim resources
      }
      
      int operator()() {             // the generator action
    	float f = s->get();
    	m->text( ftoa( newton(f) ) );     // display value
    	return OK;
    }
    
    private:
      scale* s;
      message* m;
    };
    
    // The application class takes care of installing the interface
    
    class application : public session { 
    public:
      application(int argc, char* argv[])
  			     : session(argc,argv,"newton") {}
      
      void main( ) {                    // tk is an instance variable
          
          tk->source("interface.tcl");  // read interface script
          handler* g = new generator(); 
      
          tk->bind("generate",g);     // bind Tcl command
      }
    };
    
    // Finally, the function main is defined
    
    void main (int  argc, char  **argv) { 
        session* s = new application(argc,argv);
        s->run();
    }
    
  

Comments

An overview of the hush class library

The library

---

slide: Hush handler classes

---

The handler class may also be considered an abstract class, in the sense that it is intended to be used as the ancestor of a user-defined handler class. Recall that in the example we defined the generator class as a descendant of handler. The handler class has two pre-defined descendant classes, namely the widget class and the class item. This implies, indeed, that both the widget and the item class (that is treated in section Items) may be used as ancestor handler classes as well. The reason for this is that any descendant of a widget or item class may declare itself to be its own handler and define the actions that are invoked in response to particular events. This will be illustrated and discussed in sections Binding and User.

The hush interpreter

In the introduction, hush was announced as both a C++ library and as an interpreter extending the wish interpreter. The program shown below substantiates this claim, albeit in a perhaps disappointingly simple way.

---

    
    #include "hush.h"       
  
    // Include definitions of external package(s)
  
    #include "extern/ht.h"
  
    // Define the application class
    
    class application : public session { 
    public:
    
      application(int argc, char* argv[]) : session(argc,argv) {
          hyper = 0;
          if ((argc==3) && !strcmp(argv[1],"-x")) {  // check for -x
      		hyper = 1;
      		strcpy(hyperfile,argv[2]);
      		}
      }
      
      void main() {                         // tk represents the kit
         init_ht(tk);                       // initialize package(s)
      
         if (hyper) {                      // initialize hypertext
      	hypertext* h = new hypertext(".help"); 
      	h->file(hyperfile);
      	h->geometry(330,250);
      	h->pack();
      	tk->pack(".quit");         // predefined button to quit
      	}
      }
    private:
      char hyperfile[BUFSIZ]; 
      int hyper;
    };
    
    // Define the main function
    
    int main (int argc, char* argv[]) { 
      session* s = new application(argc,argv);
      s->run();                            // start X event loop
    }
  

---

slide: A simple interpreter

---

The structure of the program is similar to the C++ example of section Example. In addition to including the hush.h header file, however, we must include the declarations needed for employing the external hypertext (ht) and distributed processing (dp) packages. Next, we need to define an application class, derived from session, specifying how the hush interpreter deals with command-line arguments and what initialization must take place before starting the main event loop. At this stage it suffices to know that the hush library provides a hypertext widget and that the -x option treats the next argument as the name of a hypertext file. In section Hypertext, an example will be given that involves the hypertext widget. Further, a predefined button .quit is packed to the root widget. The hush interpreter defined by the program extends the wish interpreter by loading the distributed processing extension and by allowing for the display of a hypertext file. The interpreter accepts any command-line argument accepted by the wish interpreter, in addition to the -x hypertext option. The Tcl interface script given in section Script, for example, may be executed using the hush interpreter.

The kit class

Hush is meant to provide a simple 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 (treated in section 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 article. However, since an instance of kit is used in almost any other object (class), it is presented here first. The reader will undoubtly gradually learn the functionality of kit by studying the examples. The class interface of kit is given below: ( Each function listed in the class interface is public unless it is explicitly indicated as protected. The interface descriptions start with the pseudo-keyword interface. This is merely done to avoid the explicit indication of public for both the ancestor and the member functions of the class. )

---

kit interface">

    interface kit { 
    
      int eval(char* cmd);       // to evaluate script commands
      char* result();            // to fetch the result of eval
      void result(char* s);      // to set the result of eval
      char* evaluate(char* cmd)  // combines eval and result
      int source(char* f);       // to load a script from file
      
      void bind(char* name, handler* h); // to bind Tcl command
      
      widget* root();            // returns toplevel (root) widget
      widget* pack(widget* w, char* options = "-side top -fill x");
      widget* pack(char* wp, char* options = "-side top -fill x";
      
      char* selection(char* options="");         // X environment
      
      void after(int msecs, char* cmd); 
      void after(int n, handler* h);
      
      void update(char* options="");
      
      char* send(char* it, char* cmd);
      
      void trace(int level = 1); 
      void notrace(); 
      void quit()                      // to terminate the session
    };
  

---

slide: The

---

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. The first group of functions (eval, result, evaluate and source) may be used to execute commands in 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::bind). 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. Also, we have the kit::bind function that may be used to associate a Tcl command with a handler object. The next group of functions is related to widgets. 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 Configure. 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 enforce that all pending events are processed. For example, when moving items on a canvas, an update may be needed for making the changes visible. Also, we have a function send 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. Further, we have the functions trace and notrace, which may be used to turn on, respectively off, tracing. The level indicates in 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.

The session class

Each program written with hush may contain only one embedded hush interpreter. To initialize the kit object wrapping the interpreter and to start the main event loop, an instance of the class session must be created. The preferred way of doing this is by defining a descendant class of the session class, redefining the virtual function session::main to specify what needs to be done before starting the main loop. In addition, the constructor of the newly defined class may be used to check command line arguments and to initialize application specific data, as illustrated in the code for the interpreter in section Interpreter.

---

    interface session  { 
      session(int argc, char** argv, char* name = 0);
      
      virtual void prelude();  
      virtual void main();
      int run( );
    protected:
      kit* tk;
    };
  

---

slide: The session class

---

When creating a session object, the name of the application may be given as the last parameter. By this name the application is known to other Tk applications, that may communicate with each other by means of the send command. Apart from the function main, also a function prelude may be defined. When the program is used as an interpreter (by giving -f file as command line arguments) only the prelude function will be executed, otherwise prelude will be executed before main. In interpreter mode, the function main will also be executed when the script contains the command go-back. Finally, the function run must be called to actually initialize the program and start the main loop.

---

intro Tcl/Tk programs handler actions to events widgets graphics appendix

---