Widget.A basic GUI component used in Tcl/Tk programming is a widget. A GUI widget can be created, packed, reconfigured, bound, and destroyed. It can be implemented in Tcl/Tk scripts, "C" language, as well as the combination of both. A widget can be either a generic widget (e.g., a Tk build-in widget), or a combined one that is made of these generic widgets in Tcl. In addition to be a GUI component, a widget can be any types of objects that accept messages in a standard protocol such as configure, cget, and etc. In XBit, any objects that are configurable are considered as widgets in the following discussions. 

Generic Widget. A generic widget is one that complies with the protocol of a Tcl/Tk widget creation, and configuration. A generic GUI widget also complies with the protocol of pack, place, grid, bind, and destroy of Tk. It is created by a widget command (e.g., frame, label, button, canvas, etc.). Once it is created, it is assigned a pathname, a Tcl command name, and can be manipulated with the following command syntax called generic widget protocol: 

widgetCmd pathname
pathname configure ?options?
pathname cget -varName
pathname otherCmds ...
pack pathname ?options?
place pathname ?options?
grid pathname ?options?
bind pathname <Event> ?scripts?
destroy pathname

Combined Widget. GUI of XBit is built upon combined widgets. A combined widget can be made of generic widgets. It has two levels of structures: a structure of a combined widget and structures of offspring sub-widgets. A sub-widget can also be a combined widget. A combined widget is created by a combined widget command. Once it is created, it is assigned a pathname, and can be manipulated with the following command syntax called combined widget protocol: 

cwidget.create pathname ?options?
cwidget.config pathname ?options?
cwidget.cget pathname -varName
cwidget.bind pathname -varName <Event> ?scripts?
cwidget.otherCmds pathname ...
pack pathname ?options?
place pathname ?options?
grid pathname ?options?
destroy pathname

Options, -varName and varList. A comb-widget is configured with options in a same way as a generic widget is configured. Options of a comb-widget consists of "-varName value" pairs. A -varName identifies a variable used in a comb-widget and a value specifies the variable's value. A -varName can also refers to an offspring sub-widget. In this case, the value is an option list that is used for the sub-widget configuration. An ?option? or ?options? can also be a -varName. In this case, it is used in a query of the value of that particular option. This protocol can be recursively applied to any offspring sub-widgets. A varList can be either a single -varName or a list of -varNames. There are two senarios a varList may be used. In the first senario, a varList refers to a varName of a sub-widget. Each -varName except for the last one refers to a lower layer sub-widget and the last -varName refers to the variable name of the refered sub-widget. In the second senario, it refers to a sub-widget in a lower hierarchic level. Each -varName in a varList refers to a lower layer sub-widget than the one the previous -varName refers to. A varList of a single -varName means a sub-widget and a varList of two -varNames means a grand-sub-widget, and so on so forth. 

The following example is the creation and configuration of a frame container widget, frm: 

# creation
frm.create .f -label {-text TEST} 

# configuration CASE I: 
frm.config .f {-label -bg} grey {-label -fg} red 

# configuration CASE II: 
frm.config .f -label {-bg grey -fg red} 

cwidget.bind pathname event scripts varList. This command binds the event of a sub-widget refered to by the varList with the scripts. 

cwidget.cget pathname -varName. This command retrieves the confiuration for a given -varName. If the -varName identifies a variable, its value is returned. If the -varName refers to a sub-widget, the configuration of the sub-widget is returned. 

cwidget.config pathname ?options?. This command configures the combined widget with the given options. If the ?options? is -varName, a configuration option for that -varName is returned. If the ->varName refers to a sub-widget, the command returns a list of the sub-widget configuration, {-varName pathname class options}. The second element pathname is the pathname of the sub-widget, the third element class is the class name of the widget and the last element of the list is the configuration optoins of that sub-widget. 

cwidget.create pathname ?options?. This command creates a combined widget with the given pathname and configures the widget with the given options. 

cwidget.otherCmds pathname .... This is the other applicaiton command. 

Notice that the name convention of a widget command consists of two parts separated by a period. The left part is the class of a widget, and the right part is the name of a message for that type of widget. The pathname uniquely identifies a particular widget instance, and the ?options? provide additional information about the attributes of a particular widget instance. 

