TYPE AND WIDGET DEFINITIONS

Snit provides the following commands for defining new types:

snit::type name definition

Defines a new abstract data type called name. If name is not a fully qualified command name, it is assumed to be a name in the namespace in which the snit::type command was called (usually the global namespace). It returns the fully qualified name of the new type.

The type name is then a command that is used to create objects of the new type, along with other activities.

The snit::type definition block is a script that may contain the following definitions:

snit::widget name definition

This command defines a Snit megawidget type with the specified name. The definition is defined as for snit::type. A snit::widget differs from a snit::type in these ways:

snit::widgetadaptor name definition

This command defines a Snit megawidget type with the specified name. It differs from snit::widget in that the instance's hull component is not created automatically, but is created in the constructor and installed using the installhull command. Once the hull is installed, its instance command is renamed and replaced as with normal snit::widgets. The original command is again accessible in the instance variable hull.

Note that in general it is not possible to change the widget class of a snit::widgetadaptor's hull widget.

See The Tk Option Database for information on how snit::widgetadaptors interact with the option database.

snit::typemethod type name arglist body

Defines a new type method (or redefines an existing type method) for a previously existing type.

snit::method type name arglist body

Defines a new instance method (or redefines an existing instance method) for a previously existing type. Note that delegated instance methods can't be redefined.

snit::macro name arglist body

Defines a Snit macro with the specified name, arglist, and body. Macros are used to define new type and widget definition statements in terms of the statements defined in this man page.

A macro is simply a Tcl proc that is defined in the slave interpreter used to compile type and widget definitions. Thus, macros have access to all of the type and widget definition statements. See Macros and Meta-programming for more details.

The macro name cannot be the same as any standard Tcl command, or any Snit type or widget definition statement, e.g., you can't redefine the method or delegate statements, or the standard set, list, or string commands.

snit::compile which type body

Snit defines a type, widget, or widgetadaptor by "compiling" the definition into a Tcl script; this script is then evaluated in the Tcl interpreter, which actually defines the new type.

This command exposes the "compiler". Given a definition body for the named type, where which is type, widget, or widgetadaptor, snit::compile returns a list of two elements. The first element is the fully qualified type name; the second element is the definition script.

snit::compile is useful when additional processing must be done on the Snit-generated code--if it must be instrumented, for example, or run through the TclDevKit compiler. In addition, the returned script could be saved in a ".tcl" file and used to define the type as part of an application or library, thus saving the compilation overhead at application start-up. Note that the same version of Snit must be used at run-time as at compile-time.

THE TYPE COMMAND

A type or widget definition creates a type command, which is used to create instances of the type. The type command has this form:

$type typemethod args...

The typemethod can be any of the Standard Type Methods (e.g., create), or any type method defined in the type definition. The subsequent args depend on the specific typemethod chosen.

The type command is most often used to create new instances of the type; hence, the create method is assumed if the first argument to the type command doesn't name a valid type method, unless the type definition includes delegate typemethod * or the -hasinstances pragma is set to false.

Furthermore, if the -hastypemethods pragma is false, then Snit type commands can be called with no arguments at all; in this case, the type command creates an instance with an automatically generated name. In other words, provided that the -hastypemethods pragma is false and the type has instances, the following commands are equivalent:

snit::type dog { ... }
set mydog [dog create %AUTO%]
set mydog [dog %AUTO%]
set mydog [dog]
    

This doesn't work for Snit widgets, for obvious reasons.

Snit 1.x Incompatibility: In Snit 1.x, the above behavior is available whether -hastypemethods is true (the default) or false.

STANDARD TYPE METHODS

In addition to any type methods in the type's definition, all type and widget commands will usually have at least the following subcommands:

$type create name ?option value ...?

Creates a new instance of the type, giving it the specified name and calling the type's constructor.

For snit::types, if name is not a fully-qualified command name, it is assumed to be a name in the namespace in which the call to snit::type appears. The method returns the fully-qualified instance name.

For snit::widgets and snit::widgetadaptors, name must be a valid widget name; the method returns the widget name.

