Class Documentation

Name:Image
Version:1.0
ID:ID_IMAGE
Status:Unspecified
Category:GUI
Date:May 2001
Author:Rocklyte Systems
Copyright:  Rocklyte Systems (c) 2000-2001. 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"/>

If the picture file utilises a transparent colour for masking purposes, you will need to tell the Image 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.

Structure

The Image object consists of the following public fields:

Align  This field allows you to align the Image within its container.
Flags  Special flags.
Frame  Determines the frame that the Image will be applied to.
Height  Defines the Image's height in pixels.
Location  Identifies the location of the image graphic file (e.g. pcx, jpeg, gif).
Mask  Identifies the colour to use for masking the image (string format).
MaskRGB  Identifies the colour to use for masking the image (RGB format).
Tile  Set this field to TRUE to turn on image tiling (wallpaper).
Width  Defines the Image's width in pixels.
XCoord  Defines the horizontal position of the Image.
XOffset  Defines the horizontal offset of the Image.
YCoord  Defines the vertical position of the Image.
YOffset  Defines the vertical offset of the Image.
Field:Align
Short:This field allows you to align the Image within its container.
Type:LONG/FLAGS
Prefix:ALIGN_
Status:Read/Write

If you would like to set an abstract position for the 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
MASKThis flag will be set automatically when the Mask or MaskRGB fields are written. You can turn off masking by switching the flag off.
TILEIf the 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.
FADEWhen this flag is set, the edges of the Image will be faded into the container's background. Note that the drawing speed will be a little slower due to the extra computation required.
ENLARGE  If the width of the picture file is smaller than the value specified in the Width field, the Image will be stretched to fit the given width.
SHRINKIf the width of the picture file is larger than the value specified in the Width field, the Image will be shrunk to fit the given width.

 

Field:Frame
Short:Determines the frame that the 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:Height
Short:Defines the Image's height in pixels.
Type:FLOAT
Status:Read/Write

The height of the 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: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 the 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 the 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: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:Defines the Image's width in pixels.
Type:FLOAT
Status:Read/Write

The width of the 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:XCoord
Short:Defines the horizontal position of the Image.
Type:FLOAT
Status:Read/Write

The horizontal position of the Image can be set through this field.

 

Field:XOffset
Short:Defines the horizontal offset of the Image.
Type:FLOAT
Status:Write

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 the Image.
Type:FLOAT
Status:Read/Write

The vertical position of the Image can be set through this field.

 

Field:YOffset
Short:Defines the vertical offset of the Image.
Type:FLOAT
Status:Write

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