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 isn't 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 across multiple displays

When you have multiple displays, the effect of your cursor moving from one display to another
is achieved by using the SCREEN_PROPERTY_ALTERNATE property of pointer sessions. By
creating appropriate pointer sessions that are associated to each display and setting each of their
SCREEN_PROPERTY_ALTERNATE property to the appropriate session, you can make your pointer
jump from one session to another. When the pointer jumps to a different session, the cursor becomes
visible on a different display.

Let's say that you have two displays and you want to show your cursor on the first display.
As the pointer device moves towards the right, you want the cursor to move and eventually be shown on
the second display.

Figure 1. Moving your cursor across two displays

In this example, your application uses two displays and two pointer sessions.

Figure 2. Displays and pointer sessions

Create pointer sessions at the boundaries of your displays where you want the cursor to stop and
start being visble. The size of your pointer sessions doesn't need to be more than one pixel in width
for the purpose of these sessions. The wider the sessions, the more space you'll see between where the
cursor disappears from one display and reappears on the second. In this example, the cursor is travelling
from left to right, from Display 1 (dpy-1) to Display 2 (dpy-2). Therefore, you need to create two
sessions. Session 1 (ssn-1) is positioned at the right-most edge of Display 1 because that is the point
where the cursor will stop being visible on Display 1. Session 2 (ssn-2) is positioned at the left-most
edge of Display 2 because that is the point where the cursor will start being visible on Display 2.
For example:

After you create your sessions, you must set the SCREEN_PROPERTY_ALTERNATE property of
either one of the sessions so that they are associated with each other. The SCREEN_PROPERTY_ALTERNATE
property indicates which session next receives input. In this example, you need to indicate that
ssn-2 is the alternae for ssn-1 because the position of ssn-2 is where you want the cursor to be visible
once it leaves ssn-1. For example:

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.