So long as name does not conflict with any defined type method name the create keyword may be omitted, unless the type definition includes delegate typemethod * or the -hasinstances pragma is set to false.

If the name includes the string %AUTO%, it will be replaced with the string $type$counter where $type is the type name and $counter is a counter that increments each time %AUTO% is used for this type.

By default, any arguments following the name will be a list of option names and their values; however, a type's constructor can specify a different argument list.

As of Snit V0.95, create will throw an error if the name is the same as any existing command--note that this was always true for snit::widgets and snit::widgetadaptors. You can restore the previous behavior using the -canreplace pragma.

$type info typevars ?pattern?

Returns a list of the type's type variables (excluding Snit internal variables); all variable names are fully-qualified.

If pattern is given, it's used as a string match pattern; only names that match the pattern are returned.

$type info typemethods ?pattern?

Returns a list of the names of the type's type methods. If the type has hierarchical type methods, whether locally-defined or delegated, only the first word of each will be included in the list.

If the type definition includes delegate typemethod *, the list will include only the names of those implicitly delegated type methods that have been called at least once and are still in the type method cache.

If pattern is given, it's used as a string match pattern; only names that match the pattern are returned.

$type info args method

Returns a list containing the names of the arguments to the type's method, in order. This method cannot be applied to delegated type methods.

$type info body method

Returns the body of typemethod method. This method cannot be applied to delegated type methods.

$type info default method aname varname

Returns a boolean value indicating whether the argument aname of the type's method has a default value (true) or not (false). If the argument has a default its value is placed into the variable varname.

$type info instances ?pattern?

Returns a list of the type's instances. For snit::types, it will be a list of fully-qualified instance names; for snit::widgets, it will be a list of Tk widget names.

If pattern is given, it's used as a string match pattern; only names that match the pattern are returned.

Snit 1.x Incompatibility: In Snit 1.x, the full multi-word names of hierarchical type methods are included in the return value.

$type destroy

Destroys the type's instances, the type's namespace, and the type command itself.

THE INSTANCE COMMAND

A Snit type or widget's create type method creates objects of the type; each object has a unique name that is also a Tcl command. This command is used to access the object's methods and data, and has this form:

$object method args...

The method can be any of the Standard Instance Methods, or any instance method defined in the type definition. The subsequent args depend on the specific method chosen.

STANDARD INSTANCE METHODS

In addition to any delegated or locally-defined instance methods in the type's definition, all Snit objects will have at least the following subcommands:

$object configure ?option? ?value? ...

Assigns new values to one or more options. If called with one argument, an option name, returns a list describing the option, as Tk widgets do; if called with no arguments, returns a list of lists describing all options, as Tk widgets do.

Warning: This information will be available for delegated options only if the component to which they are delegated has a configure method that returns this same kind of information.

Note: Snit defines this method only if the type has at least one option.

$object configurelist optionlist

Like configure, but takes one argument, a list of options and their values. It's mostly useful in the type constructor, but can be used anywhere.

Note: Snit defines this method only if the type has at least one option.

$object cget option

Returns the option's value.

Note: Snit defines this method only if the type has at least one option.

$object destroy

Destroys the object, calling the destructor and freeing all related memory.

Note: The destroy method isn't defined for snit::widget or snit::widgetadaptor objects; instances of these are destroyed by calling Tk's destroy command, just as normal widgets are.

$object info type

Returns the instance's type.

$object info vars ?pattern?

Returns a list of the object's instance variables (excluding Snit internal variables). The names are fully qualified.

If pattern is given, it's used as a string match pattern; only names that match the pattern are returned.

$object info typevars ?pattern?

Returns a list of the object's type's type variables (excluding Snit internal variables). The names are fully qualified.

If pattern is given, it's used as a string match pattern; only names that match the pattern are returned.

$object info typemethods ?pattern?

Returns a list of the names of the type's type methods. If the type has hierarchical type methods, whether locally-defined or delegated, only the first word of each will be included in the list.

If the type definition includes delegate typemethod *, the list will include only the names of those implicitly delegated type methods that have been called at least once and are still in the type method cache.

If pattern is given, it's used as a string match pattern; only names that match the pattern are returned.

