Class Documentation

Name:Pointer
Version:1.0
ID:ID_POINTER
Status:Unspecified
Category:Graphics
Date:January 2004
Author:Rocklyte Systems
Copyright:  Rocklyte Systems (c) 1998-2004. All rights reserved.
Short:  Used to support mouse pointers.



Description

The Pointer class is used to provide the computer user with a means of interacting with the graphical interface. Traditionally the pointer is controlled by an attached mouse device, but the use of a keyboard, joystick or other device is acceptable. The pointer class operates in 3 dimensions (X, Y, Z) and the Z axis is typically controlled by a mouse wheel.

A pointer object should usually be created at boot-up unless you don't want a pointer in your system (e.g. for keyboard-only input). Not creating a pointer will also mean that the system will not support user-click and user-movement management, unless you have some other means of achieving this. It is recommended that when creating a pointer at boot-up you give it a name of "SystemPointer". This is a system-wide standard that makes it easier for other objects to find the pointing device. If you give it a different name then the pointer will effectively be hidden from other objects.

The Pointer class manages action-events such as UserMovement, UserClick and UserClickRelease. These actions are called and passed to other objects on the desktop as appropriate.

Actions

The Pointer class supports the following actions:

DataChannel  This action can be used to send fake input to a pointer object.
Hide  Hides the pointer from the display.
Move  Moves the position of a pointer to a new location.
MoveToPoint  Moves the position of a pointer to a new location.
Reset  Resets the pointer settings back to the default.
SaveToObject  Saves the current pointer settings to another object.
Show  Shows the pointer if it is not already on the display.
UserClick  Customised click messages can be passed to the pointer through this action.

Methods

The Pointer class implements the following methods:

HardwareCursor  Enables the hardware cursor if the software cursor is currently active.
SoftwareCursor  Forces use of the software cursor instead of the hardware cursor.

Structure

The Pointer object consists of the following public fields:

ButtonState  Indicates the current button-press state.
Cursor  Sets the pointer image, selected from the pre-defined graphics bank.
Input  Declares the I/O object to read movement from.
MaxSpeed  Restricts the maximum speed of a pointer's movement.
OverObject  Readable field that gives the ID of the object under the pointer.
OverX  The horizontal position of the Pointer with respect to the object underneath the hot-spot.
OverY  The vertical position of the Pointer with respect to the object underneath the hot-spot.
OverZ  The position of the Pointer within an object.
Speed  Speed multiplier for Pointer movement.
Theme  The pointer graphics theme is defined in this field.
XCoord  Defines the horizontal position of the Pointer within its master container.
YCoord  Defines the vertical position of the Pointer within its master container.
ZCoord  Defines the depth-based position of the Pointer within its master container.
Action:DataChannel
Short:This action can be used to send fake input to a pointer object.

Fake input can be sent to a pointer object with the DATA_JOYPORT data type, as if the user was using the mouse. The data will be interpreted no differently to 'real' user input.

It is extremely important that when setting the button flags to indicate a button-click, you follow up with the equivalent release flags.


Action:Move
Short:Moves the position of a pointer to a new location.

Calling the Move action allows you to move the position of the pointer to a new location instantly. This has the effect of bypassing the normal set of routines for pointer movement (i.e. no UserMovement signals will be sent to applications to indicate the change).


Action:MoveToPoint
Short:Moves the position of a pointer to a new location.

Calling the MoveToPoint action allows you to move the position of the pointer to a new location instantly. This has the effect of bypassing the normal set of routines for pointer movement (i.e. no UserMovement signals will be sent to applications to indicate the change).

You may subscribe to this action if you would like to listen for changes to the pointer's screen position.


Method:SoftwareCursor()
Short:Forces use of the software cursor instead of the hardware cursor.

By default the system will use a hardware based mouse pointer in order to maintain maximum speed in the graphical interface. You can change this behaviour by calling the SoftwareCursor method, which forces the hardware mouse cursor to be replaced with a software based one.


Field:ButtonState
Short:Indicates the current button-press state.
Type:LONG
Status:Get

You can read this field at any time to get an indication of the buttons that are currently being held by the user. The flags returned by this field are JD_LMB, JD_RMB and JD_MMB indicating left, right and middle mouse buttons respectively.


Field:Cursor
Short:Sets the pointer image, selected from the pre-defined graphics bank.
Type:LONG
Prefix:PTR
Status:Read/Init

Set the Cursor field when you want to alter the current graphic displayed by the pointer. The cursor is declared as a numeric value which must be selected from the following table:

