The two obligatory arguments of a widget object are widget type and widget id.  The widget type may be a plain Tk widget class, or a predefined shortcut type.

Optionally, widget's type and id may be followed by any number of creation arguments describing widget's instance properties.  For a description of default and instance properties look further below.


The mapping from widget types to Tk widget classes is defined in widget definition files.  Usually, there should be just one setup.wid file containing all definitions.  Optionally, each shortcut type without entry in the setup.wid file, may be defined in a separate file.  The name of an individual widget definition file consists of a widget type and the .wid suffix.  Note, though, that this file will not be used, if the widget type has its entry in the main setup.wid file.

The widget definition files are searched for according to the standard Pd library loading rules.  This is done only once, when the very first widget (in case of the main file), or the first widget of a separately defined type, is created.  If there is no file setup.wid in any directory on the Pd path, the standard, built-in version of the file will be used, instead.  If no definition of a widget type is found, neither in the main file, nor in a separate file, then the type's name is assumed to refer to a Tk widget class.

The four parts of a shortcut definition are:  the header, widget options, message handlers, and initializing scriptlet.  The header part is obligatory and has to come first.  It identifies the widget type being defined, and associates with the type a class name, and, optionally, a package name.  Other parts may be omitted, their ordering is irrelevant, and they may be interleaved.  For an example of the syntax, see the file setup.wid, which is included in the snapshot release.


The widget id, which may be any symbol, is used for referencing specific widget objects.  Widgets may be grouped, or remotely controlled, for example by their tows, etc.


There are two sets of widget properties:  shortcut defaults (if loaded from widget definition file) and instance properties.  Apart from specifying instance properties in creation arguments of a widget, it is also possible to access them at any time later.  The messages to a widget enable adding new instance properties, and modifying or removing those already specified.  The set of shortcut defaults, on the other hand, cannot be modified during run-time.

The properties are Tk options, initializer's arguments, and message handlers.  An option starts with a dash-prefixed Tk option switch, and defines a Tk option for a widget.  An initializer's argument starts with a hash-prefixed name of a dot-parameter, followed by that parameter's value.  A message handler starts with a message handler selector, which has to be prefixed with at sign, and defines a Tcl handler for a Pd message.

The property message is used for adding and replacing instance properties.  Its selector is a property selector (an option switch, a dot-parameter's name, or a message handler selector) of the first property specified.  Multiple properties of various kinds are allowed in a single message.

The rules are slightly different, if the symbol set is prepended as the property message selector.  Multiple properties may still be specified, but only of a single kind.  Thus, the set message accepts, for example, hash-prefixed word as a part of an option property, instead of interpreting it as a dot-parameter's name starting an initializer's argument property.

An instance property may be removed with a remove <property-selector> message.

The precedence rules for applying options, arguments, and handlers, are as follows.  System (Tk) default options are replaced by shortcut defaults (if any), which are in turn replaced by instance options (if any).  Shortcut arguments are replaced by instance arguments of the same dot-parameter's name.  Likewise, any shortcut message handler would be replaced by an instance handler of the same message.

A widget object processes instance options and instance message handlers (but not initializer's arguments) as scriptlets.  Therefore, both creation arguments, and property messages, have to conform to all scriptlet notation peculiarities, may contain dot-names, callback sequences, dot-parameters, etc.  The same rules are valid for property lines in a widget definition file.

Message handlers may be parameterized.  When a widget object receives a Pd message, and a corresponding message handler is invoked, the handler's numbered dot-parameters are replaced with Pd message arguments.


Right after a widget has been drawn on a canvas, a set of initializing scriptlets are invoked (unless they are empty), in the following order:  the master initializer, the type initializer, and an instance initializer.

An instance initializer is to be defined with the ini message, triggered by a loadbang.

Setup scriptlet

Each widget definition file may include a special scriptlet, consisting of any number of commands, usually procedure definitions, source, or package commands, etc.  This scriptlet is executed only once, right after reading of the file.

Auxiliary messages

tot, followed by a scriptlet, invokes the widget's transient scriptlet processor, just as if the same message, was sent to a tot object.  A special widget's feature is resolving of the destination item's dot-name into a Tk pathname of a widget, while the tot leaves it unresolved.

refresh redraws a widget.  This is useful after modifying a Tk option that affects a widget's feature linked to a variable.


to be continued...

complaints to this address