path ::= . | .string | path.string

The widget class When creating a widget, a pathname must be given to the widget constructor. Pathnames may be defined relative to a parent widget. The class interface of widget is given below:

---

    interface widget : handler { 
      
      widget(char* p); 
      widget(widget& w, char* p); 
      
      char* type();                // returns type of the widget
      char* path();                // returns path of the widget
      
      int eval(char* cmd);         // invokes "thepath() cmd"
      char* result();              // returns the result of eval
      char* evaluate(char* cmd);   // combines eval and result()
      
      virtual void configure(char* cmd);  // invokes Tk configure 
      virtual void geometry(int w, int h); // determines w x h
      
      widget* pack(char* options = "" ); // maps it to the screen
      
      bind(char *b, handler* h, char* args = "" );  // binding
  
      bind(handler* h, char* args = "" );           // implicit
      
      void xscroll(scrollbar* s);        // to attach scrollbars
      void yscroll(scrollbar* s);
      
      void focus(char* options="");
      void grab(char* options="");
      
      void destroy();             // to remove it from the screen
      
      void* tkwin();  // gives access to Tk_Window implementation
      
      widget* self();            // for constructing mega widgets
      void redirect(widget* w);
  
    protected:
      char* thepath();                // delivers the virtual path
      void alias( widget* );          // to create widget command
      virtual install(binding*,char* args="");  // default bindings
      virtual direct(char* bnd, binding*, char* args=""); // effect
    };
  

---

slide: The widget interface

---

The widget class is an abstract class. Calling the constructor widget as in

  widget* w = new widget(".awry");

does not result in creating an actual widget but only defines a pointer to the widget with that particular name. If a widget with that name exists, it may be treated as an ordinary widget object, otherwise an error will occur. The constructor widget(widget* w,char* path) creates a widget by appending the pathname path to the pathname of the argument widget w. The function path delivers the pathname of a widget object. Each widget created by Tk actually defines a Tcl command associated with the pathname of the widget. In other words, an actual widget may be regarded as an object which can be asked to evaluate commands. For example a widget ".b" may be asked to change its background color by a Tcl command like

 
  .b configure -background blue

The functions eval, result and evaluate enable the programmer to apply Tcl commands to the widget directly, as does the configure command. The function geometry sets the width and height of the widget.

Packing

Naming widgets in a hierarchical fashion does not imply that the widgets behave accordingly. In particular, to position widgets properly, they must be packed in relation to one another. Packing results in displaying the widgets on the screen. The widget class interface offers two pack functions. The function widget::pack(char*) applies to individual widgets. As options one may specify for example -side X, where X is either top, bottom, left or right, to pack the widget to the appropriate side of the cavity specified by the ancestor widget. Other options are -fill x or -fill y, to fill up the space in the appropriate dimensions or -padx N or -pady N, for some integer N, to surround the widget with some extra space. As a remark, the kit::pack function may only be used to pack widgets to the root window.

Binding events

Widgets may respond to events. To associate an event with an action, an explicit binding must be specified for that particular widget. Some widgets provide default bindings. These may, however, be overruled. The function bind is used to associate handlers or bindings with events. The first string parameter of bind may be used to specify the event type. Common event types are, for example, ButtonPress, ButtonRelease and Motion, which are the default events for canvas widgets. Also keystrokes may be defined as events, as for example Return, which is the default event for the entry widget. The function widget::bind(handler*, char*) may be used to associate a handler object or action with the default bindings for the widget. Concrete widgets may not override the handler function itself, but must define the protected virtual function install. Typically, the install function consists of calls to bind for each of the event types that is relevant to the widget. Bindings are effected by the virtual function direct that may be redefined to effect the binding for multiple widgets, for example. For both the bind functions, the optional args parameter may be used to specify the arguments that will be passed to the handler or action when it is invoked. For the button widget for example, the default install function supplies the text of the button as an additional argument for its handler.

Compound widgets

In addition, the widget class offers four functions that may be used when defining compound or mega widgets. The function call redirect(w) must by used to delegate the invocation of the eval, configure, bind and handler functions to the widget w. The function self() gives access to the widget to which the commands are redirected. After invoking redirect, the function thepath will deliver the path that is determined by self()->path(). In contrast, the function path will still deliver the pathname of the outer widget. Calling redirect when creating the compound widget class suffices for most situations. However, when the default events must be changed or the declaration of a handler must take effect for several component widgets, the virtual function install must be redefined to handle the delegation explicitly. The alias function is needed when creating widgets that are also used in Tcl scripts. It creates the command corresponding to the widget's path name. How redirect and alias actually work will hopefully become clear in the examples.

Buttons

As the first component of the drawing tool, we will look at the toolbox. The toolbox is a collection of buttons packed in a frame:

---

