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

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.

Control	Default 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.