Controls

A control is a special Window that provides a method for interacting with the user. Buttons, Combo boxes, List boxes, and Text boxes are all examples of controls. Whenever the user interacts with a control (clicks a button or types into a text box), an event occurs causing Windows to send a message to your application. Your application processes these messages in special functions called Callback Functions.

When you add a control to a dialog, it is important that each control has a unique numeric identifier. This identifier helps your application to know which control is sending an event. For example, if your program has two buttons in it, the control ID allows you distinguish between them.

As each control is created, Windows assigns a unique window handle to identify the control. Because your program does not assign these handle values, your code cannot directly use them to identify individual controls. Further, each time a control is destroyed and recreated, a new unique handle value is assigned, further complicating the task. The control ID overcomes these problems, as the programmer determines the ID for each control.

Controls are added to your dialog with the CONTROL ADD statement. Make sure that each control you create has a unique numeric identifier, so that you (and Windows) can tell it apart from other controls on the dialog.

Given the ID of a control, DDT provides the CONTROL HANDLE statement to retrieve the window handle value of the control. If a given ID is duplicated in a dialog, CONTROL HANDLE is only able to identify the first control that matches the ID, and the remaining controls will essentially be ignored. Control ID's can often be duplicated for Label (static) text controls, provided these controls (and their contents, color, or styles) are not going to be modified at run-time. If such a Label control is to be modified, its control ID must be unique.

PowerBASIC provides a comprehensive set of statements and functions for dealing with controls. The following is a small sample of these statements and functions with a brief description of the purpose of each:

Function Description

#MESSAGES	Specify which messages should be sent to a Control Callback Function
CB.CTL	Return the ID of the control sending a message to your Callback Function. (Only valid inside a Callback Function).
CB.CTLMSG	Return the notification ID of the control sending a message to your Callback Function. (Only valid inside a Callback Function).
CB.HNDL	Returns the dialog handle sending a message to your Callback Function. (Only valid inside a Callback Function).
CB.LPARAM	Returns the lParam& value sent to your Callback Function. (Only valid inside a Callback Function).
CB.MSG	Returns the wMsg& value sent to your Callback Function. (Only valid inside a Callback Function).
CB.NMCODE	Returns the specific notification message describing the event which occurred. (Only valid inside a Callback Function).
CB.NMHDR	Returns the address (a pointer) to the NMHDR UDT for a notification message sent to your Callback Function. (Only valid inside a Callback Function).
CB.NMHDR$	Returns the contents of the NMHDR UDT as a dynamic string. (Only valid inside a Callback Function).
CB.NMHWND	Returns the handle of the control which sent this message to your Callback Function. (Only valid inside a Callback Function).
CB.NMID	Returns the ID number assigned to this control which sent this message to your Callback Function. (Only valid inside a Callback Function).
CB.WPARAM	Returns the wParam& value sent to your Callback Function. (Only valid inside a Callback Function).
CONTROL ADD	Create a control in a dialog.
CONTROL DISABLE	Disable a control so that it can no longer send messages to a callback. If the control is a button, it is grayed. If it is a text box, it becomes grayed out and you can no longer edit the text contained within it.
CONTROL ENABLE	Enable a control that was previously disabled. A control must be enabled in order for it to send notifications to a Callback Function.
CONTROL GET SIZE	Get the size of a control.
CONTROL GET LOC	Get the location of a control inside of its parent dialog.
CONTROL GET TEXT	Retrieve the text from a control, such as a Text box or Label, etc.
CONTROL HANDLE	Return a window handle for a given control.
CONTROL KILL	Remove a control from a dialog.
CONTROL SEND	Send a message to a control.
CONTROL SET FOCUS	Set the keyboard focus to a given control. If the control is a button, it receives keyboard focus. If the control is a text box, the caret is placed in the text box to allow the user to edit the text.
CONTROL SET FONT	Select a font to be used for a particular control.
CONTROL SET IMAGE	Change the image on an image button or image control. Also see CONTROL SET IMAGEX.
CONTROL SET SIZE	Change the size of a control.
CONTROL SET LOC	Change the location of a control within its parent dialog.
CONTROL SET TEXT	Place new text into a control. Any existing text in the control is replaced.
WINDOW GET ID	Returns the Control ID for a given control.
WINDOW GET PARENT	Returns the handle of a controls parent.

For a more comprehensive list of DDT statements and functions, See the Command Summary for DDT.

See Also

Dynamic Dialog Tools (DDT)

Creating a Dialog

Adding Controls to the Dialog