Toolbar

Encapsulation of the system Toolbar API.

(see toolbar.png)

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	Encapsulation of the system Toolbar API.
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
Customize	Launches customization dialog
GetButton	Get button information
Define	Get the toolbar definition list.
DeleteButton	Delete button from the toolbar.
GetButton	Get button information
Count	Get count of buttons on the toolbar
GetRect	Get button rectangle
GetMaxSize	Retrieves the total size of all of the visible buttons and separators in the toolbar.
CommandToIndex	Retrieves the button position given the ID.
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
Example
About

Add

Toolbar_Add( hGui,
Handler,
Style = "WRAPABLE",
ImageList = "1L",
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 catalogs.png). 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.

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(hCtrl, Event, Txt, Pos, Id)

Ctrl	Handle of the Toolbar that sends 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

Customize

Toolbar_Customize( hCtrl )

Launches customization dialog

(see customize.png)

GetButton

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.

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

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

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.

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.

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,
OldPos,
NewPos )

Moves a button from one position to another.

Parameters

OldPos	1-based postion of the button to be moved.
NewPos	1-based postion 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.

Example

   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.21 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
Licenced under GNU GPL http://creativecommons.org/licenses/GPL/2.0/