>

    
    class toolbutton : public button {       // the toolbutton
    public:
      toolbutton(widget* w, char* name) : button(w,name) { 
          text(name);
  	bind(w,name);    // the parent becomes the handler
  	pack(); 
      }
    };
    	
    class toolbox : public frame {               // the toolbox
    public:
      toolbox(widget* w, tablet* t) : c(t), frame(w,"toolbox") { 
          button* b0 = new toolbutton(this,"draw");
          button* b1 = new toolbutton(this,"move");
          button* b2 = new toolbutton(this,"box");
          button* b3 = new toolbutton(this,"circle");
          button* b4 = new toolbutton(this,"arrow");
      }
    
      int operator()() {
  		c->mode( _event->arg(1) );     // transfer to tablet
  		return OK;
  		} 
    private:
      tablet* c;
    };
  

---

slide: The toolbutton class

---

Each individual button is an instance of the class toolbutton. When a toolbutton is created, the actual button is given the name of the button as its path. Next, the button is given the name as its text, the parent widget w is declared to be the handler for the button and the button is packed. The function text is a member function of the class button, whereas both bind and pack are common widget functions. Note that the parameter name is used as a pathname, as the text to display, and as an argument for the handler, that will passed as a parameter when invoking the handler object. The toolbox class inherits from the frame widget class, and creates a frame widget with a path relative to the widget parameter provided by the constructor. The constructor further creates the toolbuttons. The toolbox is both the parent widget and handler for each individual toolbutton. When the operator() function of the toolbox is invoked in response to pressing a button, the call is delegated to the mode function of the tablet. The argument given to mode corresponds to the name of the button pressed.

Comments

The definition of the toolbutton and toolbox illustrates that a widget need not necessarily be its own handler. The decision whether to define a subclass which is made its own handler or to install an external handler depends on what is considered the most convenient way to access the resources needed. As a guideline, exploit the regularity of the application!

Menus

The second component of our drawing tool is the menu_bar:

---

  
    class menu_bar : public menubar {          // row of menubuttons 
    public:
      menu_bar(widget* w, tablet* t, toolbox* b) : menubar(w,"bar") { 
        configure("-relief sunken"); 
    
        menubutton* b1 = new file_menu(this,t); 
        menubutton* b2 = new edit_menu(this,b);
        button* b3 = new help_button(this); 
      }
    };
  

---

slide: Our menubar class

---

The class menu_bar is derived from the hush widget menubar, which is described in the appendix. Its constructor requires an ancestor widget, a tablet and a toolbox. The tablet is passed as a parameter to the file_menu, so that the application can write to a file and read from a file. The toolbox is passed as a parameter to the edit_menu because the toolbox is employed as a handler for the edit_menu. In addition, a help_button is created, which provides on-line help in a hypertext format when pressed. The help facility will be discussed in section Hypertext. The menu_bar consists of menubuttons to which actual menus are attached. The menubutton and menu widgets are built-in widgets. They are described in the appendix. Each menu consists of a number of entries, which may possibly lead to cascaded menus. The file_menu class defines a menu, but is derived from menubutton in order to attach the menu to its menu_bar parent:

---

  
    class file_menu : public menubutton { 
    
    public:
      file_menu(widget* w, tablet* t) : c(t), menubutton(w,"file") { 
    
        configure("-relief sunken"); text("File"); pack("-side left"); 
  
        f = new file_handler(c);   // create a file_handler
    
        class menu* m = new class menu(this,"menu"); 
        this->menu(m);             // declares it for the menubutton
        m->bind(this);             // installs this as the handler
    
        m->entry("Open");
        m->entry("Save");
        m->entry("Quit");
      }
    
      int operator()() { 
  
    	if (!strcmp( _event->arg(1),"Quit")) tk->quit(); 
    	else f->dispatch( _event ); // transfer to file_handler
    	return OK;
      }
  
    protected:
      tablet* c;
      file_handler* f;
    };
  

---

slide: The file_menu class

---

The file_menu constructor defines the appearance of the button and creates a file_handler (which will be discussed in section Dialogs). It then defines the actual menu. The menu must explicitly be attached to the menubutton by invoking the function menubutton::menu. For creating the menu, the keyword class is needed to disambiguate between the creation of an instance of the class menu and the call of the menubutton::menu function. Before defining the various entries of the menu, the file_menu instance is declared as the handler for the menu entries. However, except for the entry Quit, which is handled by calling the kit::quit function, the calls are delegated to the previously created file_handler. The second button of the menu_bar is defined by the edit_menu. The edit_menu requires a toolbox and creates a menubutton. It configures the button and defines a menu containing two entries, one of which is a cascaded menu. Both the main menu and the cascaded menu are given the toolbox as a handler. This makes sense only because for our simple application, the functionality offered by the toolbox and edit_menu coincide.

Defining actions -- delegation versus inheritance

The most important component of our drawtool application is defined by the tablet class:

