Toolbar Control
The toolbar control is a vertical or horizontal strip of buttons, positioned on any edge of a dialog. Pressing a button executes specified code (usually corresponding to menu options).

Standard buttons, push/pull buttons and group buttons are supported. Buttons can have an image and/or text.

Arguments
The Control Add statement is used to create all new controls. Here are the statement's arguments and any special significance to the toolbar control.

Usage
Putting a toolbar on a dialog is a 4-step process.

  1. Create Toolbar with Control Add Toolbar
  2. Create ImageList with ImageList New Icon
  3. Add icons with ImageList Add Icon
  4. Add Buttons with Toolbar Insert Button

Responding to toolbar buttons is covered in the section below on Callback functions.

Using the Control Add TOOLBAR statement simply creates a blank control, one with no buttons at all. Once the toolbar is created, buttons are added with a Toolbar Add Button statement for each new button.

The Toolbar Add Separator allows insertion of a gap between buttons, along with a vertical bar in the gap. This separator bar provides a visual grouping of buttons.

The toolbar background color takes on the background color of the parent dialog at the time the toolbar was created. It does not change automatically with changes in the dialog background color.

The icon size and text fontsize determines the size (height) of the toolbar. The width of the buttons is set by the largest text for any button.

However, if text = "" for all toolbar buttons, the toolbar height drops to accommodate only the height of the button images. If any one button text is not "", then the toolbar height is increased for all buttons.

Here's the code to create a dialog with a simple toolbar. 

    Function PBMain()
        Dim hDlg as DWORD, hLst as DWORD
        Dialog New Pixels, 0, "Toolbar Examples",,, 500,250, _
                              %WS_SysMenu, To hDlg

        'create toolbar
        Control Add Toolbar, hdlg, 500,"", 0,0,0,0

        'create imagelist
        ImageList New Icon 16,16,32,4 To hLst

        'add icons (from resource file)
        ImageList Add Icon hLst, "x"              '1
        ImageList Add Icon hLst, "y"              '2
        ImageList Add Icon hLst, "z"              '3

        'attach imagelist
        Toolbar Set ImageList hDlg, 500, hLst, 0

        'create buttons
        Toolbar Add Button    hdlg, 500, 1, 1, %TbStyle_Button, "x"
        Toolbar Add Button    hdlg, 500, 2, 2, %TbStyle_Button, "y"
        Toolbar Add Separator hdlg, 500, 10
        Toolbar Add Button    hdlg, 500, 3, 3, %TbStyle_Button, "z"

        Dialog Show Modal hdlg Call DialogCallback
    End Function

In this example, a resource file has already been included which contains 16x16, 32-bit icons "x", "y", and "z".

When toolbar control is destroyed, any attached imagelist is also destroyed

Buttons can be referenced with their position on the toolbar or by their command id number assigned to the button when it was created.

Button styles come in 4 flavors - standard, check, group, checkgroup. The checkgroup is the same as combining the check and group styles. Group is generally not used alone.

A group is created when side-by-side buttons use the %tbstyle_group or %tbstyle_checkgroup styles. Any other style interrupts the group. For example, this code creates 3 separate button groups. In this case, the groups are broken up by separators or by standard buttons. 

    Toolbar Add Button    hdlg, 500, 1, 1, %TbStyle_Button, "x"
    Toolbar Add Button    hdlg, 500, 2, 2, %TbStyle_Check,  "y"
    Toolbar Add Separator hdlg, 500, 10

    Toolbar Add Button    hdlg, 500, 3, 3, %TbStyle_CheckGroup, "a"  'group 1
    Toolbar Add Button    hdlg, 500, 4, 4, %TbStyle_CheckGroup, "b"
    Toolbar Add Separator hdlg, 500, 10

    Toolbar Add Button    hdlg, 500, 1, 5, %TbStyle_CheckGroup, "c"  'group 2
    Toolbar Add Button    hdlg, 500, 2, 6, %TbStyle_CheckGroup, "d"
    Toolbar Add Separator hdlg, 500, 10

    Toolbar Add Button    hdlg, 500, 3, 7, %TbStyle_CheckGroup, "e"  'group 3
    Toolbar Add Button    hdlg, 500, 4, 8, %TbStyle_CheckGroup, "f"

    Toolbar Add Button    hdlg, 500, 1, 1, %TbStyle_Button, "x"
    Toolbar Add Button    hdlg, 500, 2, 2, %TbStyle_Check,  "y"

