classBuilder(3gk)

NAME

classBuilder - Syntax summary and overview of GroupKit's mega-widget facilities.

REQUIREMENTS

Tcl 7.3 and Tk 3.6 (or later versions)

AVAILABILITY

This Tcl/Tk extension included in the GroupKit distribution

TERMINOLOGY

Mega-widget

A widget composed of one or more widgets that behaves like a standard Tk widget.

Component Widgets

The individual widgets that a mega-widget is comprised of.

Root Window

The window which encompasses the entire mega-widget.

Classname

Throughout this manual page, classname refers to the name of the widget class or type of the widget.

DESCRIPTION

The GroupKit class builder makes building mega-widgets that behave like standard Tk widgets easier. A widget is defined by both its class data and widget specific data. Class data includes all the options, subcommands and bindings that are identical for an entire class of widgets whereas widget data may be different for different widgets. The class builder initializes both sets of data.

All Tk widgets have two main components: a data structure and a widget command. Both of these have the same name as the widget's path name, which can cause confusion. The one being referred to can be determined by the context.

Class Data Structure

This is one of the two basic data structures used by the class builder; it defines attributes for the class of widgets. his array is created only once and the values are stored in the global array classname.

classname(inherit) inheritanceList

Denotes which class(es), if any, a particular widget class inherits its options and widget subcommands from. What is inherited is based on the order the classes appear in the list; the first one in the list is given highest priority. Any widget class defined by this class builder any standard Tcl/Tk classes and widgets defined by other class(widget) builders are valid entries. It is assumed that all widgets in the inheritance list are defined. For more information on option handling see classname_Config and for more inofmation on subcommands see

classname(rootOptions) optionList

The options that are not specific to the class itself. Typically, contains the inherited options. There is usually no need to add to the list, since by specifying the inheritance the list will be created automatically.

classname(options) optionList

The options that are unique to the particular class of widgets; these are not inherited. See classname(optionName) for more information.

classname(methods) methodList

The methods ( commands ) that can be applied to widgets whose class is classname. It includes the methods that are inherited as well as the methods that are unique to the class. See classname_Methods for more information.

classname(optionName) {abbreviation optionName} , or classname(optionName) {optionName objectName className classValue}

optionName is a particular option usually specified in either the root option list or the option list. There must be a class definition for each one of the options of a class.

classname(rootWindow) widgetClass

This specifies the type of root window. If it is not specified, then a Tk frame widget is used for the root Window.

Widget Data Structure

This is the second data structure that is created by the class builder , and it is created for each widget whose class is classname. It defines the properties of a particular widget and ( unlike the class data ) it may change over time. The widget record is an array whose name is the same as the widget's window path name. A useful technique is to store the window path names of the subwidgets in the widget data structure; this makes it easy to retrieve the path names later.

data(class) class

The class type the widget belongs to.

data(className) className

The class name the widget belongs to.

data(rootCmd) pathName

The window path name of the root widget or window. This widget type is specified by classname(rootWindow).

data(optionName) objectValue

Defines the default object value for a particular option. If none is specified then the object option value is defined to be the class option value which may have been inherited.

data(tmpOptionName) objectValue

The value of the object value is determined from the arguments given to a widget when it is created. This allows access to the option/optionValue pairs given when the widget is created. These variables exist from the time the request is made to create the widget until it is completely constructed by the widget builder.

Creating A Widget Class

There are a number of procedures that may or may not be defined in order to create a widget class. The GroupKit class builder gets its information from these procedures in order to create the new widget class. However the widget builder need only define the classname procedure. Those that are not defined are defined automatically by the widget builder.

classname pathName args

This procedure is called when a widget of the class classname is created. Typically it just calls gkInt_CreateWidget with the appropriate arguments and returns the widget's path name.

classname_Cget pathName optionName

This procedure allows the widget builder to over-ride the default procedure for the cget command. If an error occurs then the default behavior, returning the value stored in the widget record, is attempted.

classname_Config pathName optionName args

The configuration routine is activated whenever the configure command is invoked on a widget and specifies what is to be done when an option value is changed. Note that the optionName and args will each have a single value, not a list of values, this routine can only operate on a single option at any given time. If an error occurs in this routine and the option specified is valid, then an attempt will be made to apply the command to the root widget which is the default action of this procedure.

classname_ConstructWidget pathName

This procedure constructs the widget. Often it consists of the creation and packing of a number of component widgets. Normally, the component widgets are created within the root widget. It is useful, although not necessary, to store the path name for each of the component widgets in the widget's data record. The default procedure does nothing.

classname_CreateClassRec pathName class className

This procedure defines the class options, commands, inheritance, and the root window - all the items discussed in the class data structure section. Any of the undefined items are an empty list by default. The class record must be made a global variable so that widgets of this type can be constructed.

classname_CreateWidgetRoot pathName

This procedure allows the widget builder to over-ride the default mechanism for creating the root widget. It allows any widget to be the root widget. The preferred method is to specify classname(rootWindow).

classname_DestroyWidget pathName

Defines what is to be done when a widget of the particular class is destroyed. The default method is to do nothing.

classname_InitWidgetRec pathName class className

Defines the default values for a widget's data structure. Typically defines all of the items discussed in the widget data structure section as well as other variables needed for the widget.

classname_Methods pathName command args

This procedure defines what action to take when any of the commands are invoked ( except for configure and cget ). See classname_Config and classname_Cget sections for more details on these commands. If the application of this method causes error then an attempt to apply the method to the root window is made.

classname_SetWidgetBindings pathName

Defines the various bindings for the class; the default procedure does nothing.

Using A New Widget Class

Mega-widgets designed with the class builder are used the same way the standard Tk widgets are.

The syntax for creating a widget of a particular class:

class pathName ?option OptionValue ....?

The syntax for using widget commands

pathName command ?args?

FILES

GroupKit/classBuilder/gkClassBuiler: source file

KEYWORDS

Tcl, Tk, widget, mega-widget

AUTHOR

Shannon Jaeger ([email protected])