Getting Started
Sample Programs
Code Snippets

Web Sites
More Tutorials
User Groups
Talk Shows

Progress Bar

GBIC >> PowerBASIC >> Tutorials >> Controls >> Option 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
  • Option Control
    The option control provides a way to indicate a selection of a single item from within a group of items. Multiple option controls represent a group, from which only one control can be selected. Multiple groups are allowed. When a member of a group is selected, Windows unselects all other members of the group. Also, using the %bs_pushlike style& enables creation of a button-like control which simulates staying in a pressed condition.

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

    • Source Code Example:
      This short example creates a complete application with three Option controls which are part of the same group. When clicked, each Option control responds with a message that pops up a MsgBox with the ID of the control that was clicked.

      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, "Option Test",300,300,300,200, _
                                            %WS_SysMenu, 0 To hDlg
            Control Add Option, hDlg, 197,"Click Me!", 50,50,100,20, _
                                            %WS_Group  Or %WS_TabStop
            Control Add Option, hDlg, 198,"Click Me!", 50,80,100,20
            Control Add Option, hDlg, 199,"Click Me!", 50,110,100,20
            Control Set Option hdlg, 197,197,199
            Dialog Show Modal hDlg Call DlgProc
         End Function
         CallBack Function DlgProc() As Long
            If Cb.Msg = %WM_Command  Then
               MsgBox Str$(Cb.Ctl)
            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 option control in PowerBASIC. Variations on the Control Add Option statement were used to create the examples. In some cases, other Control statements were used to modify the results.

      The choices are fairly basic - a place to check and a text description. The text can be on either side of the control. You can change the font, change the justification of the text, and display multi-line content.

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

    • hDlg
      The dialog handle to which the option 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$
      An ampersand can be included in txt$, such as "&Stop", to specify a hot key Alt-S. Using the hotkey clicks the option control. Hotkeys are underlined in the option control. In WinXP, the hotkey underline will not appear until the Alt key is pressed.

      Note that when an option control gets pressed, it displays a dotted line around the text, but only after the Alt key has been pressed to expose underlined hotkeys.

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

    The Control Set Option statement is critical! Be sure to set a selected Option or else the program can generate unexpected message on startup.

    Also, be sure to note the range used in the Control Set Option (197-199) must include the ID of the Option control which is to be set. It cannot be outside the range.

    A single Option control can be used by itself, but Help recommends using a checkbox instead.

    Option Control-Specific PowerBASIC Statements
    Although PowerBASIC provides control-specific statements for some controls (Treeview, Imagelist, ...), there are no OPTION PowerBASIC 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 (option controls are windows).

    Since the PowerBASIC option control is derived from the Windows button class, the first column contains MSDN button control constants.

    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.

        bcn_dropdown          -n click on drop down arrow on control
        bcn_hotitemchange     -n mouse enters/leaves client area
        bn_clicked            -c mouse click
        bn_dblclk             -c mouse doubleclick
        bn_disable            -c (n/a - win3.0 only)
        bn_doubleclicked      -n mouse doubleclick
        bn_hilite             -c (n/a - win3.0 only)
        bn_killfocus          -c focus is lost
        bn_paint              -c control should be painted
        bn_pushed             -c (n/a - win3.0 only)
        bn_setfocus           -n focus is received
        bn_unhilite           -c when highlight should be removed 
        bn_unpushed           -c (n/a - win3.0 only)
        bs_bottom             - text at bottom
        bs_center             - center text horizontally
        bs_default            - heavy black border, ENTER selects, 1 per dialog
        bs_defpushbutton      - same as bs_default
        bs_left               - text on left side
        bs_multiline          - wrap text
        bs_notify             - allows bn_killfocus/bn_setfocus messages
        bs_pushlike           - toggle between raised/sunken
        bs_right              - text on right side
        bs_top                - text at top
        bs_vcenter            - center text vertically
        nm_customdraw         -n custom draw operation
        wm_ctlcolorbtn        - before drawing owner-drawn control
        ws_border             - use thin line border
        ws_disabled           - initially disabled (no user input)
        ws_ex_left            - generic left-aligned properties
        ws_ex_right           - generic right-aligned properties
        ws_ex_transparent     - draw controls/windows beneath control first
        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.

    In addition, %bs_notify must be included in style& to receive the %bn_killfocus and %bn_setfocus messages

    Here's a sample option control callback function.

       CallBack Function cbOption()
          Select Case CB.MSG
             Case %WM_COMMAND
                Select Case CB.CTL
                   Case %MyControl_ID   'whatever ID was assigned
                      Select Case CB.CTLMSG
                         Case %bn_clicked
                         Case %bn_disable
                         Case %bn_killfocus
                         Case %bn_setfocus
                      End Select
                   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 option 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.