Toolbar-Specific PowerBASIC Statements
PowerBASIC provides several statements specific to the toolbar control. These allow getting/setting toolbar properties.

Using only in the Add Button and Add Separator statements, the AT clauses are optional. When omitted, the buttons/separators are added at the right end of the toolbar.

"BYCMD item&" refers to the button command id, as defined by the Toolbar Add Button statements. The "BYCMD" part is optional. If BYCMD is omitted, then item& refers to the position of the button on the toolbar. Separator buttons count as a position.

Here is a list of the parameters used in the toolbar-specific statements listed above.

When a button is created it is given a number, called a command id number (cmd& in the syntax above). Toolbar Delete, Get, and Set statements can refer to the button by that number using the BYCMD option. Otherwise, they use the

When a button is created it can be given an image, specified by the position of the image in the attached imagelist (1,2,...)

Button State
The state of a button is defined by any combination of the following. 

    %tbstate_disabled      - disabled and grayed
    %tbstate_checked       - checked
    %tbstate_pressed       - pressed
    %tbstate_enabled       - enabled
    %tbstate_hidden        - not visible
    %tbstate_indeterminate - indeterminate and grayed.
    %tbstate_marked        - highlighted
    %tbstate_wrap          - 
    %tbstate-ellipses      - 
    %tbstate_marked        -

Style and ExtStyle
These values can be used to modify the way the toolbar control is displayed. The default values, used when style and extstyle are not supplied, are marked with an "*".

These values apply to the toolbar: 

    ---style&
    %ccs_bottom           - place at bottom of dialog
    %ccs_left             - place at left edge of dialog
    %ccs_right            - place at right edge of dialog
    %ccs_top              - place at top of dialog

    %tbstyle_altdrag      - use alt to change position (drag)
    %tbstyle_customerase  - nm_customdraw in response to wm_erasebkgnd
    %tbstyle_flat         - flat toolbar, text under bitmaps
    %tbstyle_list         - flat toolbar, text right of bitmaps
    %tbstyle_registerdrop - send tbn_getobject on cursor pass over
    %tbstyle_tooltips     - create tooltip control
    %tbstyle_transparent  - transparent toolbar, text under bitmaps
    %tbstyle_wrapable     - buttons wrap if dialog to narrow

    ---extstyle&
    %ws_ex_clientedge     - apply sunken edge border
    %ws_ex_staticedge     - apply 3D border
    %ws_ex_windowedge     - apply raised edge border

These values apply to the buttons on the toolbars. 

    ---style&
    %btns_autosize      - width based on text+image
    %btns_button        - standard button
    %btns_check         - toggles between pressed/nonpressed
    %btns_checkgroup    - pressed until press another group button
    %btns_dropdown      - drop-down (with tbstyle_ex_drawddarrows)
    %btns_group         - with btns_check, same as %btns_checkgroup
    %btns_noprefix      - no accelerator prefix
    %btns_sep           - separator button
    %btns_showtext      - display text (with _list/_ex_mixedbuttons)
    %btns_wholedropdown - integrated drop-down arrow

    %tbstyle_autosize   - equivalent to btns_autosize (4.72 and earlier)
    %tbstyle_button     - equivalent to btns_button (4.72 and earlier)
    %tbstyle_check      - equivalent to btns_check (4.72 and earlier)
    %tbstyle_checkgroup - equivalent to btns_checkgroup (4.72 and earlier)
    %tbstyle_dropdown   - equivalent to btns_dropdown (4.72 and earlier)
    %tbstyle_group      - equivalent to btns_group (4.72 and earlier)
    %bstyle_noprefix    - equivalent to btns_noprefix (4.72 and earlier)
    %tbstyle_sep        - equivalent to btns_sep (4.72 and earlier)

    ---extstyle&
    n/a (buttons simply have a style&, not an extstyle&)