---

  
    class drawmode {                               // drawing modes
    public: enum { draw, move, box, circle, arrow, lastmode };
    };
      
    class tablet : public canvas {                    // the tablet
    public:
      
      tablet(widget* w, char* options="");  
      
      int operator()() {                      // according to _mode
      	return handlers [mode]->dispatch( _event );
      }
      
      void mode(char* m);                // to set the drawing mode
      
    protected:
      void init(char* options);           // initializes the tablet
      int _mode; 
      class handler* handlers[drawmode::lastmode];   // keeps modes
      canvas* c;                               // the actual canvas
    };
  

---

slide: The tablet class

---

The various modes supported by the drawing tool are enumerated in a separate class drawmode. The tablet class itself inherits from the canvas widget class. This has the advantage that it offers the full functionality of a canvas. In addition to the constructor and operator() function, which delegates the incoming event to the appropriate handler according to the _mode variable, it offers a function mode, which sets the mode of the canvas as indicated by its string argument, and a function init that determines the creation and geometrical layout of the component widgets. As instance variables, it contains the integer _mode variable and an array of handlers that contains the handlers corresponding to the modes supported. See section Canvas for an example of a typical canvas handler.

Dispatching

Although the tablet must act as a canvas, the actual tablet widget is nothing but a frame that contains a canvas widget as one of its components. This is reflected in the definition of the tablet constructor and the way it invokes the canvas constructor.

---

>

    tablet::tablet(widget* w, char* options) : canvas(w,"tablet",0) { 
      widget* top = new frame(path());
  
      init(options);                          // inialization, layout
      redirect(c);                            // redirect to canvas
      bind(this);                             // this is the handler
  
      handlers[drawmode::draw] = new draw_handler(this);
      handlers[drawmode::move] = new move_handler(this);
      handlers[drawmode::box] = new box_handler(this);
      handlers[drawmode::circle] = new circle_handler(this);
      handlers[drawmode::arrow] = new arrow_handler(this);
      _mode = drawmode::draw;
    }
  

---

slide: The tablet constructor

---

By convention, when the options parameter is 0 instead of the empty string, no actual widget is created but only an abstract widget, as happens when calling the widget class constructor. Instead of creating a canvas rightaway, the tablet constructor creates a top frame, initializes the actual component widgets, and redirects the eval, configure, bind and handler invocations to the canvas child widget. It then declares itself to be its own handler, which results in declaring itself to be the handler for the canvas component. Note that reversing the order of calling redirect and handler would be disastrous, since the bindings resulting from calling handler would then be defined not for the canvas but for the frame containing the canvas. After that it creates the handlers for the various modes and sets the initial mode to draw. The operator() function takes care of dispatching calls to the appropriate handler. The dispatch function must be called to pass the event information.

Creating new widgets

Having taken care of the basic components of the drawing tool, that is the toolbox, menu_bar and tablet widgets, all that remains to be done is to define a suitable file_handler, appropriate handlers for the various drawing modes and a help_handler. This will be done in sections Dialogs, Canvas and Hypertext, respectively. However, before that we will look at how to define the drawtool widget class such that we may also declare a corresponding drawtool script command. The actual declaration of the drawtool command is done in the application class defined below, which will by now look familiar, except for the function prelude:

      
    class application : public session {              
    public:
      application(int argc, char* argv[])
  				: session(argc,argv,"drawtool") {}
      
      void prelude( ) {
      	tk->bind("drawtool", new drawtool());    // declare
      }
      
      void main( kit* tk, int, char* argv[] ) {
      	drawtool* d = new drawtool(".draw");
      	tk->bind("drawtool",d);                // override
      	d->pack();
      }
    };
  

In the body of the prelude function, the Tcl command drawtool is declared, with an instance of drawtool as its handler. In this way, the drawtool widget is made available as a command when the program is used as an interpreter. However, in the function main this declaration is overridden. Instead, the actual drawtool widget is made the handler of the command, in order to allow for a script to address the drawtool by calling drawtool self, as will be explained later.

Since an instance of drawtool may also be used as simply a handler for the drawtool command, the drawtool class must offer a constructor that creates no widget, in addition to a constructor that does create a drawtool widget:

---

    class drawtool : public canvas { 
    public:
      drawtool() : canvas() {  }                        // no widget
      drawtool(char* p, char* opts="") : canvas(p,0) {  
  	top = new frame(path(),"-class Drawtool");  // outer frame
      	init(opts);
      	redirect(c);                      // redirect to tablet
  	alias( top );              // to declare widget command
      }
                                           
      // Define the semantics of the drawtool command
  
      int operator()(){                     
      	if (!strcmp("self",argv[1]) )                     // self
  			   tk->result(self()->path());
      	else if ( !strcmp( "drawtool" ,*argv) )           // create
  			   create(--argc,++argv); 
      	else                                              // eval
  			   self()->eval( flatten(--argc,++argv) );
      	return OK;
      }
      
    protected:
      wiget* top;                                      // outer frame
      tablet* c;                                   // inner component
      
      void init(char* options);
  
      // To create a new drawtool widget and corresponding command
  
      void create(int argc, char* argv[]) {    
        char* name = *argv;
        new drawtool(name, flatten(--argc,++argv));
      }
    };
  

