snit(3tcl)

📦

version 2.0 · 2 versions

2.0 · debian trixie, ubuntu questing, ubuntu resolute, ubuntu stonking (latest)
1.21 · debian bookworm, ubuntu jammy, ubuntu noble

, in debian trixie, ubuntu questing, ubuntu resolute, ubuntu stonking

snit(3tcl) — Snit's Not Incr Tcl, OO system, and it's giving pure-Tcl royalty 👑✨

✨ NAME ✨

snit — Snit's Not Incr Tcl

💖 SYNOPSIS 💖

Okay bestie, here's the full vibe check of every command and form, no cap:

package require Tcl 8.5 9

package require snit ?2.3.4?

snit::type name definition

typevariable name ?-array? ?value?

typemethod name arglist body

typeconstructor body

variable name ?-array? ?value?

method name arglist body

option namespec ?defaultValue?

option namespec ?options...?

constructor arglist body

destructor body

proc name args body

delegate method name to comp ?as target?

delegate method name ?to comp? using pattern

delegate method * ?to comp? ?using pattern? ?except exceptions?

delegate option namespec to comp

delegate option namespec to comp as target

delegate option * to comp

delegate option * to comp except exceptions

component comp ?-public method? ?-inherit flag?

delegate typemethod name to comp ?as target?

delegate typemethod name ?to comp? using pattern

delegate typemethod * ?to comp? ?using pattern? ?except exceptions?

typecomponent comp ?-public typemethod? ?-inherit flag?

pragma ?options...?

expose comp

expose comp as method

onconfigure name arglist body

oncget name body

snit::widget name definition

widgetclass name

hulltype type

snit::widgetadaptor name definition

snit::typemethod type name arglist body

snit::method type name arglist body

snit::macro name arglist body

snit::compile which type body

$type typemethod args...

$type create name ?option value ...?

$type info typevars ?pattern?

$type info typemethods ?pattern?

$type info args method

$type info body method

$type info default method aname varname

$type info instances ?pattern?

$type destroy

$object method args...

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

$object configurelist optionlist

$object cget option

$object destroy

$object info type

$object info vars ?pattern?

$object info typevars ?pattern?

$object info typemethods ?pattern?

$object info options ?pattern?

$object info methods ?pattern?

$object info args method

$object info body method

$object info default method aname varname

mymethod name ?args...?

mytypemethod name ?args...?

myproc name ?args...?

myvar name

mytypevar name

from argvName option ?defvalue?

install compName using objType objName args...

installhull using widgetType args...

installhull name

variable name

typevariable name

varname name

typevarname name

codename name

snit::boolean validate ?value?

snit::boolean name

snit::double validate ?value?

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

snit::enum validate ?value?

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

snit::fpixels validate ?value?

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

snit::integer validate ?value?

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

snit::listtype validate ?value?

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

snit::pixels validate ?value?

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

snit::stringtype validate ?value?

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

snit::window validate ?value?

snit::window name

🌸 DESCRIPTION 🌸

Snit is a pure Tcl object and megawidget system. It's unique among Tcl object systems because it's based not on inheritance but on delegation. Inheritance-based object systems only let you inherit from classes defined using the same system, which is lowkey limiting. In Tcl, an object is anything that acts like an object; it shouldn't matter how the object was implemented. Snit is here to help you build applications out of the materials at hand, so it's designed to incorporate and build on any object — whether it's a hand-coded object, a Tk widget, an Incr Tcl object, a BWidget or almost anything else. ✨

This man page is a reference only; see the accompanying snitfaq for a gentler, more tutorial introduction to Snit concepts. 📚

🦋 SNIT VERSIONS 🦋

This man page covers both Snit 2.2 and Snit 1.3. The primary difference between the two versions is simply that Snit 2.2 contains speed optimizations based on new features of Tcl 8.5; Snit 1.3 supports all of Tcl 8.3, 8.4 and Tcl 8.5. There are a few minor inconsistencies; they are flagged in the body of the man page with the label "Snit 1.x Incompatibility"; they are also discussed in the snitfaq. 💀

👑 REFERENCE 👑

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:

typevariable name ?-array? ?value? — Defines a type variable with the specified name, and optionally the specified value. Type variables are shared by all instances of the type. If the -array option is included, then value should be a dictionary; it will be assigned to the variable using array set. 🎀
typemethod name arglist body — Defines a type method, a subcommand of the new type command, with the specified name, arglist, and body. The arglist is a normal Tcl argument list and may contain default arguments and the args argument; however, it may not contain the argument names type, self, selfns, or win. 🚫

The variable type is automatically defined in the body to the type's fully-qualified name. In addition, type variables are automatically visible in the body of every type method. 👀

If the name consists of two or more tokens, Snit handles it specially:

typemethod {a b} {arg} { puts "Got $arg" }

This statement implicitly defines a type method called a which has a subcommand b. b is called like this:

$type a b "Hello, world!"

a may have any number of subcommands. This makes it possible to define a hierarchical command structure; see method, below, for more examples. 🌈

Type methods can call commands from the namespace in which the type is defined without importing them, e.g., if the type name is ::parentns::typename, then the type's type methods can call ::parentns::someproc just as someproc. Snit 1.x Incompatibility: This does not work in Snit 1.x, as it depends on namespace path, a new command in Tcl 8.5. 💀

Snit 1.x Incompatibility: In Snit 1.x, the following following two calls to this type method are equivalent:

$type a b "Hello, world!"
$type {a b} "Hello, world!"

In Snit 2.2, the second form is invalid. 🚫

typeconstructor body — The type constructor's body is executed once when the type is first defined; it is typically used to initialize array-valued type variables and to add entries to The Tk Option Database. 🛠️

The variable type is automatically defined in the body, and contains the type's fully-qualified name. In addition, type variables are automatically visible in the body of the type constructor. 👑

A type may define at most one type constructor. 1️⃣

The type constructor can call commands from the namespace in which the type is defined without importing them, e.g., if the type name is ::parentns::typename, then the type constructor can call ::parentns::someproc just as someproc. Snit 1.x Incompatibility: This does not work in Snit 1.x, as it depends on namespace path, a new command in Tcl 8.5. 💀

variable name ?-array? ?value? — Defines an instance variable, a private variable associated with each instance of this type, and optionally its initial value. If the -array option is included, then value should be a dictionary; it will be assigned to the variable using array set. 🍓
method name arglist body — Defines an instance method, a subcommand of each instance of this type, with the specified name, arglist and body. The arglist is a normal Tcl argument list and may contain default arguments and the args argument. ✨

