CONTROL ADD IMAGE statement

Purpose

Add a (non-resizing) image control to a dialog. This is typically used to display a bitmap or icon stored in a resource file.

Syntax

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

hDlg

Handle of the dialog in which the image 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 %WizardBMP is more informative than a literal value such as 497. If you will not be changing the image in the control after it is created, you may use -1 for the id&; however, best practice suggests identifiers should start at 100 to avoid conflict with any of the standard predefined identifiers.

image$

Name of the bitmap or icon in the resource file. If the image resource uses an integral identifier, image$ should begin with a Number symbol (#) followed by the identifier in an ASCII format, e.g., "#998" or FORMAT$(rcid&, "\##"). Otherwise, use the text identifier name for the image.

x, y

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

Integral 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. This value is ignored unless the %SS_CENTERIMAGE style is specified.

Integral 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. This value is ignored unless the %SS_CENTERIMAGE style is specified.

style&

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.

In addition, the initial image format may be specified explicitly as either %SS_ICON or %SS_BITMAP, or the image format may be omitted completely.

If the image format is specified, it must match the format of the file specified in image$. However, if the image format is not specified, PowerBASIC will examine the file to determine the correct image format to use.

%SS_BITMAP	Display only bitmap images. Also see %SS_ICON. (persistent)
%SS_CENTERIMAGE	If the image is smaller than the label, fill the rest of the label with the color of the pixel in the top left corner of the image.
%SS_ICON	Display only icon images. Also see %SS_ICON. (persistent)
%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 image control.
%WS_GROUP	Define the start of a group of controls. The first control in each group should also use %WS_TABSTOP style. The next %WS_GROUP control in the tab order defines the end of this group and the start of a new group. Groups configured this way permit the arrow keys to shift focus between the controls within the group, and focus can jump from group to group with the usual TAB and SHIFT+TAB keys. Both tab stops and groups are permitted to wrap from the end of the tab order back to the start.

exstyle&

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

The extended image 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.
%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.

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.

In general, when the control 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

The bitmap or icon used in the image is not resized to fit the control. If your control is 64 dialog units wide and your icon or bitmap is only 32, half of the image will be blank. For best results, icons should be 32x32 pixels.

Once an image control has been created, the images it displays can be changed with the CONTROL SET IMAGE statement, but only if the images are of the same format as the original. For example, if an image control was initially created showing a bitmap file, all subsequent image changes must also be bitmap images. However, if the image format must be changed at run-time, for example, because icons are to be displayed instead of bitmaps, there are a couple of options. For example, the application could use separate controls for each image format, or the existing control could be destroyed, and a new control created with an image of the opposite format.

An image 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 the following values:

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