Class Documentation

Name:Image
Version:1.0
ID:ID_IMAGE
Status:Unspecified
Category:GUI
Date:June 2003
Author:Rocklyte Systems
Copyright:  Rocklyte Systems (c) 2000-2003. All rights reserved.
Short:  Draws images to drawable areas.



Description

The Image class is designed for object scripting and closely follows the general definition of the 'img' tag in HTML. The main difference that you will notice is that it sports a few extra effects, and you have complete control over the positioning of the image graphic.

Here is a DML based example for loading a picture file via an Image object:

  <image src="pictures:logos/athene.jpeg" x="25" y="50"/>

The Image class supports transparent colour management for file formats such as GIF and PNG, as well as images that are accompanied by an alpha channel. If an image utilises a transparent colour but the file format cannot declare it, you can tell the object what the mask colour is. This is set via the Mask field, e.g:

  <image src="icons:misc/paintcan.pcx" mask="128,0,0" width="32" height="32"/>

There are no restrictions on the data format of the picture file, but it must be supported by one of the Picture classes in the system. If for example the file format is JPEG, but the system does not have a JPEG Picture class installed, it will not be possible to load the file. To obtain a list of supported file formats, check the list of Picture classes in the Graphics category.

All pictures that are loaded via the Image class are cached into a shared memory pool. This means that if a particular image file is loaded multiple times, the data will be stored only once to save on memory and load times. Image files are automatically unloaded when their open-count reaches zero.

Actions

The Image class supports the following actions:

Hide  Hides an image from view.
ScrollToPoint  Scrolls an image within its allocated drawing space.
Show  Shows an image.

Structure

The Image object consists of the following public fields:

Align  This field allows you to align an image within its owner.
Flags  Special flags.
Frame  Determines the frame that an image will be applied to.
Frames  Determines a sequence of frames that an image may be drawn to.
Height  The height of an image is specified here.
ImageHeight  Defines an image's height in pixels.
ImageWidth  Defines an image's width in pixels.
Location  Identifies the location of the image graphic file (e.g. pcx, jpeg, gif).
Mask  Identifies the colour to use for masking an image (string format).
MaskRGB  Identifies the colour to use for masking an image (RGB format).
Opacity  Determines the level of translucency applied to an image.
PixelSize  Reflects the overall pixel size of the image at its widest point.
Tile  Set this field to TRUE to turn on image tiling (wallpaper).
Width  The width of an image's drawable area is specified here.
XCoord  Defines the horizontal position of an image.
XOffset  Defines the horizontal offset of an image.
YCoord  Defines the vertical position of an image.
YOffset  Defines the vertical offset of an image.
Field:Align
Short:This field allows you to align an image within its owner.
Type:LONG/FLAGS
Prefix:ALIGN
Status:Read/Write

If you would like to set an abstract position for an image, you can give it an alignment. Note that setting the alignment over-rides any settings in related coordinate fields. Valid alignment flags are as follows:

BOTTOM
CENTER/MIDDLE
LEFT
HORIZONTAL
RIGHT
TOP
VERTICAL


Field:Flags
Short:Special flags.
Type:LONG/FLAGS
Prefix:IMF
Status:Read/Write

Special flags that are available for the Image class are as follows:

FlagDescription
CENTERThis is a helper flag that provides an alternative to centering an image with the Align field.
ENLARGE  If the dimensions of the original picture are smaller than the destination drawable, the image will be stretched to fit. Enlargement is dynamic, so if the drawable changes in size then the size of the picture will be recalculated to fit.
MASKThis flag will be set automatically when the Mask or MaskRGB fields are written. You can turn off masking by switching the flag off.
SHRINKIf the dimensions of the original picture are larger than the destination drawable, the image will be stretched to fit. Shrinking is dynamic, so if the drawable changes in size then the size of the picture will be recalculated to fit.
TILEIf an image is to be tiled, you can set this flag as an alternative to setting the Tile field. You can turn off tiling by switching the flag off.
STRETCHThis flag conveniently combines the ENLARGE and SHRINK flags to ensure that the image always covers the dimensions of the destination drawable.

Field:Frame
Short:Determines the frame that an image will be applied to.
Type:LONG
Status:Read/Write

Setting the Frame field to any value other than zero will force the Image to be drawn only when the drawable's frame matches the specified value. For instance, if the drawable container has a Frame setting of 2, and the Image has a Frame of 1, then the Image graphic will not be drawn as the numbers do not match.


Field:Frames
Short:Determines a sequence of frames that an image may be drawn to.
Type:STRING
Status:Set

For long animation sequences you can set the Frames field to determine individual frames that an image should be drawn to. For instance, if a drawable has been assigned 20 animation frames and you want an image to appear in frames 5, 6, 7, 8, 17 and 19, you would use this frame specification:

   5-8,17,19

Individual frame sets are separated by any non-numeric character such as a comma, and ranges can be specified through the '-' character.

Setting the Frames field will override any setting that you may have previously set in the Frame field.