Snit 1.x Incompatibility: In Snit 1.x, the full multi-word names of hierarchical type methods are included in the return value.

$object info options ?pattern?

Returns a list of the object's option names. This always includes local options and explicitly delegated options. If unknown options are delegated as well, and if the component to which they are delegated responds to $object configure like Tk widgets do, then the result will include all possible unknown options that can be delegated to the component.

If pattern is given, it's used as a string match pattern; only names that match the pattern are returned.

Note that the return value might be different for different instances of the same type, if component object types can vary from one instance to another.

$object info methods ?pattern?

Returns a list of the names of the instance's methods. If the type has hierarchical methods, whether locally-defined or delegated, only the first word of each will be included in the list.

If the type definition includes delegate method *, the list will include only the names of those implicitly delegated methods that have been called at least once and are still in the method cache.

If pattern is given, it's used as a string match pattern; only names that match the pattern are returned.

Snit 1.x Incompatibility: In Snit 1.x, the full multi-word names of hierarchical type methods are included in the return value.

$object info args method

Returns a list containing the names of the arguments to the instance's method, in order. This method cannot be applied to delegated methods.

$object info body method

Returns the body of the instance's method method. This method cannot be applied to delegated methods.

$object info default method aname varname

Returns a boolean value indicating whether the argument aname of the instance's method has a default value (true) or not (false). If the argument has a default its value is placed into the variable varname.

COMMANDS FOR USE IN OBJECT CODE

Snit defines the following commands for use in your object code: that is, for use in type methods, instance methods, constructors, destructors, onconfigure handlers, oncget handlers, and procs. They do not reside in the ::snit:: namespace; instead, they are created with the type, and can be used without qualification.

mymethod name ?args...?

The mymethod command is used for formatting callback commands to be passed to other objects. It returns a command that when called will invoke method name with the specified arguments, plus of course any arguments added by the caller. In other words, both of the following commands will cause the object's dosomething method to be called when the $button is pressed:

    $button configure -command [list $self dosomething myargument]
    $button configure -command [mymethod dosomething myargument]
    

The chief distinction between the two is that the latter form will not break if the object's command is renamed.

mytypemethod name ?args...?

The mytypemethod command is used for formatting callback commands to be passed to other objects. It returns a command that when called will invoke type method name with the specified arguments, plus of course any arguments added by the caller. In other words, both of the following commands will cause the object's dosomething type method to be called when $button is pressed:

    $button configure -command [list $type dosomething myargument]
    $button configure -command [mytypemethod dosomething myargument]
    

Type commands cannot be renamed, so in practice there's little difference between the two forms. mytypemethod is provided for parallelism with mymethod.

myproc name ?args...?

The myproc command is used for formatting callback commands to be passed to other objects. It returns a command that when called will invoke the type proc name with the specified arguments, plus of course any arguments added by the caller. In other words, both of the following commands will cause the object's dosomething proc to be called when $button is pressed:

    $button configure -command [list ${type}::dosomething myargument]
    $button configure -command [myproc dosomething myargument]
    

myvar name

Given an instance variable name, returns the fully qualified name. Use this if you're passing the variable to some other object, e.g., as a -textvariable to a Tk label widget.

mytypevar name

Given an type variable name, returns the fully qualified name. Use this if you're passing the variable to some other object, e.g., as a -textvariable to a Tk label widget.

from argvName option ?defvalue?

The from command plucks an option value from a list of options and their values, such as is passed into a type's constructor. argvName must be the name of a variable containing such a list; option is the name of the specific option.

from looks for option in the option list. If it is found, it and its value are removed from the list, and the value is returned. If option doesn't appear in the list, then the defvalue is returned. If the option is locally-defined option, and defvalue is not specified, then the option's default value as specified in the type definition will be returned instead.

install compName using objType objName args...

Creates a new object of type objType called objName and installs it as component compName, as described in Components and Delegation. Any additional args... are passed along with the name to the objType command. If this is a snit::type, then the following two commands are equivalent:

    install myComp using myObjType $self.myComp args...
    set myComp [myObjType $self.myComp args...]
    

