Getting Started
Introduction
Sample Programs
IDEs
History
Advice
Mini-Tutorial
Tutorials
Code Snippets

Resources
Web Sites
More Tutorials
Forums
Vendors/Tools
Books
Magazines
Newsletters
NewsGroups
User Groups
Talk Shows
Blogs

Controls
Overview
Button
Check3State
Checkbox
ComboBox
Frame
Graphic
Image
ImageX
ImgButton
ImgButtonX
Label
Line
ListBox
ListView
Option
Progress Bar
Scrollbar
StatusBar
TAB
TextBox
Toolbar
TreeView

GBIC >> PowerBASIC >> Tutorials >> Controls >> Toolbar Control

PowerBASIC Information Center Tutorials
These tutorials were written to help you get a quick, but thorough, understanding of PowerBASIC - the scope of the language as well as it's specific capabilities.

Introduction       Projects       Language           Messages       Functions           Advanced
  • Overview
  • Examples
  • IDE
  • Compilation
  • Distribution
  • Project Files
  • DDT Windows
  • Controls
  • Menus
  • Dialogs  
  • Help Files
  • Resources  
  • Templates  
  • Project Shell  
  • Syntax
  • Operators
  • Data Types
  • Variables
  • Scope
  • Declarations  
  • Procedures
  • Flow Control
  • Windows
  • Messages
  • Callbacks
  • Mouse
  • Keyboard
  • Dialogs
  • Controls
  • Subclassing
  • Arithmetic
  • Trig  
  • Strings
  • Arrays
  • Date/Time
  • Printing
  • Files
  • Folders
  • Keyboard
  • Mouse
  • Sound
  • System
  • Error Traps
  • Debugging
  • Objects
  • Graphics
  • Databases
  • API
  • DLLs
  • ASM
  • Threads
  • 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.

    • Syntax:
        Control Add TOOLBAR, hDlg, id&, txt$, x, y, xx, yy, _
                                   style&, extsytle& CALL callback
      
        Toolbar Add Button hDlg, id&, image&, cmd&, _
                                   style&, text$, At item& Call callback
      

      Note that the Add Toolbar statement simply creates an empty toolbar. The Add Buttons statement must be used to put buttons on the empty toolbar.

      Note also that an imagelist is required if images are to be included on the toolbar. Imagelists are discussed further down the page.

    • Source Code Example:
      This short example creates a complete application with toolbar with 3 buttons. When any of the buttons are clicked, a popup message appears. This tutorial page discusses most of the statements used, however the DDT, Controls, Messages, and Callback tutorials provide background information that may be helpful in understanding the example.

      #Compile Exe
      #Dim All
      #Resource "pb-test.pbr"     'misc icons
      
      Global hDlg As Dword    'main dialog handle
      Global hLst As Dword    'imagelist handle
      
      Function PBMain()
          'create dialog
          Dialog New Pixels, 0, "Toolbar Test",,, 500,250, %WS_SysMenu, To hDlg
          Dialog Set Color hdlg, %White, %White
          Dialog Set Icon hDlg, "x"
          'add toolbar
          Control Add Toolbar, hdlg, 500,"", 0,0,0,0
          'create imagelist
          ImageList New Icon 16,16,32,3 To hLst
          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, 200, %TbStyle_Button, "x"
          Toolbar Add Button    hdlg, 500, 2, 201, %TbStyle_Button, "y
          Toolbar Add Button    hdlg, 500, 3, 202, %TbStyle_Button, "z"
      
          Dialog Show Modal hdlg Call DlgProc
      End Function
      
      CallBack Function DlgProc() As Long
         If Cb.Msg = %WM_Command Then
            If Cb.Ctl = 200 Then MsgBox "Pushed X!"
            If Cb.Ctl = 201 Then MsgBox "Pushed Y!"
            If Cb.Ctl = 202 Then MsgBox "Pushed Z!"
         End If
      End Function 
      

      In this example, the toolbar images are stored in a resource file, available from here.

      An additional example of a callback function is provided further down this page.

    • Visual Examples:
      And here are a few examples of what you can do with toolbar controls in PowerBASIC. Variations on the Control Add TOOLBAR statement were used to create the examples. In some cases, other Control statements were used to modify the results.

      The first two examples show the effect of flat vs normal 3D buttons. The third example shows no text and the fourth shows buttons which stay pressed when pushed.

      There are several other variations possible. Toolbars can be placed on any side, icon sizes can be changed, color and font of the labels can be changed, and buttons can be part of groups, where only one member of a group can be pressed at a time. Buttons can also be hidden/made visible programmatically.

    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.

    • hDlg
      The dialog handle to which the toolbar control is to be added. The value was returned by the DIALOG NEW statement.

    • id&
      The id& argument is a control identifier assigned by the programmer. It must be a value of 1-65535. Values of 100+ are suggested, as PowerBASIC pre-assigns identifiers with special meaning. Numeric equates are suggested over the use of literal values.

    • txt$
      The toolbar control itself does not display text, so the txt$ argument is usually set to "". However, any entered txt$ value can be accessed using the GET/SET TEXT statements. This provides the application with a control-specific property that can used for any purpose.

      Text can be displayed on the individual toolbar buttons.

    • x,y and xx,yy
      The integer x,y and xx,yy dimensions use the same units as the parent dialog. (x,y) is the upper/left coordinates of the control. (xx,yy) is the width/height of the control.

    • style& and extstyle&
      The style& and extstyle& arguments (listed below) are optional. If not supplied, default values are used (see the table below). If values are supplied, they completely replace default values (i.e., the entered values are not in addition to the default values).

    • CALL
      The "CALL callback" section is optional. If not supplied, the callback function of the parent dialog is used. An example callback function for toolbar controls is provided further down this page. The #MESSAGE COMMAND compiler directive can be used to prevent sending %WS_NOTIFY messages to the callback function. By default, both %WS_NOTIFY and %WS_COMMAND messages are sent.

    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.

    • %tbstyle_button - standard push and release button
    • %tbstyle_check - toggles between pressed and non-pressed
    • %tbstyle_group - only 1 button can be pressed (requires %tbstyle_group)
    • %tbstyle_checkgroup - same as %tbstyle_check OR %tbstylegroup

    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.

      Toolbar Add Button add button
      hDlg, id&, image$, cmd$, style&, text$, AT item&
      Toolbar Add Separator     add separator (dead space between buttons)
      hDlg, id&, size& AT item$
      Toolbar Delete Button remove button
      hDlg, id&, BYCMD item&
      Toolbar Get State get button state (see below)
      hDlg, id&, BYCMD item& TO datav&
      Toolbar Get Count number of buttons + separators
      hDlg, id& TO datav&
      Toolbar Set ImageList attach imagelist to toolbar (0-default, 1-disabled, 2-hot)
      hDlg, id& hLst, type&
      Toolbar Set State set button state (see below)
      hDlg, id&, BYCMD item&, state&

    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.

    • hDlg - dialog handle
    • hLst - imagelist handle
    • id& - toolbar control id&
    • cmd& - button command id
    • image& - imagelist image number (1,2,...)
    • item& - button toolbar position (1,2,...)
    • size& - width of separator (pixels)
    • state& - button state values (see table below)
    • style& - button style values (see table below)
    • text$ - button text (can be "")
    • type& - imagelist type (0-default 1-disabled 2-hot images)
    • callback - callback function (receives button messages)
    • datav& - returned value (button count or state)

    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.

      CONTROL DISABLEdisable
      hDlg, id&
      CONTROL ENABLEenable hDlg, id&
      CONTROL GET CHECKcheck state hDlg, id& TO iResult1&
      CONTROL GET CLIENTtop/left location hDlg, id& TO wide&, high&
      CONTROL GET LOCtop/left location hDlg, id& TO x&, y&
      CONTROL GET SIZEwidth/height hDlg, id& TO width&, height&
      CONTROL GET TEXTtext hDlg, id& TO txt$
      CONTROL GET USERget user data hDlg, id&, index& TO retvar&
      CONTROL HANDLE window handle for control id hDlg, id& TO hCtl&
      CONTROL KILLremove control hDlg, id&
      CONTROL POSTput message in queue (non-blocking) hDlg, id&, Msg&, wParam&, lParam&
      CONTROL REDRAWschedule redraw of control hDlg, id&
      CONTROL SENDsend message to control, wait for processing hDlg, id&, Msg&, wParam&, lParam& TO iResult2&
      CONTROL SET CHECKset check for 3state or checkbox hDlg, id&, checkstate&
      CONTROL SET CLIENTchange size to specific client area size hDlg, id&, wide&, high&
      CONTROL SET COLORset fg/bg color hDlg, id&, fgcolor&, bgcolor&
      CONTROL SET FOCUSset focus hDlg, id&
      CONTROL SET FONTselect font for a control hDlg, id&, fonthandle&
      CONTROL SET LOCrelocate control within dialog hDlg, id&, x&, y&
      CONTROL SET OPTIONset check state of option control hDlg, id&, minid&, maxid&
      CONTROL SET SIZEchange control size hDlg, id&, width&, height&
      CONTROL SET TEXTchange control text hDlg, id&, text$
      CONTROL SET USERset user data hDlg, id&, index&, uservalue&
      CONTROL SHOW STATE     toggle visibility hDlg, id&, showstate& TO iResult3&

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