Class Documentation

Name:OnClick
Version:1.0
ID:ID_ONCLICK
Status:Stable
Category:GUI
Include:input/onclick.h
Date:February 2003
Author:Rocklyte Systems
Copyright:  Rocklyte Systems (c) 1999-2003. All rights reserved.
Short:  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:

FlagDescription
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".