Starting with version 8.1a4, AlphaX attaches a toolbar to the document windows (see the AlphaToolbar page) and provides a [toolbar] command to create custom items for this toolbar and manipulate them (more about this on the ToolbarCommand page).
On the AlphaTcl side, there is a a new early and always-on feature called toolbar which takes care of managing additional custom toolbar items provided by the library. The purpose of this page is to provide more insight about the technique of creating custom toolbar items and considerations about the implications.
The toolbar feature is defined in
$HOME/Tcl/SystemCode/toolbar.tcl. It is loaded early during the
startup phase which executes an initialzation procedure
(toolbar::initializePackage). This procedure is called when this package
is first activated and defines additional default toolbar items that the
user can add via the Customize commands.
A few notes about the AlphaX implementation of the toolbar will help explain why this procedure is very important, and should be modified with care. The user's toolbar configuration is always saved between editing sessions; internally it is built with the kHIToolbarAutoSavesConfig flag turned on. This includes the size (small, normal, default), the mode (iconlabel, icon, label, and default), and any items added to the toolbar via the Customize command.
The AlphaX core defines a few default items as well as a Default Set, and hard-wires the names of any AlphaTcl callback procedures required to execute them. These include:
All these built-in toolbar items have symbolic names so that they can be invoked by several [toolbar] subcommands. See Built-in toolbar items.
When the user changes the toolbar configuration, the new settings are
saved in the file
file will be read the first time that a window is created by AlphaX.
The procedure [toolbar::initializePackage] defines additional default items that will appear in the Customize sheet, allowing the user to add them if desired, and these customized configuration settings are also saved in the user's .plist file.
If you create a custom item with [toolbar create] it receives a token toolbaritem1. If the user inserts it in the toolbar, the preferences are saved to disk when AlphaX quits.
(If you open the net.cabal.alphax.plist file with Property List Editor, for instance, you will see the list of the identifiers corresponding to the items present in your toolbar (in the left to right order). The custom item will have the following identifier:
Now when you relaunch AlphaX there is no problem until you display a
window: at this point the toolbar must be attached to the window and the
toolbar object reads the preferences file in order to reconstruct the
items in the right order. A kEventToolbarCreateItemWithIdentifier
CarbonEvent is sent for each item; when it sees
the core recognizes that it is one of our objects so it checks to see if
it already knows the toolbaritem1 token. The answer will be no if the
[toolbar create] command has not yet been invoked), so it skips the
creation of the item.
Here is the tricky scenario: if, before any window is displayed, AlphaTcl has created some custom items there would certainly be an item with token toolbaritem1 so, in the previous steps, this item would be instanciated. But we have no way to know if this toolbaritem1 corresponds to the same object as the toolbaritem1 which had been saved in the .plist file.
And that is why we have this package: so long as it is defined as an early and always-on AlphaTcl feature in runAlphaTcl.tcl then we know that the procedure [toolbar::initializePackage] will be evaluated before any other code has an opportunity to make any [toolbar create ...] calls. This will ensure that toolbaritem1 will always correspond to the very first item defined here, and toolbaritem2 will always correspond to the second item, etc.
Thus there are three implications of this scheme that AlphaTcl developers should keep in mind: