Class Documentation
Pointer |
1.0 |
ID_POINTER |
Unspecified |
GUI |
October 2001 |
Rocklyte Systems |
Rocklyte Systems (c) 1998-2001. All rights reserved. |
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.
|
|