CONTROL ADD LINE statement

Purpose | Add a line control to a dialog. A line control may also be a rectangle (empty or filled).
Syntax | CONTROL ADD LINE, hDlg, id&, txt$, x, y, xx, yy [, [style&] [, [exstyle&]]] [[,] CALL callback]
hDlg | Handle of the dialog in which the line will be created. The dialog will become the parent of the control.
id& | Unique identifier for the control in the range 1 to 65535, frequently specified with numeric equates for clarity of the code. For example, the equate %SeparatorLeft is more informative than a literal value such as 497. If you will not be changing the size or location of a line control after it is created, you may use -1 for the id. Otherwise, best practice suggests identifiers should start at 100 to avoid conflict with any of the standard predefined identifiers.
txt$ | Text to associate with the line control. A line control does not display text, so it is possible to use this string for your own purposes; however, an ampersand (&) may be included in txt$ to specify a hot-key. See the Remarks section below.
x, y | Integer expressions, variables, or numeric literal values, specifying the location of the control inside the dialog client area. x is the horizontal position, and y is the vertical position. 0,0 refers to the upper left corner of the dialog box client area. Coordinates are specified in the same terms (pixels or dialog units) as the parent dialog.
xx | Integral expression, variable, or numeric literal value, specifying the width of the control. The width is given in the same terms (pixels or dialog units) as the parent dialog. The most common value used in the Microsoft Dialog Editor and Visual Studio is 40 dialog units.
yy | Integral expression, variable, or numeric literal value, specifying the height of the control. The height is given in the same terms (pixels or dialog units) as the parent dialog. The most common value used in the Microsoft Dialog Editor and Visual Studio is 1 dialog unit.

style&

Primary style of the line control. The default line style is %SS_ETCHEDFRAME. The default style is used if both the primary and extended style parameters are omitted from the statement. For example:

CONTROL ADD LINE, hDlg, id&, "", 100, 100, 150, 1, , , CALL LineCallback() ' Use default styles

Custom style values replace the default values. That is, they are not additional to the default style values - your code must specify all necessary primary and extended style parameters.

The primary line style value can be a combination of any values below, combined together with the OR operator to form a bitmask:

%SS_BLACKFRAME | Draw a box with the frame drawn in the same color as the window frames. This color is black in the default Windows color scheme.
%SS_BLACKRECT | Draw a rectangle filled with the current window frame color. This color is black in the default Windows color scheme.
%SS_ETCHEDFRAME | Draw the frame of the control using an etched edge style. (default)
%SS_ETCHEDHORZ | Draw the horizontal edges of the control using an etched edge style.
%SS_ETCHEDVERT | Draw the vertical edges of the control using an etched edge style.
%SS_GRAYFRAME | Draw a box with the frame drawn with the same color as the screen background (desktop). This color is gray in the default Windows color scheme.
%SS_GRAYRECT | Draw a rectangle filled with the current screen background color. This color is gray in the default Windows color scheme.
%SS_NOPREFIX | Prevent interpretation of any ampersand (&) characters in the control's text as a control accelerator prefix characters. These normally are displayed with the ampersand removed and the next character in the string underscored.
%SS_NOTIFY | Sends %STN_CLICKED and %STN_DBLCLK notification messages to the line controls Callback Function when the user clicks or double-clicks the line control.
%SS_RIGHTJUST | Force the bottom-right corner of the control to remain fixed when the control is resized. Only the top and left sides are adjusted to accommodate a new image.
%SS_WHITEFRAME | Draw a box with the frame drawn with the same color as the window backgrounds. This color is white in the default Windows color scheme.
%SS_WHITERECT | Draw a rectangle filled with the current window background color. This color is white in the default Windows color scheme.

exstyle&

Extended style of the line control. The default extended line style comprises %WS_EX_LEFT. The default extended style is used if both the primary and extended parameters are omitted from the CONTROL ADD LINE statement, in the same manner as style& above.

The extended line control style value can be a combination of any values below, combined together with the OR operator to form a bitmask:

%WS_EX_CLIENTEDGE | Apply a sunken edge border to the control.
%WS_EX_LEFT | The control has generic "left-aligned" properties. (default)
%WS_EX_RIGHT | The control has generic "right-aligned" properties. This style has an effect only if the shell language is Hebrew, Arabic, or another language that supports reading order alignment; otherwise, the style is ignored.
%WS_EX_STATICEDGE | Apply a three-dimensional border style to the control (intended to be used for items that do not accept user input).
%WS_EX_TRANSPARENT | Controls/windows beneath the control are drawn before the control is drawn. The control is deemed transparent because elements behind the control have already been painted - the control itself is not drawn differently. True transparency is achieved by using Regions - see MSDN for more information.
%WS_EX_WINDOWEDGE | Apply a raised edge border to the control.

callback

Optional name of a Callback Function that receives all %WM_COMMAND and %WM_NOTIFY messages for the control. See the #MESSAGES metastatement to choose which messages will be received. If a callback for the control is not designated, you must create a dialog Callback Function to process messages from your control. The Callback Function will only receive messages if the %SS_NOTIFY style is used.

If the Callback Function processes a message, it should return TRUE (non-zero) to prevent the message being passed unnecessarily to the dialog callback (if one exists). The dialog callback should also return TRUE if the notification message is processed by that Callback Function. Otherwise, the DDT engine processes unhandled messages.

Remarks

If the ampersand (&) character appears in the txt$ parameter, the letter that follows will be displayed underscored. This adds a control accelerator (hot-key) to enable the user to directly "click" the control that immediately follows in the Tab-Order after the Line control, simply by pressing and holding the ALT key while pressing the specified hot-key. For example, "&Test Suite " makes ALT+T the hot-key.

A line control will only send messages to a callback if the %SS_NOTIFY style is used. The following notifications are sent to the Callback Function:

%STN_CLICKED | Sent when the user clicks a line control (unless the control has been disabled).
%STN_DBLCLK | Sent when the user double-clicks a line control (unless the control has been disabled).
%STN_DISABLE | Sent when a line control has been disabled.
%STN_ENABLE | Sent when a line control has been enabled.

When a Callback Function receives a %WM_COMMAND message, it should explicitly test the value of CB.CTL and CB.CTLMSG to guarantee it is responding appropriately to the notification message.

See also | Dynamic Dialog Tools, CONTROL HANDLE, CONTROL SEND