CONTROL ADD TAB statement

Purpose

Add a Tab Control to a dialog. A Tab Control is analogous to the dividers in a notebook. It displays one particular page, selecting it from multiple pages, when the user chooses the corresponding tab.

Syntax

CONTROL ADD TAB, hDlg, id&, txt$, x, y, xx, yy [, [style&] [, [exstyle&]]] [[,] CALL callback]

hDlg

Handle of the dialog in which the Tab Control 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 %PickList is more informative than a literal value such as 497. Best practice suggests identifiers should start at 100 to avoid conflict with any of the standard predefined identifiers.

txt$

Text to associate with the Tab Control. A Tab Control does not display this text, so it is common to set this value to a null, empty string literal ("").

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,yy

Integer expressions, variable, or numeric literal values, specifying the width and height of the control. xx is the width and yy is the height, given in the same terms (pixels or dialog units) as the parent dialog.

style&

Primary style of the Tab control. The default Tab style is %WS_CHILD and %WS_TABSTOP. This default style is used if both the primary and extended style parameters are omitted from the statement, as in the following example:

CONTROL ADD TAB, hDlg, id&, "",90,90,200,90, , , CALL PBCallback()

If you include explicit style values, they replace the default values. That is, they are not added to the default styles values - your code must specify all necessary primary and extended style parameters.

The primary style value can be a combination of the standard window values, and the values specific to a Tab Control (below), which are combined together with the OR operator to form a bitmask:

%TCS_BOTTOM	Tabs are placed at the bottom
%TCS_RIGHT	Tabs are placed at the right side
%TCS_FORCEICONLEFT	Icons are forced to the left
%TCS_FORCELABELLEFT	Labels are forced to the left
%TCS_VERTICAL	Tabs are placed vertically.
%TCS_SINGLELINE	Displays one row of tabs
%TCS_RIGHTJUSTIFY	Tabs fill the entire width of the control
%TCS_FIXEDWIDTH	All tabs are the same size
%TCS_RAGGEDRIGHT	Tabs are not stretched
%TCS_FOCUSONBUTTONDOWN	Tabs receive the focus when clicked
%TCS_OWNERDRAWFIXED	Parent window is responsible for drawing tabs
%TCS_TOOLTIPS	A Tooltip control is associated with the control
%TCS_FOCUSNEVER	Tab never receives the focus

exstyle&

Extended style of the control. The value can be a combination of the 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_STATICEDGE	Apply a three-dimensional border style to the control (intended to be used for items that do not accept user input).
%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.

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

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