README.definable-cursor

Definable Mouse Cursors for Window Maker
----------------------------------------

The definable-cursor feature allows user-definable mouse cursors; the
cursors can either be the built-in ones from the X11 cursor font, or
they can be bitmap (XBM) files.  User-definable cursors can be useful
for theme-builders, lefthanders, and the visually impaired.


Defining Your Own Cursors
-------------------------

A cursor specification takes one of the following forms in the
~/GNUstep/Defaults/WindowMaker file:

    (none)
    (builtin, <cursor-name>)
    (bitmap, <bitmap-filename>, <mask-filename>)

They have the following meanings:

    none     The cursor is inherited from the parent window (often,
             this means the root window).

    builtin  Use the cursor named <cursor-name> from X11's set of
             built-in cursors.  The names are the same as you use
             with 'xsetroot -cursor_name'.  See the xsetroot(1) man
             page for more information.

    bitmap   Use the bitmap in <bitmap-filename> as the foreground
             cursor bitmap, and the one in <mask-filename> as the
             background (mask) bitmap.  This is pretty much the same
             as 'xsetroot -cursor', except that Window Maker searches
             for the bitmaps along its PixmapPath.

You can set the following cursor types (they're shown here with their
defaults):

    NormalCursor            = (builtin, left_ptr);
    ArrowCursor             = (builtin, top_left_arrow);
    MoveCursor              = (builtin, fleur);
    TopLeftResizeCursor     = (builtin, top_left_corner);
    TopRightResizeCursor    = (builtin, top_right_corner);
    BottomLeftResizeCursor  = (builtin, bottom_left_corner);
    BottomRightResizeCursor = (builtin, bottom_right_corner);
    VerticalResizeCursor    = (builtin, sb_v_double_arrow);
    HorizontalResizeCursor  = (builtin, sb_h_double_arrow);
    WaitCursor              = (builtin, watch);
    QuestionCursor          = (builtin, question_arrow);
    TextCursor              = (builtin, xterm);
    SelectCursor            = (builtin, cross);

The following cursor types are allowed, but they're deprecated (Window
Maker used them in the past, but doesn't use them anymore):

    ResizeCursor            = (builtin, sizing);


Using Cursors with 'getstyle' and 'setstyle'
--------------------------------------------

The 'getstyle' and 'setstyle' style/theme-management utilities can
handle user-definable cursors.  By default, 'getstyle' ignores cursor
definitions; using 'getstyle -t' to get theme-related settings will
also include any cursors you've defined in the resulting style file.

However, by default, 'setstyle' does NOT ignore cursor settings.  If
you wish to set a style or theme without installing cursor settings,
you can use 'setstyle --no-cursors' to ignore the cursor definitions.


Random Notes
------------

Most X11 cursors are 16x16 bitmaps.  Many X servers can actually handle
larger cursors, though.  To check, use:

    xdpyinfo

and in the resulting output look for a line such as:

    largest cursor:    64x64

The example above indicates that my X server can handle cursors up to
64 pixels wide by 64 pixels high.

You can create your own bitmap cursors using the 'bitmap' program that
accompanies most X11 distributions.  For example bitmap cursors and
masks, see <http://www.pobox.com/~jmknoble/WindowMaker/cursors/>.