Archetype(3itk)

okay bestie, it's giving documentation era, and we're diving into Archetype(3itk) 💅✨

---

🎀 NAME 🎀

Archetype — base class for all [incr Tk] mega-widgets 💖

🦋 INHERITANCE 🦋

none. literally none, she's the blueprint, the moment, the origin story 👑

✨ WIDGET-SPECIFIC OPTIONS ✨

• -clientdata — Name: clientData, Class: ClientData, Command-Line Switch: -clientdata.

This does not affect the widget operation in any way. It is simply a hook that clients can use to store a bit of data with each widget. This can come in handy when using widgets to build applications. 🎀

🌸 DESCRIPTION 🌸

The Archetype class is the basis for all [incr Tk] mega-widgets. She keeps track of component widgets and provides methods like configure and cget that are used to access the composite configuration options. Each component widget must be registered with the Archetype base class using the itk_component add method. When the component is registered, its configuration options are integrated into the composite option list. Configuring a composite option like -background causes all of the internal components to change their background color. 🔥

It is not used as a widget by itself, but is used as a base class for more specialized widgets. The Widget base class inherits from Archetype, and adds a Tk frame which acts as the hull for the mega-widget. The Toplevel base class inherits from Archetype, but adds a Tk toplevel which acts as the hull. 🛠️

Each derived class must invoke the itk_initialize method within its constructor, so that all options are properly integrated and initialized in the composite list. no cap, that's mandatory bestie ⭐

💅 PUBLIC METHODS 💅

The following methods are provided to support the public interface of the mega-widget. okay so these are the main character methods 👑

pathName cget option

Returns the current value of the configuration option given by option. ✨

In this case, option refers to a composite configuration option for the mega-widget. Individual components integrate their own configuration options onto the composite list when they are registered by the itk_component add method. 💖

pathName component ?name? ?command arg arg ...?

Used to query or access component widgets within a mega-widget. With no arguments, this returns a list of symbolic names for component widgets that are accessible in the current scope. The symbolic name for a component is established when it is registered by the itk_component add method. Note that component widgets obey any public/protected/private access restriction that is in force when the component is created. 🦋

If a symbolic name is specified, this method returns the window path name for that component. 👀

Otherwise, the command and any remaining arg arguments are invoked as a method on the component with the symbolic name name. This provides a well-defined way of accessing internal components without relying on specific window path names, which are really details of the implementation. 💯

pathName configure ?option? ?value option value ...?

Query or modify the configuration options of the widget. If no option is specified, returns a list describing all of the available options for pathName (see Tk_ConfigureInfo for information on the format of this list). If option is specified with no value, then the command returns a list describing the one named option (this list will be identical to the corresponding sublist of the value returned if no option is specified). If one or more option-value pairs are specified, then the command modifies the given widget option(s) to have the given value(s); in this case the command returns an empty string. 🎀

In this case, the options refer to composite configuration options for the mega-widget. Individual components integrate their own configuration options onto the composite list when they are registered by the itk_component add method. periodt 💅

🛠 PROTECTED METHODS 🛠

okay bestie, these are the methods your derived classes get to use when you're building out a mega-widget, the behind-the-scenes stuff 💅

• itk_component add ?-protected? ?-private? ?--? name createCmds ?optionCmds? — this one makes a whole component widget by running the createCmds you hand it, then registers that new component under the symbolic name name. The -protected and -private flags keep the component hidden from the outside world, and ngl they do basically the same thing to component visibility that they do to class members. The createCmds code can hold as many commands as you want, but it absolutely must return the window path name for the new component widget. And the optionCmds script is where you describe how the new component's configuration options should get integrated into the composite list for the mega-widget — it can contain any of these commands:
  • ignore option ?option option ...? — yeets one or more configuration options out of the composite list. Everything is ignored by default, so you only reach for ignore to undo a previous keep or rename. Super handy when some options added by the usual command shouldn't apply to a particular component and need to be ignored.
  • keep option ?option option ...? — pulls one or more configuration options into the composite list while keeping the name exactly the same. Every time the mega-widget option gets configured, the new value also lands on the current component. Options like -background and -cursor are the classic keep-list girlies.
  • rename option switchName resourceName resourceClass — integrates the configuration option into the composite list but under a different name. On the composite list the option is called switchName, and it also gets modified by setting values for resourceName and resourceClass in the X11 resource database. The -highlightbackground option commonly gets renamed to -background, so when the mega-widget background changes, the background of the focus ring changes too. iconic behavior honestly.
  • usual ?tag? — finds the usual option-handling commands for the tag name you give it and runs them. No tag? Then the widget class name is used as the tag name. Those "usual" option-handling commands are registered via the usual command.

If you don't specify the optionCmds script at all, the usual option-handling commands tied to the class of the component widget are used by default. no extra work, slay ✨

