Class Documentation

Name:OnClick
Version:1.0
ID:ID_ONCLICK
Status:Alpha
Category:GUI
Date:August 2001
Author:Rocklyte Systems
Copyright:  Rocklyte Systems (c) 1999-2001. 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.

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:

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