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 >> ComboBox 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
  • ComboBox Control
    The combobox control provides a combination text box and listbox. Three types of comboboxes are available - one where the list always shows and two where the list only shown when the control is clicked. With the two dropdown lists, one is editable and the other is not.

    • Simple - editable textbox, list always displayed
    • Dropdown - editable textbox, dropdown list on demand
    • DropdownList - non-editable textbox, dropdown list on demand

    An item selected from the list appears in the textbox. Depending on how the application is programmed, users can edit existing items or create new items by typing in the textbox. In the case of the dropdownlist style, the textbox is disabled (works like a non-editable label). The list may contain strings and or images. One or more list items may be selected. Horizontal and vertical scrollbars are available to help view the list. Automatic sorting of items is provided.

    • Syntax:
      Control Add ComboBox, hDlg, id&, data$(), x, y, xx, yy, _
                                           style&, extsytle& CALL callback
      

    • Source Code Example:
      This short example creates a complete application with a single combobox. When a selection is made from the dropdown list, the combobox 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
            Dim MyArray(3) As String
            Array Assign MyArray() = "zero", "one", "two", "three"
            Dialog New Pixels, 0, "ComboBox Test",300,300,200,200, _
                                            %WS_SysMenu, 0 To hDlg
            Control Add ComboBox, hDlg, 100, MyArray(), 50,50,75,100
            Dialog Show Modal hDlg Call DlgProc
         End Function
      
         CallBack Function DlgProc() As Long
            If Cb.Msg = %WM_Command And Cb.Ctl = 100 And _
                              Cb.CtlMsg = %LBN_SelChange Then
               MsgBox "Selected!"
            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 combobox control in PowerBASIC. Variations on the Control Add ComboBox statement were used to create the examples. In some cases, other Control statements were used to modify the results.

      The options are pretty basic. A list of selectable items is displayed, either always or on demand. Selecting an item places it in the textbox for editing. The textbox can be made read-only. Vertical scrolling is supported. Fonts and colors may be changed.

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

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

    • data$
      The initial data for the combobox is supplied in a dynamic string array. If data$ is omitted the list will be empty.

    • 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 combobox 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
    Some of these comments refer to the ComboBox-specific statement in the next section below.

    The ComboBox is limited to 32,767 items.

    Indexing is starts at 1 for all Control and ComboBox statements.

    Item numbers and returned item numbers are long integers.

    The textbox is initially empty and must be filled programmatically.

    To change an item and sort the results, use Delete/Add instead of Set Text.

    To add an item and sort the results, use Add instead of Insert.

    ComboBox-Specific PowerBASIC Statements
    PowerBASIC provides several statements specific to the combobox control. These allow the application to manage the content and display of the control.

      ComboBox Add     add new item to end of list (sorted if %cbs_sort is used)
      hDlg, id&, item$
      ComboBox Delete     delete specified item.
      hDlg, id&, item&
      ComboBox Find     find 1st item in list that starts with search$. starts at item&. pos& is position of matching item (zero if not found). search is case-insensitive.
      hDlg, id&, item&, search$ TO pos&
      ComboBox Find Exact     find 1st item in list exactly matches search$. starts at item&. pos& is position of matching item (zero if not found). search is case-insensitive.
      hDlg, id&, item&, search$ TO pos&
      ComboBox Get Count     get number of item in combobox
      hDlg, id& TO count&
      ComboBox Get SelCount     get number of selected items in combobox
      hDlg, id& TO count&
      ComboBox Get Select     get index of selected item. pos& is position of selected item (zero if none selected)
      hDlg, id& TO pos$
      ComboBox Get State     get selected status of item. status$ is True (-1) or False (0).
      hDlg, id&, item& TO status$
      ComboBox Get Text     get specified item. if optional item& omitted, currently selected text is returned (single selection list) or text of 1st selected item is returned (multi-selection list)
      hDlg, id&, item& TO item$
      ComboBox Get User     get optional numeric value associated with item
      hDlg, id&, item& TO value&
      ComboBox Insert     insert string item, moves all items down. does not resort.
      hDlg, id&, item&, value$
      ComboBox Reset     delete all items
      hDlg, id&
      ComboBox Select     select and scroll to item. select all if item& = 0.
      hDlg, id&, item&
      ComboBox Set Text     change text at item& to value$. does not resort.
      hDlg, id&, item&, value$
      ComboBox Set User     set optional numeric value associated with item
      hDlg, id& TO value&
      ComboBox UnSelect     unselect item&. item& is optional. if item& is omitted, or is zero, all items are unselected.
      hDlg, id&, item&

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

        %cbn_closeup           -c list box closed
        %cbn_dblclk            -c double-clicks list box
        %cbn_dropdown          -c before list is shown
        %cbn_editchange        -c change made in edit box
        %cbn_editupdate        -c before change made in edit box
        %cbn_errspace          -c memory allocation problem
        %cbn_killfocus         -c keyboard focus lost
        %cbn_selcancel         -c item selection canceled
        %cbn_selchange         -c selection about to change (mouse or arrow keys)
        %cbn_selendok          -c item selection accepted
        %cbn_setfocus          -c keyboard focus received
        %cbs_autohscroll       - auto scroll text right, wide text allowed
        %cbs_disablenoscroll   - show disabled vertical scrollbar, else autohide
        %cbs_dropdown          - display list only when down arrow selected
        %cbs_dropdownlist      - display non-editable label in lieu of textbox
        %cbs_hasstrings        - combobox contains strings
        %cbs_lowercase         - convert user input in textbox to lower case
        %cbs_nointegralheight  - use exact dimensions (partial display of lines)
        %cbs_simple            - always display list (selection in textbox)
        %cbs_sort              - automatically sort list 
        %cbs_uppercase         - convert user input in textbox to upper case
        %wm_compareitem        -  position of item in owner-drawn control
        %wm_drawitem           -  owner-drawn control has changed
        %wm_measureitem        -  owner-drawn control is created
        %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
        %ws_vscroll            - autodisplay vertical scroll
    

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

       CallBack Function cbComboBox()
          Select Case CB.MSG
             Case %WM_COMMAND
                Select Case CB.CTLMSG
                   Case %cbn_closeup
                   Case %cbn_dblclk
                   Case %cbn_dropdown
                   Case %cbn_editchange
                   Case %cbn_editupdate
                   Case %cbn_errspace
                   Case %cbn_killfocus
                   Case %cbn_selchange
                   Case %cbn_selcancel
                   Case %cbn_selendok
                   Case %cbn_setfocus
                End Selection
          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 mentions that comboboxes can contain images, but no information is provided on how to add the images. There are two samples apps distributed with PowerBASIC but with little explanation.

    I'll update this page as more 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 combobox 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.