Toolbar Control

The toolbar control (ctype MBF_TOOLBAR) is a standard Windows control which acts as a container for buttons. It is attached to one of the four edges of the parent window. Although created with the standard AUI_CONTROL function, toolbars differ from other controls in the following ways:

• The coordinates specified when creating a toolbar are ignored; position is determined by the CCS_xxx option set in the winstyle parameter, which selects the edge of the parent window to which the toolbar will be attached. The thickness of the bar is determined by the size of the images, labels, and style.

• Toolbars do not scale with changes in size to the parent window. Instead, they only stretch to match the length of the window edge to which they are attached.

• Toolbars do not take up space within the main window grid. Instead, the grid itself adjusts to make room for the toolbar.

• Toolbars are not removed by the tab(-1,0) command, unless they were created with the MBF_UNPROTECTED flag. They must be removed explicitly by AUI_CONTROL with the CTLOP_DEL opcode.

• Currently, toolbars may only be created in the main window. This restriction may be lifted later.

You can also create toolbar-like controls or panels using standard buttons or icons, either positioned manually in a row along one edge of the screen, or contained within a floating dialog (i.e. a floating tool panel).

See A-Shell Screen Elements for an extreme example with all four toolbars in use. Other examples:

Syntax and Parameters

Like the TabX Control, the Toolbar is largely configured via the AUI_CONTROL ctext parameter using the following syntax:

ctext = {@toolbarattribs~~}{opcur}{btndef~~btndef~~...btndef~~}

opcur

identifies the operation and button when modifying an existing toolbar. If present it must start with a "+" or "=" and end with a ":", according to the following:

opcur	Description
+:	Append subsequent btndefs to the end of the toolbar
-labelid:	Modify the button whose id or cmd attribute matches the specified labelid.

toolbarattribs

defines attributes of the toolbar as a whole, most importantly the image size info. Starts with a @ and ends with ~~, between which you may have any number of <attrib>=<value> pairs separated a single tilde, i.e.:

@<attrib>=<value>~<attrib>=<value>~...<attrib>=<value>~~

Attrib	Value	Description
ImgSiz	<width>,<height>,<bpp>	width, height (in pixels), bits per pixel. All images for the toolbar will be scaled to the specified size (although the quality will be best if the original images are already of the specified size). For bpp < 32, you must specify the MBF2_GDIPLUS ctype2 flag when creating the control in order to support some of the more advanced options, like the automatic transparency and ImgDis/ImgHot features.
ImgDir	<default directory> or standard icon set id	(optional) Default location for images, which avoids need to specify the full directory for each individual image. May be in native format (e.g. ImgDir=c:\images\toolbars) with or without %env% variables, or AMOS format. Note that A-Shell and ATE will also look in their own default locations if not found here. To use one of the standard icon sets built in to Windows, specify the id # here in place of a directory; see Using Windows Native Icons below.
ImgCount	# of images to expect	(optional) estimate of the number of images in the toolbar. Simply improves the efficiency of memory allocation operations.
ImgDis	<rop>{,<suffix>}	(optional) Rendering OPtion and suffix for disabled version of images. Rop 0 is the standard Windows scheme; 1 uses an A-Shell alternate algorithm for generating the disabled/gray version of the image. If the suffix is specified, A-Shell looks for an alternate image file to use for the disabled image. For example, if the img file is clickme.png and <suffix> is _d, then it will look for clickme_d.png. See following topic Disabled and Hot Images.
ImgHot	<rop>{,<suffix>}	(optional) Rendering OPtion and suffix for hot version of images. Same concept as for ImgDis except for the "hot" version of the image (displayed when the mouse is hovering over it). See following topic Disabled and Hot Images.

btndefs

define each individual button. Each btndef clause is made up of a series of <attrib>=<value> pairs, each delimited by a single tilde with the entire clause terminated by a double tilde, i.e.:

<attrib>=<value>~<attrib>=<value>~...<attrib>=<value>~~

Attrib	Value	Description
img	Image specification or standard icon id	The image to load for the button. If no directory specified, the default directory (see ImgDir in the toolbarattribs) is used. Note that only discrete PNG files are properly supported. If using standard built-in icons, specify the icon id number instead of the image file specification; see Using Windows Native Icons below.
cmd	command string	May be any of the following: keyboard client string (e.g. VK_xF201, VK_ESCAPE, etc.) MENUID:<menu identifier> (see Edit Menu Control) CMDLIN:<windows command line> (see HOSTEX) SHLEXC:<url or file object> (see MX_SHELLEX)
lbl	Label text	(optional) If specified, text will display either under the button (for toolbar winstyle TBLSTYLE_FLAT) or to the side of the button (winstyle TBSTYLE_LIST). Note that in the typical toolbar aesthetic style, label text for the buttons is omitted, relying instead of tooltips to clarify the function of each button. You cannot have both labels and tooltips, so either specify the lbl attribute or the tip attribute, but not both.
tip	Tooltip text	(optional) If specified (and lbl not specified), establishes the tooltip to display when the mouse hovers over the button.
id	Button ID	(optional) unique identifier for the button. Mainly used as a way to identify the button later for the purpose of enabling/disabling or otherwise altering it. You may also use the cmd string or the ordinal button position, but this approach probably makes for more readable and robust code.
enabled	0,1	(optional) state. Defaults to 1 (enabled)
type	SEP	(optional) type of button. Currently the only available type is SEP (separator). Separators require no other attributes, and normal buttons do not require the type attribute.
opaque	0,1	(optional) If set to 1, the image background will be displayed as opaque; otherwise it will be transparent. For images with bpp < 32, requires the MBF2_GDIPLUS flag when creating the toolbar. Note that 32 bit PNG images are assumed to be pre-configured with the alpha channel controlling transparency; for other image types, the first pixel determines the background color, which is converted to match the toolbar background.