---

slide: The drawtool class

---

The drawtool widget constructor redirects itself to the tablet widget, which is initialized by calling init. The drawtool::operator() function defines the semantics of the drawtool script command. When the first argument of the call is drawtool, a new drawtool widget is created, except when the second argument is self. In that case, the virtual path of the widget is returned, which is actually the path of the tablet's canvas. As an example of a script employing self consider

    set x [drawtool self]
    \$x create rectangle 100 20 160 80 
    \$x create rectangle 90 30 150 90 
    \$x create oval 120 40 170 90
  

Evaluating the script results in the drawing displayed in figure Drawtool. Such a script may be read in by using the Open option in the File menu (see section Dialogs).

If neither of these cases apply, the function widget::eval is invoked for self(), with the remaining arguments flattened to a string. This makes it possible to use the drawtool almost as an ordinary canvas as illustrated above and in the example hypertext script shown in section Hypertext. The creation of the actual widget and declaration of the corresponding Tcl command, according to the Tk convention, is somewhat more involved. Recall that each Tk widget is identified by its path, which simultaneously defines a command that may be used to configure the widget or, as for a canvas, to draw figures on the screen. Hence, the function create must create a new widget and declare the widget to be the handler of the command corresponding to its pathname.

Discussion

By now you may have lost track of how delegation within a compound widget takes place. Hopefully, a brief look at the implementation will clarify this. Each eval, configure or bind function call for a widget results in a command addressed at the path of the widget. By redirecting the command to a different path, the instructions may be delegated to the appropriate (component) widget. Delegation occurs, in other words, by directing the commands to the widget's virtual path, which is obtained by the protected function thepath(). In contrast, the function path() delivers the path of the widget's outer component. Indirection takes place by invoking the function self(), which relies on an instance variable _self that may be set by the redirect function.

---

---

slide: Dereferencing self()

---

Figure Dereferencing represents the evaluation of self() for drawtool in a pictorial way. Dereferencing ultimately results in addressing commands to the canvas widget, because of the redirections declared for drawtool and tablet. The implementation of thepath() and self() is simply:

    char* thepath() { return self()->path(); }
    widget* self() { return _self?_self->self():this; }
  

Hence, resolving a compound widget's primary inner component relies on simple pointer chasing, which may be applied recursively to an arbitrary depth at acceptable costs.

Dialogs

Interactive applications may require the user to type some input after reading a message or to select an item from a list of alternatives. One of the widgets that may be used in a dialog with the user is a file_chooser widget as depicted in figure Filechooser.

---

---

slide: A filechoose

---

Despite its simple appearance, the file_chooser widget has some subtle complexities. The file_chooser class is given below: file_chooser class">>

    class file_chooser : public toplevel {              // toplevel 
  
      file_chooser() : toplevel( gensym("filechooser") ) { init(); }
  
      int operator()();
      char* get() { return e->get(); }
  
    protected:
      button* b; button *c;                          // OK and CANCEL 
      entry* e; listbox* l;
      int install(char* s, binding* a, char* opts);
      void init();
      void list();
    };
  

The file_chooser widget consists of a listbox filled with filenames and an entry widget that contains the filename selected by the user (by double clicking on the name) or which may, alternatively, be used to type in a filename directly. In addition, the file_chooser has an OK button, to confirm the choice and a CANCEL button, to break off the dialog. Typically, a file_chooser is a toplevel widget, that is a widget that is independently mapped to the screen. To avoid name clashes the function gensym, which delivers a system-wide unique name (with filechooser as a prefix), is used to determine its path. Apart from the operator() function, the file_chooser has only one public function get, which delivers the name selected or typed in by the user. The widget components of the file_chooser, two buttons and the entry and listbox widgets, are stored in its instance variables. Further, we have a function init to construct the actual file_chooser widget, a function list to fill the listbox and the function install, which is used to install an external handler for the two button widgets. The install function is defined as

  void file_chooser::install(binding* a, char* args) {
   	b->handler(a,args);
    	c->handler(a,args);
  }

Recall, that when declaring a handler for a button, the name of the button is given as an additional argument when invoking the handler. This enables the file_handler to distinguish between a call due to pressing the OK button and a call due to pressing the CANCEL button. The interplay between the C++ definition and the underlying Tcl/Tk toolkit is nicely illustrated by the definition of the list function.

 void file_chooser::list() {
   sprintf(buf,"foreach i [glob *.tcl] { %s insert end $$i }",
						     l->path());
   tk->eval( buf );
  }

