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
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.
- 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.
- This item can be removed by the user. It is executed by the procedure [toolbar::doPrint] in this file.
- 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.
- 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
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:
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
Thus there are three implications of this scheme that AlphaTcl developers
should keep in mind:
- 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.
- 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.
- 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.