Getting Started
Sample Programs
Code Snippets

Web Sites
More Tutorials
User Groups
Talk Shows

Progress Bar

GBIC >> PowerBASIC >> Tutorials >> Controls >> ScrollBar 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
  • ScrollBar Control
    The scrollbar control provides a visual approach to setting a value. It consists of a vertical/horizontal bar and enclosed scroll box. The user can use a mouse click or drag action to reposition the scroll box, which in turn changes the position property of the scroll bar. The position of a scrollbar takes on a value bounded by the scrollbar's range (hi and lo values).

    Scrollbars are often located on the right/bottom sides of dialogs, but may be aligned with any edge of its parent dialog.

    A scrollbar can also be added to a dialog using the dialog style& properties. In that case, there is no child control to monitor and all events go directly to the dialog callback function.

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

    • Source Code Example:
      This short example creates a complete application with a single scrollbar. When clicked, the scrollbar 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, "Scrollbar Test",300,300,200,200, _
                                            %WS_SysMenu, 0 To hDlg
            Control Add ScrollBar, hDlg, 100,"", 50,50,100,20
            Dialog Show Modal hDlg Call DlgProc
         End Function
         CallBack Function DlgProc() As Long
            If Cb.Msg = %WM_HScroll Then
                  Select Case Lo(Word, Cb.WParam)
                     Case %SB_LineLeft
                         MsgBox "Moved left!"
                     Case %SB_LineRight
                         MsgBox "Moved right!"
                  End Select
            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 scrollbar control in PowerBASIC. Variations on the Control Add ScrollBar statement were used to create the examples. The image also shows the various parts of the scrollbar. In some cases, other Control statements were used to modify the results.

      The options are pretty basic. You can have vertical or horizontal orientation. You can also align the scrollbar to any side of a dialog. You can also change the scrollbar body.

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

    • hDlg
      The dialog handle to which the scrollbar 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 scrollbar control 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.

      An ampersand can also be included in txt$, such as "&Stop", to specify a hot key Alt-S.

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

      When the control is aligned to an edge of the dialog using one of the style& options, the x,y and xx,yy values are ignored.

    • 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 scrollbar 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 Notes
    A scrollbar has three parts - body, scroll box, and arrows. The location of the scroll box visually indicates the position (value) of the scrollbar. The position is constrained to a range of values (lo and hi).

    Lo is the bottom position in a vertical scrollbar and left-most position in a horizontal scrollbar.

    Hi is the top position in a vertical scrollbar and right-most position in a horizontal scrollbar.

    Clicking on arrows is associated with a making a small value change. If the click is on the hi side of the scroll box, the value increases. If the click is on the lo side of the scroll box, the value decreases.

    Clicking on the body is associated with a making a larger value change. If the click is on the hi side of the scroll box, the value increases. If the click is on the lo side of the scroll box, the value decreases.

    The user can also change the value of the scrollbar by dragging the scroll box to a new position.

    Regardless of how the new value is assigned, the position of the scroll box must be made programmatically.

    To align the scrollbar with an edge, use one of the %sbs_xxx alignment styles with the corresponding %sbs_xxx vert/horz style. Also set x,y to 0,0 and set xx,yy to the size of the client area. In this approach, remember that the scrollbar will not automatically change size when the Dialog size is changed. The application must handle resizing of the scrollbar control.

    With %sbs_vert, a scrollbar is always displayed vertically. But with %sbs_horz, if width is less than height the scrollbar is automatically switched to %sbs_vert.

    To get bottom or top alignment, the %sbs_horz must be used in combination with %sbs_bottomalign or %sbs_topalign.

    To get left or right alignment, the %sbs_vert must be used in combination with %sbs_leftalign or %sbs_rightalign.

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

      ScrollBar Get PageSize     get pagesize - value associated with scrollbar body click
      hDlg, id& TO value&
      ScrollBar Get POS get current position of scroll box
      hDlg, id&, TO value&
      ScrollBar Get Range get hi/lo values (range)
      hDlg, id& TO LoValue&, HiValue$
      ScrollBar Get TrackPOS get position of scroll box as user drags it
      hDlg, id&, TO value&
      ScrollBar Set PageSize set pagesize - value associated with scrollbar body click
      hDlg, id&, pagesize&
      ScrollBar Set POS set scrollbar position
      hDlg, id&, pos&
      ScrollBar Set Range set hi/lo values (range)
      hDlg, id&, LoValue&, HiValue&

    See the Usage section above for information on how to use the values made available by these statements.

    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 (scrollbar 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.

    %sb_bottom - scrolls to lower right %sb_endscroll - ends scroll %sb_endscroll - ends scroll %sb_left - scroll to upper left %sb_linedown - scrolls one line down %sb_lineleft - scrolls left by one unit %sb_lineright - scrolls right by one unit %sb_lineup - scrolls one line up %sb_pagedown - scrolls one page down %sb_pageleft - scrolls left by the width of the window %sb_pageright - scrolls right by the width of the window %sb_pageup - scrolls one page up %sb_right - scroll to lower right %sb_thumbposition - scroll box dragged and released %sb_thumbposition - scroll box dragged and released %sb_thumbtrack - scroll box is being dragged %sb_thumbtrack - scroll box is being dragged %sb_top - scrolls to upper left %sbs_bottomalign - align scrollbar bottom with dialog bottom %sbs_horz - horizontal scroll bar %sbs_leftalign - align left edge with dialog left edge %sbs_rightalign - align right edge with dialog right edge %sbs_topalign - align top edge with dialog top edge %sbs_vert - vertical scroll bar %wm_ctlcolorscrollbar - control about to be drawn %wm_hscroll - horizontal scroll event %wm_vscroll - vertical scroll event %ws_disabled - initially disabled (no user input) %ws_ex_clientedge - apply sunken edge border %ws_ex_left - generic left-aligned properties %ws_ex_right - generic right-aligned properties %ws_ex_staticedge - apply 3D border %ws_ex_windowedge - apply raised edge border %ws_group - starts/ends group. use %ws_tabstop style. %ws_tabstop - allows receipt of keyboard focus

    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.

    The scrollbar also receives the %WM_SCROLL and %WM_VSCROLL messages. In both cases, the low word of wParam contains the event information.

    Here's a sample scrollbar control callback function.

       CallBack Function cbScrollBar()
          Select Case CB.MSG
             Case %WM_HSCROLL
                Select Case LO(WORD, CB.WPARAM)
                   Case %sb_endscroll      'mouse up (arrow/shaft)
                   Case %sb_left           'HOME keypress
                   Case %sb_right          'END keypress
                   Case %sb_lineleft       'arrow
                   Case %sb_lineright      'arrow
                   Case %sb_pageleft       'shaft
                   Case %sb_pageright      'shaft
                   Case %sb_thumbposition  'scroll box
                   Case %sb_thumbtrack     'scroll box
                End Selection
             Case %WM_VSCROLL
                Select Case LO(WORD, CB.WPARAM)
                   Case %sb_bottom          'END keypress
                   Case %sb_endscroll       'mouse up (arrow/shaft)
                   Case %sb_linedown        'arrow
                   Case %sb_lineup          'arrow
                   Case %sb_pagedown        'shaft
                   Case %sb_pageup          'shaft
                   Case %sb_thumbposition   'scrollbox
                   Case %sb_thumbtrack      'scrollbox
                   Case %sb_top             'HOME keypress
                End Selection
          End Select
       End Function

    To help clarify which parts of a scrollbar correspond to received messages, here is a diagram of the parts of a scrollbar.

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