Note that whichever method is used, compName must still be declared in the type definition using component, or must be referenced in at least one delegate statement.

If this is a snit::widget or snit::widgetadaptor, and if options have been delegated to component compName, then those options will receive default values from the Tk option database. Note that it doesn't matter whether the component to be installed is a widget or not. See The Tk Option Database for more information.

install cannot be used to install type components; just assign the type component's command name to the type component's variable instead.

installhull using widgetType args...

installhull name

The constructor of a snit::widgetadaptor must create a widget to be the object's hull component; the widget is installed as the hull component using this command. Note that the installed widget's name must be $win. This command has two forms.

The first form specifies the widgetType and the args... (that is, the hardcoded option list) to use in creating the hull. Given this form, installhull creates the hull widget, and initializes any options delegated to the hull from the Tk option database.

In the second form, the hull widget has already been created; note that its name must be "$win". In this case, the Tk option database is not queried for any options delegated to the hull. The longer form is preferred; however, the shorter form allows the programmer to adapt a widget created elsewhere, which is sometimes useful. For example, it can be used to adapt a "page" widget created by a BWidgets tabbed notebook or pages manager widget.

See The Tk Option Database for more information about snit::widgetadaptors and the option database.

variable name

Normally, instance variables are defined in the type definition along with the options, methods, and so forth; such instance variables are automatically visible in all instance code (e.g., method bodies). However, instance code can use the variable command to declare instance variables that don't appear in the type definition, and also to bring variables from other namespaces into scope in the usual way.

It's generally clearest to define all instance variables in the type definition, and omit declaring them in methods and so forth.

Note that this is an instance-specific version of the standard Tcl ::variable command.

typevariable name

Normally, type variables are defined in the type definition, along with the instance variables; such type variables are automatically visible in all of the type's code. However, type methods, instance methods and so forth can use typevariable to declare type variables that don't appear in the type definition.

It's generally clearest to declare all type variables in the type definition, and omit declaring them in methods, type methods, etc.

varname name

Deprecated. Use myvar instead.

Given an instance variable name, returns the fully qualified name. Use this if you're passing the variable to some other object, e.g., as a -textvariable to a Tk label widget.

typevarname name

Deprecated. Use mytypevar instead.

Given a type variable name, returns the fully qualified name. Use this if you're passing the type variable to some other object, e.g., as a -textvariable to a Tk label widget.

codename name

Deprecated. Use myproc instead. Given the name of a proc (but not a type or instance method), returns the fully-qualified command name, suitable for passing as a callback.

COMPONENTS AND DELEGATION

When an object includes other objects, as when a toolbar contains buttons or a GUI object contains an object that references a database, the included object is called a component. The standard way to handle component objects owned by a Snit object is to declare them using component, which creates a component instance variable. In the following example, a dog object has a tail object:

    snit::type dog {
        component mytail
        constructor {args} {
            set mytail [tail %AUTO% -partof $self]
            $self configurelist $args
        }
        method wag {} {
            $mytail wag
        }
    }
    snit::type tail {
        option -length 5
        option -partof
        method wag {} { return "Wag, wag, wag."}
    }

Because the tail object's name is stored in an instance variable, it's easily accessible in any method.

The install command provides an alternate way to create and install the component:

    snit::type dog {
        component mytail
        constructor {args} {
            install mytail using tail %AUTO% -partof $self
            $self configurelist $args
        }
        method wag {} {
            $mytail wag
        }
    }

For snit::types, the two methods are equivalent; for snit::widgets and snit::widgetadaptors, the install command properly initializes the widget's options by querying The Tk Option Database.

In the above examples, the dog object's wag method simply calls the tail component's wag method. In OO jargon, this is called delegation. Snit provides an easier way to do this:

    snit::type dog {
        delegate method wag to mytail
        constructor {args} {
            install mytail using tail %AUTO% -partof $self
            $self configurelist $args
        }
    }

The delegate statement in the type definition implicitly defines the instance variable mytail to hold the component's name (though it's good form to use component to declare it explicitly); it also defines the dog object's wag method, delegating it to the mytail component.

