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).
| 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

Modal vs. Modeless

Control Styles

Callbacks

Dialog Styles

Menus