Screen

Version:1.0
Status:Stable
Date:July 2004
Author:Rocklyte Systems
Copyright:  Rocklyte Systems, 1996-2004. All rights reserved.



Function Index
AccessPointer  Returns a lock on the default pointer object.
GetCursorInfo  Retrieves graphics information from the active mouse cursor.
GetCursorPos  Returns the coordinates of the pointer cursor.
GetRelativeCursorPos  Returns the coordinates of the pointer cursor, relative to a drawable object.
GetScreenInfo  Retrieves display information.
RestoreCursor  Returns the pointer image to its original state.
ScanDisplayModes  Returns formatted resolution information from the display database.
SetCursor  Sets the cursor image and can anchor the pointer to any drawable.
SetCursorPos  Changes the position of the pointer cursor.
SetCustomCursor  Sets the cursor to a customised bitmap image.

 

Function:AccessPointer()
Short:Returns a lock on the default pointer object.
Synopsis:struct Pointer * AccessPointer(void)

Use AccessPointer() to grab a lock on the default pointer object that is active in the system. This is typically the first object created from the Pointer class with a name of "SystemPointer".

You must call ReleasePointer() to free the lock once you are finished with the pointer object.

Result
Returns the address of the default pointer object.


Function:GetCursorInfo()
Short:Retrieves graphics information from the active mouse cursor.
Synopsis:ERROR GetCursorInfo(struct CursorInfo *Info, LONG Size)
Arguments:
Info  Pointer to a CursorInfo structure.
Size  The byte-size of the Info structure.

The GetCursorInfo() function is used to retrieve useful information on the graphics structure of the mouse cursor. It will tell you the maximum possible dimensions for custom cursor graphics and indicates the optimal bits-per-pixel setting for the hardware cursor.

Note: If the hardware cursor is monochrome, the bits-per-pixel setting will be set to 2 on return. This does not indicate a 4 colour cursor image; rather colour 0 is the mask, 1 is the foreground colour (black), 2 is the background colour (white) and 3 is an XOR pixel. When creating the bitmap, remember to set the palette to the values that you want and the mask colour must for the bitmap must refer to colour index 0.

Result
ERR_Okay  Pointer changed successfully.
ERR_Args  The Info parameter was not specified.

Function:GetCursorPos()
Short:Returns the coordinates of the pointer cursor.
Synopsis:ERROR GetCursorPos(LONG *XCoord, LONG *YCoord)
Arguments:
XCoord  32-bit variable that will store the pointer's horizontal coordinate.
YCoord  32-bit variable that will store the pointer's vertical coordinate.

This function is used to retrieve the current coordinates of the pointer cursor.

Result
ERR_Okay  Success.
ERR_AccessObject  Failed to access the SystemPointer object.

Function:GetRelativeCursorPos()
Short:Returns the coordinates of the pointer cursor, relative to a drawable object.
Synopsis:ERROR GetRelativeCursorPos(OBJECTID Drawable, LONG *XCoord, LONG *YCoord)
Arguments:
Drawable  Unique ID of the drawable that the coordinates need to be relative to.
XCoord  32-bit variable that will store the pointer's horizontal coordinate.
YCoord  32-bit variable that will store the pointer's vertical coordinate.

This function is used to retrieve the current coordinates of the pointer cursor. The coordinates are relative to the drawable object that you specify in the Drawable argument.

The XCoord and YCoord parmeters will not be set if a failure occurs.

Result
ERR_Okay  Success.
ERR_AccessObject  Failed to access the SystemPointer object.

Function:RestoreCursor()
Short:Returns the pointer image to its original state.
Synopsis:ERROR RestoreCursor(LONG Cursor, OBJECTID OwnerID)
Arguments:
Cursor  The cursor number that you want to restore the pointer to (NULL for the default).
OwnerID  The ownership ID that you gave in the initial call to SetCursor().

Use the RestoreCursor() function if you have called SetCursor() earlier and want to return the cursor to its default state. You must provide the same OwnerID that you used in your original call to SetCursor().

If you want to release your ownership of the cursor without changing the current cursor image, use a Cursor setting of PTR_NOCHANGE.

Result
ERR_Okay  Success.
ERR_Args  Invalid arguments specified.

Function:ScanDisplayModes()
Short:Returns formatted resolution information from the display database.
Synopsis:ERROR GetDisplayModes(STRING Filter, SCREENINFO *Info, LONG Size)
Arguments:
Filter  The filter to apply to the resolution database. May be NULL for no filter.
Info  A pointer to a SCREENINFO structure must be referenced here. The structure will be filled with information when the function returns.
Size  Size of the SCREENINFO structure.
   SCREENINFO info;

   ClearMemory(&Info, sizeof(Info));
   while (ScanDisplayModes("depth=32", &info, sizeof(info)) IS ERR_Okay) {
      ...
   }
