Getting Started
Sample Programs
Code Snippets

Web Sites
More Tutorials
User Groups
Talk Shows

Progress Bar

GBIC >> PowerBASIC >> Tutorials >> Controls >> TAB 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
  • TAB Control
    The tab control consists of a group of small dialogs, where the group is kept together and treated as one large control - a child control of the dialog in which it is created. Each of the smaller dialogs are called pages and overlap one another so that only one is visible at a time, except for a small label called the tab. The tab can be positioned on any edge of the page. Clicking on a tab brings its page to the forefront of any other page in the control.

    Each page, like any dialog, can have child controls placed on it. When the tab is selected (page made visible), all of the child controls on the page are also visible. When a page is not selected (place behind the visible page), its child controls are not visible.

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

    • Source Code Example:
      This short example creates a complete application with a single tab, containing two pages. When clicked, the a new page is selected, the tab control 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 hPage1 As Long, hPage2 As Long
            Dialog New Pixels, 0, "TAB Test",300,300,200,200, _
                                            %WS_SysMenu, 0 To hDlg
          Control Add Tab, hdlg, 500, "", 20,20,100,150
              Tab Insert Page hdlg, 500, 1,0,"Page1" To hPage1
                  Control Add Label, hPage1, 600, "Label1", 20,20,60,20
                  Control Add Label, hPage1, 601, "Label2", 20,50,60,20
                  Control Add Label, hPage1, 602, "Label3", 20,80,60,20
              Tab Insert Page hdlg, 500, 2,0,"Page2" To hPage2
                  Control Add TextBox, hPage2, 603, "Text1", 20,20,60,20
                  Control Add TextBox, hPage2, 604, "Text2", 20,50,60,20
                  Control Add TextBox, hPage2, 605, "Text3", 20,80,60,20
            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 tab controls in PowerBASIC. Variations on the Control Add TAB statement were used to create the examples. In some cases, other Control statements were used to modify the results.

      There are several basic variations possible. Tabs can be placed on any side, icons can be used in the tabs, color and font of the labels can be changed, and the body of a page can be modified using DIALOG statements.

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

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

      The tab control itself does not display text - the text on the tab labels are considered part of their respective pages - 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.

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

    Using the Control Add TAB statement simply creates a blank control - no tabs (pages) at all. Use the TAB Insert Page statement to create individual tabs (pages) within the control, and to return the handle to the page. The handle is used with Control Add statements to place child controls on the page.

    Here's the code to create a tab control with 2 tabs (pages). On the first page are 3 label controls. On the second page are 3 textbox controls. Page indexing starts at 1.

        Control Add Tab, hdlg, 500, "MyTab", 20,20,100,150
            Tab Insert Page hdlg, 500, 1,0,"Page1" To hPage1
                Control Add Label, hPage1, 600, "Label1", 20,20,60,20
                Control Add Label, hPage1, 601, "Label2", 20,50,60,20
                Control Add Label, hPage1, 602, "Label3", 20,80,60,20
            Tab Insert Page hdlg, 500, 2,0,"Page2" To hPage2
                Control Add TextBox, hPage2, 603, "Text1", 20,20,60,20
                Control Add TextBox, hPage2, 604, "Text2", 20,50,60,20
                Control Add TextBox, hPage2, 605, "Text3", 20,80,60,20 

    Note that the handle used in the Control Add Label/Textbox statements is the handle of the page on which the control is placed - NOT the handle of the dialog.

    An image can be placed in the tab area of a page. but must come from an imagelist attached to the tab control using the TAB Set ImageList statement.

        IMAGELIST NEW ICON 16,16,32,4 To hLst
        IMAGELIST ADD ICON hLst, "face"
        IMAGELIST ADD ICON hLst, "x"
        IMAGELIST ADD ICON hLst, "y"
        IMAGELIST ADD ICON hLst, "z"
        Tab Set Imagelist hdlg, 500, hLst
        Tab Insert Page hdlg, 500, 2,1,"Page2" To hPage2

    In this example, a resource file has already been included which contains 16x16, 32-bit icons "x", "y", and "z". The ImageList is set up to handle 4 images, although more can be added.

    The Tab Set Imagelist statements attaches the imagelist to the Tab control, and the Tab Insert Page statement selected the 1st icon in the imagelist. The Tab Insert Page does not allow selecting the icon by name, such as "x".

    When TAB control is destroyed, any attached imagelist is also destroyed.

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

      TAB Delete deletes a page
      hDlg, id&, page&
      TAB Get Count number of pages
      hDlg, id&, TO count&
      TAB Get Dialog
      hDlg, id&, TO value&
      TAB Get Select get index of selected page
      hDlg, id&, TO index&
      TAB Insert Page add a page
      hDlg, id&, page&, image&, txt$ CALL callback TO hPage&
      TAB Reset delete all pages
      hDlg, id&
      TAB Select select a specific page
      hDlg, id&, page&
      TAB Set ImageList   select imagelist to attach to tab control
      hDlg, id&, hImageList&

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

        %nm_click              -n mouse click
        %nm_dblclk             -n mouse doubleclick
        %nm_rclick             -n right mouse click
        %nm_rdblclk            -n right mouse double click
        %nm_releasedcapture    -n releasing mouse capture
        %tcn_focuschange       -  focus has changed
        %tcn_getobject         -n object dragged over tab item
        %tcn_keydown           -n key pressed
        %tcn_selchange         -n selected tab has changed
        %tcn_selchanging       -n tab is about to change
        %tcs_bottom            - tabs at bottom
        %tcs_fixedwidth        - all tabs are the same size
        %tcs_focusnever        - cannot receive focus
        %tcs_focusonbuttondown - tabs receive focus
        %tcs_forceiconleft     - icons on left
        %tcs_forcelabelleft    - labels on left
        %tcs_ownerdrawfixed    - parent dialog must draw tabs
        %tcs_raggedright       - tabs are not stretched to fill width
        %tcs_right             - tabs on right side
        %tcs_rightjustify      - tabs fill width of control
        %tcs_singleline        - one row of tabs
        %tcs_tooltips          - enable tooltips
        %tcs_vertical          - tabs placed vertically
        %ws_child              - 
        %ws_ex_clientedge      - apply sunken edge border
        %ws_ex_staticedge      - apply 3D border
        %ws_ex_transparent     - draw controls/windows beneath control first
        %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.

    Here's a sample tab control callback function.

       CallBack Function cbTAB()
          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_releasedcapture
                   Case %tcn_focuschange
                   Case %tcn_getobject
                   Case %tcn_keydown
                   Case %tcn_selchange
                   Case %tcn_selchanging
             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.

    Help does not define the extstyle& default.

    Help defines default style& as %ws_border OR %ws_child, but neither is in the list of style values.

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