Class Documentation
Movement |
1.0 |
ID_MOVEMENT |
Unspecified |
GUI |
February 2003 |
Rocklyte Systems |
Rocklyte Systems (c) 2000-2003. All rights reserved. |
Used to react to the user's movement within the GUI. |
Description
The Movement class is used to detect the movement of any 'pointing
device' that the user is moving on the display. In the vast majority of
cases this means dealing with mouse pointers, although touch screens can
also express movement, as well as joysticks and other devices that can
move the pointer.
The Movement class supports a number of native actions that can be
performed when movement is detected, including:
Can move objects to the back or front of the display.
Can alter the frame of its monitored object.
Will send Activate messages to all children of the movement object,
which can then perform whatever commands you specified.
By default, a movement object will monitor the user's motion in the local
container. The handling of movement is split into
three parts - movement entry, internal movement and movement exit. The
default behaviour is to monitor movement entry, which causes the movement
object to react only when the pointer moves over the object for the first
time. You can do the opposite and monitor for a user exit by setting the
Exit field to TRUE.
Structure
The Movement object consists of the following public fields:
Drawable | Refers to the drawable to be used for movement monitoring. |
Enter | Set to TRUE to activate child object/s when the user enters the monitored area. |
Exit | Set to TRUE to activate child object/s when the user leaves the monitored area. |
ExitFrame | Enables frame switching when the user leaves the monitored object. |
Frame | Enables frame switching when the user enters the monitored object. |
Height | Defines the height of a Movement object's monitored area. |
MoveToBack | Can refer to an object that should be moved to the back when movement is detected. |
MoveToFront | Can refer to an object that should be moved to the front when movement is detected. |
Pointer | Defines the pointer cursor to use when the pointer enters the vicinity of the movement area. |
State | Reflects the current state of the movement object. |
Width | Defines the width of a Movement object's monitored area. |
XCoord | The horizontal position of a Movement object's monitored area. |
XOffset | Specifies the horizontal offset of a Movement object's monitored area. |
YCoord | The vertical position of a Movement object's monitored area. |
YOffset | Specifies the vertical offset of a Movement object's monitored area. |
Field: | Drawable |
Short: | Refers to the drawable to be used for movement monitoring. |
Type: | OBJECTID |
Status: | Read/Write |
In most cases, when you create a Movement object it should be
contained by a drawable area, such as a Render object. However there may
be situations where you want to initialise a Movement object to a
non-graphical container. If this is the case then you must set the
Drawable field so that the Movement object knows what drawable it needs to
monitor for movement.
|
|
Field: | Enter |
Short: | Set to TRUE to activate child object/s when the user enters the monitored area. |
Type: | BOOLEAN |
Status: | Read/Write |
If this field is set to TRUE, the Movement object will activate all
of its child objects when the user enters the monitored area.
|
|
Field: | Exit |
Short: | Set to TRUE to activate child object/s when the user leaves the monitored area. |
Type: | BOOLEAN |
Status: | Read/Write |
If this field is set to TRUE, the Movement object will activate all
of its child objects when the user leaves the monitored area.
|
|
Field: | ExitFrame |
Short: | Enables frame switching when the user leaves the monitored object. |
Type: | LONG |
Status: | Read/Write |
If you would like the Movement object to change the frame number of its
related drawable when the user leaves the object, set this field to the frame
number that you want to use.
|
|
Field: | Frame |
Short: | Enables frame switching when the user enters the monitored object. |
Type: | LONG |
Status: | Read/Write |
If you would like the Movement object to change the frame number of its
related drawable when the user enters the object, set this field to the
frame number that you want to use.
|
|
Field: | Height |
Short: | Defines the height of a Movement object's monitored area. |
Type: | FLOAT |
Status: | Read/Write |
If you want a Movement object to monitor a specific region of the drawable
that it is connected to, set the XCoord, YCoord, Width and Height fields. If
you would rather have the Movement object monitor the entire area of the
drawable, do not set any of the fields.
To set a relative height, use the FD_PERCENT flag when setting the field;
otherwise a fixed height is assumed.
|
|
Field: | MoveToBack |
Short: | Can refer to an object that should be moved to the back when movement is detected. |
Type: | OBJECTID |
Status: | Read/Write |
When the user enters the monitored area, you can move a selected object
to the back of its container by setting this field to that object's ID.
Here is an example that moves a Render object to the back when the user
enters it:
<render name="drawable" width="100" height="100" colour="#606000">
<movement object="drawable" movetoback="[drawable]"/>
</render>
|
|
Field: | MoveToFront |
Short: | Can refer to an object that should be moved to the front when movement is detected. |
Type: | OBJECTID |
Status: | Read/Write |
When the user enters the monitored area, you can move a selected object
to the front of its container by setting this field to that object's ID.
Here is an example that moves a Render object to the front when the user
enters it:
<render name="drawable" width="100" height="100" colour="#606000">
<movement object="drawable" movetofront="[drawable]"/>
</render>
|
|
Field: | Pointer |
Short: | Defines the pointer cursor to use when the pointer enters the vicinity of the movement area. |
Type: | STRING |
Status: | Get/Set |
Set the Pointer field if you would like to use a special pointer image
when the user's pointer enters the movement area. Valid image names for the
pointer are defined in the Pointer class documentation.
|
|
Field: | State |
Short: | Reflects the current state of the movement object. |
Type: | LONG |
Status: | Read |
The current state of the Movement object in relation to the user is
always reflected in this field. The numbers that may be returned from the
field are as follows:
ENTERED = 1
INSIDE = 2
EXITED = 3
The ENTERED state means that the user has just entered the monitored area.
The INSIDE state means that the user is moving within the monitored area.
The EXITED state means that the user has left the monitored area.
|
|
Field: | Width |
Short: | Defines the width of a Movement object's monitored area. |
Type: | FLOAT |
Status: | Get/Set |
If you want a Movement object to monitor a specific region of the drawable
that it is connected to, set the XCoord, YCoord, Width and Height fields. If
you would rather have the Movement object monitor the entire area of the
drawable, do not set any of the fields.
To set a relative width, use the FD_PERCENT flag when setting the field;
otherwise a fixed width is assumed.
|
|
Field: | XCoord |
Synonyms: | X |
Short: | The horizontal position of a Movement object's monitored area. |
Type: | FLOAT |
Status: | Get/Set |
If you want a Movement object to monitor a specific region of the drawable
it is connected to, set the XCoord, YCoord, Width and Height fields. If you
would rather have the Movement object monitor the entire area of the drawable,
do not set any of the fields.
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: | Specifies the horizontal offset of a Movement object's monitored area. |
Type: | FLOAT |
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 monitored area will be
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 area 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 monitored area will start from an X coordinate calculated from the
formula "XCoord = ContainerWidth - Width - XOffset".
|
|
Field: | YCoord |
Synonyms: | Y |
Short: | The vertical position of a Movement object's monitored area. |
Type: | FLOAT |
Status: | Get/Set |
If you want a Movement object to monitor a specific region of the drawable
it is connected to, set the XCoord, YCoord, Width and Height fields. If you
would rather have the Movement object monitor the entire area of the drawable,
do not set any of the fields.
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: | Specifies the vertical offset of a Movement object's monitored area. |
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 monitored area will be
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 area 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 monitored area will start from a Y coordinate calculated from the
formula "YCoord = ContainerHeight - Height - YOffset".
|
|