Class Documentation
Image |
1.0 |
ID_IMAGE |
Unspecified |
GUI |
June 2003 |
Rocklyte Systems |
Rocklyte Systems (c) 2000-2003. 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"/>
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:
CENTER | This 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. |
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. |
SHRINK | If 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. |
TILE | If 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. |
STRETCH | This 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".
|
|