If desired, all otherwise unknown methods can be delegated to a specific component:

    snit::type dog {
	delegate method * to mytail
	constructor {args} {
	    set mytail [tail %AUTO% -partof $self]
	    $self configurelist $args
	}
	method bark { return "Bark, bark, bark!" }
    }

In this case, a dog object will handle its own bark method; but wag will be passed along to mytail. Any other method, being recognized by neither dog nor tail, will simply raise an error.

Option delegation is similar to method delegation, except for the interactions with the Tk option database; this is described in The Tk Option Database.

TYPE COMPONENTS AND DELEGATION

The relationship between type components and instance components is identical to that between type variables and instance variables, and that between type methods and instance methods. Just as an instance component is an instance variable that holds the name of a command, so a type component is a type variable that holds the name of a command. In essence, a type component is a component that's shared by every instance of the type.

Just as delegate method can be used to delegate methods to instance components, as described in Components and Delegation, so delegate typemethod can be used to delegate type methods to type components.

Note also that as of Snit 0.95 delegate method can delegate methods to both instance components and type components.

THE TK OPTION DATABASE

This section describes how Snit interacts with the Tk option database, and assumes the reader has a working knowledge of the option database and its uses. The book Practical Programming in Tcl and Tk by Welch et al has a good introduction to the option database, as does Effective Tcl/Tk Programming.

Snit is implemented so that most of the time it will simply do the right thing with respect to the option database, provided that the widget developer does the right thing by Snit. The body of this section goes into great deal about what Snit requires. The following is a brief statement of the requirements, for reference.

• If the snit::widget's default widget class is not what is desired, set it explicitly using widgetclass in the widget definition.
• When defining or delegating options, specify the resource and class names explicitly when if the defaults aren't what you want.
• Use installhull using to install the hull for snit::widgetadaptors.
• Use install to install all other components.

The interaction of Tk widgets with the option database is a complex thing; the interaction of Snit with the option database is even more so, and repays attention to detail.

Setting the widget class: Every Tk widget has a widget class. For Tk widgets, the widget class name is the just the widget type name with an initial capital letter, e.g., the widget class for button widgets is "Button".

Similarly, the widget class of a snit::widget defaults to the unqualified type name with the first letter capitalized. For example, the widget class of

    snit::widget ::mylibrary::scrolledText { ... }

is "ScrolledText". The widget class can also be set explicitly using the widgetclass statement within the snit::widget definition.

Any widget can be used as the hulltype provided that it supports the -class option for changing its widget class name. See the discussion of the hulltype command, above. The user may pass -class to the widget at instantion.

The widget class of a snit::widgetadaptor is just the widget class of its hull widget; this cannot be changed unless the hull widget supports -class, in which case it will usually make more sense to use snit::widget rather than snit::widgetadaptor.

Setting option resource names and classes: In Tk, every option has three names: the option name, the resource name, and the class name. The option name begins with a hyphen and is all lowercase; it's used when creating widgets, and with the configure and cget commands.

The resource and class names are used to initialize option default values by querying the Tk option database. The resource name is usually just the option name minus the hyphen, but may contain uppercase letters at word boundaries; the class name is usually just the resource name with an initial capital, but not always. For example, here are the option, resource, and class names for several text widget options:

    -background         background         Background
    -borderwidth        borderWidth        BorderWidth
    -insertborderwidth  insertBorderWidth  BorderWidth
    -padx               padX               Pad

As is easily seen, sometimes the resource and class names can be inferred from the option name, but not always.

Snit options also have a resource name and a class name. By default, these names follow the rule given above: the resource name is the option name without the hyphen, and the class name is the resource name with an initial capital. This is true for both locally-defined options and explicitly delegated options:

    snit::widget mywidget {
        option -background
        delegate option -borderwidth to hull
        delegate option * to text
	# ...
    }

In this case, the widget class name is "Mywidget". The widget has the following options: -background, which is locally defined, and -borderwidth, which is explicitly delegated; all other widgets are delegated to a component called "text", which is probably a Tk text widget. If so, mywidget has all the same options as a text widget. The option, resource, and class names are as follows:

    -background  background  Background
    -borderwidth borderwidth Borderwidth
    -padx        padX        Pad