Cursor IDNameDescription
DEFAULTDefaultThe default cursor (usually an arrow pointing to the upper left).
SIZE_BOTTOM_LEFTSizeBottomLeftSizing cursor - for resizing the bottom left corner of any rectangular area.
SIZE_BOTTOM_RIGHTSizeBottomRightSizing cursor - for resizing the bottom right corner of any rectangular area.
SIZE_TOP_LEFTSizeTopLeftSizing cursor - for resizing the top left corner of any rectangular area.
SIZE_TOP_RIGHTSizeTopRightSizing cursor - for resizing the top right corner of any rectangular area.
SIZE_LEFTSizeLeftSizing cursor - for resizing the left edge of any rectangular area.
SIZE_RIGHTSizeRightSizing cursor - for resizing the right edge of any rectangular area.
SIZE_TOPSizeTopSizing cursor - for resizing the top edge of any rectangular area.
SIZE_BOTTOMSizeBottomSizing cursor - for resizing the bottom edge of any rectangular area.
CROSSHAIRCrosshairThe cross hair is used for targetting specific pixel points (common in paint programs).
SLEEPSleepThe sleep cursor is used to inform the user that the computer is busy.
SIZINGSizingMulti-directional sizing cursor - for resizing in any direction.
SPLIT_VERTICALSplitVerticalThe vertical split cursor is typically used for splitting rectangles in half, or dragging a vertical split within a large rectangular space.
SPLIT_HORIZONTALSplitHorizontalThe horizontal split cursor is typically used for splitting rectangles in half, or dragging a horizontal split within a large rectangular space.
MAGNIFIERMagnifierRepresents a magnifying glass.
HANDHandThe hand cursor is often used for indicating clickable content (hyperlinks, icons etc).
HAND_LEFTHandLeftSimilar to the standard hand cursor, but points to the left.
HAND_RIGHTHandRightSimilar to the standard hand cursor, but points to the right.
TEXTTextThe text cursor is popular for the precise positioning of text cursors.
PAINTBRUSHPaintbrushThe paintbrush cursor is typically employed by paint programs.
STOPStopThe stop cursor is used to inform the user that an operation is not possible (e.g. drag and drop to an unsupported object area).

Cursor specification does not work on all Athene systems, e.g. X11 based systems do not support this feature. In such cases the Cursor field is ignored and ERR_NoSupport is returned.


Field:Input
Short:Declares the I/O object to read movement from.
Type:OBJECTID
Status:Init

By default a pointer will read its input directly from the mouse port. However it may be convenient for the pointer to receive its information from elsewhere, in which case you can set this field to point to a different input object. The object that you use must be able to send joyport information over data channels.


Field:MaxSpeed
Short:Restricts the maximum speed of a pointer's movement.
Type:LONG
Status:Read/Write

The maximum speed at which the pointer can move per frame is specified in this field. This field is provided to help the user for times where the pointer may be moving to fast (for example if the hardware driver is interpreting the mouse movement at larger offsets than what is normal). You can also set the value to 1 if a digital simulation is required.


Field:OverObject
Short:Readable field that gives the ID of the object under the pointer.
Type:OBJECTID
Status:Read

This field returns a reference to the object directly under the pointer's hot-spot. NULL can be returned if there is no drawable object under the pointer.


Field:OverX
Short:The horizontal position of the Pointer with respect to the object underneath the hot-spot.
Type:LONG
Status:Read

The OverX field provides other classes with a means of finding out exactly where the pointer is positioned over their display area. For example, if a user click occurs on an Image and it is necessary to find out what coordinates where affected, the OverX and OverY fields can be polled to determine the exact position of the user click.


Field:OverY
Short:The vertical position of the Pointer with respect to the object underneath the hot-spot.
Type:LONG
Status:Read

The OverY field provides other classes with a means of finding out exactly where the pointer is positioned over their display area. For example, if a user click occurs on an Image and it is necessary to find out what coordinates where affected, the OverX and OverY fields can be polled to determine the exact position of the user click.


Field:OverZ
Short:The position of the Pointer within an object.
Type:LONG
Status:Read Only

This special field applies to 3D interfaces only. It reflects the position of the Pointer within 3-Dimensional containers, by returning its coordinate along the Z axis.


Field:Speed
Short:Speed multiplier for Pointer movement.
Type:LONG
Status:Read/Write

The speed at which the pointer moves can be adjusted with this field. To lower the speed, use a value between 0 and 100%. To increaase the speed, use a value between 100 and 1000%. The Speed of the Pointer is complemented by the MaxSpeed field, which restricts the maximum amount of pixels that a Pointer can move each time the input device is polled.


Field:Theme
Short:The pointer graphics theme is defined in this field.
Type:STRING
Status:Get/Set

The graphical theme used by the pointer can be defined in this field. It will cause the pointer to load and switch to the indicated theme immediately. The theme must refer to a valid theme XML file stored in the pictures:pointers/ directory.

Cursor themes are not supported in all of the freely distributed versions of Athene.


Field:XCoord
Short:Defines the horizontal position of the Pointer within its master container.
Type:LONG
Status:Read/Write

You can read the current X coordinate of the Pointer via this field. The coordinate is measured from the top left of the screen display.


Field:YCoord
Short:Defines the vertical position of the Pointer within its master container.
Type:LONG
Status:Read/Write

You can read the current Y coordinate of the Pointer via this field. The coordinate is measured from the top left of the screen display.


Field:ZCoord
Short:Defines the depth-based position of the Pointer within its master container.
Type:LONG
Status:Read

If the Pointer's container supports 3-Dimensional space then it will have a depth setting that can be read from this field. Negative values indicate that the Pointer has receded into the display, while positive values indicate that the Pointer has moved into the foreground of the display.