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

Button Control
The button control gives a visual indication of having been "pushed" when clicked with a mouse. It is normally used to take action when the button is clicked.

The button control does not support images. If you need image support in a button, consider using the ImgButton and ImgButtonX controls.

• Control Add Syntax:
  

  Control Add Button, hDlg, id&, txt$, x, y, xx, yy, _
                                       style&, extsytle& CALL callback
  

• Source Code Example:
  This short example creates a complete application with a single button. When clicked, the button 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, "Button Test",300,300,200,200, _
                                        %WS_SysMenu, 0 To hDlg
        Control Add Button, hDlg, 100,"Push", 50,50,100,20
        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 = %BN_Clicked Then
           MsgBox "Pushed!"
        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 button control in PowerBASIC. Variations on the Control Add Button statement were used to create the examples. In some cases, other Control statements were used to modify the results.

  

  As you can see, there's really not much you can do with a button - change the font, change the justification of the text, and multi-line content is about it. You can also set which button is associated with pressing ENTER and ESC.

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

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

  A button with equate value %IDOK is triggered when the ENTER key is pressed.

  A button with equate value %IDCANCEL is triggered when the ESCAPE key is pressed.

• txt$
  An ampersand can be included in txt$, such as "&Stop", to specify a hot key Alt-S. Using the hotkey clicks the button. Hotkeys are underlined in the button control. In WinXP, the hotkey underline will not appear until the Alt key is pressed.

  Note that when a button 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 button 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.

Button-Specific PowerBASIC Statements
Although PowerBASIC provides control-specific statements for some controls (Treeview, Imagelist, ...), there are no BUTTON 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 (buttons 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.

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

   CallBack Function cbButton()
      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, code statements are inserted to respond to the event, including assigning the function a value of TRUE 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 button control. A one-line description of the statement and then its syntax are presented.

CONTROL DISABLE	disable
	hDlg, id&
CONTROL ENABLE	enable	hDlg, id&
CONTROL GET CHECK	check state	hDlg, id& TO iResult1&
CONTROL GET CLIENT	top/left location	hDlg, id& TO wide&, high&
CONTROL GET LOC	top/left location	hDlg, id& TO x&, y&
CONTROL GET SIZE	width/height	hDlg, id& TO width&, height&
CONTROL GET TEXT	text	hDlg, id& TO txt$
CONTROL GET USER	get user data	hDlg, id&, index& TO retvar&
CONTROL HANDLE	window handle for control id	hDlg, id& TO hCtl&
CONTROL KILL	remove control	hDlg, id&
CONTROL POST	put message in queue (non-blocking)	hDlg, id&, Msg&, wParam&, lParam&
CONTROL REDRAW	schedule redraw of control	hDlg, id&
CONTROL SEND	send message to control, wait for processing	hDlg, id&, Msg&, wParam&, lParam& TO iResult2&
CONTROL SET CHECK	set check for 3state or checkbox	hDlg, id&, checkstate&
CONTROL SET CLIENT	change size to specific client area size	hDlg, id&, wide&, high&
CONTROL SET COLOR	set fg/bg color	hDlg, id&, fgcolor&, bgcolor&
CONTROL SET FOCUS	set focus	hDlg, id&
CONTROL SET FONT	select font for a control	hDlg, id&, fonthandle&
CONTROL SET LOC	relocate control within dialog	hDlg, id&, x&, y&
CONTROL SET OPTION	set check state of option control	hDlg, id&, minid&, maxid&
CONTROL SET SIZE	change control size	hDlg, id&, width&, height&
CONTROL SET TEXT	change control text	hDlg, id&, text$
CONTROL SET USER	set 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.