Windows Message Support
The following toolbar control events are available through Windows notification messages. 

    ----CB.CTLMSG:
    %nm_char                 -n has received WM_CHAR message
    %nm_click                -n mouse click
    %nm_customdraw           -n custom drawing operation
    %nm_dblclk               -n mouse double click
    %nm_keydown              -n key pressed
    %nm_ldown                -  left mouse button pressed
    %nm_rclick               -n right mouse click
    %nm_rdblclk              -n right mouse double click
    %nm_releasedcapture      -n releasing mouse capture
    %nm_tooltipscreated      -n created tooltip control
    %tbn_beginadjust         -n begun customizing toolbar
    %tbn_begindrag           -n begun dragging a button
    %tbn_custhelp            -n chosen Help button
    %tbn_deletingbutton      -  button about to be deleted
    %tbn_dragout             -n cursor moved off a clicked button
    %tbn_dragover            -  button being dragged over
    %tbn_dropdown            -n dropdown button clicked
    %tbn_dupaccelerator      -  use accelerator key on multi-toolbars
    %tbn_endadjust           -n toolbar customization has stopped
    %tbn_enddrag             -n dragging a button has stopped
    %tbn_getbuttoninfo       -n get customization information
    %tbn_getdispinfo         -n get display information for item
    %tbn_getinfotip          -n get infotip information for item
    %tbn_getobject           -  get drop target object
    %tbn_hotitemchange       -n highlighted (hot) item changed
    %tbn_initcustomize       -  customizing has started
    %tbn_mapaccelerator      -  get button index w/accelerator
    %tbn_querydelete         -n pending deletion of button
    %tbn_queryinsert         -n pending insertion of button
    %tbn_reset               -n reset Customize Toolbar dialog
    %tbn_restore             -  toolbar being restored
    %tbn_save                -  toolbar being saved
    %tbn_toolbarchange       -n customization complete
    %tbn_wrapaccelerator     -  get button index w/accel char
    %tbn_wraphotitem         -  hot item about to change

Descriptions starting with -n and -c refer to events received through %wm_notify and %wm_command messages, which provide all events that are passed to PowerBASIC application callback functions.

Callback Function
A control can have its own callback function, or use the parent dialog callback function. In the case of a toolbar, the individual buttons can also have their own callback functions.

A control callback function should return TRUE to indicate it has processed the message. This prevents unnecessarily calling the dialog callback function, which will process the message if no control callback function is available, or if the control callback function returns FALSE.

By default, both %WM_COMMAND and %WM_NOTIFY messages are received. However, if the #MESSAGE COMMAND compiler directive is invoked, the %WM_NOTIFY messages will not be available.

Here's a sample toolbar control callback function. 

   CallBack Function cbToolbar()
      Select Case CB.MSG
         Case %WM_NOTIFY
            Select Case CB.CTLMSG
               Case %nm_char
               Case %nm_click
               Case %nm_customdraw
               Case %nm_dblclk
               Case %nm_keydown
               Case %nm_ldown
               Case %nm_rclick
               Case %nm_rdblclk
               Case %nm_releasedcapture
               Case %nm_tooltipscreated
               Case %tbn_beginadjust
               Case %tbn_begindrag
               Case %tbn_custhelp
               Case %tbn_deletingbutton
               Case %tbn_dragout
               Case %tbn_dragover
               Case %tbn_dropdown
               Case %tbn_dupaccelerator
               Case %tbn_endadjust
               Case %tbn_enddrag
               Case %tbn_getbuttoninfo
               Case %tbn_getdispinfo
               Case %tbn_getinfotip
               Case %tbn_getobject
               Case %tbn_hotitemchange
               Case %tbn_initcustomize
               Case %tbn_mapaccelerator
               Case %tbn_querydelete
               Case %tbn_queryinsert
               Case %tbn_reset
               Case %tbn_restore
               Case %tbn_save
               Case %tbn_toolbarchange
               Case %tbn_wrapaccelerator
               Case %tbn_wraphotitem
         End Select
      End Select
   End Function

In each Case section, add the statements the application needs to respond to the event. Also, be sure to add "Function=1" as appropriate to indicate that the event was handled by the callback function.

Issues
Help does not define the extstyle& default.

Help defines default style& as including %ws_border OR %ws_visible OR %tbsstyle_flat - none of which are in the list of possible styles.

Help at Toolbar Add Button talks about an optional "Call callback", but the syntax

I'll update this page as soon as information becomes available.

CONTROL Statement Syntax
The following table lists the various Control statements (except the ADD statements). Most, but not all, can be used with the toolbar control. A one-line description of the statement and then its syntax are presented.

If you have any suggestions or corrections, please let me know.