Calling list results in filling the listbox with the filenames in the current directory. Its corresponding definition in C++ would, no doubt, be much more involved.

The file_handler class

Window-based interactive applications differ from ordinary interactive applications by relying on an event-driven flow of control. The indirection that is typical for event-driven control is exemplified in the definition of the file_handler depicted below (recall that the file_handler was employed by the file_menu described in section Menus):

---

>

      
    class file_handler : public handler {
    public:
      file_handler( canvas* x ) : c(x) {}
  
      int operator()() {
  	char* key = _event->arg(1);
      	if (!strcmp("Open", key)) launch("OPEN");
      	else if (!strcmp("Save", key)) launch("SAVE");
      	else if (!strcmp("OPEN", key)) open();
      	else if (!strcmp("SAVE", key)) save();
      	return OK;
      }
  
    protected:
      canvas* c;
      file_chooser* f;
      
      void launch(char* args) {       // launch new filechooser
      	f = new file_chooser();
      	f->handler(this, args);
      }
  
      void open() { tk->source( f->get() ); f->destroy(); }
      void save() { c->postscript( f->get() ); f->destroy(); }
    };
  

---

slide: The file_handler class

---

Since the file_handler does not correspond to an actual widget when created, its constructor merely stores the canvas pointer, which is actually a pointer to the tablet. In response to the Open or Save menu entries, the file_handler launches a file_chooser and declares itself to be the handler (with the appropriate arguments). For example, when selecting the Open entry, the file_chooser is launched which eventually calls the file_handler::dispatch$$ function with OPEN as its argument. The file_handler then invokes the open function, which results in reading in the file and destroys the file_chooser. In a similar way, the menu entry Save results in writing the canvas to a postscript file. (The code for checking whether the OK or CANCEL button is pressed is left as an exercise.)

---

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

---

Graphics and hypertext

---

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

---

[-<--%--^-->-] The Tk toolkit offers powerful facilities for graphics and (hyper)text. See Ousterhout93. In this section we discuss the canvas widget offered by Tk. Instead of looking at the text widget provided by Tk, we will (briefly) look at the hypertext widget, which presents an alternative approach to defining hyperstructures.

The item class

The canvas widget allows the programmer to create a number of built-in graphic items. Items are given a numerical index when created and, in addition, they may be given a (string) tag. Tags allow items to be manipulated in a group-wise fashion. To deal with items in a C++ context, the hush library contains a class item of which the functionality is shown below.

---

    interface item { 
      operator int();                        // returns item index
      
      void configure(char* cmd);    // calls canvas::itemconfigure
      
      void tag(char* s);                      // sets tag for item
      char* tags();              // delivers tags set for the item
      void move(int x, int y);
      
      bind(char *b, handler* h, char* args = "" );
      bind(char *b, binding* ac, char* args = "" );
      
      handler(class handler* h, char* args = "" );
      handler(binding* ac, char* args = "" );
      
    protected:
      virtual install(action&,char* args="");    // default bindings
    };
  

---

slide: The item interface

---

Instances of item may not be created directly by the user, but instead are created by the canvas widget. For an item, its index may be obtained by casting the item to int. If the index does not identify an existing item, it will be zero. Existing items may be moved, in a relative way, by the function move. In a similar way as for widgets, items may be associated with events, either explicitly by using item::bind, or implicitly by using item::handler. The default bindings for items are identical to the default bindings for the canvas widget, but these may be overridden by descendant classes. Similar as the widget class, the item class is derived from the handler class. This allows the user to define possibly compound shapes that have their own handlers.

The canvas widget

The Tk canvas widget offers powerful means for doing structured graphics. The hush class canvas provides merely a simplified interface to the corresponding Tk widget. As an example of the use of a canvas, consider the definition of the move_handler below. The move_handler defines one of the modes of the tablet and allows for moving graphical items on the canvas.

---

  
    class move_handler : public handler { 
    public:
      
      move_handler( canvas* cv ) : c(cv) { dragging = 0; }
      
      void press( event& e ) {     // if overlapping start dragging
      	  x = e.x(); y = e.y();     
      	  id = c->overlapping(x, y);
      	  if (id) dragging = 1;
      }
      
      void motion( event& e ) {                  // if dragging move
        if (dragging) {                
      	id.move( e.x() - x, e.y() - y );
      	x = e.x(); y = e.y();
      	}
      }
      
      void release( event&  ) { dragging = 0; }     // stop dragging
      
    protected:
      canvas* c; int dragging; item id; int x,y;
    };
  

---

slide: Moving items on a canvas

---