Note that the locally defined option, -background, happens to have the same three names as the standard Tk -background option; and -pad, which is delegated implicitly to the text component, has the same three names for mywidget as it does for the text widget. -borderwidth, on the other hand, has different resource and class names than usual, because the internal word "width" isn't capitalized. For consistency, it should be; this is done as follows:

    snit::widget mywidget {
	option -background
	delegate option {-borderwidth borderWidth} to hull
	delegate option * to text
	# ...
    }

The class name will default to "BorderWidth", as expected.

Suppose, however, that mywidget also delegated -padx and -pady to the hull. In this case, both the resource name and the class name must be specified explicitly:

    snit::widget mywidget {
	option -background
	delegate option {-borderwidth borderWidth} to hull
	delegate option {-padx padX Pad} to hull
	delegate option {-pady padY Pad} to hull
	delegate option * to text
	# ...
    }

Querying the option database: If you set your widgetclass and option names as described above, Snit will query the option database when each instance is created, and will generally do the right thing when it comes to querying the option database. The remainder of this section goes into the gory details.

Initializing locally defined options: When an instance of a snit::widget is created, its locally defined options are initialized as follows: each option's resource and class names are used to query the Tk option database. If the result is non-empty, it is used as the option's default; otherwise, the default hardcoded in the type definition is used. In either case, the default can be overridden by the caller. For example,

    option add *Mywidget.texture pebbled
    snit::widget mywidget {
	option -texture smooth
	# ...
    }
    mywidget .mywidget -texture greasy

Here, -texture would normally default to "smooth", but because of the entry added to the option database it defaults to "pebbled". However, the caller has explicitly overridden the default, and so the new widget will be "greasy".

Initializing options delegated to the hull: A snit::widget's hull is a widget, and given that its class has been set it is expected to query the option database for itself. The only exception concerns options that are delegated to it with a different name. Consider the following code:

    option add *Mywidget.borderWidth 5
    option add *Mywidget.relief sunken
    option add *Mywidget.hullbackground red
    option add *Mywidget.background green
    snit::widget mywidget {
	delegate option -borderwidth to hull
	delegate option -hullbackground to hull as -background
	delegate option * to hull
	# ...
    }
    mywidget .mywidget
    set A [.mywidget cget -relief]
    set B [.mywidget cget -hullbackground]
    set C [.mywidget cget -background]
    set D [.mywidget cget -borderwidth]

The question is, what are the values of variables A, B, C and D?

The value of A is "sunken". The hull is a Tk frame that has been given the widget class "Mywidget"; it will automatically query the option database and pick up this value. Since the -relief option is implicitly delegated to the hull, Snit takes no action.

The value of B is "red". The hull will automatically pick up the value "green" for its -background option, just as it picked up the -relief value. However, Snit knows that -hullbackground is mapped to the hull's -background option; hence, it queries the option database for -hullbackground and gets "red" and updates the hull accordingly.

The value of C is also "red", because -background is implicitly delegated to the hull; thus, retrieving it is the same as retrieving -hullbackground. Note that this case is unusual; in practice, -background would probably be explicitly delegated to some other component.

The value of D is "5", but not for the reason you think. Note that as it is defined above, the resource name for -borderwidth defaults to "borderwidth", whereas the option database entry is "borderWidth". As with -relief, the hull picks up its own -borderwidth option before Snit does anything. Because the option is delegated under its own name, Snit assumes that the correct thing has happened, and doesn't worry about it any further.

For snit::widgetadaptors, the case is somewhat altered. Widget adaptors retain the widget class of their hull, and the hull is not created automatically by Snit. Instead, the snit::widgetadaptor must call installhull in its constructor. The normal way to do this is as follows:

    snit::widgetadaptor mywidget {
	# ...
	constructor {args} {
	    # ...
	    installhull using text -foreground white
	    #
	}
	#...
    }

In this case, the installhull command will create the hull using a command like this:

    set hull [text $win -foreground white]

The hull is a text widget, so its widget class is "Text". Just as with snit::widget hulls, Snit assumes that it will pick up all of its normal option values automatically; options delegated from a different name are initialized from the option database in the same way.

