DEFINE IMAGE statement

(Windows only; Graphical interfaces only)

Defines an image widget in a graphical interface that is created at compile time for use within a single procedure or class. An image widget is a container for an operating system image file and can be displayed in a form or used as a form background.

Note: Does not apply to SpeedScript programming.

Syntax

DEFINE [ PRIVATE ] IMAGE `image-name` { `image-phrase` \| LIKE `image` \| `size-phrase` } [ BGCOLOR `expression` ] [ FGCOLOR `expression` ] [ CONVERT-3D-COLORS ] [ TOOLTIP `tooltip` ] [ STRETCH-TO-FIT [ RETAIN-SHAPE ] ] [ TRANSPARENT ]

DEFINE [ PRIVATE ] IMAGE image-name 
  { image-phrase | LIKE image | size-phrase } 
  [ BGCOLOR expression ] 
  [ FGCOLOR expression ] 
  [ CONVERT-3D-COLORS ] 
  [ TOOLTIP tooltip ] 
  [ STRETCH-TO-FIT [ RETAIN-SHAPE ] ] [ TRANSPARENT ]

[ PRIVATE ] IMAGE image-name

Defines and identifies an image widget as a class-scoped object. A class-scoped handle-based object is not a member of a class, but provides a resource that is privately available to the class definition similar to a non-shared data element in a procedure definition. The option to specify the PRIVATE access mode is provided for readability. You cannot specify PRIVATE when defining an image widget as a data element in a method or procedure.

Note: This option is applicable only when defining a class-scoped image widget in a class definition (.cls) file.

IMAGE image-name

Defines and identifies an image widget for access only within the current procedure, class, or method of a class.

image-phrase

Specifies the file where the image is stored and the portion of the image to read. This is the syntax for image-phrase:


FILE `name` [ { IMAGE-SIZE \| IMAGE-SIZE-CHARS \| IMAGE-SIZE-PIXELS } `width` BY `height` ] [ FROM { { X `n` Y `n` } \| { ROW `n` COLUMN `n` } } ]

For more information on this syntax, see the Image phrase reference entry.

You must specify either the LIKE option, an Image phrase or a Size phrase within the DEFINE IMAGE statement, and you may specify any two or all three.

LIKE image

Specifies a previously defined image from which this image inherits attributes. You can override specific attributes by specifying other options of the DEFINE IMAGE statement.

You must specify either the LIKE option, an Image phrase or a Size phrase within the DEFINE IMAGE statement, and you may specify any two or all three.

size-phrase

Specifies the outside dimensions of the image widget. This is the syntax for size-phrase:


{ SIZE \| SIZE-CHARS \| SIZE-PIXELS } `width` BY `height`

If you specify SIZE or SIZE-CHARS, the units are characters; if you specify SIZE-PIXELS, the units are pixels. If you use character units, the values width and height must be decimal constants; for pixel units, they must be integer constants. For more information, see the SIZE phrase reference entry.

You must specify either the LIKE option, an Image phrase or a Size phrase within the DEFINE IMAGE statement, and you may specify any two or all three.

BGCOLOR expression

Has no effect; supported only for backward compatibility.

FGCOLOR expression

Has no effect; supported only for backward compatibility.

CONVERT-3D-COLORS

Specifies that the colors associated with an image will be converted to the system 3D colors when an image is loaded. Table 29 describes the color conversion process.

Table 29: 3D-color conversions for images
If the color is . . .	And the original Red-Green-Blue (RGB) color value is . . .	Then the new converted system color is . . .
White	(255, 255, 255)	System button highlight color
Light Gray	(192, 192, 192)	System button face color
Dark Gray	(128, 128, 128)	System button shadow color
Black	(0, 0, 0)	System button text color

During a session, if Windows notifies the AVM that the system colors are changed, all images that have this option are reloaded and converted to the new system colors.

TOOLTIP tooltip

