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. On Microsoft Windows, cursor files must be in .cur or .ani format. On Cocoa, cursor files should be in TIFF format. 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 (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, they are not used on Microsoft Windows, but hotspot arguments are supported on Cocoa as in the example below.

Examples

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