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

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
  • Windows Controls & PowerBASIC
    PowerBASIC allows any registered control to be added to a dialog by using the CONTROL ADD statement. But, with many of the Windows common controls PowerBASIC provides a variety of statements which simplify the job of the programmer in creating and modifying controls, as well as monitoring control events. These statements minimize the need for the programmer to work at the lower level of communication between control and dialog via the Control Send statement, or by manually extracting information from Windows messages.

    The following list shows the 22 controls for which PowerBASIC provides special support.

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

    Some PowerBASIC controls are actually derivations of the Windows Common Controls, so if you review the MSDN documentation you won't find every PowerBASIC control listed. Here's a list which maps derived PowerBASIC controls to the corresponding Windows common control.

      Common Control     PowerBASIC Control
      edit control textbox
      static control graphic, image, imagex, label, line
      button control button, check3state, checkbox, frame, imgbutton, imgbuttonx, option

    In the following table, use the corresponding Windows common control data to get style/exstyle values for a PowerBASIC control.

    Control Categories
    The following categorized list of the supported controls will help understand the basic capabilities of the available controls.

      • Text Display
       Label, TextBox 
      • Status Indicators  
       Button, Check3State, CheckBox,
       Option Button, Progress Bar, Statusbar
      
      • Simple Lists
       ComboBox, ListBox 
      • Content Display
       ListView, TreeView, Toolbar 
      • Image Display
       Graphic, Image, ImageX, ImgButton, ImgButtonX 
      • Containers
       Frame, Tab 

    Source code for creating each of these controls is discussed below. More detailed examples are provided on each of the specific control pages.

    PowerBASIC CONTROL Statements
    The various CONTROL statements, which include CONTROL ADD, provide most of the functions needed to create and manage child controls. As will be discussed below, there are also control-specific statements which supplement the CONTROL statements.

    The starting point for creating controls and placing them on a dialog is is the CONTROL ADD statement. It defines the basic size/location and visual look of a control.

    Other CONTROL statements are available to further manage controls, such as getting or setting control properties, as well as deleting or disabling the controls.

    Here is a summary of all available CONTROL statements and a short description of the capabilities they provide.

    • CONTROL ADD
    • one for each of 22 control types
    • CONTROL DISABLE
    • disables a specific control
    • CONTROL ENABLE
    • enables a specific control
    • CONTROL GET
    • 6 versions (CHECK, CLIENT, LOC, SIZE, TEXT, USER)
    • CONTROL HANDLE
    • returns Windows handle of control
    • CONTROL KILL
    • remove child from dialog
    • CONTROL POST
    • place message in queue
    • CONTROL REDRAW
    • redraw a control
    • CONTROL SEND
    • send message to control
    • CONTROL SET
    • 14 versions (CHECK, CLIENT, LOC SIZE, TEXT, USER, ...)
    • CONTROL SHOW STATE    
    • set visible state

    Note that there are several versions of the CONTROL GET and CONTROL SET, corresponding the 20 different control properties they can access or set.

    In addition to CONTROL statements, PowerBASIC provides statements that are specific to eight of the controls (ComboBox, ImageList, ListView, ProgressBar, Scrollbar, Statusbar, Toolbar, and TreeView). The control-specific statements are discussed on the individual control pages.

    Finally, there are other PowerBASIC statements, such as FONT NEW, which can be used to modify how a control looks or behaves. These too are covered in the individual control pages.

    CONTROL ADD Statements
    The CONTROL ADD statement is used to create all controls. Fortunately, the syntax is the same for all of the controls, with only a few differences for controls which use images or which display lists.

    Here's the syntax for the CONTROL ADD statement, along with a few specific examples.

        Syntax:
        CONTROL ADD BUTTON, hDlg,id&,text$,x,y,xx,yy,style&,exstyle& CALL callback
    
        Examples:
        CONTROL ADD BUTTON, hDlg, 500&, "OK", 100,100,300,300
        CONTROL ADD CHECKBOX, hDlg, 501&, "Vote", 100,100, 300,300
        CONTROL ADD LABEL, hDlg, 502&, "Title", 100,100,300,300
    

    The above examples demonstrate the minimum code needed to create a control - the handle of the parent dialog, a control ID, text content, upper/left coordinates and width/height.

    And here is a description of each of the arguments.

    • hdlg
    • parent dialog handle
    • id&
    • programmer assigned ID
    • text$
    • control text OR resource file image name
    • x
    • upper left x coordinate
    • y
    • upper left y coordinate
    • xx
    • width of control
    • yy
    • height of control
    • style&
    • primary style (optional)
    • exstyle&    
    • extended style (optional)
    • callback
    • named callback function (optional)

    The style&, exstyle& and CALL arguments are optional. The default values used when style&/exstyle& are omitted are listed further down this page, as is a full list of the style&/exstyle& values each control can use.

    CONTROL ADD Notes
    While the syntax above applies to all controls, there are some slight variations on the content of the arguments, depending on the control involved.

    • ComboBox / Listbox
      The text$ argument should be replaced by a string array which contains the data to be placed in the control lists.

    • Image, Imagex, Imgbutton and Imgbuttonx
      The value of text$ should be the name or numeric identifier of an image from a resource file (*.pbr).

    • Button, Check3State, Checkbox, Frame, Label, Option, Statusbar
      Only these controls display the value of text$.

    • Graphic, Line, Listview, Progressbar, Scrollbar, Tab, Toolbar, Treeview
      The text$ argument is accepted, but not displayed. The text$ values is normally set to "". If a text$ value is entered, the Control Get/Set statements can access the value, effectively creating a hidden property that some programmers make use of. Some of these controls do display text but it does not come from the text$ argument.

    • Image, ImageX
      The width/height arguments refer to the image dimensions, not those of the control.

    • Graphic Control
      The graphic control also displays images but the image is not defined by the CONTROL ADD statements. See the graphics tutorial for information on placing images into graphic controls.

    CONTROL Statements
    In addition to the CONTROL ADD statement there are another 28 CONTROL statements that manage controls once they are created. A simple one-line description of each is provided below, followed by the syntax for using the statement.

      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 client 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&

    And here is a description of the arguments for the CONTROL statements listed above. For each of the arguments, the CONTROL statements that apply are also listed.

    • bgcolor&
    • background color(SET COLOR, SET COLOR)
    • checkstate$
    • check state (SET CHECK)
    • fgcolor&
    • foreground color (SET CHECK, SET COLOR)
    • fonthandle&    
    • font handle returned by FONT NEW (SET FONT)
    • hCtl&
    • Window-assigned handle (HANDLE)
    • hdlg
    • parent dialog handle (ALL)
    • height&
    • width of control (GET SIZE, SET SIZE)
    • high&
    • width of client area (GET CLIENT, SET CLIENT)
    • id&
    • programmer assigned control ID (ALL)
    • index&
    • index number of 8 user values (GET USER, SET USER)
    • lParam&
    • 2nd msg$ parameter, message-dependent content (POST/SEND)
    • iResult1&
    • 0-unchecked, 1-checked, 2-grayed (GET CHECK)
    • iResult2&
    • SEND - return value from a msg$ (SEND)
    • iResult3&
    • 0-was invisible, non-zero if was visible (SHOW STATE)
    • maxid&
    • top end of range to unset (SET OPTION)
    • minid&
    • low end of range to unset (SET OPTION)
    • msg&
    • message (POST/SEND)
    • newimage$
    • image name (Image, ImageX, ImgButton, ImgButtonX)
    • showstate&
    • visible state (SHOW STATE)
    • text&
    • text from edit portion of the control (SET TEXT)
    • uservalue&
    • value of selected user value (SET USER)
    • wide&
    • width of client area (GET CLIENT, SET CLIENT)
    • width&
    • width of contol (GET SIZE, SET SIZE)
    • wParam&
    • 1st msg$ parameter, message-dependent content (POST/SEND)
    • x&
    • top/left horizontal position (SET LOC)
    • y&
    • top/left vertical position (SET LOC)

    Default Style& and ExStyle& Values
    The style& and exstyle& arguments define the way a control looks, allowing the programmer a means of adjusting the controls visible features as needed in an application. Use of style& and exstyle& is optional on all controls. If not specified, the following default values are used by PowerBASIC.

      ControlDefault Style&Default ExStyle&
      BUTTON %BS_CENTER
      %BS_VCENTER
      %WS_TABSTOP
      %WS_EX_LEFT
      CHECK3STATE %BS_LEFT
      %BS_VCENTER
      %WS_TABSTOP
      %WS_EX_LEFT
      CHECKBOX %BS_LEFT
      %BS_VCENTER
      %WS_TABSTOP
      %WS_EX_LEFT
      COMBOBOX %CBS_DROPDOWN
      %CBS_SORT
      %WS_TABSTOP
      %WS_EX_LEFT
      %WS_EX_CLIENTEDGE
      FRAME %BS_LEFT
      %BS_TOP
      %WS_EX_LEFT
      GRAPHIC %WS_CHILD
      %WS_VISIBLE
      %SS_OWNERDRAW
      -no default-
      IMAGE -no default- %WS_EX_LEFT
      IMAGEX -no default- %WS_EX_LEFT
      IMGBUTTON %WS_TABSTOP %WS_EX_LEFT
      IMGBUTTONX %WS_TABSTOP %WS_EX_LEFT
      LABEL %SS_LEFT %WS_EX_LEFT
      LINE %SS_ETCHEDFRAME %WS_EX_LEFT
      LISTBOX %LBS_SORT
      %LBS_NOTIFY
      %WS_TABSTOP
      %WS_VSCROLL
      %WS_EX_LEFT
      %WS_EX_CLIENTEDGE
      LISTVIEW %WS_TABSTOP
      %LVS_REPORT
      %LVS_SHOWSELAWAYS
      %WS_EX_LEFT
      OPTION %WS_TABSTOP
      %BS_LEFT
      %BS_VCENTERv
      %WS_EX_LEFT
      PROGRESSBAR %WS_BORDER -no default-
      SCROLLBAR %SBS_HORZ %WS_EX_LEFT
      STATUSBAR %CCS_BOTTOM -no default-
      TAB %WS_CHILD
      %WS_TABSTOP
      -no default-
      TEXTBOX %WS_TABSTOP
      %WS_BORDER
      %ES_LEFT
      %ES_AUTOHSCROLL
      %WS_EX_CLIENTEDGE
      %WS_EX_LEFT
      TOOLBAR %WS_CHILD
      %WS_VISIBLE
      %WS_BORDER
      %CCS_TOP
      %TBSTYLE_FLAT
      -no default-
      TREEVIEW %WS_TABSTOP
      %TVS_HASBUTTONS
      %TVS_HASLINESATROOT
      %TVS_HASLINES
      %TVS_SHOWSELALWAYS
      %WS_EX_LEFT

    Managing Controls - Style, ExStyle
    Style and extended style values determine the visual look of a control. Microsoft documents the allowed values at its MSDN site.

    I've pulled the information for the controls supported by PowerBASIC to create the following list of style and extended values for each control.

    As noted earlier, some of the PowerBASIC controls are derivations of the Windows common controls. So, in the following table, use the corresponding Windows common control data to get style/exstyle values for a PowerBASIC control.

       

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