Manipulating Toolbars, Part I

In this page we'll teach you how to control the toolbars from JavaScript. Familiarize yourself with HomeSite's toolbars. Each toolbar is identified by a unique name which is both its file name as well as its window caption. Toolbars are loaded from files in the toolbar directory, which can be obtained from the ToolbarDir property. If, for example, the name of the toolbar is Common, its file will be stored under c:\homesite\toolbars\Common.tbr. The rest of this page covers the toolbar-related Application Object's property and methods.

ToolbarDir

String

Returns the full path of the directory where toolbar files reside. For example, the following JavaScript call:

app.MessageBox(app.ToolbarDir, "test", 0)

yields the following dialog box on our machine:

CreateToolbar(toolbarName)

Boolean

Creates a new toolbar with the given name (toolbarName). For example, calling app.CreateToolbar("yehuda") creates a new toolbar named "yehuda". You can see the list of toolbars under the Options/Customize menu. Returns a true value if successful, a false value otherwise.

HideToolbar(toolbarName)

Boolean

Hides the given toolbar (toolbarName). Returns a true value if successful, a false value otherwise. A false value is returned when the given toolbar is not found. The JavaScript call app.HideToolbar("yehuda") hides the previously-created toolbar. You can also verify that the toolbar named "yehuda" is unchecked in the toolbar list under Options/Customize menu.

DeleteToolbar(toolbarName)

Boolean

Deletes the given toolbar (toolbarName). You can delete only custom toolbars. You can hide built-in toolbars but you cannot delete them. Returns a true value if successful, a false value otherwise. A false value is returned when the given toolbar is not found. For example, the call app.DeleteToolbar("yehuda") deletes the previously-created-and-hidden toolbar "yehuda." You can verify that the toolbar "yehuda" does not exist in the toolbar list under Options/Customize/Toolbars menu.

ShowToolbar(toolbarName)

Boolean

Shows the given toolbar (toolbarName) if it's hidden. Returns a true value if successful, a false value otherwise. A false value is returned when the toolbar is not found. You can verify that the toolbar is deleted by going over the toolbar list under the Options/Customize/Toolbar menu.

ToolbarExists(toolbarName)

Boolean

Returns a true value if the given toolbar (toolbarName) exists. For example, the call app.ToolbarExists("linkbot") returns a true value. You can scan all existing toolbars under the Options/Customize/Toolbars menu.

SetToolbarDockPos(toolbarName, positionFlag)

Boolean

Sets the position of the given toolbar (toolbarName). The toolbar position (positionFlag) can be one of the following: 1 (top), 2 (bottom), 3 (left), or 4 (right). See what happens when you call app.SetToolbarDockPos("linkbot", 1). You should see the linkbot toolbar at the left top corner of the window. When you change the parameter to 2, it will be at the bottom left corner. Specifying 3 will position the toolbar along the left edge of the window, and the 4 value does so along the right hand side. Returns a true value when successful, a false value otherwise. A false value is returned when the given toolbar is not found.