Class Documentation
| Icon |
| 1.0 |
| ID_ICON |
| Beta |
| GUI |
| January 2005 |
| Rocklyte Systems |
| Rocklyte Systems, 2005. All rights reserved. |
| The Icon class is used to create icons. |
Description
The Icon class provides a convenient interface for creating and managing icons.
An Icon is essentially a borderless button, combining image and text within a
rendered area. Icons can typically be dragged with the mouse pointer, which
allows the user to customise icon positions within the interface.
Icons are often used to run programs or open files. The Icon class supports
this feature by including a direct interface to the Run class. Popup menus can
also be attached to icons and will appear when the user clicks the right mouse
button.
This DML based example creates an icon that launches the Athene File
Manager:
<icon x="10" y="10" text="File Manager" image="programs/filemanager"
flags="!textbkgd" run.src="programs:bin/runscript"
run.args="tools:filemanager/main.dml"/>
Icons are publicly shared objects as standard, and may not be allocated
privately. This issue is automatically managed when using icons in scripts. When
programming an icon object directly, remember to grab its unique ID and
access/release the object when you use it.
Actions
The Icon class supports the following actions:
| Activate | Activates the icon. |
| Disable | Disables the user's ability to interact with the icon. |
| Enable | Enables user interactivity after prior disablement. |
| Focus | Sets the user focus to the icon's drawable. |
| Hide | Removes the icon from the display. |
| MoveToBack | Moves the icon to the back of the display area. |
| MoveToFront | Moves the icon to the front of the display area. |
| MoveToPoint | Moves the icon to preset coordinates. |
| Show | Puts the icon on display. |
Structure
The Icon object consists of the following public fields:
| Drawable | ID of the drawable created by the icon. |
| FadeDelay | Delays the initial start of an icon fade. |
| FadeRate | The speed of icon fading is defined here. |
| Flags | Optional flags can be set here. |
| Image | The location of the image that should be displayed inside the icon. |
| ImageClick | The location of an image that should be displayed when the icon is clicked. |
| Menu | Reference to popup menu object. |
| MenuSrc | References the location of an XML menu file to be applied to the icon. |
| Run | Interface to the Run class, for launching programs when the user clicks the icon. |
| Size | The preferred size of the icon, in pixels. |
| String | The string displayed in the icon. |
| Target | The icon's parent drawable. |
| Field: | Drawable |
| Short: | ID of the drawable created by the icon. |
| Type: | OBJECTID |
| Status: | Read |
|
The drawable that represents the icon on the display can be retrieved
through this field. The reference is a direct pointer to the Render object
in question. It is possible to manipulate the drawable without
encountering adverse effects with the icon object, although it is wise to
refrain from doing so where functionality is duplicated in the Icon class.
For instance, Hide and Show actions may not be called on the drawable object
as this functionality is already controlled by the icon system.
|
|
| Field: | FadeDelay |
| Short: | Delays the initial start of an icon fade. |
| Type: | FLOAT |
| Status: | Read/Init |
|
If the icon will be faded into the display (i.e. the FADE flag has been
set), then an optional delay may be specified, so that the fade starts after
a predefined interval has passed. This is achieved by setting the FadeDelay
with the number of seconds that you want the fade effect to be delayed.
|
|
| Field: | FadeRate |
| Short: | The speed of icon fading is defined here. |
| Type: | FLOAT |
| Status: | Read/Init |
|
If the icon will be faded into the display (i.e. the FADE flag has been set),
then the FadeRate will be used to determine the speed of the fade. The FadeRate
reflects the total number of seconds that will pass before the fade will
be completed. Thus if the FadeRate is set to 0.5, the fade will take half a
second between the start and finish of the effect.
|
|
| Field: | Flags |
| Short: | Optional flags can be set here. |
| Type: | LONG |
| Prefix: | ICF |
| Status: | Read/Init |
|
Optional flags that may be set against a icon object are as follows:
|
| TEXTBKGD | Draw a dark background behind the icon text. |
| DISABLED | This flag is automatically set when the icon is disabled. |
| SMARTLIMITS | Use display limits to prevent the icon from leaving the display. |
| FADE | Fade the icon into the display. |
| MESSAGE | Use messages to contact child objects when the icon is activated. |
|
|
| Field: | Image |
| Short: | The location of the image that should be displayed inside the icon. |
| Type: | STRING |
| Status: | Read/Set |
|
The image to display inside the icon is defined here. It is highly recommended
that an image is used from the icon database, as this will ensure that the
image is consistent with the loaded desktop theme.
|
|
| Field: | ImageClick |
| Short: | The location of an image that should be displayed when the icon is clicked. |
| Type: | STRING |
| Status: | Read/Set |
|
The ImageClick field can be defined if you wish for a special image to
be displayed when the icon is clicked by the user. The location string should
follow the same conventions as the Image field.
|
|
| Field: | Menu |
| Short: | Reference to popup menu object. |
| Type: | *Menu |
| Status: | Read |
|
If a menu has been loaded for an icon, the menu object will be referenced
here.
|
|
| Field: | MenuSrc |
| Short: | References the location of an XML menu file to be applied to the icon. |
| Type: | STRING |
| Status: | Get/Set |
|
To apply a menu to an icon, you will need to set this field with
the location of a menu file. The file
must be in XML format and contain at least one menu tag. Each menu tag that
you specify will create a new menu option in the menu that is owned by the
icon. Non-menu tags will be ignored.
Any unlisted arguments that you have specified for the icon will be
passed on to each created menu.
For information on the specifics of menu customisation, please
refer to the Menu class.
|
|
| Field: | Run |
| Short: | Interface to the Run class, for launching programs when the user clicks the icon. |
| Type: | *Run |
| Status: | Read |
|
To launch a program when the user clicks on the icon, use the Run object
that is defined in this field to setup the program parmaeters. More
details are available in the Run class manual. At a minimum you must define
the location of the program that you wish to run.
|
|
| Field: | Size |
| Short: | The preferred size of the icon, in pixels. |
| Type: | LONG |
| Status: | Read/Init |
|
The size of the icon can be defined in this field prior to initialisation.
It is recommended that you do not define preset the icon size - doing so will
override the user's preferred icon size. The size value is used as an
approximation only - the width of the icon may extend up to 20% of the original
value. The height of the icon will be considerably larger, in order to
accomodate the icon text.
|
|
| Field: | String |
| Short: | The string displayed in the icon. |
| Type: | STRING |
| Status: | Get/Set |
|
The string that is displayed in the icon is defined here. The string will
be automatically trimmed to fit inside the amount of space that is available
inside the icon drawable. There is a limit of two lines of text in the icon,
each of which is limited to roughly 10 characters.
|
|
| Field: | Target |
| Short: | The icon's parent drawable. |
| Type: | struct Render * |
| Status: | Get/Set |
|
The drawable that the icon is displayed in can be set using the
Target field.
|
|