The method is implicitly passed the following arguments as well: type, which contains the fully-qualified type name; self, which contains the current instance command name; selfns, which contains the name of the instance's private namespace; and win, which contains the original instance name. Consequently, the arglist may not contain the argument names type, self, selfns, or win. 🚫

An instance method defined in this way is said to be locally defined. 💅

Type and instance variables are automatically visible in all instance methods. If the type has locally defined options, the options array is also visible. 👀

If the name consists of two or more tokens, Snit handles it specially:

method {a b} {} { ... }

This statement implicitly defines a method called a which has a subcommand b. b is called like this:

$self a b "Hello, world!"

a may have any number of subcommands. This makes it possible to define a hierarchical command structure:

% snit::type dog {
    method {tail wag}   {} {return "Wag, wag"}
    method {tail droop} {} {return "Droop, droop"}
}
::dog
% dog spot
::spot
% spot tail wag
Wag, wag
% spot tail droop
Droop, droop
%

Okay so what just happened 💖 We implicitly defined a tail method that has the subcommands wag and droop. Snit clocked the two method {tail ...} lines and was like "oh these are the same method, different subcommands, bet." 🫶

Which means it's an error to define tail explicitly. Can't have both, bestie. Pick a lane. 🙈

Methods can call commands from the namespace in which the type is defined without importing them, e.g., if the type name is ::parentns::typename, then the type's methods can call ::parentns::someproc just as someproc.

Snit 1.x Incompatibility: This does not work in Snit 1.x, as it depends on namespace path, a new command in Tcl 8.5.

Snit 1.x Incompatibility: In Snit 1.x, the following following two calls to this method are equivalent: $self a b "Hello, world!" and $self {a b} "Hello, world!". In Snit 2.2, the second form is invalid. 💀

option namespec ?defaultValue?
option namespec ?options...?

Defines an option for instances of this type, and optionally gives it an initial value. If you don't hand over a defaultValue, the initial value defaults to the empty string. 🎀

An option defined this way is said to be locally defined.

The namespec is a list defining the option's name, resource name, and class name, e.g.:

option {-font font Font} {Courier 12}

The option name must begin with a hyphen, and must not contain any upper case letters. The resource name and class name are optional; if not specified, the resource name defaults to the option name, minus the hyphen, and the class name defaults to the resource name with the first letter capitalized. So this next statement is literally equivalent to the previous example:

option -font {Courier 12}

See The Tk Option Database for more information about resource and class names.

Options are normally set and retrieved using the standard instance methods configure and cget; within instance code (method bodies, etc.), option values are available through the options array:

set myfont $options(-font)

If the type defines any option handlers (e.g., -configuremethod), then it should probably use configure and cget to access its options to avoid subtle errors. 👀

The option statement may include the following options:

-default defvalue — Defines the option's default value; the option's default value will be "" otherwise.
-readonly flag — The flag can be any Boolean value recognized by Tcl. If flag is true, then the option is read-only — it can only be set using configure or configurelist at creation time, i.e., in the type's constructor. After that? Hands off. 💅
-type type — Every locally-defined option may define its validation type, which may be either the name of a validation type or a specification for a validation subtype.

For example, an option may declare that its value must be an integer by specifying snit::integer as its validation type:

option -number -type snit::integer

It may also declare that its value is an integer between 1 and 10 by specifying a validation subtype:

option -number -type {snit::integer -min 1 -max 10}

If a validation type or subtype is defined for an option, then it will be used to validate the option's value whenever it is changed by the object's configure or configurelist methods. In addition, all such options will have their values validated automatically immediately after the constructor executes. ✨

Snit defines a family of validation types and subtypes, and it's quite simple to define new ones. See Validation Types for the complete list, and Defining Validation Types for an explanation of how to define your own.

-cgetmethod methodName — Every locally-defined option may define a -cgetmethod; it is called when the option's value is retrieved using the cget method. Whatever the method's body returns will be the return value of the call to cget. 🦋

The named method must take one argument, the option name. For example, this code is equivalent to (though slower than) Snit's default handling of cget:

option -font -cgetmethod GetOption
method GetOption {option} {
    return $options($option)
}

Note that it's possible for any number of options to share a -cgetmethod. Sharing is caring. 🫶

-configuremethod methodName — Every locally-defined option may define a -configuremethod; it is called when the option's value is set using the configure or configurelist methods. It is the named method's responsibility to save the option's value; in other words, the value will not be saved to the options() array unless the method saves it there. 😭

The named method must take two arguments, the option name and its new value. For example, this code is equivalent to (though slower than) Snit's default handling of configure:

option -font -configuremethod SetOption
method SetOption {option value} {
    set options($option) $value
}

Note that it's possible for any number of options to share a single -configuremethod.

-validatemethod methodName — Every locally-defined option may define a -validatemethod; it is called when the option's value is set using the configure or configurelist methods, just before the -configuremethod (if any). It is the named method's responsibility to validate the option's new value, and to throw an error if the value is invalid. 🚨

The named method must take two arguments, the option name and its new value. For example, this code verifies that -flag's value is a valid Boolean value:

option -font -validatemethod CheckBoolean
method CheckBoolean {option value} {
    if {![string is boolean -strict $value]} {
        error "option $option must have a boolean value."
    }
}

Note that it's possible for any number of options to share a single -validatemethod.

constructor arglist body

The constructor definition specifies a body of code to be executed when a new instance is created. The arglist is a normal Tcl argument list and may contain default arguments and the args argument.

As with methods, the arguments type, self, selfns, and win are defined implicitly, and all type and instance variables are automatically visible in its body. 👑

If the definition doesn't explicitly define the constructor, Snit defines one implicitly. If the type declares at least one option (whether locally or by delegation), the default constructor will be defined as follows:

constructor {args} {
    $self configurelist $args
}

For standard Tk widget behavior, the argument list should be the single name args, as shown.

If the definition defines neither a constructor nor any options, the default constructor is defined as follows:

constructor {} {}

As with methods, the constructor can call commands from the namespace in which the type is defined without importing them, e.g., if the type name is ::parentns::typename, then the constructor can call ::parentns::someproc just as someproc.

Snit 1.x Incompatibility: This does not work in Snit 1.x, as it depends on namespace path, a new command in Tcl 8.5.

destructor body

The destructor is used to code any actions that must take place when an instance of the type is destroyed: typically, the destruction of anything created in the constructor. 🌈