Allows you to define a help text message for an image widget. The AVM automatically displays this text when the user pauses the mouse pointer over the image widget.

You can add or change the TOOLTIP option at any time. If TOOLTIP is set to "" or the Unknown value (?), then the ToolTip is removed from the button. No ToolTip is the default. ToolTips are supported in Windows only.

STRETCH-TO-FIT

Forces the image to expand or contract to fit within the image widget’s boundaries.

This option has no effect if an icon is displayed on the image widget.

RETAIN-SHAPE

Indicates that the image should retain its aspect ratio (expand or contract equally in both dimensions). This may leave some uncovered space at the bottom or right of the image widget.

RETAIN-SHAPE is ignored if STRETCH-TO-FIT is FALSE or if an icon is displayed on the image widget.

TRANSPARENT

Indicates that the background color of the image is transparent. The background color is determined by the color of the pixel in the lower left corner of the image.

The TRANSPARENT option overrides the CONVERT-3D-COLORS option; if both are set, CONVERT-3D-COLORS is ignored.

This option has no effect if an icon is displayed on the image widget.

Example

This procedure defines an image widget named trashcan, and loads into the widget a series of operating system image files that create an animation of a fire burning in a trash can. The user begins the animation by choosing the Animate button. This procedure serves as an illustration only. It depends on the existence of image filenames ANI01, ANI02. ... ANI14 , which are not provided.

r-image.p
DEFINE VARIABLE repeat_loop AS INTEGER NO-UNDO. DEFINE VARIABLE animation_loop AS INTEGER NO-UNDO.. DEFINE VARIABLE lok AS LOGICAL NO-UNDO.. DEFINE BUTTON animate LABEL "Animate". DEFINE IMAGE trashcan FILE "ANI01.BMP". DISPLAY animate trashcan WITH FRAME y TITLE " Animation Sample ". ON CHOOSE OF animate IN FRAME y DO: /* Begin Animation */ DO repeat_loop = 1 TO 5: DO animation_loop = 1 TO 14: lok = trashcan:LOAD-IMAGE("ANI" + STRING(animation_loop,"99")) IN FRAME y. END. END. END. UPDATE animate WITH FRAME y.

r-image.p

DEFINE VARIABLE repeat_loop    AS INTEGER NO-UNDO. 
DEFINE VARIABLE animation_loop AS INTEGER NO-UNDO.. 
DEFINE VARIABLE lok            AS LOGICAL NO-UNDO.. 
DEFINE BUTTON animate LABEL "Animate". 
DEFINE IMAGE trashcan FILE "ANI01.BMP". 
DISPLAY animate trashcan WITH FRAME y TITLE "**  Animation Sample  **". 
ON CHOOSE OF animate IN FRAME y DO: 
  /* Begin Animation */ 
  DO repeat_loop = 1 TO 5: 
    DO animation_loop = 1 TO 14: 
      lok = trashcan:LOAD-IMAGE("ANI" + STRING(animation_loop,"99"))  
        IN FRAME y. 
    END. 
  END. 
END. 
UPDATE animate WITH FRAME y.

Notes

In Windows, if the file has no extension, the AVM by default looks for image files with either a .bmp or .ico extension.

To create the compile-time defined image you are defining, you must define a compile-time defined frame that contains the image. Each frame you define that contains the same image creates an additional instance of that image. The handle for a compile-time defined image is not available until the image is created.

The AVM only performs the color conversion process on bitmaps (.bmp files) that contain 256 or fewer colors. However, you might consider using 16-color bitmaps because only the first sixteen entries in the bitmap’s color table will be converted.

Icon colors (.ico files) are not converted, even if CONVERT-3D-COLORS is TRUE.

See Image phrase for the list of supported image file formats.

You can specify an application-defined widget ID for a compile-time defined image using the form-item phrase in either the FORM statement or the DEFINE FRAME statement. See the FORM statement and DEFINE FRAME statement reference entries for more information.