Class Documentation
OnClick |
1.0 |
ID_ONCLICK |
Stable |
GUI |
input/onclick.h |
February 2003 |
Rocklyte Systems |
Rocklyte Systems (c) 1999-2003. 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.
Actions
The OnClick class supports the following actions:
Activate | Calling this action on an onclick object will send Activate messages to its children. |
Disable | Temporarily disables an onclick object. |
Enable | Enables the functionality of an onclick object. |
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 an onclick area. |
Pointer | Defines the pointer image to use when the pointer enters the vicinity of the onclick area. |
ReleaseFrame | If set, an onclick object will change to this frame number when a click is released. |
ToolTip | Set this field with a string to enable a delayed tool tip within the onclick area. |
Width | Defines the width of an 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:
AUTOACTIVATE |
If this flag is set then the onclick object will automatically activate itself if the pointer enters the area and stops.
Once a preset amount of time has elapsed and the pointer has remained still, the onclick object will activate itself (as
if the user had clicked a mouse button).
|
DISABLED |
When an onclick object has been disabled, this flag will be automatically
set to indicate that it is not functioning. You can disable an onclick object
by calling the Disable action, while the Enable action will reactivate a disabled onclick object.
|
DOUBLECLICK |
When this flag is enabled, an onclick object will only respond to double clicks. Single clicks are always ignored.
|
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.
|
IGNOREDOUBLE |
Set this flag if you want to limit the onclick object to responding to
single-clicks only. Any secondary clicks that occur within the double-click
timeout period will be ignored by the object.
|
MESSAGE |
Setting this flag will force the onclick object to always use delayed
messaging when activating child objects, rather than attempting to use
the faster method of instant object activation.
|
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.
|
TOGGLEFRAME |
If this flag is set then the onclick object will toggle between its
drawable's current frame and the value in the
ReleaseFrame field whenever a user click is
detected. Button releases will not have an effect on the drawable's frame.
|
|
|
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 an 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. Note that the default behaviour is to change
the drawable's frame back to 0 when the button is released. You can
change this behaviour by setting the ReleaseFrame
field or the TOGGLEFRAME flag.
|
|
Field: | Height |
Short: | Defines the height of an onclick area. |
Type: | DOUBLE/PERCENTAGE |
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: | Pointer |
Short: | Defines the pointer image to use when the pointer enters the vicinity of the onclick 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 onclick area. Valid image names for the
pointer are defined in the Pointer class documentation.
|
|
Field: | ReleaseFrame |
Short: | If set, an onclick object will change to this frame number when a click is released. |
Type: | LONG |
Status: | Read/Set |
If this field is set to a frame value, an onclick object will
automatically change the frame of its drawable to the indicated value when
a click is released. This behaviour only occurs when this field is used
in conjunction with the Frame field.
|
|
Field: | ToolTip |
Short: | Set this field with a string to enable a delayed tool tip within the onclick area. |
Type: | STRING |
Status: | Get/Set |
This field provides tool tip support for onclick objects. Tool tips are
enabled when the mouse pointer sits over an onclick area without
motion. When this occurs, a small box will pop up containing the text that
you have set in the ToolTip field. When the pointer is moved, the tool tip
disappears.
The time that it takes for a tool tip to appear is controlled
internally and may be adjusted only by the user.
|
|
Field: | Width |
Short: | Defines the width of an onclick area. |
Type: | DOUBLE/PERCENTAGE |
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: | DOUBLE/PERCENTAGE |
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: | 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 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: | DOUBLE/PERCENTAGE |
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: | DOUBLE/PERCENTAGE |
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".
|
|