Initializing options delegated to other components: Non-hull components are matched against the option database in two ways. First, a component widget remains a widget still, and therefore is initialized from the option database in the usual way. Second, the option database is queried for all options delegated to the component, and the component is initialized accordingly--provided that the install command is used to create it.

Before option database support was added to Snit, the usual way to create a component was to simply create it in the constructor and assign its command name to the component variable:

    snit::widget mywidget {
	delegate option -background to myComp
	constructor {args} {
	    set myComp [text $win.text -foreground black]
	}
    }

The drawback of this method is that Snit has no opportunity to initialize the component properly. Hence, the following approach is now used:

    snit::widget mywidget {
	delegate option -background to myComp
	constructor {args} {
	    install myComp using text $win.text -foreground black
	}
    }

The install command does the following:

• Builds a list of the options explicitly included in the install command -- in this case, -foreground.
• Queries the option database for all options delegated explicitly to the named component.
• Creates the component using the specified command, after inserting into it a list of options and values read from the option database. Thus, the explicitly included options (-foreground) will override anything read from the option database.
• If the widget definition implicitly delegated options to the component using delegate option *, then Snit calls the newly created component's configure method to receive a list of all of the component's options. From this Snit builds a list of options implicitly delegated to the component that were not explicitly included in the install command. For all such options, Snit queries the option database and configures the component accordingly.

Non-widget components: The option database is never queried for snit::types, since it can only be queried given a Tk widget name. However, snit::widgets can have non-widget components. And if options are delegated to those components, and if the install command is used to install those components, then they will be initialized from the option database just as widget components are.

MACROS AND META-PROGRAMMING

The snit::macro command enables a certain amount of meta-programming with Snit classes. For example, suppose you like to define properties: instance variables that have set/get methods. Your code might look like this:

    snit::type dog {
        variable mood happy
        method getmood {} {
            return $mood
        }
        method setmood {newmood} {
            set mood $newmood
        }
    }

That's nine lines of text per property. Or, you could define the following snit::macro:

    snit::macro property {name initValue} {
        variable $name $initValue
        method get$name {} "return $name"
        method set$name {value} "set $name \$value"
    }

Note that a snit::macro is just a normal Tcl proc defined in the slave interpreter used to compile type and widget definitions; as a result, it has access to all the commands used to define types and widgets.

Given this new macro, you can define a property in one line of code:

    snit::type dog {
        property mood happy
    }

Because a single slave interpreter is used for compiling all Snit types and widgets in the application, there's the possibility of macro name collisions. If you're writing a reuseable package using Snit, and you use some snit::macros, define them in your package namespace:

    snit::macro mypkg::property {name initValue} { ... }
    snit::type dog {
        mypkg::property mood happy
    }

VALIDATION TYPES

A validation type is an object that can be used to validate Tcl values of a particular kind. For example, snit::integer is used to validate that a Tcl value is an integer.

Every validation type has a validate method which is used to do the validation. This method must take a single argument, the value to be validated; further, it must do nothing if the value is valid, but throw an error if the value is invalid:

    snit::integer validate 5     ;# Does nothing
    snit::integer validate 5.0   ;# Throws an error (not an integer!)

The validate method will always return the validated value on success, and throw the -errorcode INVALID on error.

Snit defines a family of validation types, all of which are implemented as snit::type's. They can be used as is; in addition, their instances serve as parameterized subtypes. For example, a probability is a number between 0.0 and 1.0 inclusive:

    snit::double probability -min 0.0 -max 1.0

    probability validate 0.5   ;# Does nothing
    probability validate 7.9   ;# Throws an error

    snit::enum ::dog::breed -values {mutt retriever sheepdog}
    snit::type dog {
        # Define subtypes on the fly...
        option -breed -type {
            snit::enum -values {mutt retriever sheepdog}
        }
        # Or use predefined subtypes...
        option -breed -type ::dog::breed
    }

Any object that has a validate method with the semantics described above can be used as a validation type; see Defining Validation Types for information on how to define new ones.

Snit defines the following validation types:

snit::boolean validate ?value?

snit::boolean name

