Class Documentation
Image |
1.0 |
ID_IMAGE |
Unspecified |
GUI |
May 2001 |
Rocklyte Systems |
Rocklyte Systems (c) 2000-2001. All rights reserved. |
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:
MASK | This flag will be set automatically when the Mask or MaskRGB fields are written. You can turn off masking by switching the flag off. |
TILE | If 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. |
FADE | When 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. |
SHRINK | If 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".
|
|