Documentation
[SDK Documentation] [CGapiCursor]

 

GapiDraw Classes CGapiSurface CGapiRGBASurface CGapiDraw CGapiDisplay CGapiMaskSurface CGapiBitmapFont CGapiCursor CGapiApplication CGapiInput CGapiVFS CGapiTimer CGapiGradient

CGapiCursor

Overview

CGapiCursor is used to draw a cursor when an application is run in full screen mode on a Stationary computer.

This document has been updated for use with GapiDraw 4.0 or later.
Last updated on October 5, 2008.

 

CGapiCursor::CreateCursor

This method creates the cursor.

HRESULT CreateCursor(DWORD dwFlags, DWORD dwFrameCount, DWORD dwFrameStep);
Parameters
dwFlags
Not used. Set to NULL.
dwFrameCount
The number of frames contained in the cursor bitmap. See remarks below.
dwFrameStep
The FrameStep value indicates how often the frame index should increase. A value of 1 adds 1 to the frame index on every call to CGapiCursor::DrawCursor. A value of 2 adds 1 to the frame index on every second call to CGapiCursor::DrawCursor.
Return values

If this method succeeds, the return value is GD_OK.

If the method fails, the return value may be one of the following return values:

GDERR_INVALIDPARAMS

Remarks

A bitmapped cursor is mostly used on stationary computers in full screen mode. Since CGapiCursor is a subclass of CGapiRGBASurface, you must manually load a bitmap with transparency (typically PNG with embedded alpha information) into the CGapiCursor instance. The following steps are necessary to create a new cursor:

  1. Create a CGapiCursor object.
  2. Call CGapiCursor::CreateSurface and supply a valid PNG image with alpha transparency.
  3. Call CGapiCursor::CreateCursor to set the number of frames and update interval.
  4. On each mouse move, call CGapiCursor::SetPosition.
  5. On each frame, call CGapiCursor::DrawCursor.

There are several cursors you can use included with the GapiDraw distribution. A typical cursor looks like the following:


A typical, animated, alpha blended GapiCursor.
The above image is an alpha blended cursor consisting of 5 frames.

CGapiCursor::SetHotSpot

Sets the hotspot of the cursor.

HRESULT SetHotSpot(LONG x, LONG y);
x
The zero-based X-position of the hot spot. Can be negative.
y
The zero-based Y-position of the hot spot. Can be negative.
Return values

The return value is GD_OK.

CGapiCursor::SetFrameIndex

Sets the frame index of the cursor animation.

HRESULT SetFrameIndex(DWORD dwFrameIndex);
dwFrameIndex
The zero-based index of the next frame to be displayed on CGapiCursor::DrawCursor.
Return values

If this method succeeds, the return value is GD_OK.

If the method fails, the return value may be one of the following return values:

GDERR_INVALIDPARAMS

CGapiCursor::SetPosition

Sets the position of the cursor.

HRESULT SetPosition(LONG x, LONG y);
x
The zero-based X-position of the cursor. Can be negative if clipping is enabled.
y
The zero-based Y-position of the cursor. Can be negative if clipping is enabled.
Return values

The return value is GD_OK

CGapiCursor::DrawCursor

Draws the cursor using the current position on a target surface.

HRESULT DrawCursor(CGapiSurface* pDestSurface);
Parameters
pDestSurface
A target surface where the cursor will be drawn.
Return values

If this method succeeds, the return value is GD_OK.

If the method fails, the return value may be one of the following return values:

GDERR_INCOMPATIBLEPRIMARY
GDERR_INVALIDPARAMS
GDERR_INVALIDRECT
GDERR_LOCKEDSURFACES
GDERR_NOTINITIALIZED

Remarks

Please enable clipping on the surface using CGapiSurface::SetClipper if you want the cursor to clip correctly to the surface boundaries.