Special Properties

BITMAP-HANDLE (numeric)

This property indicates the bitmap to display. The value must correspond to the bitmap handle returned by the WBITMAP-LOAD option of W$BITMAP. If this value is omitted, the control uses the bitmap most recently loaded by W$BITMAP.

BITMAP-NUMBER (numeric)

Use this property to display an image from a bitmap strip. A bitmap strip is a series of images of equal width that are strung together horizontally in a single bitmap file. The value of this property is the number of the image in the strip, beginning on the left with 1. You can identify a particular image if you specify the width of the logical image with the SIZE phrase and the number of the image with the BITMAP-NUMBER property. The default value for this property is 1.

BITMAP-NUMBER is updated by the runtime to reflect the current image shown when an animated bitmap is displayed. You can retrieve this value with the INQUIRE verb.

BITMAP-RAW-HEIGHT (numeric)

This property may not be invoked before the property BITMAP-HANDLE has been set to a valid bitmap loaded with WBITMAP-LOAD. The value returned is the image height in device-independent pixels.

The value is read only, any attempt to MODIFY will fail. The receiving variable should take into account a possible image size of 5 digits (PIC 9(5)). The receiving datatype typically is an integer, but any numeric value is accepted.

BITMAP-RAW-WIDTH

This property may not be invoked before the property BITMAP-HANDLE has been set to a valid bitmap loaded with WBITMAP-LOAD. The value returned is the image width in device-independent pixels. The value is read only, any attempt to MODIFY will fail. The receiving variable should take into account a possible image size of 5 digits (PIC 9(5)). The receiving datatype typically is an integer, but any numeric value is accepted.

BITMAP-SCALE

This property is used to enable resizing of bitmaps. If not set, or set to its default value of 0, the bitmap cannot be resized. This means if the size of the interior of the image is smaller than the image, the image is cut to fit. If the interior is larger than the image size, the image size does not increase to fill the interior.

If set to 1, the bitmap will scale up or down to fit the interior given, and no cutting of the bitmap occurs.

When setting this property, you must set it prior to setting the property BITMAP-HANDLE to have any effect. For example:

SCREEN      SECTION.
01  TEMPLATE-SCREEN.
  03      bmp              BITMAP
          BITMAP-SCALE     1 
          BITMAP-HANDLE    GT-BITMAP
          SIZE             100 pixels
          LINES            200 pixels
          LINE             1
          placeStateCOL              1.

With this new property, if you perform a MODIFY statement such as

MODIFY bmp SIZE = 200 LINES = 400.

the bitmap is resized accordingly and automatically. Note that you are not limited to specifying pixel units; you may specify any legal display unit.

Important:

To keep the image from becoming blurred in the resizing process, do not scale up or down in just one direction. For example, if you have an image that is 200x300, increase or decrease the width and height, not just one or the other.

If you enter an invalid resizing value for either the width or height, the invalid entry will be ignored and the previous width or height value will be used.

Resizing images is based on the image size, not the interior size. With multiple resizes, you always will be resizing based on the original image size, not the last resizing that you performed. This is done to maintain the best image quality, as resizing a resized image can degrade image quality.

Currently, only 24-bit colors are supported. If your bitmap is not 24 bit, you can use Microsoft paint to store the bitmap as 24 bit.

We recommend that jpeg files be used whenever possible, as they appear to give the best resizing capability.

BITMAP-START and BITMAP-END (both numeric)

These properties are used when you want to animate a bitmap. Like BITMAP-NUMBER, the value of BITMAP-START is the number of a particular image in a bitmap strip, specifically, the first one to use during animation. Animation runs sequentially in the strip from BITMAP-START to BITMAP-END, looping back to BITMAP-START. If BITMAP-START is not set smaller than BITMAP-END, the control sets BITMAP-START equal to BITMAP-END. The default value for each property is 1.

BITMAP-TIMER (numeric)

This property is used for bitmap animation. Its value is the amount of time each bitmap image is displayed during animation, in hundredths of seconds. When this property is set to 0, the bitmap is not animated. Setting the property to a negative value has an undefined effect.

TRANSPARENT-COLOR (numeric)

Restriction: This property is supported for BMP and PNG image formats only; it is not supported for JPG or GIF formats.

Use this special property to designate transparent regions in a bitmap. This is done by reserving one of the colors in the bitmap as the transparent color. Any points in the bitmap that contain this color will not be displayed when the bitmap is drawn, allowing the background to show through. This can be useful if you want to integrate a logo onto a screen in a way that accommodates the user's choice of desktop colors.

To designate a transparent region, choose one color in the bitmap to be the transparent color. Then, set the TRANSPARENT-COLOR property to the RGB color value of this color. The RGB color value is computed by the following formula:

   (red * 65536) + (green * 256) + blue

where red, green, and blue are values between 0 and 255. You can use a hexadecimal numeric literal to express this value, because each component of the color occupies one byte in a binary value. For example, the following literal expresses an orange color with red at 255, green at 128, and blue at 0:

78  orange    value x#FF8000.

The first byte (x 'FF') is the red value, the second byte (x'80') is the green value, and the last byte (x'00') is the blue value.

If you set TRANSPARENT-COLOR to -1 (the default), the transparency property is turned off and all colors display normally.

Setting TRANSPARENT-COLOR to the hex value x#1000000 will automatically specify the pixel in the upper-left corner of a bitmap as the transparent color. (This is the level 78 constant BM-CORNER-COLOR in acugui.def.) You don't need to know the exact color of that pixel to use this value.

In order to avoid flashing, the runtime will not update the region under a transparent bitmap once it is in place. One effect of this is that if you animate a bitmap with transparent regions, you must ensure that those regions are the same in each frame of the animation, or the image will blur.