CONTROL ADD GRAPHIC statement

Purpose

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

Syntax

CONTROL ADD GRAPHIC, hDlg, ID, Txt$, x, y, nWide, nHigh [,style] [,exstyle] [,CALL CallBack]

hDlg

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

A unique numeric identifier for this control which is specified by the programmer. It must be an integral value in the range of 1 to 65535. This ID is usually specified with a numeric equate for clarity of the code. For example, the equate %IDC_GRAPHIC1 is more informative than a literal value such as 497. PowerBASIC recommends that identifier values should start at 100 to avoid conflict with any of the standard predefined identifiers.

Txt$

Text to associate with the Graphic control. A Graphic control does not display this text, so it is common to set this value to a null, empty string literal ("" or $NUL).

x, y

Integral expressions which specify the location of the control within 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. Coordinates are specified in the same terms (pixels or dialog units) as the parent dialog.

nWide, nHigh

Integral expressions which specify the overall width and height of the image area. If you choose a style which includes a border, the client area will be slightly smaller, in order to accommodate it. You use GRAPHIC GET CLIENT to determine the exact client size available to you. The width and height are 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 would normally use GRAPHIC ATTACH to select it as the target of subsequent GRAPHIC statements. However, if there is no selected graphic target at the time of creation, the new Graphic Control is automatically attached and selected.

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.