Class Documentation
OnClick |
1.0 |
ID_ONCLICK |
Alpha |
GUI |
August 2001 |
Rocklyte Systems |
Rocklyte Systems (c) 1999-2001. All rights reserved. |
Manages interface reactions to mouse click events. |
Description
The OnClick class is used for creating interactive areas between
the user and the display, and is typically facilitated by a pointing device
that supports buttons. If you need to create clickable icons and buttons on
the display, you need to use this class to actually grab and process the
clicks.
Here is an example of a rendered area that destroys itself when you click
on it:
<render name="drawable" width="40" height="20" colour="#808080">
<onclick release>
<action static call="free" object="[drawable]"/>
</onclick>
</render>
The OnClick class is almost always used in conjunction with child objects
that perform a certain action for you. Typically you will want to use Action
and Script objects to achieve the effect that you require. Make sure that
you declare them as static, or they will not be initialised to the OnClick
object correctly.
Structure
The OnClick object consists of the following public fields:
Button | Determines the button that the OnClick object will react to. |
Drawable | Determines the drawable to use for click-monitoring and frame setting. |
Flags | Special flags that modify OnClick behaviour. |
Frame | Provides an easy method for frame-switching when a button press is detected. |
Height | Defines the height of the OnClick area. |
Width | Defines the width of the OnClick area. |
XCoord | The horizontal position of the OnClick area. |
XOffset | Specifies the horizontal offset of the OnClick area. |
YCoord | The vertical position of the OnClick area. |
YOffset | Specifies the vertical offset of the OnClick area. |
Field: | Button |
Short: | Determines the button that the OnClick object will react to. |
Type: | LONG |
Status: | Read/Write |
You can set the Button field to the button number that the OnClick object
should react to. A value of 1 is used for the left button, 2 for the right
button and 3 for the middle button. If the pointing device has more than
3 buttons and the software supports it, further numbers are assigned to each
button in a device-associated order.
|
|
Field: | Drawable |
Short: | Determines the drawable to use for click-monitoring and frame setting. |
Type: | OBJECTID |
Status: | Read/Write |
In most cases, when you create an OnClick object it should be
contained by a drawable area, such as a Render object. However there may
be situations where you want to initialise an OnClick object to a
non-graphical container. If this is the case then you must set the
Drawable field so that the OnClick object knows what object it needs to
monitor for mouse clicks.
|
|
Field: | Flags |
Short: | Special flags that modify OnClick behaviour. |
Type: | LONG/FLAGS |
Prefix: | OCF |
Status: | Read/Write |
Special flags supported by the OnClick object are as follows:
DOUBLECLICK | When this flag is enabled, the OnClick object will only respond to double clicks. Single clicks are always ignored. |
RELEASE |
If this flag is set, the OnClick object will activate its children
as soon as the mouse button is released. The only restrction is that the
mouse must still be in the same position from when the original click
took place. If any movement has occured then the children will not be
activated.
The flag is an equally opposite complement to the HELDRELEASE flag, so
if you set both flags the children will be activated on any condition
of a button's release.
|
HELDRELEASE |
If this flag is set, the OnClick object will activate its children
as soon as the mouse button is released. The only restrction is that the
mouse must have moved from the position where the original click took
place.
The flag is an equally opposite complement to the RELEASE flag, so
if you set both flags the children will be activated on any condition
of a button's release.
|
|
|
Field: | Frame |
Short: | Provides an easy method for frame-switching when a button press is detected. |
Type: | LONG |
Status: | Read/Write |
If you would like the OnClick object to change the frame number of its
related drawable when a click is detected, set this field to the frame
number that you want to use.
|
|
Field: | Height |
Short: | Defines the height of the OnClick area. |
Type: | FLOAT |
Status: | Read/Write |
If you want an OnClick 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 OnClick 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: | Width |
Short: | Defines the width of the OnClick area. |
Type: | FLOAT |
Status: | Get/Set |
If you want an OnClick 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 OnClick 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 the OnClick area. |
Type: | FLOAT |
Status: | Get/Set |
If you want an OnClick 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 OnClick 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 the OnClick 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 clickable 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 clickable area will start from an X coordinate calculated from the
formula "XCoord = ContainerWidth - Width - XOffset".
|
|
Field: | YCoord |
Synonyms: | Y |
Short: | The vertical position of the OnClick area. |
Type: | FLOAT |
Status: | Get/Set |
If you want an OnClick 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 OnClick 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 the OnClick 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 clickable 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 clickable area will start from a Y coordinate calculated from the
formula "YCoord = ContainerHeight - Height - YOffset".
|
|