Function

Summary

Loads a cursor.

Package

capi

Signature

load-cursor filename-or-list => cursor

Arguments

filename-or-list

A string or a list.

Values

cursor

A cursor object.

Description

The function load-cursor loads a cursor from your cursor file, or loads a built-in cursor. It returns a cursor object which can be supplied as the value of the simple-pane :cursor initarg.

The cursor object can also be set with (setf simple-pane-cursor) to change a pane's cursor. This must be done in the process of the pane's interface.

If filename-or-list is a string, then it names a file which should be in a suitable format for the platform, as follows:

Microsoft Windows

.cur or .ani format.

Cocoa

TIFF format.

GTK+

Any image format that load-image supports.

Note: The image can be of any dimension, but it will be clipped to what the server thinks is an appropriate size, 32x32 or 16x16. Using large images would waste space, because the image would still be in memory.

The file is loaded at the time load-cursor is called, so the cursor object does not require the file at the time the cursor is displayed. The cursor object survives saving and delivering the image.

If filename-or-list is a list then it names a file or a built-in cursor to be loaded for a particular library, optionally together with arguments to be passed to the library. It should be of the form:

((libname_1
 filename_1
 arg_1a
 arg_1b
 ...)

 (libname_2
 filename_2
 arg_2a
 arg_2b
 ...)

 ...

 )

where libname_n is a keyword naming a supported library such as :cocoa, :win32 or :gtk (see default-library for the values) and filename_n is either a string naming the cursor file to load for this library or a keyword naming one of the built-in cursors. arg_na , arg_nb and so on are library-specific arguments. Currently these are not used on Microsoft Windows. Hotspot keyword arguments :x-hot and :y-hot are supported on Cocoa and GTK+ as in the example below. They specify the hotspot of the cursor. The values must be integers inside the image dimensions, that is they satisfy:

(and (> 
image-width
 
x-hot
 -1)

     (> 
image-height
 
y-hot
 -1))

On GTK+ the library-specific arguments also include the keywords :transparent-color-index and :type, which are passed to read-external-image. Note that supplying the transparent-color-index allows making a useful cursor with a simple format image file which does not have transparency.

Example

This example loads a standard Microsoft Windows cursor file:

(setq cur1 (capi:load-cursor "arrow_l"))

This example loads a standard Windows cursor file, and on Motif uses one of the built-in cursors:

(setq cur2 

      (capi:load-cursor '((:win32 "3dwns")

                          (:motif :v-double-arrow))))

This example loads a horizontal double-arrow on Windows, and a vertical double-arrow on Motif:

(setq cur3 

      (capi:load-cursor '((:win32 :h-double-arrow)

                          (:motif :v-double-arrow))))

This example loads a custom .cur file:

(setq cur4 

      (capi:load-cursor "C:/Temp/Animated_Cursors/1a.cur"))

In this extended example, firstly we load a custom cursor for two platforms:

(setq cur 

      (capi:load-cursor

       '((:win32

          "c:/WINNT40/Cursors/O_CROSS.CUR")

         (:cocoa

          "/Applications/iPhoto.app/Contents/Resources/retouch-cursor.tif"

          :x-hot 2

          :y-hot 2))))

Now we display a pane with the custom cursor loaded above:

(setq oo 

      (capi:contain

       (make-instance 

        'capi:output-pane

        :cursor cur

        :input-model

        `(((:button-1 :press)

           ,(lambda (&rest x) 

              (print x)))))))

We can remove the custom cursor:

(capi:apply-in-pane-process

 oo

 (lambda () 

   (setf (capi:simple-pane-cursor oo) 

         :default)))

And we can restore the custom cursor:

(capi:apply-in-pane-process

 oo

 (lambda ()

   (setf (capi:simple-pane-cursor oo)

         cur)))

See also

simple-pane