How toolbars work

Toolbars are defined by XML and image files that are stored in the Toolbars folder of the main Dreamweaver Configuration folder. The default Dreamweaver toolbars are stored in the toolbars.xml file in the Configuration/Toolbars folder. When Dreamweaver starts, it loads all the toolbar files in the Toolbars folder. You can add new toolbars simply by copying a file into the Toolbars folder rather than modifying the original toolbars.xml file.

Toolbar XML files define one or more toolbars and their toolbar items. A toolbar is a list of items such as buttons, text boxes, pop-up menus, and so on. A toolbar item represents a single control that a user can access in a toolbar.

Some types of toolbar controls, such as push buttons and pop-up menus, have icon images associated with them. Icon images are stored in an images folder in the Toolbars folder. Images can be in any format that Dreamweaver can render but are typically GIF or JPEG file formats. Images for Macromedia-authored toolbars are stored in the Toolbars/images/MM folder.

As with menus, you can specify the functionality of individual toolbar items either through the item attributes or through a command file. Macromedia-authored toolbar command files are stored in the Toolbars/MM folder.

TIP

The Toolbar API is compatible with the Menu Commands API, so toolbar controls can reuse menu command files.

Unlike menus, you can define toolbar items independently from the toolbars that use them. This flexibility lets you use toolbar items in multiple toolbars by using the itemref tag.

The first time Dreamweaver loads a toolbar, its visibility and position are set by the toolbar definition. After that, its visibility and position are saved in and restored from the registry (Windows) or the Dreamweaver Preferences file (Macintosh).

How toolbars behave

In Windows, Dreamweaver toolbars generally act the same as standard Windows toolbars. Dreamweaver toolbars have the following characteristics:

• You can drag and drop toolbars to dock them, undock them, and reposition them relative to other toolbars.

• You can horizontally dock toolbars to the top or bottom of the frame window.

  In the Dreamweaver workspace, which integrates all the Dreamweaver document windows within a single parent frame, you can specify whether toolbars dock to the workspace frame or to the document window.

  For toolbars that dock to the Dreamweaver workspace frame, there is only one instance of each toolbar. In this case, the toolbars always operate on the document in front. In the Dreamweaver workspace, you can dock toolbars above, below, or to the left or right of the Insert toolbar. Toolbars that are attached to the Dreamweaver workspace frame do not automatically disable when there is no document window. The toolbar items determine whether they are enabled when no document is open.

  When toolbars stay docked to the document window, there is one instance for each window. Toolbars that are attached to a document window completely disable themselves when their window is not the front document and rerun all their update handlers when their window comes to the front.You cannot drag and drop toolbars between the document window and the Dreamweaver workspace frame.

• Toolbars remain a fixed size. A toolbar does not shrink if the container shrinks or if other toolbars are placed next to it.

• You can show or hide toolbars from the View >Toolbars menu.

• Toolbars cannot overlap.

• Only the outline of the toolbar appears while you drag it.

On the Macintosh, toolbars are always attached to the document window. They can be shown or hidden from the menu, but you cannot drag and drop, rearrange, or undock them.

How toolbar commands work

When Dreamweaver draws a toolbar, the following events occur:

1.	For each toolbar control item, Dreamweaver determines whether the file attribute exists.
2.	If the file attribute exists, Dreamweaver calls the canAcceptCommand() function to determine whether it should enable the control in the current context of the document. For the Document Title text box in the Dreamweaver toolbar, for example, the canAcceptCommand() function checks to see if there is a current DOM and if the current document is an HTML file. If both these conditions are true, the function returns TRue and Dreamweaver enables the text box on the toolbar.
3.	If the file attribute exists, Dreamweaver ignores the following attributes, if they are specified: checked, command, DOMRequired, enabled, script, showif, update, and value.
4.	If the file attribute does not exist, Dreamweaver processes the attributes that are set for the toolbar control item: checked, command, DomRequired, and so on. For more information on specific item tag attributes, see "Item tag attributes" on page 232.
5.	Dreamweaver calls the getCurrentValue() function on every update cycle, as specified by the update attribute, to determine what value to display for the control.
6.	The user selects an item on the toolbar.
7.	Dreamweaver calls the receiveArguments() function to process any arguments that the arguments attribute of the toolbar item specifies.

For more information on the purpose of specific functions in the Toolbar Command API, see "The toolbar command API" on page 238.