# Toolbar

Toolbar control.

The module is designed with following goals in mind :

- To allow programmers to quickly create toolbars in intuitive way.
- 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 on your script.

Summary

Toolbar | Toolbar control.
Add | Add a Toolbar to the GUI
AutoSize | Causes a toolbar to be resized.
Clear | Removes all buttons from the toolbar, both current and available
Count | Get count of buttons on the toolbar
CommandToIndex | Retrieves the button position given the ID.
Customize | Launches customization dialog
CheckButton | Get button information
Define | Get the toolbar definition list.
DeleteButton | Delete button from the toolbar.
GetButton | Get button information
GetButtonSize | Gets the size of buttons.
GetMaxSize | Retrieves the total size of all of the visible buttons and separators in the toolbar.
GetRect | Get button rectangle
Insert | Insert button(s) on the Toolbar.
MoveButton | Moves a button from one position to another.
SetBitmapSize | Sets the size of the bitmapped images to be added to a toolbar.
SetButton | Set button information
SetButtonWidth | Sets button width.
SetDrawTextFlags | Sets the text drawing flags for the toolbar.
SetButtonSize | Sets the size of buttons.
SetImageList | Set toolbar image list.
SetMaxTextRows | Sets the maximum number of text rows displayed on a toolbar button.
ToggleStyle | Toggle specific toolbar creation style
Examples |
About |

### Add

> Toolbar_Add( | hGui, |  |
> | Handler, |  |
> | Style | = | "",
> | ImageList | = | "",
> | Pos | = | "" | )

Add a Toolbar to the GUI

#### Parameters

hGui | HWND of the GUI. GUI must have defined size.
Handler | User function that handles Toolbar events. See below.
Style | Styles to apply to the toolbar control, see list of styles bellow.
ImageList | Handle of the image list that contains button images. Otherwise it specifies number and icon size of the one of the 3 system catalogs (see Toolbar_catalogs). Each catalog contains number of common icons in large and small size -- S or L (default). Defaults to “1L” (first catalog, large icons)
Pos | Position of the toolbar specified - any space separated combination of the x y w h keywords followed by the size.

> Toolbar_catalogs

#### Control Styles

adjustable | Allows users to change a toolbar button’s position by dragging it while holding down the SHIFT key and to open customization dialog by double clicking Toolbar empty area, or separator.
border | Creates a Toolbar that has a thin-line border.
bottom | Causes the control to position itself at the bottom of the parent window’s client area.
flat | Creates a flat toolbar. In a flat toolbar, both the toolbar and the buttons are transparent and hot-tracking is enabled. Button text appears under button bitmaps. To prevent repainting problems, this style should be set before the toolbar control becomes visible.
list | Creates a flat toolbar with button text to the right of the bitmap. Otherwise, this style is identical to FLAT style. To prevent repainting problems, this style should be set before the toolbar control becomes visible.
tooltips | Creates a ToolTip control that an application can use to display descriptive text for the buttons in the toolbar.
nodivider | Prevents a two-pixel highlight from being drawn at the top of the control.
tabstop | Specifies that a control can receive the keyboard focus when the user presses the TAB key.
wrapable | Creates a toolbar that can have multiple lines of buttons. Toolbar buttons can “wrap” to the next line when the toolbar becomes too narrow to include all buttons on the same line. When the toolbar is wrapped, the break will occur on either the rightmost separator or the rightmost button if there are no separators on the bar. This style must be set to display a vertical toolbar control when the toolbar is part of a vertical rebar control.
vertical | Creates vertical toolbar.
menu | Creates a toolbar that simulates Windows menu.

#### Handler

>     Handler(Hwnd, Event, Txt, Pos, Id)

Hwnd | Handle of the Toolbar control sending the message.
Event | Event name. See bellow.
Txt | Button caption.
Pos | Button position.
Id | Button ID.

#### Events

click | User has clicked on the button.
rclick | User has clicked the right button.
menu | User has clicked on the dropdown icon.
hot | User is hovering the button with the mouse.
change | User has dragged the button using SHIFT + drag.
adjust | User has finished customizing the toolbar.

#### Returns

Control’s handle or error message.

#### Remarks