• itk_component delete name ?name name ...? — removes the component widget with symbolic name name from the mega-widget. Heads up though: the component widget still exists, it's just not accessible as a component of the mega-widget anymore. Also, any options associated with that component get removed from the composite option list.

lowkey you can also just destroy a component with the destroy command, same as you'd destroy any Tk widget. Components auto-detach themselves from their mega-widget parent when destroyed, so itk_component delete is rarely used fr fr.

• itk_initialize ?option value option value...? — bestie this one is mandatory, you must invoke it inside the constructor for every single class in a mega-widget hierarchy. It makes sure all options are properly integrated into the composite option list and syncs every component to the initial option values. Usually you call it near the bottom of the constructor, after all the component widgets have been added. If you pass any option/value pairs, they override settings determined from the X11 resource database. The arguments to the constructor are usually passed along to this method like so:

itcl::class MyWidget {
    inherit Widget

    constructor {args} {
        .
        .
        .
        eval itk_initialize $args
    }
}

• itk_option add optName ?optName optName ...? — adds one or more options to the composite option list for a mega-widget. Here optName can take one of these forms:
  • component.option — accesses an option belonging to a component with the symbolic name component. The option name is written without a leading - sign.
  • className::option — accesses an option defined by the itk_option define command in class className. Again, the option name is written without a leading - sign.

Options normally get integrated into the composite option list the moment a component widget is first created, but this method lets you add options later on. For example, the Widget and Toplevel base classes keep only the absolute bare minimum options for their hull component: -background and -cursor. A derived class can override that decision and add options that control the border of the hull component too:

itcl::class MyWidget {
    inherit Widget

    constructor {args} {
        itk_option add hull.borderwidth hull.relief

        itk_component add label {
            label $itk_interior.l1 -text "Hello World!"
        }
        pack $itk_component(label)

        eval itk_initialize $args
    }
}

• itk_option define switchName resourceName resourceClass init ?config? — this command lives at the level of the class definition and defines a synthetic mega-widget option. Inside the configure and cget methods, this option is referenced by switchName, which must start with a - sign. It can also be modified by setting values for resourceName and resourceClass in the X11 resource database. The init value string is the last resort for initializing the option, used only if no other value can be pulled from an existing option or queried from the X11 resource database. If you specify any config code, it runs every time the option is modified via the configure method. That config code can also be set outside of the class definition via the configbody command.

In this next example, a synthetic -background option is added to the class, so whenever the background changes, the new value gets reported to standard output. Note that this synthetic option is integrated with the rest of the -background options that have been kept from component widgets:

itcl::class MyWidget {
    inherit Widget
    constructor {args} {
        itk_component add label {
            label $itk_interior.l1 -text "Hello World!"
        }
        pack $itk_component(label)

        eval itk_initialize $args
    }
    itk_option define -background background Background #d9d9d9 {
        puts "new background: $itk_option(-background)"
    }
}

• itk_option remove optName ?optName optName ...? — removes one or more options from the composite option list for a mega-widget. Here optName can take either of the forms described above for the itk_option add command.

Options normally get integrated into the composite option list when a component widget is first created, and this method lets you remove them later. For example, a derived class can override an option defined in a base class by removing it and redefining it:

itcl::class Base {
    inherit itk::Widget
    constructor {args} {
        eval itk_initialize $args
    }

    itk_option define -foo foo Foo "" {
        puts "Base: $itk_option(-foo)"
    }
}

itcl::class Derived {
    inherit Base

    constructor {args} {
        itk_option remove Base::foo
        eval itk_initialize $args
    }
    itk_option define -foo foo Foo "" {
        puts "Derived: $itk_option(-foo)"
    }
}

Without the itk_option remove command, the code fragments for both of the -foo options would be executed every single time the composite -foo option is configured. In the example above, the Base::foo option is suppressed in all Derived class widgets, so only the Derived::foo option remains. crisis averted 💀

---

🔮 PROTECTED VARIABLES 🔮

derived classes can find all kinds of useful info in these protected variables, bestie 🫶

• itk_component(name) — this array returns the real window path name for a component widget with the symbolic name name. You can get the same info with the component method, but accessing this array is faster and more convenient. efficiency queen 👑
• itk_interior — this variable holds the name of the window that acts as a parent for internal components. It's initialized to the name of the hull component provided by the Widget and Toplevel classes. Derived classes can override that initial setting to point at another interior window to be used for further-derived classes.
• itk_option(option) — this array returns the current option value for the composite widget option named option. Here, the option name should include a leading - sign. Same info as the cget method, but again, accessing this array is faster and more convenient. 💅

---

🔑 KEYWORDS 🔑

itk, Widget, Toplevel, mega-widget

---

and that's the whole page babes 🎀 that was Archetype(3itk) from itk 3.0 — go forth and build your mega-widgets, you're literally the main character of this inheritance hierarchy now 🌈✨💖