The move_handler class is derived from the class handler. It makes use of the dispatch and operator() function defined for handler, but redefines the (virtual) functions press, motion and release. When creating an instance of move_handler, a pointer to the canvas must be given to the constructor. In addition, the class has data members to record position coordinates and whether a particular item is being moved. Actually moving an item occurs by pressing the (left) mouse button on an item and dragging the item along. When the mouse button is released, moving stops. To identify the item, the function overlapping is used. The movement is determined by the distance between the last recorded position and the current position of the cursor. In an analogous manner, a box_handler may be defined, which is used for drawing rectangles and allows for rubberbanding. The box_handler sets dragging to true when the button is pressed and creates a rectangle of zero width and height. Each time the function motion is called, the item created in the previous round is deleted and a new rectangle is created:

---

    void box_handler::motion( event& e ) {   // if dragging stretch
        if (dragging) {
  	id.del();
  	id = c->rectangle(x,y,e.x(),e.y());  // x and y are fixed
      	}
      }
  

---

slide: A box handler

---

where c is a pointer to the canvas and x and y the button pointer coordinates stored when dragging began. For circles and lines, it suffices to replace the call to rectangle with a call to the appropriate figure creation function.

---

---

slide: Hypertext help

---

The hypertext widget

Both the Tk canvas and text widget allow to bind actions to particular items and hence to define dynamically what we may call hyperstructures. A different, in a way more static, approach is offered by the hypertext widget originally developed by George Howlett. %%george.howlett@att.com. The hypertext widget may be used to display text files containing embedded Tcl code. The Tcl code must be placed between escapes, that take the form of %% for both the begin and end of the code. A screen shot of a fragment of the on-line help for drawtool is given in figure Help. Notice, that the on-line help provides a replica of the drawtool application, surrounded by text. When looking at (again a fragment of) the hypertext file specifying the contents of the on-line help, given below, you see that the drawtool command defined in section new is employed to create the embedded widget:

---

>

    Rubber banding: press the left mouse button
    and release when the rectangle is of appropriate
    size
        %%
    drawtool \$this.draw 
    \$this append \$this.draw 
    \$this.draw create rectangle 20 20 80 80
    \$this.draw create rectangle 10 30 70 90
    \$this.draw create oval 40 40 90 90
    \$this append \$this.draw 
    %%
    For additional information click on the %% 
    button \$this.goto -text instruction -command end-of-text
    \$this append \$this.goto
    %%
    button.  Press %%
    button \$this.quit -command { destroy . } -text quit -bg pink
    \$this append quit
    %% to remove the window.
  

---

slide: Rubber banding

---

When specifying the hypertext file, widgets may be given a pathname relative to the pathname of the hypertext widget by using the variable this. In addition the hypertext widget offers the variables thisline and thisfile to identify the current line number and current file name. Any of the widgets and commands offered by Tcl/Tk or supported by hush may be included in a hypertext file, including the ones defined by the program itself.

---

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

---

Conclusions

[-<--%--^-->-] The Tcl/Tk toolkit offers very versatile means to create graphical user interfaces and couple these with programs written in C. However, from the point of view of object oriented programming and the use of Tcl/Tk in a C++ context, the standard interface does not suffice. The hush library is meant to provide a flexible, yet easy to use, and above all simple, interface for Tcl/Tk in C++. To some extent, it may be regarded as syntactic sugar of an object oriented flavor, merely simplifying the interface already provided by Tcl/Tk. However, hush improves on the standard Tcl C interface by providing the opportunity to employ handler objects, allowing the programmer to deal in a type-secure way with client information associated with events. In addition, the hush library allows for the definition of composite widgets with the behavior of one of the standard widgets. To support such composite widgets, each widget has a virtual path that coincides with the widget's own path, unless it is redirected to an inner component widget. Composite widgets may be nested to arbitrary depth. This solution has the advantage that the composite widget may be given an already familiar interface, both in C++ and Tcl, with a minimum of coding. The approach embodied by hush is intended to allow the novice programmer to develop graphical user interfaces easily, however, without restricting experienced and more demanding programmers, who may gradually exploit the full functionality offered by Tk and extend this by using C++.

Acknowledgement

I would like to thank Paula Ferguson from The X Resource for her detailed advice on improving the readability of the original article. Acknowledgements are also due to Jacco van Ossenbruggen, Martijn van Welie and Bastiaan Sch\"onhage for their suggestions, their contributions to the extensions of hush, and their unrelenting insistence on conceptual clarity.

Appendix: The hush widget classes

---

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

---

[-<--%--^-->-] The hush widget class library encapsulates the standard Tk widgets. In addition, a hypertext widget is offered. The widget classes are organized as a tree, with the class widget at the root.

---

---

slide: Widget classes

---