Validates Tcl boolean values: 1, 0, on, off, yes, no, true, false. It's possible to define subtypes--that is, instances--of snit::boolean, but as it has no options there's no reason to do so.

snit::double validate ?value?

snit::double name ?option value...?

Validates floating-point values. Subtypes may be created with the following options:

snit::enum validate ?value?

snit::enum name ?option value...?

Validates that a value comes from an enumerated list. The base type is of little use by itself, as only subtypes actually have an enumerated list to validate against. Subtypes may be created with the following options:

snit::fpixels validate ?value?

snit::fpixels name ?option value...?

Tk programs only. Validates screen distances, in any of the forms accepted by winfo fpixels. Subtypes may be created with the following options:

snit::integer validate ?value?

snit::integer name ?option value...?

Validates integer values. Subtypes may be created with the following options:

snit::listtype validate ?value?

snit::listtype name ?option value...?

Validates Tcl lists. Subtypes may be created with the following options:

snit::pixels validate ?value?

snit::pixels name ?option value...?

Tk programs only. Validates screen distances, in any of the forms accepted by winfo pixels. Subtypes may be created with the following options:

snit::stringtype validate ?value?

snit::stringtype name ?option value...?

Validates Tcl strings. The base type is of little use by itself, since very Tcl value is also a valid string. Subtypes may be created with the following options:

snit::window validate ?value?

snit::window name

Tk programs only. Validates Tk window names. The value must cause winfo exists to return true; otherwise, the value is invalid. It's possible to define subtypes--that is, instances--of snit::window, but as it has no options at present there's no reason to do so.

DEFINING VALIDATION TYPES

There are three ways to define a new validation type: as a subtype of one of Snit's validation types, as a validation type command, and as a full-fledged validation type similar to those provided by Snit. Defining subtypes of Snit's validation types is described above, under Validation Types.

The next simplest way to create a new validation type is as a validation type command. A validation type is simply an object that has a validate method; the validate method must take one argument, a value, return the value if it is valid, and throw an error with -errorcode INVALID if the value is invalid. This can be done with a simple proc. For example, the snit::boolean validate type could have been implemented like this:

    proc ::snit::boolean {"validate" value} {
        if {![string is boolean -strict $value]} {
            return -code error -errorcode INVALID \
                "invalid boolean \"$value\", should be one of: 1, 0, ..."
        }
        return $value
    }

Finally, one can define a full-fledged, subtype-able validation type as a snit::type. Here's a skeleton to get you started:

    snit::type myinteger {
        # First, define any options you'd like to use to define
        # subtypes.  Give them defaults such that they won't take
        # effect if they aren't used, and marked them "read-only".
        # After all, you shouldn't be changing their values after
        # a subtype is defined.
        #
        # For example:
        option -min -default "" -readonly 1
        option -max -default "" -readonly 1
        # Next, define a "validate" type method which should do the
        # validation in the basic case.  This will allow the
        # type command to be used as a validation type.
        typemethod validate {value} {
            if {![string is integer -strict $value]} {
                return -code error -errorcode INVALID \
                    "invalid value \"$value\", expected integer"
            }
            return $value
        }
        # Next, the constructor should validate the subtype options,
        # if any.  Since they are all readonly, we don't need to worry
        # about validating the options on change.
        constructor {args} {
            # FIRST, get the options
            $self configurelist $args
            # NEXT, validate them.
            # I'll leave this to your imagination.
        }
        # Next, define a "validate" instance method; its job is to
        # validate values for subtypes.
        method validate {value} {
            # First, call the type method to do the basic validation.
            $type validate $value
            # Now we know it's a valid integer.
            if {("" != $options(-min) && $value < $options(-min))  ||
                ("" != $options(-max) && $value > $options(-max))} {
                # It's out of range; format a detailed message about
                # the error, and throw it.
                set msg "...."
                return -code error -errorcode INVALID $msg
            }
            # Otherwise, if it's valid just return it.
            return $valid
        }
    }

The file "validate.tcl" in the Snit distribution defines all of Snit's validation types; you can find the complete implementation for snit::integer and the other types there, to use as examples for your own types.