---
name: "classBuilder"
section: "3gk"
platform: "linux"
package: "groupkit"
version: "3.2-1"
release: "Debian 1.3 (Bo)"
platforms: ["linux"]
url: "https://new.carta.tech/classBuilder"
---

# classBuilder(3gk)

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

## 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

## SEE ALSO

p.TP 40 **GroupKit/classBuilder/Label.tcl** sample file

- **GroupKit/classBuilder/FancyLabel.tcl**

  sample file

- **GroupKit/classBuiler/FrameLabel.tcl**

  sample file

- **GroupKit/docs/userman.ps**

  user manual

- **GroupKit/widgets/\***

  ## KEYWORDS

Tcl, Tk, widget, mega-widget

## AUTHOR

Shannon Jaeger (jaeger@cpsc.ucalgary.ca)