Result
ERR_Okay  The resolution information was retrieved.
ERR_Args  Invalid arguments specified.
ERR_NoSupport  Native graphics system not available (e.g. hosted on Windows or X11).
ERR_Search  There are no more display modes to return that are a match for the Filter.

Function:SetCursor()
Short:Sets the cursor image and can anchor the pointer to any drawable.
Synopsis:ERROR SetCursor(OBJECTID ObjectID, LONG Flags, LONG CursorID, STRING Name, OBJECTID OwnerID, LONG *PreviousCursor)
Arguments:
ObjectID  Refers to the drawable object that the pointer should anchor itself to, if the ACF_ANCHOR or ACF_RESTRICT flags are used. Otherwise, this parameter can be set to a drawable that the new cursor image should be limited to. The object referred to here must be publicly accessible to all tasks.
Flags  Optional flags affecting the cursor are set here.
Cursor  The ID of the cursor that you want to set.
Name  The name of the cursor that you want to set (if Cursor is zero).
OwnerID  The object nominated as the owner of the anchor or cursor image setting.
PreviousCursor  The ID of the previous cursor is returned in this parameter.

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:

FlagDescription
ACF_BUFFERUse 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_LMBRelease the cursor after the left mouse button is held and released.
ACF_MMBRelease the cursor after the middle mouse button is held and released.
ACF_RMBRelease the cursor after the right mouse button is held and released.
ACF_NOBUTTONSSet 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_ANCHORAnchor 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_RESTRICTSimilar 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.

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

Function:SetCursorPos()
Short:Changes the position of the pointer cursor.
Synopsis:ERROR SetCursorPos(LONG XCoord, LONG YCoord)
Arguments:
XCoord  The new horizontal coordinate for the pointer.
YCoord  The new vertical coordinate for the pointer.

Changes the position of the pointer cursor using coordinates relative to the entire display.

Result
ERR_Okay  Success.
ERR_AccessObject  Failed to access the SystemPointer object.

Function:SetCustomCursor()
Short:Sets the cursor to a customised bitmap image.
Synopsis:ERROR SetCustomCursor(OBJECTID ObjectID, LONG Flags, struct Bitmap *Bitmap, LONG HotX, LONG HotY, OBJECTID OwnerID, LONG *PreviousCursor)
Arguments:
ObjectID  Refers to the drawable object that the pointer should anchor itself to, if the ACF_ANCHOR or ACF_RESTRICT flags are used. Otherwise, this parameter can be set to a drawable that the new cursor image should be limited to. The object referred to here must be publicly accessible to all tasks.
Flags  Optional flags affecting the cursor are set here.
Bitmap  The bitmap that you want to set for the mouse cursor.
HotX  The horizontal position of the cursor hot-spot.
HotY  The vertical position of the cursor hot-spot.
OwnerID  The object nominated as the owner of the anchor.
PreviousCursor  The ID of the previous cursor is returned in this parameter.

Use the SetCustomCursor() function to change the pointer image and/or anchor the position of the pointer so that it cannot move without your permission. The functionality provided is identical to that of the SetCursor() function with some minor adjustments to allow custom images to be set.

The Bitmap that you provide should be within the width, height and bits-per-pixel settings that are returned by the GetCursorInfo() function. If the basic settings are outside the allowable parameters, the Bitmap will be trimmed or resampled appropriately when the cursor is downloaded to the video card.

Potentially, you may be able to speed up the creation of custom cursors by drawing directly to the pointer's internal bitmap rather than supplying your own bitmap. If you would like to do this, the Bitmap parameter must be NULL and you will have to draw to the pointer's bitmap before calling SetCustomCursor(). Note that the bitmap is always returned as a 32-bit, alpha-enabled graphics area. The following code illustrates this process:

   struct Pointer *pointer;
   struct Bitmap *bitmap;

   if ((pointer = AccessPointer())) {
      if (AccessObject(pointer->BitmapID, 3000, &bitmap) IS ERR_Okay) {
         // Adjust clipping to match the cursor size.
         buffer->ClipRight  = YourCursorWidth;
         buffer->ClipBottom = YourCursorHeight;
         if (buffer->ClipRight > buffer->Width) buffer->ClipRight = buffer->Width;
         if (buffer->ClipBottom > buffer->Height) buffer->ClipBottom = buffer->Height;

         // Draw to the bitmap here.
         ...

         SetCustomCursor(ObjectID, NULL, NULL, 1, 1, glTaskID, NULL);
         ReleaseObject(bitmap);
      }
      ReleasePointer(pointer);
   }
Result
ERR_Okay  Pointer changed successfully.
ERR_Args  Invalid arguments were specified.
ERR_NoSupport  The pointer cannot be set due to system limitations.
ERR_AccessObject  Failed to access the internally maintained image object.