DEFINE IMAGE statement

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.

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 ]

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.

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

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}}]

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.

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

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

Table 30. 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.

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.

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.

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.

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.

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.

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.

DEFINE IMAGE statement

Syntax

Example

Notes

See also