To avoid lost messages and/or script lockup, events triggered by the toolbar buttons should complete quickly. If an event takes more than a few milliseconds to complete, consider creating an independent thread to accomplish the task:

>     if event=click
>         if button=BigFatRoutine
>         {
>             SetTimer MyBigFatRoutine,0
>             return
>         }

If you happen to have unusual control behavior-missing events, redrawing issues etc... try adding Critical command (or better Critical N) at the start of the Toolbar_onNotify function. It helps to improve the odds that no messages are dropped. The drawback of using the command is that the function refuses to be interrupted. This is not a problem if the developer is very careful not to call any routines or functions that use anything more than a few milliseconds. However, any little mistake -- an unexpected menu, prompt, MsgBox, etc., and the script will lock up. Without the Critical command, the function is a lot more forgiving. The developer should still be careful but the script won’t shut down if something unexpected happens.

### AutoSize

> Toolbar_AutoSize( | hCtrl, |  |
> | Align | = | "fit" | )

Causes a toolbar to be resized.

#### Parameters

Align | How toolbar is aligned to its parent. bottom left (bl), bottom right (br), top right (tr), top left (tl) or fit (doesn’t reposition control resizes it so it takes minimum possible space with all buttons visible)

#### Remarks

An application calls the AutoSize function after causing the size of a toolbar to change either by setting the button or bitmap size or by adding strings for the first time.

### Clear

> Toolbar_Clear( | hCtrl | )

Removes all buttons from the toolbar, both current and available

### Count

> Toolbar_Count( | hCtrl, |  |
> | pQ | = | "c" | )

Get count of buttons on the toolbar

#### Parameters

pQ | Query parameter, set to “c” to get the number of current buttons (default) Set to “a” to get the number of available buttons. Set to empty string to return both.

#### Returns

if pQ is empty function returns rational number in the form cntC.cntA otherwise requested count

### CommandToIndex

> Toolbar_CommandToIndex( | hCtrl,
> | ID | )

Retrieves the button position given the ID.

#### Parameters

ID | Button ID, number > 0.

#### Returns

0 if button with that ID doesn’t exist, pos > 0 otherwise.

### Customize

> Toolbar_Customize( | hCtrl | )

Launches customization dialog

### CheckButton

> Toolbar_CheckButton( | hCtrl, |  |
> | WhichButton, |  |
> | bCheck | = | 1 | )

Get button information

#### Parameters

WhichButtton | One of the ways to identify the button: 1-based button position or button ID. If WhichButton is negative, the information about available (*) button on position -WhichButton will be returned.
bCheck | Set to 1 to check the button (default).

#### Returns

Returns TRUE if successful, or FALSE otherwise.

#### Remarks

With groupcheck use this function to check button. Using SetButton function will not uncheck other buttons in the group.

### Define

> Toolbar_Define( | hCtrl, |  |
> | pQ | = | "" | )

Get the toolbar definition list.

#### Parameters

pQ | Query parameter. Specify “c” to get only current buttons, “a” to get only available buttons. Leave empty to get all buttons. Returns: Button definition list. You can use the list directly with Insert function.

### DeleteButton

> Toolbar_DeleteButton( | hCtrl, |  |
> | Pos | = | 1 | )

Delete button from the toolbar.

#### Parameters

Pos | 1-based position of the button, by default 1. To delete one of the available buttons, specify “*” before the position.

#### Returns

TRUE if successful.

### GetButton

> Toolbar_GetButton( | hCtrl, |  |
> | WhichButton, |  |
> | pQ | = | "" | )

Get button information

#### Parameters

WhichButtton | One of the ways to identify the button: 1-based button position or button ID. If WhichButton is negative, the information about available (*) button on position -WhichButton will be returned.
pQ | Query parameter, can be C (Caption) I (Icon number), S (State), L (styLe) or ID. If omitted, all information will be returned in the form of button definition.

#### Returns

If pQ is omitted, button definition, otherwise requested button information.

#### Examples

>     s := GetButton(hCtrl, 3)          ;returns button definition for the third button.
>     c := GetButton(hCtrl, 3, "c")     ;returns only caption of that button.
>     d := GetButton(hCtrl,-2, "id")    ;returns only id of the 2nd button from the group of available (*) buttons.
>     s := GetButton(hCtrl, .101, "s")  ;returns the state of the button with ID=101.

### GetButtonSize

> Toolbar_GetButtonSize( |  | hCtrl,
> | ByRef | W,
> | ByRef | H | )

Gets the size of buttons.

#### Parameters

W, H | Output width & height.

### GetMaxSize

> Toolbar_GetMaxSize( |  | hCtrl,
> | ByRef | Width,
> | ByRef | Height | )

Retrieves the total size of all of the visible buttons and separators in the toolbar.

#### Parameters

Width, Height | Variables which will receive size.

#### Returns

Returns TRUE if successful.

### GetRect

> Toolbar_GetRect( | hCtrl, |  |
> | Pos | = | "",
> | pQ | = | "" | )

Get button rectangle

#### Parameters

pPos | Button position. Leave blank to get dimensions of the toolbar control itself.
pQ | Query parameter: set x,y,w,h to return appropriate value, or leave blank to return all in single line.

#### Returns

String with 4 values separated by space or requested information

### Insert

> Toolbar_Insert( | hCtrl, |  |
> | Btns, |  |
> | Pos | = | "" | )

Insert button(s) on the Toolbar.

#### Parameters

Btns | The button definition list. Each button to be added is specified on separate line using button definition string. Empty lines will be skipped.
Pos | Optional 1-based index of a button, to insert the new buttons to the left of this button. This doesn’t apply to the list of available buttons.

#### Button Definition

Button is defined by set of its characteristics separated by comma:

caption | Button caption. All printable letters are valid except comma. “-” can be used to add separator. Add more “-” to set the separator width. Each “-” adds 10px to the separator.
iconNumber | Number of icon in the image list
states | Space separated list of button states. See bellow list of possible states.
styles | Space separated list of button styles. See bellow list of possible styles.
ID | Button ID, unique number you choose to identify button. On customizable toolbars position can’t be used to set button information. If you need to setup button information using SetButton function or obtain information using GetButton, you need to use button ID as user can change button position any time. It can by any number. Numbers > 10,000 are choosen by module as auto ID feature, that module does on its own when you don’t use this option. In most typical scenarios you don’t need to use ID or think about them to identify the button. To specify ID in functions that accept it put dot infront of it, for instance .427 represents ID=427. This must be done in order to differentiate IDs from button position.

#### Button Styles

AUTOSIZE | Specifies that the toolbar control should not assign the standard width to the button. Instead, the button’s width will be calculated based on the width of the text plus the image of the button.
CHECK | Creates a dual-state push button that toggles between the pressed and nonpressed states each time the user clicks it.
CHECKGROUP | Creates a button that stays pressed until another button in the group is pressed, similar to option buttons (also known as radio buttons).
DROPDOWN | Creates a drop-down style button that can display a list when the button is clicked.
NOPREFIX | Specifies that the button text will not have an accelerator prefix associated with it.
SHOWTEXT | Specifies that button text should be displayed. All buttons can have text, but only those buttons with the SHOWTEXT button style will display it. This button style must be used with the LIST style. If you set text for buttons that do not have the SHOWTEXT style, the toolbar control will automatically display it as a ToolTip when the cursor hovers over the button. For this to work you must create the toolbar with TOOLTIPS style. You can create multiline tooltips by using `r in the tooltip caption. Each `r will be replaced with new line.

#### Button States

CHECKED | The button has the CHECK style and is being clicked.
DISABLED | The button does not accept user input.
HIDDEN | The button is not visible and cannot receive user input.
WRAP | The button is followed by a line break. Toolbar must not have WRAPABLE style.

#### Remarks

