IMAGE item type

Syntax 1: Defining a form field image

IMAGE item-tag = field-name [ , attribute-list ] ;

Syntax 2: Defining a static image

IMAGE item-tag: item-name [ , attribute-list ] ;

item-tag is an identifier that defines the name of the item tag in the layout section.
field-name identifies the name of the screen record field.
item-name identifies the form item.
attribute-list defines the aspect and behavior of the form item.

Attributes

AUTOSCALE, COMMENT, HEIGHT, HIDDEN, STYLE, STRETCH, TAG, WIDTH.

Static image only: IMAGE.

Image field only: COLOR, COLOR WHERE, FONTPITCH, JUSTIFY, SIZEPOLICY, SAMPLE.

Table column only: UNSORTABLE, UNSIZABLE, UNHIDABLE, UNMOVABLE, TITLE.

Usage

The IMAGE item type defines an area where a picture file can be displayed.

An IMAGE form item can be defined as a form field image or as a static image.

Form field image

This type of image item must be used to display values that change often during program execution, for example if the image is stored in the database. The picture resource is defined by the value of the field. This value can be changed from the program by using the DISPLAY BY NAME / DISPLAY TO instruction or just by changing the value of the program variable bound to the image field, when using the UNBUFFERED mode in an interactive instruction.

When using a string variable containing a file name or file path, the values of an IMAGE field defining the picture resource follow the same rules as the IMAGE attribute of static images (see also FGLIMAGEPATH). However, images displayed by program to image fields are considered as valid files to be transferred to the clients without risk and do not follow the FGLIMAGEPATH security restrictions. Images are searched according to the path list defined in FGLIMAGEPATH.

When located in a file, the content of a BYTE variable can be automatically displayed to an IMAGE in field, by using DISPLAY BY NAME / DISPLAY TO or when the BYTE variable is controlled by a dialog instruction.

Static image

This type of image item must be used to display an image that does not change often, such as background pictures or logos. The resource of the image is defined by the IMAGE attribute; the item is not a form field: This kind of item is not affected by instructions such as CLEAR FORM or the DISPLAY TO instruction. The image resource can be changed from the program by using the API provided to manipulate the user interface. For more details about supported image resources, read the section dedicated to the IMAGE attribute (see also FGLIMAGEPATH environment variable).

Controlling the image widget

The STRETCH attribute can be used to define how the image widget size must change when the parent container is re-sized. Values can be NONE, X, Y or BOTH. Default value is NONE for IMAGE fields.

The AUTOSCALE attribute can be set to indicate if the image must be scaled to the available space defined by the width and height of the form item.

The SIZEPOLICY and AUTOSCALE attributes can be used together to control how the size of the image widget is defined:

When SIZEPOLICY is INITIAL and AUTOSCALE is not used, the size of the widget will be defined by the first picture displayed in the form element, and that size will not change if other pictures with different sizes are displayed in the widget.
When SIZEPOLICY is DYNAMIC, the size of the widget will be automatically adapted to the size of the pictures displayed in the image form item. With this option, the AUTOSCALE attribute makes no sense and will have no effect.
If SIZEPOLICY attribute is set to FIXED, the size of the widget will be defined by the form specification file, either by the size of the item-tag in the layout, or by the WIDTH and HEIGHT attributes. With a fixed image widget size, if AUTOSCALE is not used, scrollbars may appear if the picture is greater than the widget.

The size of an image widget can also be specified in the WIDTH and HEIGHT attributes, but this will only have an effect if the SIZEPOLICY attribute is set to FIXED. If the WIDTH/HEIGHT attributes are not used, the size of the image widget defaults to the relative width and height defined by the item-tag in the form layout section. The size specified by WIDTH and HEIGHT defines the size of the image widget. On some platforms, the image widgets automatically add a border to the source picture. Therefore, to avoid automatic scrollbars, you might need to increase the size of the image form item if a border is used. For example, if your image source has a size of 500x500 pixels and the widget displays a border with as size of 1 pixel, you will have to set WIDTH and HEIGHT to 502 pixels, otherwise either scrollbars will appear, or the image will shrink if AUTOSCALE is used. Alternatively, you can avoid the image border with a presentation style attribute.