winstyle and winstylex

Aside from the toolbarattribs in the ctext parameter, other global attributes of the toolbar control are set via bits in the winstyle and winstylex parameters, including:

Winstyle Symbol	Value	Description
TBSTYLE_WRAPABLE	&h00000200	Wrap-able text labels (applies only with horizontal toolbars)
TBSTYLE_FLAT	&h00000400	Standard toolbar style; any button labels appear beneath the buttons
TBSTYLE_LIST	&h00001000	Alternate style; labels appear to right of buttons
CCS_TOP	&h00000001	horizontal toolbar along top of window (default)
CCS_BOTTOM	&h00000003	horizontal toolbar along bottom of parent window
CCS_LEFT	&h00000081	vertical toolbar along left edge of parent window
CCS_RIGHT	&h00000083	vertical toolbar along right edge of parent window
WS_BORDER	&h00800000	gives toolbar a thin black border

Winstylex Symbol	Value	Description
WS_EX_CLIENTEDGE	&h00000200	gives toolbar a beveled edge

Note that attempting to add a toolbar in a position already occupied by a toolbar automatically deletes the prior toolbar.

Sample Program

This sample program creates a top toolbar with various types of 16x16x32 buttons It illustrates using CTLOP_CHG mode to disable buttons, and CTLOP_DEL to remove the toolbar.

++include ashinc:ashell.def

map1 ctext$,s,0

map1 winstyle,b,4

map1 a,b,1

! global attributes

ctext$ = "@" ! beginning of global options

ctext$ += "ImgDir=C:\vm\miame\images~"

ctext$ += "ImgSiz=16,16,32~"

ctext$ += "ImgCount=5~"

ctext$ += "ImgDis=1~" ! alternate rendering of disabled images

ctext$ += "~" ! end of global options

! buttons that simulate menu items

ctext$ += "id=copy~img=copy_16.png~tip=Copy to clipboard~" &

+ "cmd=MENUID:"+IDM_COPY+"~~"

ctext$ += "id=paste~img=paste_16.png~tip=Paste from clipboard~" &

+ "cmd=MENUID:"+IDM_PASTE+"~~"

ctext$ += "type=SEP~~"

! buttons that simulate keyboard keys

ctext$ += "id=up~img=nav_up_16.png~tip=Up one field~" &

+ "cmd=VK_UP~~"

ctext$ += "id=down~img=nav_down_16.png~tip=Next field~" &

+ "cmd=VK_DOWN~~"

ctext$ += "type=SEP~~"

! buttons that generate pseudo-function exitcodes

ctext$ += "id=bskip~img=nav_left2_16.png~tip=Back 10 recs~" &

+ "cmd=VK_xF501~~"

ctext$ += "id=fskip~img=nav_right2_16.png~tip=Forward 10 recs~" &

+ "cmd=VK_xF502~~"

ctext$ += "type=SEP~~"

! button to launch a windows app

ctext$ += "id=calc~img=calc_16.png~tip=Calculator~" &

+ "cmd=CMDLIN:calc.exe $~~" ! note $ so as not to wait for it

! button to launch a URL

ctext$ += "id=home~img=house_16.png~tip=MicroSabio Home Page~" &

+ "cmd=SHLEXC:http://www.microsabio.com~~"

winstyle = TBSTYLE_FLAT or CCS_TOP

xcall AUI, AUI_CONTROL, CTLOP_ADD, "tb1", ctext$, &

MBST_ENABLE, MBF_TOOLBAR, NUL_CMD$, NUL_FUNC$, NUL_CSTATUS, &

0, 0, 0, 0, NUL_FGC, NUL_BGC, &

NUL_FONTATTR, NUL_FONTSCALE, NUL_FONTFACE$, NUL_TOOLTIP$, &

NUL_PARENTID, NUL_WINCLASS$, winstyle, NUL_WINSTYLEX, &

NUL_CTYPE2

input "Enter to disable '^' and '<<' buttons...",a

ctext$ = "=up:enabled=0~~=bskip:enabled=0~~"

xcall AUI, AUI_CONTROL, CTLOP_CHG, "tb1", ctext$, MBST_CHANGEX

input "Enter to delete the toolbar ",a

xcall AUI, AUI_CONTROL, CTLOP_DEL, "tb1"

16x16 buttons in top toolbar with tooltips:
24x24 buttons in bottom toolbar with labels beneath (TBSTYLE_FLAT):
24x24 buttons with labels to side (TBSTYLE_LIST), with one disabled button:

Toolbar Control

Syntax and Parameters

Sample Program

Using Windows Native Icons

History