From AlphaWiki

Development: The AlphaTcl toolbar package

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.

Notes about the AlphaX toolbar

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:

Info/Mode pop-up menus

These items cannot be removed by the user. They are executed via these hooks defined in alphaHooks.tcl: wrapMenuHook, fileInfoMenuHook, and modeMenuHook. Note that the old Wrap popup has been merged into the Info popup.

Customize

This item can be removed by the user, in which case it is always available as a toolbar contextual menu command. It is executed internally by the core.

Print

This item can be removed by the user. It is executed by the procedure [toolbar::doPrint] in this file.

Search

This item is defined but not included in the Default Set defined by the core; the user can add it using the Customize command. It is a search field: its action is executed by the procedure [toolbar::doSearch] in this file.

Browse

This item is defined but not included in the Default Set defined by the core; the user can add it using the Customize command. It is a segmented button with a left and a right arrow: its action is executed by the procedure [toolbar::doSearch] in this file.

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 ~/Library/Preferences/net.cabal.alphax.plist. This file will be read the first time that a window is created by AlphaX.

The initializePackage procedure

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:

 
	 cabal.alphax.toolbar.button.toolbaritem1 

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 cabal.alphax.toolbar.button.toolbaritem1 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.

Implications

Thus there are three implications of this scheme that AlphaTcl developers should keep in mind:

1. Change the order of default custom item definitions with great discretion. ((nl The order in which additional items are defined in this [toolbar::initializePackage] procedure is very important, and should not change unless you intend to frustrate the user by arbitrarily altering the items displayed in the toolbar. Yes, this would only happen once, and when the user customizes the toolbar the new settings will be saved, but in general once an item has been added here it should not be removed or added in a different order. New default options should be defined at the end of the current list. This remark does not concern the permanent items described above which have a unique unambiguous identifier and can be reordered at no risk.
2. Other AlphaTcl packages should delete their items in a [quitHook]. ((nl Because this package is always-on and loaded early, we have some measure of control over the order in which items are defined. Other AlphaTcl packages will not have that luxury. If you have a proposed toolbar item that would be useful globally then please propose that it be added to this package. Otherwise, it is highly recommended that whenever you add an item using [toolbar create] you also register a [quitHook] that would call [toolbar delete]. Yes, this means that even if the user added the item with the Customize command it will not appear in the toolbar when AlphaX is relaunched.
3. AlphaTcl packages could use [toolbar add|remove] instead. ((nl An alternative to creating an item that would always be available to the user is to add it using the command [toolbar add]. This will automatically insert the item into the toolbar. For example, a Mail composition window might want to add a Send button. In this case an [activateHook] could be used to add the item when the composition window is active, and a [deactivateHook] to remove it when this window is closed or put in the background. In some cases, an AlphaTcl preference could be defined to allow the user to decide if these items should be added to the toolbar or not.