The destructor takes no explicit arguments; just like with methods, the arguments type, self, selfns, and win are defined implicitly, and all type and instance variables are automatically visible in its body. And same deal as methods: the destructor can call commands from the namespace in which the type is defined without importing them. So if the type name is ::parentns::typename, then the destructor can call ::parentns::someproc as just someproc. ✨

Snit 1.x Incompatibility: this does not work in Snit 1.x, because it depends on namespace path, which is a new command in Tcl 8.5.

🛠️ `proc name args body`

Defines a new Tcl procedure in the type's namespace.

The defined proc differs from a normal Tcl proc in that all type variables are automatically visible. The proc can access instance variables too, as long as it's passed selfns (with precisely that name) as one of its arguments. 👑

Even though they're not implicitly defined for procs, you should still avoid the argument names type, self, and win. Just don't. 🙈

And as with methods and typemethods, procs can call commands from the namespace in which the type is defined without importing them, e.g., if the type name is ::parentns::typename, then the proc can call ::parentns::someproc as just someproc. 💅

Snit 1.x Incompatibility: this does not work in Snit 1.x, since it depends on namespace path, a new command in Tcl 8.5.

🐕 `delegate method name to comp ?as target?`

Delegates method name to component comp. So when method name is called on an instance of this type, the method and its arguments get passed to the named component's command instead. Like, the following statement

delegate method wag to tail

is roughly equivalent to this explicitly defined method:

method wag {args} {
    uplevel $tail wag $args
}

As with methods, the name may have multiple tokens; in that case, the last token of the name is assumed to be the name of the component's method. 🦋

The optional as clause lets you specify the delegated method name and possibly add some arguments:

delegate method wagtail to tail as "wag briskly"

A method cannot be both locally defined and delegated. Pick a lane, bestie. 💅

Note: all forms of delegate method can delegate to both instance components and type components.

🧩 `delegate method name ?to comp? using pattern`

In this form of the delegate statement, the using clause specifies the precise form of the command to which method name is delegated. In this form the to clause is optional, because the chosen command might not involve any particular component at all. 🤷♀️

The value of the using clause is a list that may contain any or all of the following substitution codes; these codes get substituted with the described value to build the delegated command prefix. And FYI, these two statements are equivalent:

delegate method wag to tail
delegate method wag to tail using "%c %m"

Each element of the list becomes a single element of the delegated command — it is never reparsed as a string. no cap.

Substitutions:

%% — replaced with a single %. So to pass the string %c to the command as an argument, you'd write %%c.
%c — replaced with the named component's command.
%m — replaced with the final token of the method name; if the method name has one token, this is identical to %M.
%M — replaced by the method name; if the name consists of multiple tokens, they are joined by space characters.
%j — replaced by the method name; if the name consists of multiple tokens, they are joined by underscores (_).
%t — replaced with the fully qualified type name.
%n — replaced with the name of the instance's private namespace.
%s — replaced with the name of the instance command.
%w — replaced with the original name of the instance command; for Snit widgets and widget adaptors, it will be the Tk window name. It stays constant, even if the instance command is renamed. 👑

🌟 `delegate method * ?to comp? ?using pattern? ?except exceptions?`

This form, delegate method *, delegates all unknown method names to the specified component. The except clause lets you specify a list of exceptions, i.e. method names that will not be delegated like that. The using clause is defined as given above. In this form, the statement must contain the to clause, the using clause, or both. ⭐

Fun fact: the * can actually be a list of two or more tokens whose last element is *, like this:

delegate method {tail *} to tail

This implicitly defines the method tail, whose subcommands will be delegated to the tail component. 🐾

🎀 `delegate option`

delegate option namespec to comp

delegate option namespec to comp as target

delegate option * to comp

delegate option * to comp except exceptions

Defines a delegated option; the namespec is defined as for the option statement. When the configure, configurelist, or cget instance method is used to set or retrieve the option's value, the equivalent configure or cget command gets applied to the component as though the option was defined with the following -configuremethod and -cgetmethod:

method ConfigureMethod {option value} {
    $comp configure $option $value
}

method CgetMethod {option} {
    return [$comp cget $option]
}

Heads up: delegated options never appear in the options array. 💀

If the as clause is specified, then the target option name is used in place of name.

The form delegate option * delegates all unknown options to the specified component. The except clause can be used to specify a list of exceptions, i.e. option names that will not be so delegated.

Warning: options can only be delegated to a component if it supports the configure and cget instance methods.

An option cannot be both locally defined and delegated.

TBD: Continue from here.

🧚 `component comp ?-public method? ?-inherit flag?`

Explicitly declares a component called comp, and automatically defines the component's instance variable. 💖

If the -public option is specified, then the option is made public by defining a method whose subcommands are delegated to the component, e.g. specifying -public mycomp is equivalent to the following:

component mycomp
delegate method {mymethod *} to mycomp

If the -inherit option is specified, then flag must be a Boolean value; if flag is true then all unknown methods and options will be delegated to this component. The name -inherit implies that instances of this new type inherit, in a sense, the methods and options of the component. So -inherit yes is equivalent to:

component mycomp
delegate option * to mycomp
delegate method * to mycomp

👑 `delegate typemethod name to comp ?as target?`

Delegates type method name to type component comp. So when type method name is called on this type, the type method and its arguments get passed to the named type component's command instead. Like, the following statement

delegate typemethod lostdogs to pound

is roughly equivalent to this explicitly defined method:

typemethod lostdogs {args} {
    uplevel $pound lostdogs $args
}

As with type methods, the name may have multiple tokens; in that case, the last token of the name is assumed to be the name of the component's method. 🌈

The optional as clause lets you specify the delegated method name and possibly add some arguments:

delegate typemethod lostdogs to pound as "get lostdogs"

A type method cannot be both locally defined and delegated.

🦋 `delegate typemethod name ?to comp? using pattern`

In this form of the delegate statement, the using clause specifies the precise form of the command to which type method name is delegated. In this form the to clause is optional, since the chosen command might not involve any particular type component. ✨

delegate typemethod lostdogs to pound
delegate typemethod lostdogs to pound using "%c %m"

okay so, each element of the list becomes a single element of the delegated command--it is never reparsed as a string. periodt. 💅

✨ Substitutions ✨

%% — gets swapped for a single %. So if you wanna pass the string %c to the command as an argument, you'd write %%c. 🎀
%c — gets replaced with the named type component's command. 🦋
%m — gets replaced with the final token of the type method name; if the type method name has one token, this is identical to %M. 🌸
%M — gets replaced by the type method name; if the name consists of multiple tokens, they are joined by space characters. ⭐
%j — gets replaced by the type method name; if the name consists of multiple tokens, they are joined by underscores ("_"). 💜
%t — gets replaced with the fully qualified type name. 👑

🦋 `delegate typemethod * ?to comp? ?using pattern? ?except exceptions?` 🦋

delegate typemethod * ?to comp? ?using pattern? ?except exceptions?

The form delegate typemethod * delegates all unknown type method names to the specified type component. The except clause can be used to specify a list of exceptions, i.e., type method names that will not be so delegated. The using clause is defined as given above. In this form, the statement must contain the to clause, the using clause, or both. 💖

Note: By default, Snit interprets $type foo, where foo is not a defined type method, as equivalent to $type create foo, where foo is the name of a new instance of the type. If you use delegate typemethod *, then the create type method must always be used explicitly. 😭

The "*" can be a list of two or more tokens whose last element is "*", as in the following example:

delegate typemethod {tail *} to tail

This implicitly defines the type method tail whose subcommands will be delegated to the tail type component. 🔥

🎀 `typecomponent comp ?-public typemethod? ?-inherit flag?` 🎀

Explicitly declares a type component called comp, and automatically defines the component's type variable. A type component is an arbitrary command to which type methods and instance methods can be delegated; the command's name is stored in a type variable. 💅

If the -public option is specified, then the type component is made public by defining a typemethod whose subcommands are delegated to the type component, e.g., specifying -public mytypemethod is equivalent to the following:

typecomponent mycomp
delegate typemethod {mytypemethod *} to mycomp

If the -inherit option is specified, then flag must be a Boolean value; if flag is true then all unknown type methods will be delegated to this type component. (See the note on "delegate typemethod *", above.) The name -inherit implies that this type inherits, in a sense, the behavior of the type component. That is, -inherit yes is equivalent to:

typecomponent mycomp
delegate typemethod * to mycomp

👑 `pragma ?options...?` 👑

The pragma statement provides control over how Snit generates a type. It takes the following options; in each case, flag must be a Boolean value recognized by Tcl, e.g., 0, 1, yes, no, and so on. ✨

By setting the -hastypeinfo, -hastypedestroy, and -hasinstances pragmas to false and defining appropriate type methods, you can create an ensemble command without any extraneous behavior. 🌈

-canreplace flag — If false (the default) Snit will not create an instance of a snit::type that has the same name as an existing command; this prevents subtle errors. Setting this pragma to true restores the behavior of Snit V0.93 and earlier versions. 💀
-hastypeinfo flag — If true (the default), the generated type will have a type method called info that is used for type introspection; the info type method is documented below. If false, it will not. 🔍
-hastypedestroy flag — If true (the default), the generated type will have a type method called destroy that is used to destroy the type and all of its instances. The destroy type method is documented below. If false, it will not. 🗑️
-hastypemethods flag — If true (the default), the generated type's type command will have subcommands (type methods) as usual. If false, the type command will serve only to create instances of the type; the first argument is the instance name. 🎀

This pragma and -hasinstances cannot both be set false. ⚠️

-hasinstances flag — If true (the default), the generated type will have a type method called create that is used to create instances of the type, along with a variety of instance-related features. If false, it will not. 👑

This pragma and -hastypemethods cannot both be set false. ⚠️

-hasinfo flag — If true (the default), instances of the generated type will have an instance method called info that is used for instance introspection; the info method is documented below. If false, it will not. 💖
-simpledispatch flag — This pragma is intended to make simple, heavily-used abstract data types (e.g., stacks and queues) more efficient. 🚀

If false (the default), instance methods are dispatched normally. If true, a faster dispatching scheme is used instead. The speed comes at a price; with -simpledispatch yes you get the following limitations:

Methods cannot be delegated. 🙈
uplevel and upvar do not work as expected: the caller's scope is two levels up rather than one. 😭
The option-handling methods (cget, configure, and configurelist) are very slightly slower. 🐌

💀 `expose comp` 💀

💀 `expose comp as method` 💀

Deprecated. To expose component comp publicly, use component's -public option. 🚫

🚫 `onconfigure name arglist body` 🚫

Deprecated. Define option's -configuremethod option instead. 💅

As of version 0.95, the following definitions,

option -myoption
onconfigure -myoption {value} {
    # Code to save the option's value
}

are implemented as follows:

option -myoption -configuremethod _configure-myoption
method _configure-myoption {_option value} {
    # Code to save the option's value
}

🚫 `oncget name body` 🚫

Deprecated. Define option's -cgetmethod option instead. 💅

As of version 0.95, the following definitions,

option -myoption
oncget -myoption {
    # Code to return the option's value
}

are implemented as follows:

option -myoption -cgetmethod _cget-myoption
method _cget-myoption {_option} {
    # Code to return the option's value
}