Each concrete widget class offers the functionality supported by the (abstract) widget class and may in addition define functions specific to the particular widget class. The member function for a widget class have usually a straightforward correspondence with the command interface defined by the Tcl/Tk toolkit. See Ousterhout94 for the most recent description. Each widget class specifies two constructors, one with only a path and one which allows both for a widget and a path. In the latter case, the actual path consists of the concatenation of the path of the widget and the path specified by the string parameter. For the concrete widget classes, no widget will be created when the options parameter is zero. This convention is adopted to allow composite widgets to inherit from the standard widgets, yet define their own components. In addition, each widget class has a destructor, which is omitted for brevity. The destructor may be used to reclaim the storage for a widget object. To remove a widget from the screen, the function widget::destroy must be used.

The scale class

The scale widget may be used to obtain numerical input from the user.

---

    interface scale : widget { 
  
      scale(char* p, char* options = "");
      scale(widget* w, char* p, char* options = "");
  
      void text(char* s);                        // text to display
      void from(int n);                          // begin value
      void to(int n);                            // end value
      int get();                                 // gets the value
      void set(int v);                           // sets the value
  
    protected:
      install(binding*, char* args);
    };
  

---

slide: The scale class

---

When a handler is attached to a scale it is called when the user releases the slider. The value of the scale is passed as an additional parameter when the handler is invoked. The default binding for the scale is the ButtonRelease event.

The message class

The message widget may be used to display a message on the screen.

---

    interface message : widget { 
  
      message(char* p, char* options = "" );
      message(widget* w, char* p, char* options = "" );
      
      void text(char* s);                               // the text
    };
  

---

slide: The message class

---

The message class does not define default bindings, but the user is free to associate events to a message widget by employing widget::bind.

The button class

Buttons come in a number of varieties, such as ordinary (push) buttons, that simply invoke an action, checkbuttons, that toggle between an on and off state, and radiobuttons, that may be used to constrain buttons to allow the selection of only a single alternative. Checkbuttons and radiobuttons are implemented as subclasses of the class button, and will not be further discussed here.

---

    interface button : widget { 
  
      button(char* p, char* options = "");
      button(widget* w, char* p, char* options = "");
      
      void text(char* s);                    // text to display
      void bitmap(char* s);                  // to display a bitmap
      
      void state(char *s);            // to change the buttons state
      
      void flash();
      char* invoke();
  
    protected:
      install(binding*,char* args);           // default binding
    };
  

---

slide: The button class

---

In addition to the constructors, which have the same format for each widget class, the button class offers the function text to define the text displayed by the button and the function bitmap, which takes as argument the name of a file containing a bitmap, to have a bitmap displayed instead. The function state may be used to change the state of the button. Legal arguments are either normal, active or disabled. Further, the button class defines the function flash and invoke that result respectively in flashing the button and in invoking the action associated with the button by means of the widget::handler function. (Note that button::install is defined, albeit protected.)

The menubutton class

The menubutton is a specialization of the button widget. It allows for attaching a menu that will be displayed when pressing the button.

---

    interface menubutton : button { 
      
      menubutton(char* p, char* options = "");
      menubutton(widget* w, char* p, char* options = "");
      
      void menu(char* s);                    // to attach a menu
      void menu(class menu* m);
    };
  

---

slide: The menubutton class

---

The menubutton must be used to pack menus in a menubar.

The menu class

A menu consists of a number of button-like entries, each associated with an action. A menu entry may also consist of another menu, that pops up whenever the entry is selected.

---

    interface menu : widget { 
      
      menu(char* p, char* options = "");
      menu(widget* w, char* p, char* options = "");
      
      menu* add(char* s, char* options = "");
      
      menu* entry(char* s, char* args ="", char* options="");
      menu* entry(char* s, binding* ac, char* args="", char* opts="");
      
      menu* cascade(char* s, char* m, char* options = "");
      menu* cascade(char* s, menu* m, char* options = "");
      
      char* entryconfigure(int i, char* options);
      
      int index(char *s);
      int active();                    // returns active index
      
      void del(int i);                 // delete entry with index i
      void del(char* s);               // delete entry with tag s 
      
      char* invoke(int i);             // invoke entry with index i
      char* invoke(char *s );          // invoke entry with tag s
      
      void post(int x = 500, int y = 500); 
      void unpost();
  
    protected:
      install(binding*, char* args);
    };
  

---

slide: The menu class

---

The add function is included to allow arbitrary entries (as defined by Tk) to be added. We restrict ourselves to simple command and cascade entries. The entry function (that is used for adding simple command entries) may explicitly be given a binding to be associated with the entry. Alternatively, if no binding is specified, the default handler binding installed by invoking widget::bind will be used. The string used as a label for the entries (the first parameter of entry) will be given as a parameter to the action invoked when selecting the entry. The string given in the args parameter will be added to the actual parameters for the action invoked. The cascade function may either be given a menu or a string, containing the pathname of the menu. In any case the cascaded menu must be a child of the original menu. The function index returns the integer index associated with the string describing the entry. The function active may be used to inquire which entry has been selected. Entries may be deleted using the function del and invoked by using invoke. For both functions, the entry may be indicated by its numerical index or a string. Menus are toplevel widgets, they are mapped to the screen either by invoking the function post, or by pressing the menubutton to which the menu is attached.

