Class Documentation

Name:Pointer
Version:1.0
ID:ID_POINTER
Status:Unspecified
Category:GUI
Date:October 2001
Author:Rocklyte Systems
Copyright:  Rocklyte Systems (c) 1998-2001. 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. Currently the pointer operates in 2 dimensions (X, Y), but it is expected that 3D support may be added at a later date.

A Pointer object should usually be created at boot-up unless you don't want to accept pointer activity in your system. Not creating a Pointer will 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.

Structure

The Pointer object consists of the following public fields:

HotX  Horizontal hot-spot.
HotY  Vertical hot-spot.
Image  Picture file to use for the image of the Pointer.
Input  Declares the I/O object to read movement from.
MaxSpeed  Restricts the maximum speed of the 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.
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.
Field:HotX
Short:Horizontal hot-spot.
Type:LONG
Status:Read/Init

The HotX and HotY fields are made available for images where you might want the pointer "hotspot" to be positioned somewhere other than the top left of the image. For example, if you reversed a standard pointer image so that the tip of the pointer was over on the right hand side, you would also want to move the hotspot so that it was positioned at the top right of the image.

 

Field:HotY
Short:Vertical hot-spot.
Type:LONG
Status:Read/Init

The HotX and HotY fields are made available for images where you might want the pointer "hotspot" to be positioned somewhere other than the top left of the image. For example, if you reversed a standard pointer image so that the tip of the pointer was over on the right hand side, you would also want to move the hotspot so that it was positioned at the top right of the image.

 

Field:Image
Short:Picture file to use for the image of the Pointer.
Type:STRING
Status:Init

To choose your own image to be used as the pointer, specify the filename of a standard picture file here. Be careful not use large images for pointers because it will only slow graphical performance.

Image specification does not work on all Athene systems, e.g. X11 based systems do not support such a feature. In such cases the Image field is ignored.

 

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

By default a Pointer will read its input from the "SystemMouse" object, which is normally created during the boot process to represent the mouse port. However you may want 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.

If the field is set incorrectly or the SystemMouse object does not exist in the system, the initialisation of the Pointer will most likely fail.

 

Field:MaxSpeed
Short:Restricts the maximum speed of the 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.

 

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: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.