Field:Height
Short:The height of an image is specified here.
Type:DOUBLE/PERCENTAGE
Status:Get/Set

If an image graphic is to be limited to a specific drawable area, set this field to limit the clipping height. A percentage may be specified if the FD_PERCENT flag is used when setting the field.


Field:ImageHeight
Short:Defines an image's height in pixels.
Type:LONG
Status:Read/Init

The height of an image can be read and manipulated through this field. If you set the height to a specific value then the picture will be cropped if the height of the picture file exceeds it. However, if combined with the ENLARGE or SHRINK flags, the height of the image will be stretched to fit the given value.


Field:ImageWidth
Short:Defines an image's width in pixels.
Type:LONG
Status:Read/Init

The width of an image can be read and manipulated through this field. If you set the width to a specific value then the picture will be cropped if the width of the picture file exceeds it. However, if combined with the ENLARGE or SHRINK flags, the width of the image will be stretched to fit the given value.


Field:Location
Synonyms:Src
Short:Identifies the location of the image graphic file (e.g. pcx, jpeg, gif).
Type:STRING
Status:Read/Write

The location of the picture file that is to be used for the Image must be specified in this field. If the location is not specified then the initialisation process will fail. The file format must be recognised by at least one of the Picture classes loaded into the system.


Field:Mask
Short:Identifies the colour to use for masking an image (string format).
Type:STRING
Status:Write

If the Image source uses a masking colour to define transparent areas, you will need to set this or the MaskRGB field so that the Image object knows what the masking colour is. The mask must be specified in hexadecimal or separated-decimal format - for example a pure red mask would be defined as "#ff0000" or "255,0,0".


Field:MaskRGB
Short:Identifies the colour to use for masking an image (RGB format).
Type:*RGB
Status:Read/Write

If the Image source uses a masking colour to define transparent areas, you will need to set this or the Mask field so that the Image object knows what the masking colour is. You must pass a valid RGB structure to set the mask in this field - if you would rather use a colour string, set the Mask field instead.


Field:Opacity
Short:Determines the level of translucency applied to an image.
Type:FLOAT
Status:Get/Set

This field determines the translucency level of an image. The default setting is 100%, which means that the image will be solid. Any other value that you set here will alter the impact of an image over the destination drawable. High values will retain the boldness of the image, while low values can render it close to invisible.

Please note that the use of translucency will always have an impact on the time it normally takes to draw an image. The use of translucency also requires that the drawable area is buffered, as read access is required to perform the blending algorithm.


Field:PixelSize
Short:Reflects the overall pixel size of the image at its widest point.
Type:LONG
Status:Get

Field:Tile
Short:Set this field to TRUE to turn on image tiling (wallpaper).
Type:BOOLEAN
Status:Read/Write

If you want to tile the Image within its container (also known as the wallpaper effect), set this field to TRUE.


Field:Width
Short:The width of an image's drawable area is specified here.
Type:DOUBLE/PERCENTAGE
Status:Get/Set

If an image graphic is to be limited to a specific drawable area, set this field to limit the clipping width. A percentage may be specified if the FD_PERCENT flag is used when setting the field.


Field:XCoord
Short:Defines the horizontal position of an image.
Type:DOUBLE/PERCENTAGE
Status:Get/Set

The horizontal position of an image can be set to an absolute or relative coordinate by writing a value to the XCoord field. To set a relative/percentage based value, you must use the FD_PERCENT flag or the value will be interpreted as fixed. Negative values are permitted.


Field:XOffset
Short:Defines the horizontal offset of an image.
Type:DOUBLE/PERCENTAGE
Status:Get/Set

The XOffset has a dual purpose depending on whether or not it is set in conjunction with an X coordinate or a Width based field.

If set in conjunction with an X coordinate then the image will be drawn from that X coordinate up to the width of the container, minus the value given in the XOffset. This means that the width of the image is dynamically calculated in relation to the width of the container.

If the XOffset field is set in conjunction with a fixed or relative width then the image will be drawn at an X coordinate calculated from the formula "XCoord = ContainerWidth - ImageWidth - XOffset".


Field:YCoord
Short:Defines the vertical position of an image.
Type:DOUBLE/PERCENTAGE
Status:Get/Set

The vertical position of an image can be set to an absolute or relative coordinate by writing a value to the YCoord field. To set a relative/percentage based value, you must use the FD_PERCENT flag or the value will be interpreted as fixed. Negative values are permitted.


Field:YOffset
Short:Defines the vertical offset of an image.
Type:FLOAT
Status:Get/Set

The YOffset has a dual purpose depending on whether or not it is set in conjunction with a Y coordinate or a Height based field.

If set in conjunction with a Y coordinate then the image will be drawn from that Y coordinate up to the height of the container, minus the value given in the YOffset. This means that the height of the Image is dynamically calculated in relation to the height of the container.

If the YOffset field is set in conjunction with a fixed or relative height then the image will be drawn at a Y coordinate calculated from the formula "YCoord = ContainerHeight - ImageHeight - YOffset".