The canvas class

Apart from the two standard constructors, it offers the functions tag, tags and move that merely repeat the functions offered by the item class, except that move may also be given a tag to identify the items to be moved.

---

    interface canvas : widget { 
  
      canvas(char *p, char* options="");
      canvas(widget* w, char *p, char* options="");
      
      void tag(int id, char* tag);
      char* tags(int id);
      
      void move(int id, int x, int y);
      void move(char* id, int x, int y);
      
      item bitmap(int x1, int y1, char* bitmap, char* options="");
      item line(int x1, int y1, int x2, int y2, char* options="");
      item line(char* linespec, char* options="");
      item circle(int x1, int y1, int rad, char* options="");
      item oval(int x1, int y1, int x2, int y2, char* options="");
      item polygon(char* linespec, char* options="");
      item rectangle(int x1, int y1, int x2, int y2, char* options="");
      item text(int x1, int y1, char* txt, char* options=""); 
      item window(int x1, int y1, char* win, char* options="");
      item window(int x1, int y1, widget* win, char* options="");
      
      item current();
      item overlapping(int x, int y);
      
      itemconfigure(int it, char* options);
      itemconfigure(char* tag, char* options);
      itembind(int it, char* s, binding* a, char* args = "" );
      itembind(char* tag, char* s, binding* a, char* args = "" );
      
      void postscript(char* file, char* options="");
  
    protected:
      install(binding*, char* args);
    };
  

---

slide: The canvas class

---

Currently, the graphic items bitmap, line, oval, polygon and rectangle may created and, in addition, text items and window items consisting of a widget. The function overlapping may be used to retrieve the item overlapping a particular position. In addition, the canvas class offers auxiliary functions needed to support the functionality provided by the item class. The canvas may be written as Postscript to a file with the function canvas::postscript.

The frame class

Frame widgets may used to combine widgets. A frame has no functionality or bindings of its own.

---

    interface frame : widget { 
      
      frame(char* p, char * options = "");
      frame(widget* w, char* p, char * options = "");
    };
  

---

slide: The frame class

---

The frame widget class has the toplevel and menubar as subclasses. The toplevel widget is used when the widget must be independently mapped to the screen. The menubar widget is used as a special frame to collect button widgets including menubutton widgets.

The scrollbar class

The scrollbar allows the user to scroll through widgets that are only partly displayed.

---

    interface scrollbar : widget { 
  
      scrollbar(char* p, char* options = "");
      scrollbar(widget* w, char* p, char* options = "");
  
      void orient(char* opts="vertical");   // orientation
      xview(widget* w);                     // widget to scroll
      yview(widget* w);                     // widget to scroll
    };
  

---

slide: The scrollbar class

---

The default orientation of a scrollbar is vertical. A scrollbar must be explicitly attached to a widget w by calling the scrollbar::yview functions for vertical scrollbars and scrollbar::xview for horizontal scrollbars. To obtain the proper geometrical layout, the scrollbar and the widget it controls must usually be packed in a frame.

The listbox class

The listbox widget is used to allow the user to select an item from a list of alternatives.

---

    interface listbox : widget { 
      
      listbox(char* p, char* options = "");
      listbox(widget* w, char* p, char* options = "");
      
      void insert(char* s);
      char* get(int d);             // entry with index d
      
      void singleselect();
  
    protected:
      install(binding*, char* args);
    };
  

---

slide: The listbox class

---

The listbox may be filled by using insert. When a handler is attached to the widget, it is activated when the user double clicks on an item. The selected entry is passed as an additional parameter to the handler. The entry may also be obtained by either kit::selection or listbox::get.

The entry class

An entry widget may be used to display text or allow the user to type a short text.

---

    interface entry : widget { 
  
      entry(char* p, char* options = "");
      entry(widget* w,char* p, char* options = "");
      
      void insert(char* s);                    // insert text
      char* get();                         // to get the text
  
    protected:
      install(binding*, char* args);
    };
  

---

slide: The entry class

---

When a handler is attached to the entry widget it is activated whenever the user double clicks on the widget or presses the return key. The contents of the entry are added as an argument when calling the handler.

The hypertext class

The hypertext widget may be used to display text with embedded Tcl code.

---

    interface hypertext : widget {
  
      hypertext(char* p, char* options = "");
      hypertext(widget* w, char* p, char* options = "");
      
      void file(char* f);         // to read in hypertext file
    };
  

---

slide: The hypertext class

---

Apart from the standard constructors, it offers the function file to read in a hypertext file. Such a hypertext file allows to embed widgets in the text by inserting them in escape sequences.

---

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

---