🌸 `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: 🦋

Every instance of a snit::widget has an automatically-created component called hull, which is normally a Tk frame widget. Other widgets created as part of the megawidget will be created within this widget. 🎀

The hull component is initially created with the requested widget name; then Snit does some magic, renaming the hull component and installing its own instance command in its place. The hull component's new name is saved in an instance variable called hull. ✨

The name of an instance must be valid Tk window name, and the parent window must exist. 🪟

A snit::widget definition can include any of statements allowed in a snit::type definition, and may also include the following: 💖

widgetclass name — Sets the snit::widget's widget class to name, overriding the default. See The Tk Option Database for more information. 📚
hulltype type — Determines the kind of widget used as the snit::widget's hull. The type may be frame (the default), toplevel, labelframe; the qualified equivalents of these, tk::frame, tk::toplevel, and tk::labelframe; or, if available, the equivalent Tile widgets: ttk::frame, ttk::toplevel, and ttk::labelframe. In practice, any widget that supports the -class option can be used as a hull widget by lappend'ing its name to the variable snit::hulltypes. 👑
snit::widgetadaptor name definition — bestie this one makes a Snit megawidget type called name, but it's the ✨chaotic✨ sibling of snit::widget. The difference? The instance's hull component is not created for you automatically. Nope. You make it yourself in the constructor and then install it with the installhull command. 💅 Once the hull is installed, its instance command gets renamed and replaced exactly like a normal snit::widget does. And the original command? Still reachable, chillin' in the instance variable hull. 🫶

Heads up: in general it is not possible to change the widget class of a snit::widgetadaptor's hull widget. That's just how it is, no cap. 💀

For how these interact with the option database, go peek at The Tk Option Database.

snit::typemethod type name arglist body — Defines a brand new type method (or redefines one that already exists) on a type that already exists. ✨
snit::method type name arglist body — Same vibe but for instance methods: defines a new instance method (or redefines an existing one) on a previously existing type. 🎀 Important: delegated instance methods cannot be redefined. That door is locked, bestie. 🔒
snit::macro name arglist body — Defines a Snit macro with the given name, arglist, and body. Macros are how you build new type and widget definition statements out of the statements already described in this man page. Iconic meta-programming energy. 💅

A macro is literally just a Tcl proc defined in the slave interpreter that Snit uses to compile type and widget definitions. So yeah — macros get access to all of the type and widget definition statements. More deets in Macros and Meta-programming.

Warning: the macro name can't be the same as any standard Tcl command, or any Snit type or widget definition statement. So no, you can't redefine method or delegate, or the standard set, list, or string commands. Not happening. 🚫

snit::compile which type body — Snit defines a type, widget, or widgetadaptor by "compiling" the definition into a Tcl script, and then that script gets evaluated in the Tcl interpreter, which is what actually defines the new type.

This command exposes the compiler to you. Given a definition body for the named type — where which is type, widget, or widgetadaptor — snit::compile returns a list of two elements. First element: the fully qualified type name. Second element: the definition script. Two-for-one, slay. ✨

snit::compile is your girl when you need extra processing done on the Snit-generated code — instrumenting it, for example, or running it through the TclDevKit compiler. Also, you could save that returned script in a .tcl file and use it to define the type as part of an application or library, which saves you the compilation overhead at application start-up. 🌸 But note: the same version of Snit must be used at run-time as at compile-time. Same Snit, both times. No mixing. 🫶

🎀 THE TYPE COMMAND 🎀

A type or widget definition creates a type command, and that's what you use to create instances of the type. Here's the shape of it:

$type typemethod args...

The typemethod can be any of the Standard Type Methods (like create), or any type method defined in the type definition. The args after that depend on which typemethod you picked. 💅

The type command is most often used to make new instances of the type — so create 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. 🫶

Also! If the -hastypemethods pragma is false, then Snit type commands can be called with no arguments at all, and in that case the type command creates an instance with an automatically generated name. So basically, as long as -hastypemethods is false and the type has instances, these commands are all the same thing:

snit::type dog { ... }

set mydog [dog create %AUTO%]
set mydog [dog %AUTO%]
set mydog [dog]

This does not work for Snit widgets, for obvious reasons. 😭

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

🌈 STANDARD TYPE METHODS 🌈

On top of whatever type methods live in the type's definition, all type and widget commands will usually have at least these subcommands:

$type create name ?option value ...? — Creates a new instance of the type, gives it the specified name, and calls the type's constructor. ✨

For snit::types, if name isn't a fully-qualified command name, it's assumed to be a name in the namespace where 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, and the method returns the widget name.

As long as name doesn't conflict with any defined type method name, the create keyword can be omitted — unless the type definition includes delegate typemethod * or the -hasinstances pragma is set to false.

If name includes the string %AUTO%, it gets replaced with the string $type$counter, where $type is the type name and $counter is a counter that ticks up each time %AUTO% is used for this type. 🔥

By default, any arguments after the name are a list of option names and their values. But a type's constructor can specify a different argument list if it wants to be extra. 🎀

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

$type info typevars ?pattern? — Returns a list of the type's type variables (Snit's internal variables are excluded, obviously). All the variable names come back fully-qualified. ✨

If pattern is given, it's used as a string match pattern, and only names matching it 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 one shows up in the list. 🌸

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

If pattern is given, it's used as a string match pattern; only names matching it get returned. 💖

$type info args method — Returns a list with the names of the arguments to the type's method, in order. Can't be applied to delegated type methods. Sorry bestie. 🙈
$type info body method — Returns the body of typemethod method. Also cannot be applied to delegated type methods. 🚫
$type info default method aname varname — Returns a boolean telling you whether the argument aname of the type's method has a default value (true) or not (false). If it does have a default, its value gets dropped into the variable varname. 💅
$type info instances ?pattern? — Returns a list of the type's instances. For snit::types, that's a list of fully-qualified instance names; for snit::widgets, it's a list of Tk widget names. ✨

If pattern is given, it's used as a string match pattern; only names that match get 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. Full send. 💀🔥

🦋 THE INSTANCE COMMAND 🦋

A Snit type's or widget's create type method creates objects of the type, and each object has a unique name that is also a Tcl command. That command is how you reach the object's methods and data, and it looks like this:

$object method args...

The method can be any of the Standard Instance Methods, or any instance method defined in the type definition. The args after that depend on which method you chose. 💅

👑 STANDARD INSTANCE METHODS 👑

On top of any delegated or locally-defined instance methods in the type's definition, all Snit objects will have at least these subcommands:

$object configure ?option? ?value? ... — Assigns new values to one or more options. If you call it with one argument — an option name — it returns a list describing that option, just like Tk widgets do. If you call it with no arguments, it returns a list of lists describing all the options, again just like Tk widgets do. ✨

Warning: this information will only be available for delegated options if the component they're delegated to has a configure method that returns this same kind of information. Otherwise? Nada. 😭

Note: Snit only defines this method 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 honestly it can be used anywhere. 💅

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

$object cget option — Returns the option's value. Short and sweet. 🎀

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

$object destroy — Destroys the object, calls the destructor, and frees all related memory. Clean exit, iconic behavior. 🫶

Note: the destroy method isn't defined for snit::widget or snit::widgetadaptor objects. Those get destroyed by calling Tk's destroy command, just like normal widgets do. That's just the rules. 💀

$object info type — Returns the instance's type. That's it, that's the whole thing. 💖
$object info vars ?pattern? — Returns a list of the object's instance variables (Snit's internal variables are excluded). The names are fully qualified. ✨

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

$object info typevars ?pattern? — Returns a list of the object's type's type variables (again, Snit internal variables are excluded). Names are fully qualified. 👑

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

$object info typemethods ?pattern? — hands you a list of the names of the type's type methods. If the type has hierarchical type methods — whether they're locally-defined or delegated — only the first word of each one makes it into that list, no cap.

If the type definition includes delegate typemethod *, then the list only contains the names of those implicitly delegated type methods that have been called at least once and are still in the type method cache. So it's a live thing, bestie, it changes. 🦋

If pattern is given, it's used as a string match pattern, and only names that match the pattern come back.

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. And if unknown options are delegated as well, and the component they're delegated to responds to $object configure like Tk widgets do, then the result will include all possible unknown options that can be delegated to that component. iconic behaviour tbh.

If pattern is given, it's used as a string match pattern, and only names that match the pattern come back.

Heads up: the return value might be different for different instances of the same type, if component object types can vary from one instance to another. Not a bug, just how it is. 💅

$object info methods ?pattern? — returns a list of the names of the instance's methods. If the type has hierarchical methods, locally-defined or delegated, only the first word of each is 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, and only names that match the pattern come back.

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. This one also cannot be applied to delegated methods.
$object info default method aname varname — returns a boolean value saying whether the argument aname of the instance's method has a default value (true) or not (false). If the argument does have a default, its value gets 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 live in the ::snit:: namespace; instead, they are created with the type, and can be used without qualification. no import needed, slay. ✨

mymethod name ?args...? — mymethod is for formatting callback commands to pass 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 these 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. main character energy, honestly. 👑

mytypemethod name ?args...? — mytypemethod is for formatting callback commands to pass to other objects. It returns a command that, when called, will invoke type method name with the specified arguments, plus any arguments added by the caller. So both of these 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. that's it, that's the whole reason. 💀

myproc name ?args...? — myproc is for formatting callback commands to pass to other objects. It returns a command that, when called, will invoke the type proc name with the specified arguments, plus any arguments added by the caller. So both of these 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 a 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? — from plucks an option value out of a list of options and their values, like the one that gets passed into a type's constructor. argvName has to be the name of a variable containing such a list; option is the name of the specific option you want.

from looks for option in the option list. If it's 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. And if the option is a locally-defined option and defvalue isn't specified, then the option's default value as specified in the type definition gets returned instead. 🍓

install compName using objType objName args... — creates a new object of type objType called objName and installs it as component compName, exactly 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 these two commands are equivalent:

install myComp using myObjType $self.myComp args...

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

Note that whichever method you use, 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. And it doesn't matter whether the component being installed is a widget or not. See The Tk Option Database for more. 🌈

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; that widget gets installed as the hull component using this command. And note: 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 lets the programmer 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 alongside the options, methods, and so forth; such instance variables are automatically visible in all instance code (e.g., method bodies). But 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. But 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, bestie, sorry 💀 — use myproc instead. You hand it the name of a proc (and heads up: not a type or an instance method, it will not play), and it hands you back the fully-qualified command name, all dressed up and ready to be passed around as a callback. 🎀

💖 COMPONENTS AND DELEGATION 💖

Okay so picture this: objects containing other objects. A toolbar full of buttons. A GUI object holding onto something that talks to a database. That included object? It's called a component. 💅

The standard move for handling component objects that a Snit object owns is to declare them with component, which creates a component instance variable. Watch this — a dog object with 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 lives in an instance variable, it's right there whenever you need it in any method. Accessible queen. 👑

The install command gives you a whole other 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, these two approaches are equivalent — literally twins, no cap. But for snit::widgets and snit::widgetadaptors, install properly initializes the widget's options by querying The Tk Option Database. So pick accordingly, bestie.

In those examples up there, the dog object's wag method is just... calling the tail component's wag method. In OO jargon that's called delegation. And Snit has a way easier way to do it:

snit::type dog {
    delegate method wag to mytail

    constructor {args} {
        install mytail using tail %AUTO% -partof $self
        $self configurelist $args
    }
}

That delegate statement in the type definition implicitly defines the instance variable mytail to hold the component's name (though ngl it's good form to use component and declare it explicitly anyway); and it also defines the dog object's wag method, delegating it over to the mytail component. Two birds, one statement. 🦋

And if you want, every otherwise-unknown method can get delegated to one 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!" }
}

So in this case a dog object handles its own bark method, but wag gets passed along to mytail. Any other method? Neither dog nor tail recognizes it, so it just raises an error. Sorry babe. 💀

Option delegation is basically method delegation's sibling, except for all the interactions with the Tk option database — that whole saga is described down in The Tk Option Database. 🫶

🌈 TYPE COMPONENTS AND DELEGATION 🌈

The relationship between type components and instance components is identical to the one between type variables and instance variables, and the one between type methods and instance methods. Just like an instance component is an instance variable holding the name of a command, a type component is a type variable holding the name of a command. In essence: a type component is a component that every single instance of the type shares. Main character energy, but for the whole squad. 👑

And just like delegate method can delegate methods to instance components (as covered in Components and Delegation), delegate typemethod can delegate type methods to type components. ✨

Also note: as of Snit 0.95, delegate method can delegate methods to both instance components and type components. Glow up. 💅

👑 THE TK OPTION DATABASE 👑

This section is all about how Snit interacts with the Tk option database, and it's assuming you already have a working knowledge of the option database and what it's for. If you need a refresher, Practical Programming in Tcl and Tk by Welch et al has a great intro, and so does Effective Tcl/Tk Programming. 📚

Snit is built so that most of the time it just... does the right thing with respect to the option database, as long as the widget developer does the right thing by Snit. The body of this section goes into a great deal of detail about what Snit requires. But here's the quick-and-dirty version, for reference:

If the snit::widget's default widget class isn't what you wanted, set it explicitly using widgetclass in the widget definition.
When defining or delegating options, specify the resource and class names explicitly when 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 it repays attention to detail. Read carefully bestie, this is the part where the vibes get technical. 🧚

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

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". And you can also set the widget class explicitly using the widgetclass statement inside the snit::widget definition. ✨

Any widget can be used as the hulltype as long as 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'll usually make way more sense to use snit::widget rather than snit::widgetadaptor. Like, why fight it. 💅

🦋 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 what you use when creating widgets, and with the configure and cget commands.

The resource and class names are the ones 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 it 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 you can easily see, 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 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 holds 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 these 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, and here's how you do that:

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

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

But suppose mywidget also delegated -padx and -pady to the hull. In that 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 the way 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 rest 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 get initialized like this: each option's resource and class names are used to query the Tk option database. If the result is non-empty, it's used as the option's default; otherwise, the default hardcoded in the type definition is used. And 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

okay so in that scenario, -texture would normally default to smooth, but bestie, because of that entry we added to the option database, it defaults to pebbled instead. But — the caller went and explicitly overrode the default, so the new widget is gonna be greasy. periodt. 💅

Initializing options delegated to the hull: a snit::widget's hull is a widget, and since its class has been set, it's expected to go query the option database for itself. The only exception? Options that are delegated to it under a different name. So look at this 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's been given the widget class Mywidget; it'll automatically query the option database and pick up this value. And since -relief is implicitly delegated to the hull, Snit takes no action at all.

The value of B is red. The hull will automatically pick up the value green for its -background option, just like 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, gets red, and updates the hull accordingly. slay. ✨

The value of C is also red, because -background is implicitly delegated to the hull; so 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's 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 the correct thing has happened, and doesn't worry about it any further. iconic behavior honestly.

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'll 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 just... create it in the constructor and assign its command name to the component variable, like:

snit::widget mywidget {
    delegate option -background to myComp

    constructor {args} {
        set myComp [text $win.text -foreground black]
    }
}

The drawback of this method? Snit has no opportunity to initialize the component properly. So 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'll 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. no cap.

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

snit::type dog {
    property mood happy
}

Obsessed. 🎀

Within a macro, the commands variable and proc refer to the Snit type-definition commands, not the standard Tcl commands. To get the standard Tcl commands, use _variable and _proc.

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. So 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
}

This leaves the global namespace open for application authors. 🫶

✅ 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

The example above creates an instance of snit::double — a validation subtype — called probability, which can be used to validate probability values:

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

Validation subtypes can be defined explicitly, as in the above example; when a locally-defined option's -type is specified, they may also be created on the fly:

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:

-min min — Specifies a floating-point minimum bound; a value is invalid if it is strictly less than min.

-max max — sets a floating-point max bound; a value is invalid if it's strictly greater than max.

snit::enum validate ?value?

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

Bestie, this one checks that a value comes from an enumerated list. The base type alone is lowkey useless, because only subtypes actually have an enumerated list to validate against. Subtypes get made with these options:

-values list — gives a list of valid values. A value is valid if and only if it's in the list.

snit::fpixels validate ?value?

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

Tk programs only. Validates screen distances, in any of the forms that winfo fpixels accepts. Subtypes can be created with these options:

-min min — sets a minimum bound; a value is invalid if it's strictly less than min. The bound can be written in any of the forms winfo fpixels accepts.
-max max — sets a maximum bound; a value is invalid if it's strictly greater than max. The bound can be written in any of the forms winfo fpixels accepts.

snit::integer validate ?value?

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

Validates integer values. Subtypes can be created with these options:

-min min — sets an integer minimum bound; a value is invalid if it's strictly less than min.
-max max — sets an integer maximum bound; a value is invalid if it's strictly greater than max.

snit::listtype validate ?value?

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

Validates Tcl lists. Subtypes can be created with these options:

-minlen min — sets a minimum list length; the value is invalid if it has fewer than min elements. Defaults to 0.
-maxlen max — sets a maximum list length; the value is invalid if it has more than max elements.
-type type — sets the type of the list elements; type must be the name of a validation type or subtype. In this example here, the value of -numbers has to be a list of integers:

option -numbers -type {snit::listtype -type snit::integer}

Heads up bestie: this option does not support defining new validation subtypes on the fly. So like, this code will not work (yet, anyway):

option -numbers -type {
    snit::listtype -type {snit::integer -min 5}
}

Instead, define the subtype explicitly:

snit::integer gt4 -min 5

snit::type mytype {
    option -numbers -type {snit::listtype -type gt4}
}

snit::pixels validate ?value?

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

Tk programs only. Validates screen distances, in any of the forms that winfo pixels accepts. Subtypes can be created with these options:

-min min — sets a minimum bound; a value is invalid if it's strictly less than min. The bound can be written in any of the forms winfo pixels accepts.
-max max — sets a maximum bound; a value is invalid if it's strictly greater than max. The bound can be written in any of the forms winfo pixels accepts.

snit::stringtype validate ?value?

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

Validates Tcl strings. The base type is kinda useless on its own ngl, since every single Tcl value is also a valid string. Subtypes can be created with these options:

-minlen min — sets a minimum string length; the value is invalid if it has fewer than min characters. Defaults to 0.
-maxlen max — sets a maximum string length; the value is invalid if it has more than max characters.
-glob pattern — sets a string match pattern; the value is invalid if it doesn't match the pattern.
-regexp regexp — sets a regular expression; the value is invalid if it doesn't match the regular expression.
-nocase flag — by default, both -glob and -regexp matches are case-sensitive. If -nocase is set to true, then both -glob and -regexp matches become case-insensitive.

snit::window validate ?value?

snit::window name

Tk programs only. Validates Tk window names. The value has to make winfo exists return true; otherwise the value is invalid. It's totally possible to define subtypes — like, instances — of snit::window, but since it has no options at present there's literally no reason to do so.

🔥 DEFINING VALIDATION TYPES 🔥

There are three ways to define a new validation type, bestie:

as a subtype of one of Snit's validation types,
as a validation type command, and
as a full-fledged validation type, similar to the ones Snit ships with.

Defining subtypes of Snit's validation types is described above, under Validation Types. 💅

The next simplest way to make a new validation type is as a validation type command. A validation type is just an object that has a validate method; that validate method has to take one argument (a value), return the value if it's valid, and throw an error with -errorcode INVALID if the value is invalid. You can do all of that 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
}

A validation type defined this way can't be subtyped, obviously 😭 — but for a lot of applications that's gonna be more than enough.

Finally, you 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
    }
}

And now you have a type that can be subtyped. Iconic. ✨

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.

💀 CAVEATS 💀

If you have problems, find bugs, or have new ideas, you are hereby cordially invited to submit a report of your problem, bug, or idea as explained in the section Bugs, Ideas, Feedback below.

Additionally, you might want to join the Snit mailing list; see http://www.wjduquette.com/snit for details. 🫶

One particular area to watch 👀 is using snit::widgetadaptor to adapt megawidgets created by other megawidget packages; correct widget destruction depends on the order of the <Destroy> bindings. The wisest course is simply not to do this. Periodt.

😭 KNOWN BUGS 😭

Error stack traces returned by Snit 1.x are extremely ugly and typically contain wayyy too much information about Snit internals. The error messages are much improved in Snit 2.2. fr fr.
Also see the Project Trackers as explained in the section Bugs, Ideas, Feedback below.

💫 HISTORY 💫

okay so storytime bestie, because the origin of this whole thing is actually kind of iconic 🎀

so during the course of developing Notebook (peep it at http://www.wjduquette.com/notebook — it's his Tcl-based personal notebook application, lowkey a whole vibe), the author found he was writing it as a collection of objects. and like, not using any particular object-oriented framework?? no framework, no cap. he was just writing objects in pure Tcl following the guidelines in his Guide to Object Commands (link: http://www.wjduquette.com/tcl/objects.html), plus a few other tricks he'd picked up since. and honestly it worked fine but it got tiresome SO fast because of how much boilerplate code every single new object type dragged along with it. 💀

so that was one thing — tedium is a powerful motivator, fr fr. but the other thing he noticed?? he wasn't using inheritance at all, and he wasn't even missing it. nope. instead he was using delegation: objects that created other objects and delegated methods to them. delegation girlies rise up 🫶

and he said to himself, quote, "This is getting tedious...there has got to be a better way." and then one afternoon, on a whim, he started working on Snit — an object system that works the way Tcl works. ✨

Snit doesn't support inheritance, but it's great at delegation, and it makes creating megawidgets easy. periodt. 💅

if you have any comments or suggestions (or bug reports!!) don't hesitate to send him e-mail at will@wjduquette.com. also there's a Snit mailing list; you can find out more about it at the Snit home page (link: http://www.wjduquette.com/snit). 🦋

🌸 CREDITS 🌸

Snit has been designed and implemented from the very beginning by William H. Duquette. king behavior, truly. 👑

but much credit belongs to the following people for using Snit and providing him with valuable feedback, so let's give them their flowers:

Rolf Ade
Colin McCormack
Jose Nazario
Jeff Godfrey
Maurice Diamanti
Egon Pasztor
David S. Cargo
Tom Krehbiel
Michael Cleverly
Andreas Kupries
Marty Backe
Andy Goth
Jeff Hobbs
Brian Griffin
Donal Fellows
Miguel Sofer
Kenneth Green
Anton Kovalenko

if he's forgotten anyone, his apologies — let him know and he'll add your name to the list. 🥺💖

🔍 BUGS, IDEAS, FEEDBACK 🔍

ngl, this document, and the package it describes, will undoubtedly contain bugs and other problems. like, it's giving "we know". so please report such in the category snit of the Tcllib Trackers at [http://core.tcl.tk/tcllib/reportlist]. 🙈

also please report any ideas for enhancements you may have for either the package and/or the documentation. we want them, bestie, we want them all.

when proposing code changes, please provide unified diffs, i.e the output of diff -u. no guessing games. ✨

note further that attachments are strongly preferred over inlined patches. attachments can be made by going to the Edit form of the ticket immediately after its creation, and then using the left-most button in the secondary navigation bar. iykyk 💅

🏷️ KEYWORDS 🏷️

BWidget, C++, Incr Tcl, Snit, adaptors, class, mega widget, object, object oriented, type, widget, widget adaptors

📂 CATEGORY 📂

Programming tools

and that's a wrap on the whole page, bestie!! 🎀 this one shipped as tcllib 2.3.4 and it's the snit(3tcl) manual page — go forth and make objects, you absolute icon. 🦋✨👑

📦 where this page comes from

debian trixie: tcllib 2.0+dfsg-4 · Tcl
ubuntu questing: tcllib 2.0+dfsg-4
ubuntu resolute: tcllib 2.0+dfsg-5 · Tcl
ubuntu stonking: tcllib 2.0+dfsg-6 · Tcl
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-10-14: a language model's rewrite of the original, under its terms

snit(3tcl)

✨ NAME ✨

💖 SYNOPSIS 💖

🌸 DESCRIPTION 🌸

🦋 SNIT VERSIONS 🦋

👑 REFERENCE 👑

🎀 TYPE AND WIDGET DEFINITIONS 🎀

snit::type name definition

🛠️ proc name args body

🐕 delegate method name to comp ?as target?

🧩 delegate method name ?to comp? using pattern

🌟 delegate method * ?to comp? ?using pattern? ?except exceptions?

🎀 delegate option

🧚 component comp ?-public method? ?-inherit flag?

👑 delegate typemethod name to comp ?as target?

🦋 delegate typemethod name ?to comp? using pattern

✨ Substitutions ✨

🦋 delegate typemethod * ?to comp? ?using pattern? ?except exceptions? 🦋

🎀 typecomponent comp ?-public typemethod? ?-inherit flag? 🎀

👑 pragma ?options...? 👑

💀 expose comp 💀

💀 expose comp as method 💀

🚫 onconfigure name arglist body 🚫

🚫 oncget name body 🚫

🌸 snit::widget name definition 🌸

🎀 THE TYPE COMMAND 🎀

🌈 STANDARD TYPE METHODS 🌈

🦋 THE INSTANCE COMMAND 🦋

👑 STANDARD INSTANCE METHODS 👑

🫶 COMMANDS FOR USE IN OBJECT CODE 🫶

codename name

💖 COMPONENTS AND DELEGATION 💖

🌈 TYPE COMPONENTS AND DELEGATION 🌈

👑 THE TK OPTION DATABASE 👑

🎀 Setting the widget class

🦋 Setting option resource names and classes

⭐ Querying the option database

💜 Initializing locally defined options

🧠 MACROS AND META-PROGRAMMING 🧠

✅ VALIDATION TYPES ✅

🔥 DEFINING VALIDATION TYPES 🔥

💀 CAVEATS 💀

😭 KNOWN BUGS 😭

💫 HISTORY 💫

🌸 CREDITS 🌸

🔍 BUGS, IDEAS, FEEDBACK 🔍

🏷️ KEYWORDS 🏷️

📂 CATEGORY 📂

©️ COPYRIGHT ©️

`snit::type name definition`

🛠️ `proc name args body`

🐕 `delegate method name to comp ?as target?`

🧩 `delegate method name ?to comp? using pattern`

🌟 `delegate method * ?to comp? ?using pattern? ?except exceptions?`

🎀 `delegate option`

🧚 `component comp ?-public method? ?-inherit flag?`

👑 `delegate typemethod name to comp ?as target?`

🦋 `delegate typemethod name ?to comp? using pattern`

🦋 `delegate typemethod * ?to comp? ?using pattern? ?except exceptions?` 🦋

🎀 `typecomponent comp ?-public typemethod? ?-inherit flag?` 🎀

👑 `pragma ?options...?` 👑

💀 `expose comp` 💀

💀 `expose comp as method` 💀

🚫 `onconfigure name arglist body` 🚫

🚫 `oncget name body` 🚫

🌸 `snit::widget name definition` 🌸

`codename` name