50.3.5 External Glyphs

There are two special kinds of glyph that are not displayed by SXEmacs. Instead, they are used to set the appearance of iconified frames and the mouse pointer. Because these uses are constrained by the window system, icons and pointers have their own special types See Glyph Types.

You may use a glyph as the icon for a frame. Do not create a new glyph; instead, change the specifications for the existing glyph frame-icon-glyph with set-glyph-image. This is a unique, predefined object. Although the natural usage is to set specifications for the global locale or a frame locale, you can also arrange for a special icon when a frame’s selected window displays a particular buffer by using a buffer locale.

The shape of the mouse pointer when over a particular section of a frame is controlled using various glyph variables. Since the image of a glyph is a specifier, it can be controlled on a per-buffer, per-frame, per-window, or per-device basis.

To use a glyph as the mouse pointer, in general you do not create a new glyph, but rather you change the specifications of various existing glyphs, such as text-pointer-glyph for the pointer used over text, modeline-pointer-glyph for the pointer used over the modeline, etc. Do an apropos over ‘pointer-glyph’ to find all of them. (Note also that you can temporarily set the mouse pointer to some specific shape by using set-frame-pointer, which takes an image instance, as obtained from calling glyph-image-instance on a glyph of type pointer – either one of the above-mentioned variables or one you created yourself. (See below for what it means to create a glyph of type pointer.) This pointer will last only until the next mouse motion event is processed or certain other things happen, such as creating or deleting a window. (In fact, the above-mentioned pointer glyph variables are implemented as part of the default handler for mouse motion events. If you want to customize this behavior, take a look at mode-motion-hook, or mouse-motion-handler if you really want to get low-level.)

You should use set-glyph-image to set the following variables, not setq.

Glyph: text-pointer-glyph

This variable specifies the shape of the mouse pointer when over text.

Glyph: nontext-pointer-glyph

This variable specifies the shape of the mouse pointer when over a buffer, but not over text. If unspecified in a particular domain, text-pointer-glyph is used.

Glyph: modeline-pointer-glyph

This variable specifies the shape of the mouse pointer when over the modeline. If unspecified in a particular domain, nontext-pointer-glyph is used.

Glyph: selection-pointer-glyph

This variable specifies the shape of the mouse pointer when over a selectable text region. If unspecified in a particular domain, text-pointer-glyph is used.

Glyph: gc-pointer-glyph

This variable specifies the shape of the mouse pointer when a garbage collection is in progress. If the selected window is on a window system and this glyph specifies a value (i.e. a pointer image instance) in the domain of the selected window, the pointer will be changed as specified during garbage collection. Otherwise, a message will be printed in the echo area, as controlled by gc-message.

Glyph: busy-pointer-glyph

This variable specifies the shape of the mouse pointer when SXEmacs is busy. If unspecified in a particular domain, the pointer is not changed when SXEmacs is busy.

Glyph: menubar-pointer-glyph

This variable specifies the shape of the mouse pointer when over the menubar. If unspecified in a particular domain, the window-system-provided default pointer is used.

Glyph: scrollbar-pointer-glyph

This variable specifies the shape of the mouse pointer when over a scrollbar. If unspecified in a particular domain, the window-system-provided default pointer is used.

Glyph: toolbar-pointer-glyph

This variable specifies the shape of the mouse pointer when over a toolbar. If unspecified in a particular domain, nontext-pointer-glyph is used.

Internally, these variables are implemented in default-mouse-motion-handler, and thus only take effect when the mouse moves. That function calls set-frame-pointer, which sets the current mouse pointer for a frame.

Function: set-frame-pointer frame image-instance

This function sets the mouse pointer of frame to the given pointer image instance. You should not call this function directly. (If you do, the pointer will change again the next time the mouse moves.)