CONTROL ADD GRAPHIC statement

Purpose

Add a static graphic control to a dialog for pictures, text, etc.

Syntax

CONTROL ADD GRAPHIC, hDlg, id&, "", x&, y&, wide&, high&[, [style&] [, [exstyle&]]] [[,] CALL callback]

hDlg

Handle of the dialog in which the graphic control will be created. The dialog will become the parent of the control.

id&

Unique identifier for the image in the range 1 to 65535, frequently specified with numeric equates for clarity of the code. For example, the equate %IDC_GRAPHIC1 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.

This string parameter is not currently used with graphic controls, but is reserved for future implementation. Any data placed at this position is ignored.

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.

wide&

Integer expression, variable, or numeric literal value, specifying the width of the image. The width is given in the same terms (pixels or dialog units) as the parent dialog.

high&

Integer expression, variable, or numeric literal value, specifying the height of the image. The height is given in the same terms (pixels or dialog units) as the parent dialog.

style&

Optional primary style of the image control. This value can be a combination of the values below, combined together with the OR operator to form a bitmask. If style& is omitted, the default combination is %WS_CHILD OR %WS_VISIBLE OR %SS_OWNERDRAW.

%SS_NOTIFY	Send %STN_CLICKED and %STN_DBLCLK notification messages to the Callback Function when the user clicks or double-clicks the control.
%SS_SUNKEN	Draw a half-sunken border around the graphic control.
%WS_BORDER	Add a thin line border around the graphic control.
%WS_DLGFRAME	Create a graphic control that has a border of the style typically used with dialog boxes.

exstyle&

Optional extended style of the graphic control. This value can be a combination of the values below, combined together with the OR operator to form a bitmask. If exstyle& is omitted, there is no default extended style.

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

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

A graphic control is typically used with graphic statements to draw graphs, pictures, text, etc. After you create a graphic control, you must use GRAPHIC ATTACH to choose it for use with other statements and functions.

A graphic control will only send notification messages to a callback if the %SS_NOTIFY style is used. Notification messages are sent to the callback function with CB.MSG = %WM_COMMAND, CB.CTL holding the ID (id&) of the control, and CB.CTLMSG holding one of the following values:

%STN_CLICKED	Sent when the user clicks a mouse button on the graphic control (unless the image control has been disabled).
%STN_DBLCLK	Sent when the user double-clicks on a graphic control (unless the control has been disabled).
%STN_DISABLE	Sent when a graphic control has been disabled.
%STN_ENABLE	Sent when a graphic 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.

All PowerBASIC graphical displays are persistent -- they will be automatically redrawn when altered or temporarily covered by another window. Due to the nature of a graphic control and its contents, it may not be resized. If a new size is needed, the control should be destroyed and recreated.