Pointer sessions

Pointer input sessions are created with the type SCREEN_EVENT_POINTER and are typically used to control the shape and position of the cursor.

The SCREEN_PROPERTY_MODE property for pointer sessions is not used. However, the following session properties are applicable to pointer sessions:

SCREEN_PROPERTY_ACCELERATION: A set of six integers that represent the linear coefficients for x and y, the quadratic coefficients for x and y, and the minimum and maximum velocity.
SCREEN_PROPERTY_ALTERNATE: Specifies an alternate session. You can make a session an alternate for another (usually, both sessions are input regions). Normally, sessions that are alternates are also windowless. You can set up your application such that if your pointer is in one region, it jumps to another session. For example, if your pointer is over a specific area, you can move to a different display. As a window manager, you can make a session an alternate for another session. You can also tag a session as an alternate. The alternate comes into play in the geometry for multiple displays using a pointer.
SCREEN_PROPERTY_BRUSH: A pointer to the pixmap containing the brush to be used. All move events (e.g., a click then drag) will translate to drawing on your front buffer.
SCREEN_PROPERTY_CURSOR: Specifies a cursor shape to display when the pointer is within the region of the session. The cursor can be one of the shapes defined in Screen cursor shapes. Typically you'd use this property on an input region so that you can change the shape of the cursor when the pointer is over a specific area.
SCREEN_PROPERTY_SPEED: The speed for the horizontal and vertical directions for the pointer device (similar to mouse sensitivity). The speed is given as the ratio between the number of pixels the cursor moves on the display and how far the device is physically moved.

Other session properties applicable to pointer sessions are SCREEN_PROPERTY_BRUSH_CLIP_POSITION and SCREEN_PROPERTY_BRUSH_CLIP_SIZE, but it's not usually necessary to use these properties because when you use sessions, you can define the size and position via the session's input region. They are made available more so for windows.

Cursor shape

You can change your cursor shape for a window, or even a specific area within a window by using a pointer input session. If you're managing cursor shapes, you'll need to have specified the image associated with the shapes you want to use through the Screen configuration file, graphics.conf.

Valid shapes for your cursor are defined by the type Screen cursor shapes.

Refer to the cursor-type parameter of Configure display subsection for more details.

Once you've configured the cursor shapes, your application can specify a cursor shape for a window:

...
screen_session_t session;
int cursor_shape = SCREEN_CURSOR_SHAPE_ARROW;
screen_create_session_type(&session, context SCREEN_EVENT_POINTER);
screen_set_session_property_pv(session, SCREEN_PROPERTY_WINDOW, (void**) &window);
screen_set_session_property_iv(session, SCREEN_PROPERTY_CURSOR, cursor_shape);
...

or for a specific area:

...
screen_session_t session;
int cursor_shape = SCREEN_CURSOR_SHAPE_HAND;
screen_create_session_type(&session, context, SCREEN_EVENT_POINTER);
screen_set_session_property_pv(session, SCREEN_PROPERTY_WINDOW, (void**) &window);
screen_set_session_property_iv(session, SCREEN_PROPERTY_POSITION, pos);
screen_set_session_property_iv(session, SCREEN_PROPERTY_SIZE, size);
screen_set_session_property_iv(session, SCREEN_PROPERTY_CURSOR, cursor_shape);
...

Gaming mode

In gaming mode, you might want to hide the cursor. In this case, you can set the cursor shape to SCREEN_CURSOR_SHAPE_NONE:

...
screen_session_t session;
int cursor_shape = SCREEN_CURSOR_SHAPE_NONE;
screen_create_session_type(&session, context, SCREEN_EVENT_POINTER);
screen_set_session_property_pv(session, SCREEN_PROPERTY_WINDOW, (void**) &window);
screen_set_session_property_iv(session, SCREEN_PROPERTY_CURSOR, cursor_shape);
...

In the case of gaming, you might find it more useful to use displacement instead of the position of the cursor.