Navigation: Subroutines > AUI > AUI_CONTROL > Control Types

Toolbar Control

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:

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:

 

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:

 

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>~~

 

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>~~

 

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:

 

 

* "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