Comb - An Abstract Widget. Comb is an abstract widget that is not used as a real GUI component, or an object. However, it provides a frame, basic procedures, and a unified message protocol for efficient Tcl/Tk programming of a combined widget. The basic Comb procedures are comb.config, comb.cget, comb.bind, comb.class, comb.parse and comb.free. A global array variable _comb and its well-defined index protocol are used as a frame for a combined widget implementation. A widget configuration variable is allocated in a _comb(pathname,ID), where the pathname identifies the widget, and the ID refers to the variable. An ID can be either a cf-varName or a -varName. A _comb(pathname,cf-varName) is allocated for the configuration value of the -varName. If the -varName refers to a sub-widget, a _comb(pathname,-varName) is allocated for the pathname of the sub-widget. Notice that, a pathname that identifies a combined widget, also identifies a generic Tk widget, which is the root of all the offspring sub-widgets. It is strongly recommended that these procedures are wrapped with application specific names such as cwidget.config, cwidget.cget, cwidget.bind, and cwidget.free. 

comb.bind pathname event scripts varList. This command binds an event of a sub-widget referred to by the varList to the scripts. The script may be appended to the current ones if +scripts is specified instead of scripts. If the event is not specified, the current event is returned. If the scripts is not specified, the current scripts is returned. If varList is not specified, the command bind pathname event scripts is invoked 

comb.class pathname. This command retrieves the class name of the widget. If the pathname is a comb-widget, the class name of the comb-widget is returned. Otherwise, the generic class name of the widget is returned. If pathname is invalid, an empty string is returned. To distinguish a generic widget from a comb-widget, the class name of a comb-widget always starts with a low-case letter. 

comb.config pathname ?opitons?. This command configures the combined widget, pathname, with the given options. An option can refer to either a variable of the combined widget, or an option of an internal sub-widget. In the latter case, the option value is a list of options for the sub-widget. If only a -varName is given for ?options?, comb.config returns the configuration information for that option. If the -varName is a variable of the comb-widget, its value is returned. If the -varName is an sub-widget, a list is returned. If the -varName is an option of the host widget (i.e., the generic widget), a generic configuration for that option is performed. The first element of the list is the -varName, the second element is tthe pathname of the sub-widget, the third element is the class and the last element is a list of options that was used in a previous widget creation or configuration. If no options are given, comb.config returns the configuration information for all the options. If the widget identified by the pathname is not a comb-widget, the command pathname config ?options? is invoked. 

comb.cget pathname -varName. This command retrieves the value of an option of a -varName that was configured previously. If the widget identified by the pathname is not a comb-widget, the command pathname cget -varName is invoked. 

comb.dir pathname. This command returns a list. The first element of the list is the class name of the widget, and the rest of the elements are all available options of the combined widget. 

comb.exec pathname cmd -varName args. This command executes a Tcl command that is applied for an sub-widget referred to by -varName. The syntax of the Tcl command is: cmd path args. 

comb.free pathname. This command should be called after the combined widget is destroyed. It frees the variables allocated during the life time of the widget. 

comb.get pathname varID. This command retrieves the value of a comb-widget variable referred to by a varID. A varID may have three different forms: -varName, cf-varName, and STRING. A -varName refers to the pathname of a sub-widget. A cf-varName refers to the configuration of a sub-widget referred to by -varName. A STRING may refer to other variables used in the comb-widget. 

comb.id pathname varList. This command retrieves the id or the pathname of a sub-widget addressed to by the varList. 

comb.parse pathname ?option?. This command parses ?options? to the global variable _comb. This command should only be invoked after all the variables have been initialized. The procedure checks the input ?options? against the existing variables, and parses the values into the corresponding _comb(pathname,cf-varName). This procedure may be called by a cwidget.create procedure in a new widget creation. 

comb.validID pathaname -varName. This command checks to see if the -varName is a valid id for a sub-widget. It returns a '1' for a valid id and a '0' otherwise. 

comb.validPath pathname status. This command checks to see if the pathname is a valid combined widget. It returns a 1 if the pathname is valid, and a 0 if the pathname is invalid. The status is either a "new" or others. To check a pathname before a widget is created, the status should be "new". 

comb.validClass pathname class. This command checks to see if the pathname has the right class type. In order to distinguish different classes of combined widgets, a global variable _comb(pathname,class) is used to store a unique id for a widget class at the time of the widget creation. This command returns a '1' if the pathname's class id matches the input class parameter. Otherwise, it returns a '0'. If the input class is not given, the command returns the class of the widget. 

[HOME][CONTENTS][DOWNLOAD]