Use the SetCursor() function to change the pointer image and/or anchor the
position of the pointer so that it cannot move without your permission.
To anchor the pointer, you must use the ACF_ANCHOR flag and set the
ObjectID parameter to refer to the object that you are anchoring the
cursor to. In this mode, the pointer will not respond to user movement
signals for as long as the anchor is active. Instead, the object referred
to in the ObjectID parameter will be sent UserMovement action messages. The
processing of movement messages can be useful for manually moving the pointer
position in response to user movement requests.
If you anchor the pointer, it is of utmost importance that you add the necessary
code to release the anchor at some stage, or you may leave the pointer in a permanently
motionless state. Use the RestoreCursor method to release the anchor that you
have obtained.
To change the cursor image, you only need to set the Cursor or Name parameters
to define the new image. Valid cursor ID's and their equivalent names are listed
in the documentation for the Cursor field. If you set the ObjectID field to a
valid drawable, then the cursor image will switch back to the default setting once
the pointer moves outside of its region. If both the Cursor and Name parameters
are NULL, the cursor image will remain unchanged from its current image.
The SetCursor() function accepts the following flags in the Flags parameter:
ACF_BUFFER | Use of the BUFFER option allows your cursor request to be buffered in the event that the cursor is locked at the time of calling the SetCursor method. Use of this flag is highly recommended in most circumstances, but may not be used in conjunction with the ANCHOR option. |
ACF_LMB | Release the cursor after the left mouse button is held and released. |
ACF_MMB | Release the cursor after the middle mouse button is held and released. |
ACF_RMB | Release the cursor after the right mouse button is held and released. |
ACF_NOBUTTONS | Set the cursor only on the condition that the user is not holding down any buttons. ERR_NothingDone is returned if the user has a button held down. |
ACF_ANCHOR | Anchor the position of the pointer to the object specified in the ObjectID parameter. Please note that some host platforms do not support this option. |
ACF_RESTRICT | Similar to the anchor option, but allows the pointer to move within the drawable referred to by ObjectID. |
The OwnerID parameter is used as a locking mechanism to prevent the cursor
from being changed whilst you have it locked. We recommend
that we set it to your task ID or relative object ID. As the owner, the cursor remains under
your control until the RestoreCursor method is called.
The SetCursor() function will return the old cursor ID in the
PreviousCursor parameter.
ERR_Okay | Pointer changed successfully. |
ERR_Args | Invalid arguments were specified. |
ERR_NoSupport | The pointer cannot be set due to system limitations. |
ERR_OutOfRange | The cursor ID is outside of acceptable range. |
ERR_AccessObject | Failed to access the internally maintained image object. |
|