Updated November 2013; see History
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. |
| • | There is a maximum of four toolbars per parent window, one for each edge. |
| • | 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).
Several example programs and PNG images are included in the EXLIB:[908,58].
Examples
See A-Shell Screen Elements for an extreme example with all four toolbars in use. Other examples:
16x16 buttons in top |
|
24x24 buttons in bottom toolbar with labels beneath (TBSTYLE_FLAT): |
|
24x24 buttons with labels to side (TBSTYLE_LIST), with one disabled button: |
|
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_EX_MIXEDBUTTONS |
&h00000007 |
Mixture of tips and labels |
TBSTYLE_EX_HIDECLIPPEDBUTTONS |
&h00000010 |
Hide truncated buttons |
TBSTYLE_TOOLTIPS |
&h00000100 |
Display tooltips |
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 |
* "CCS" stands for "Common Control Style," and "WS" for Window Style. These terms are borrowed directly from the Windows API symbols; the fact that multiple types of style bits could apply to a compound control like a toolbar is not unusual.
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"
Using Windows Native Icons
It is also possible to create toolbars using one of the sets of button images which are built in to Windows. Each toolbar can contain images from one of these built-in sets, or can contain discrete images loaded from PNG files, but not a mixture. To use one of the built-in image sets, include the file TOOLBARSTD.DEF in SOSLIB:[907,16], set the ImgDir= attribute to the identifier for one of the sets (e.g. IDB_STD_SMALL_COLOR), and each img= attribute to the identifier for one of the buttons within that set (e.g. STD_FILEOPEN). For example:
! toolbarattributes:
ctext$ = "@"
ctext$ += "Imgdir="+IDB_STD_SMALL_COLOR+"~" ! std small color images
ctext$ += "ImgSiz=16,16,24~~" ! 16x16, 24 color
! buttons
ctext$ += "id=fnew~img="+STD_FILENEW+"~tip=New file~cmd=VK_xF601~~"
ctext$ += "id=fopen~img="+STD_FILEOPEN+"~tip=Open files~cmd="VK_xF602~~"
History
2013 November, A-Shell 6.1.1368: MBF_TOOLBAR enhancement: it is now possible to split the top and bottom toolbars into two separate toolbars so as to left justify one set of buttons and right-justify the other. Within any single toolbar, all of the buttons get justified as a group. To accomplish this, set the ecol parameter to the desired ending column (main window column grid units) for the left toolbar, and ecol to the starting column for the right toolbar. All the other coordinates should remain zero, as they do for the normal toolbar configuration. Note that to avoid a seam in the middle where the two toolbars meet, you may want to set the TBSTYLE_FLAT option in the dwstyle parameter.
2013 August, A-Shell 6.1.1359: ImgDis and ImgHot toolbarattributes added. Bottom toolbar position moved to above bottom status and session lines.
2013 July, A-Shell 6.1.1358: Background transparency is now automatic for all image formats; previously it only worked with PNG ARGB images. To force the background to remain opaque, you can add the new btndef (button definition) clause: opaque=1. For example: tbdef$ += "img=clickme.bmp~opaque=1~lbl=Click me~" ...
2013 July, A-Shell 6.1.1355: MBF_TOOLBAR added to A-Shell