Using this function you can insert one or more buttons on the toolbar. Furthermore, adding group of buttons to the end (omiting pPos) is the fastest way of adding set of buttons to the toolbar and it also allows you to use some automatic features that are not available when you add button by button. If you omit some parameter in button definition it will receive default value. Button that has no icon defined will get the icon with index that is equal to the line number of its defintion list. Buttons without ID will get ID automaticaly, starting from 10 000. You can use `r instead `n to create multiline button captions. This make sense only for toolbars that have LIST TOOLTIP toolbar style and no SHOWTEXT button style (i.e. their captions are seen as tooltips and are not displayed.

### MoveButton

> Toolbar_MoveButton( | hCtrl,
> | Pos,
> | NewPos | )

Moves a button from one position to another.

#### Parameters

Pos | 1-based position of the button to be moved.
NewPos | 1-based position where the button will be moved.

#### Returns

Returns nonzero if successful, or zero otherwise.

### SetBitmapSize

> Toolbar_SetBitmapSize( | hCtrl, |  |
> | Width | = | 0,
> | Height | = | 0 | )

Sets the size of the bitmapped images to be added to a toolbar.

#### Parameters

Width, Height | Width & heightin pixels, of the bitmapped images. Defaults to 0,0

#### Returns

TRUE if successful, or FALSE otherwise.

#### Remarks

The size can be set only before adding any bitmaps to the toolbar. If an application does not explicitly set the bitmap size, the size defaults to 16 by 15 pixels.

### SetButton

> Toolbar_SetButton( | hCtrl, |  |
> | WhichButton, |  |
> | State | = | "",
> | Width | = | "" | )

Set button information

#### Parameters

WhichButton | One of the 2 ways to identify the button: 1-based button position or button ID
State | List of button states to set, separated by white space.
Width | Button width (can’t be used with LIST style)

#### Returns

Nonzero if successful, or zero otherwise.

### SetButtonWidth

> Toolbar_SetButtonWidth( | hCtrl, |  |
> | Min, |  |
> | Max | = | "" | )

Sets button width.

#### Parameters

Min, Max | Minimum and maximum button width. If you omit pMax it defaults to pMin.

#### Returns

TRUE if successful.

### SetDrawTextFlags

> Toolbar_SetDrawTextFlags( | hCtrl,
> | Mask,
> | Flags | )

Sets the text drawing flags for the toolbar.

#### Parameters

Mask | One or more of the DT_ flags, specified in DrawText, that indicate which bits in dwDTFlags will be used when drawing the text.
Flags | One or more of the DT_ flags, specified in DrawText, that indicate how the button text will be drawn. This value will be passed to the DrawText API when the button text is drawn. Returns: Returns the previous text drawing flags.

#### Remarks

See http://msdn.microsoft.com/en-us/library/bb787425(VS.85).aspx for more info.

#### Example

Toolbar_SetDrawTextFlags(hToolbar, 3, 2) ;right align text

### SetButtonSize

> Toolbar_SetButtonSize( | hCtrl, |  |
> | W, |  |
> | H | = | "" | )

Sets the size of buttons.

#### Parameters

W, H | Width & Height. If you omit height, it defaults to width.

#### Remarks

With LIST style, you can only set the height.

### SetImageList

> Toolbar_SetImageList( | hCtrl, |  |
> | hIL | = | "1S" | )

Set toolbar image list.

#### Parameters

hIL | Image list handle.

#### Returns

Handle of the previous image list.

### SetMaxTextRows

> Toolbar_SetMaxTextRows( | hCtrl, |
> | iMaxRows | = | )

Sets the maximum number of text rows displayed on a toolbar button.

#### Parameters

iMaxRows | Maximum number of rows of text that can be displayed.

#### Remarks

Returns nonzero if successful, or zero otherwise. To cause text to wrap, you must set the maximum button width by using SetButtonWidth. The text wraps at a word break. Text in LIST styled toolbars is always shown on a single line.

### ToggleStyle

> Toolbar_ToggleStyle( | hCtrl, |  |
> | Style | = | "LIST" | )

Toggle specific toolbar creation style

#### Parameters

Style | Style to toggle, by default “LIST”. You can also specify numeric style value.

### Examples

>        Gui, +LastFound
>        hGui := WinExist()
>        Gui, Show , w500 h100 Hide                              ;set gui width & height prior to adding toolbar (mandatory)

>        hCtrl := Toolbar_Add(hGui, "OnToolbar", "FLAT TOOLTIPS", "1L")    ;add the toolbar

>        btns =
>         (LTrim
>            new,  7,            ,dropdown showtext
>            open, 8
>            save, 9, disabled
>            -
>            undo, 4,            ,dropdown
>            redo, 5,            ,dropdown
>            -----
>            state, 11, checked  ,check
>         )

>         Toolbar_Insert(hCtrl, btns)
>         Toolbar_SetButtonWidth(hCtrl, 50)                   ;set button width & height to 50 pixels

>         Gui, Show
>     return

>     ;toolbar event handler
>     OnToolbar(hCtrl, Event, Txt, Pos){
>            tooltip %Event% %Txt% (%Pos%), 0, 0
>     }

### About

- Ver 2.31 by majkinetor. See http://www.autohotkey.com/forum/topic27382.html
- Parts of code in Toolbar_onNotify by jballi.
- Toolbar Reference at MSDN: http://msdn2.microsoft.com/en-us/library/bb760435(VS.85).aspx
- Licensed under GNU GPL http://creativecommons.org/licenses/GPL/2.0/

> Toolbar_Add( | hGui, |  |
> | Handler, |  |
> | Style | = | "",
> | ImageList | = | "",
> | Pos | = | "" | )

Add a Toolbar to the GUI

> Toolbar_AutoSize( | hCtrl, |  |
> | Align | = | "fit" | )

Causes a toolbar to be resized.

> Toolbar_Clear( | hCtrl | )

Removes all buttons from the toolbar, both current and available

> Toolbar_Count( | hCtrl, |  |
> | pQ | = | "c" | )

Get count of buttons on the toolbar

> Toolbar_CommandToIndex( | hCtrl,
> | ID | )

Retrieves the button position given the ID.

> Toolbar_Customize( | hCtrl | )

Launches customization dialog

> Toolbar_CheckButton( | hCtrl, |  |
> | WhichButton, |  |
> | bCheck | = | 1 | )

Get button information

> Toolbar_Define( | hCtrl, |  |
> | pQ | = | "" | )

Get the toolbar definition list.

> Toolbar_DeleteButton( | hCtrl, |  |
> | Pos | = | 1 | )

Delete button from the toolbar.

> Toolbar_GetButton( | hCtrl, |  |
> | WhichButton, |  |
> | pQ | = | "" | )

Get button information

> Toolbar_GetButtonSize( |  | hCtrl,
> | ByRef | W,
> | ByRef | H | )

Gets the size of buttons.

> Toolbar_GetMaxSize( |  | hCtrl,
> | ByRef | Width,
> | ByRef | Height | )

Retrieves the total size of all of the visible buttons and separators in the toolbar.

> Toolbar_GetRect( | hCtrl, |  |
> | Pos | = | "",
> | pQ | = | "" | )

Get button rectangle

> Toolbar_Insert( | hCtrl, |  |
> | Btns, |  |
> | Pos | = | "" | )

Insert button(s) on the Toolbar.

> Toolbar_MoveButton( | hCtrl,
> | Pos,
> | NewPos | )

Moves a button from one position to another.

> Toolbar_SetBitmapSize( | hCtrl, |  |
> | Width | = | 0,
> | Height | = | 0 | )

Sets the size of the bitmapped images to be added to a toolbar.

> Toolbar_SetButton( | hCtrl, |  |
> | WhichButton, |  |
> | State | = | "",
> | Width | = | "" | )

Set button information

> Toolbar_SetButtonWidth( | hCtrl, |  |
> | Min, |  |
> | Max | = | "" | )

Sets button width.

> Toolbar_SetDrawTextFlags( | hCtrl,
> | Mask,
> | Flags | )

Sets the text drawing flags for the toolbar.

> Toolbar_SetButtonSize( | hCtrl, |  |
> | W, |  |
> | H | = | "" | )

Sets the size of buttons.

> Toolbar_SetImageList( | hCtrl, |  |
> | hIL | = | "1S" | )

Set toolbar image list.

> Toolbar_SetMaxTextRows( | hCtrl, |
> | iMaxRows | = | )

Sets the maximum number of text rows displayed on a toolbar button.

> Toolbar_ToggleStyle( | hCtrl, |  |
> | Style | = | "LIST" | )

Toggle specific toolbar creation style
Close