Getting Started
Sample Programs
Code Snippets

Web Sites
More Tutorials
User Groups
Talk Shows

Progress Bar

GBIC >> PowerBASIC >> Tutorials >> Controls >> StatusBar 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
  • StatusBar Control
    The statusbar control provides a location for placing status information on a dialog, typically along the bottom of the dialog. It may be split into parts to show multiple data strings. It does not display images.

    • Syntax:
      Control Add StatusBar, hDlg, id&, txt$, x, y, xx, yy, _
                                           style&, extsytle& CALL callback

    • Source Code Example:
      This short example creates a complete application with a single statusbar. When clicked, the statusbar responds with a message. 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
         Global hDlg As Dword
         Function PBMain() As Long
            Dialog New Pixels, 0, "Statusbar Test",300,300,200,200, _
                                            %WS_SysMenu, 0 To hDlg
            Control Add Statusbar, hdlg, 500, "",0,0,0,0
            Statusbar Set Parts hDlg, 500, 75,75,99999
            Statusbar Set Text hdlg, 500, 1, 0, "one"
            Statusbar Set Text hdlg, 500, 2, 0, "two"
            Statusbar Set Text hdlg, 500, 3, 0, "three
            Dialog Show Modal hDlg Call DlgProc
         End Function
         CallBack Function DlgProc() As Long
            If Cb.NmCode = %NM_Click Then
              MsgBox "click"
            End If
         End Function

      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 the statusbar control in PowerBASIC. Variations on the Control Add StatusBar statement were used to create the examples. In some cases, other Control or StatusBar statements were used to modify the results.

      The options are pretty basic. You can have one or more sections, each with its own text. Sections can have their own border styel. You can also set the statusbar at the bottom or top of the window.

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

    • hDlg
      The dialog handle to which the statusbar 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$
      When first created, a statusbar has only one part, whose text content is provided by txt$.

      Use of an ampersand in a statusbar section has no special meaning (i.e., the & does not define a hotkey as it does in some controls).

    • 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.

      Note: the definitions just given match those found in the Help file. However the style& settings %css_top and %css_bottom override the x,y and xx,yy settings and size the control with the width of the dialog and a height based on the current font settings.

    • 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 statusbar 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.

    StatusBar-Specific PowerBASIC Statements
    The Control Add Statusbar statement simply adds a one-section toolbar. To create multiple sections or to change the border, you must use the following StatusBar Set statements. Up to 32 sections are allowed.

      StatusBar Set Parts     creates sections, each with its own text
      hDlg, id&, x$, y$, z$, ...
      StatusBar Set Text assigns text string for each part
      hDlg, id&, item&, style&, text$

    The item& is the section number. Numbering goes left to right, starting with 1.

    The style options for the Statusbar Set Text statement are:

        0              - border lower than dialog
        %sbt_noborders - no borders (&H0100)
        %sbt_popout    - border higher than dialog (&H0200)

    Use #INCLUDE on the file "" to retreive the statusbar equates.

    If you put text into a statusbar and later increase the number of sections, the existing text will be kept. If you decrease the number of sections, the text in the dropped sections will be lost.

    Here's an image of a 3-part statusbar and the source code used to create it.

        Control Add StatusBar, hdlg, 500, "status",0,0,0,0
        StatusBar Set Parts hDlg, 500, 75,75,99999
        StatusBar Set Text hdlg, 500, 1, 0, "one"
        StatusBar Set Text hdlg, 500, 2, &H0100, "two"
        StatusBar Set Text hdlg, 500, 3, &H0200, "three

    Note the "99999" width of the 3rd section. Using an arbitrarily large number insures that statusbar covers the entire width of the dialog. Another approach is to resize the statusbar sections whenever the dialog size changes - programmatically spreading the width of the sections to meet application needs.

    To use the %sbt_xxx equates in lieu of the literal values, include the "" file.

    Messages, Notifications, Styles, and ExtSstyles
    There are four types of named constants in the following table. All are pulled from the MSDN web site.

    • Notifications - event notifications a control receives
    • Messages - controls may send these
    • Styles - affect the visual look of a control
    • ExtStyles - additional values that affect the visual look

    The first column contains control-specific named constants and the second column contains generic window named constants (statusbar controls are windows).

    Also, if the PowerBASIC Help file has an entry on the value, it is highlighted in yellow. If the value was noted in PowerBASIC Help as a default value, it is also shown in bold text.

    In the values for notifications, descriptions starting with -n and -c refer to events received through the %wm_notify and %wm_command messages. By default, PowerBASIC controls can receive both of these messages.


    And here is a short description of many of the named constants corresponding to notifications, styles, and extstyle - particularly those discussed in the PowerBASIC Help topics.

        %ccs_bottom            - place at bottom of dialog
        %ccs_right             - place at right edge of dialog
        %nm_click              -n mouse click
        %nm_dblclk             -n double click
        %nm_rclick             -n right mouse click
        %nm_rdblclk            -n right mouse double click
        %sbars_sizegrip        - sizegrip displayed
        %sbars_tooltips        - tooltips enabled
        %sbn_simplemodechange  -n simple mode has changed
        %ws_ex_clientedge      - apply sunken edge border
        %ws_ex_staticedge      - apply 3D border
        %ws_ex_windowedge      - apply raised edge border

    Callback Function
    A control can have its own callback function, or use the parent dialog callback function.

    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 statusbar control callback function.

       CallBack Function cbStatusBar()
          Select Case CB.MSG
             Case %WM_NOTIFY
                Select Case CB.CTLMSG
                   Case %nm_click
                   Case %nm_dblclk
                   Case %nm_rclick
                   Case %nm_rdblclk
                   Case %nm_simplemodechange
             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.

    CONTROL Statement Syntax
    The following table lists the various Control statements (except the ADD statements). Most, but not all, can be used with the statusbar 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.