Overview

Toolbar module is encapsulation of the system Toolbar API. The module is designed with following goals in mind:

To allow programmers to quickly create toolbars in intuitive way (i.e. in AHK spirit)
To allow advanced (non-typical) use, such as dynamic toolbar creation in such way that it doesn’t complicate typical toolbar usage.
To allow users to customize toolbar and programmer to save changed toolbar state.
Not to have any side effects to your script.

How it works

Toolbar consist of two sets of buttons – current buttons (buttons currently visible on the toolbar) and available buttons (buttons not currently visible, but user may add them using customization dialog). If you don’t want customization feature you can entirely omit list of available buttons. When user interacts with the toolbar specific event will be fired that you can implement in the body of the toolbar event function.

Each button may have associated image and text. Images are kept in the ImageList. By default you don’t have to specify image list. In that case module will use one of the system image catalogs that contain standard application icons.

To add toolbar in your gui, you use Add function. This function returns handle to newly created toolbar which you must use in all other functions. During creation, you can specify toolbar style: is it going to be flat, customizable, with tooltips etc… You must also specify event function that will be called whenever specific event is fired:

hToolbar := Toolbar_Add(hGui, "OnToolbar", "FLAT TOOLTIPS")

After the toolbar is created you must add buttons to it. You can add buttons one by one, or as group. Each button is described using button definition – list of button characteristics separated by comma, for instance:

Toolbar_Insert(hToolbar, "open, 11, ,dropdown")
Toolbar_Insert(hToolbar, "close")
Toolbar_Insert(hToolbar, "exit, 3")

Above code will add three button to the toolbar hToolbar. First will have caption open, use 11th icon from the image list and be of type dropdown (button that also can display menu). You can omit one or more parameters in button definition as seen in second and third case.

However, you will most likely wish to handle set of button definitions as whole, so there is another syntax. You can use button definition list – list of button definitions, each one in the next line:

btns =
(LTrim
	open	,	,		,dropdown
	close	,
	-
	undo	,4	,disabled	,dropdown
	redo	,5
	---
	state	,11	,checked	,check
)
Toolbar_Insert(hToolbar, btns)

The above code is more intuitive way of creating toolbar. First two buttons (open and close) will get icons 1 and 2 (since I didn’t specify any icon number, module will automatically set the number of line as an icon. You can specify separator using – and you can even set separator size: each – adds 10px to separator, so separator – – – will be of 30px size. Then, you can see that state button is of check type and that is initially checked. Button undo is created as disabled and is of type dropdown (so you can for instance display menu with undo levels). Separators are not counted when icon numbers are automatically set, so if you order icons in image list the way they appear on the toolbar, you can totally omit manual icon specification: first button will get icon number 1, second button icon number 2 and so on…

Once you have buttons on the toolbar, you need the way to handle user events. That’s the purpose of the event function which has following prototype:

OnToolbar(hwnd, event, txt, pos, id) {
	;your code here
}

Above function must be written in order to handle toolbar events. It must have 5 parameters but you can name them whatever you like. Its parameters are, respectively, handle to the toolbar that generated event, event that is fired, position of the button that fired event, its caption and its ID (unique ID that each button has). One typical event handler would look like:

OnToolbar(hwnd, event, txt, pos, id) {
	if (event = "hot")
		return SB_SetText(txt)	;if user is hovering the button with mouse, 
					; set status bar text with the button text.
 
	;display message box about event
	MsgBox Event:  %event%`nPosition:  %pos%`nCaption:  %txt%`n`nID:%id%    
}

That pretty much covers the basics of using Toolbar module and it is everything you need to know to start using it.

Customization

You can let a user customize the toolbar in two different ways: create the toolbar with adjustable style or call Customize function. If you use the style, a user will be able to double click the empty toolbar area to show customization dialog. In the dialog user can reorder buttons or remove them from the toolbar (i.e. put them in the list of available buttons). User can also SHIFT + drag to reorder or remove the button without opening the customization dialog.

Typical scenario consist of buttons currently on the toolbar and the list of available buttons. Both types of buttons are added the same as before with one note – buttons marked with * will be added to the list of the available buttons instead to the toolbar itself:

btns =
(LTrim
	open	,	,		,dropdown
	close	,
	-
	undo	,4	,disabled	,dropdown
	redo	,5
	---
	state	,11	,checked	,check
 
       *print   ,23
       *find    ,13
       *replace ,14
)
Toolbar_Insert(hToolbar, btns)

Above, I add 5 buttons on the toolbar and I make 3 more available (marked with *). There is empty line between current and available buttons (this doesn’t influence parsing as empty lines in the button definition list are simply skipped). You can mix both type of buttons in the button definition list although I suggest to keep them separated with blank line for better visibility.

When application exits, you will most definitely want to save the current state of the toolbar in configuration file so you can start with that toolbar state on the next run. This is the purpose of the Define function. Code

btns := Toolbar_Define(hToolbar)

will save the current button state (in the form of button definition list) to the btns variable. You can then save this variable in a file and load the toolbar from it next time your application is started.

Notes and Tips

Before adding toolbar control to the GUI, you must first set its size so toolbar can set its own size based on the size of its parent. Since you will not want to show the window in that moment, you can do like this:
```
Gui, Show , w200 h300 Hide
```
If you use customization feature, be aware that you can not depend on button position in toolbar event handler as user can change it. You could use button text instead (as with AHK Menu handlers). If you let the user change the button text also, beside position, you can not know what button user clicked based on position and its caption, so you need to use ID. Just set your own unique number as the last parameter of button definition:
```
weird button,,,dropdown, 101
```
As you can see, I set 101 as button’s identifier and in event handler I can be sure that i got the weird button by comparing its ID to the ID passed to the event handler. You can use this for any other situation. If you don’t set button’s ID, module will do it on its own anyway but you can not know, generally, which number particular button may get (if the toolbar was customized)
There are two ways to implement tooltips. Button caption can be seen as tooltip if you use LIST TOOLTIPS styles of the toolbar and omit SHOWTEXT among button styles. This means that button caption will not be visible at the right side of the button (only image will be shown) but text will be visible in tooltip when user hovers over that button. You can set multiline tooltips too – just put `r (line feed) where you want new line to appear (you can’t use new lines as they start new definition in the button definition list). Another way, more flexible, which allows you to have both captions and tooltips the same time is to write code for hot event (which fires when user hovers the button). In the handler posted above I set the status bar text in hot event but you could similarly display tooltip.
You can customize toolbar without opening customization dialog by holding SHIFT and dragging buttons around. For this to work you must crate toolbar with adjustable flag. By dragging you can do all operations that customization dialog allows except adding available buttons (obviously). You can, move button left or right, remove button by dropping it outside of the parent window, move the button to the end by dropping it bellow the toolbar in the client area of parent window, create separator before the button if you drop the button on itself.
To postion tooltip anywhere in the parent window you must use optional pPos parameter when adding toolbar for the first time. This will set toolbar in movable mode, otherwise it automatically calculates its dimension according to the parent’s width. By specifying any of the x,y,w or h, you can put toolbar anywhere and size it as desired. You can use AutoSize function and set its align parameter for the toolbar to be positioned on some of the common places.
This is only small preview of possibilities. For detailed explanation of functions you can use see module manual. If you want to play with the module and experiment with its functions, see included test script.