50.2.4.2 Image Instance Functions

Function: make-image-instance data &optional domain dest-types noerror

This function creates a new image-instance object.

data is an image instantiator, which describes the image (see Image Specifiers).

dest-types should be a list of allowed image instance types that can be generated. The dest-types list is unordered. If multiple destination types are possible for a given instantiator, the “most natural” type for the instantiator’s format is chosen. These are

XBM

xface

mono-pixmap, then color-pixmap, then pointer.

XPM

GIF

JPEG

PNG

TIFF

color-pixmap, then mono-pixmap, then pointer.

string

formatted-string formats

text, then mono-pixmap (not currently implemented), then color-pixmap (not currently implemented).

For the others, color-pixmap.

The other formats can only be instantiated as one type.

If you want to control more specifically the order of the types into which an image is instantiated, call make-image-instance repeatedly until it succeeds, passing less and less preferred destination types each time.

If dest-types is omitted, all possible types are allowed.

domain specifies the domain to which the image instance will be attached. This domain is termed the governing domain. The type of the governing domain depends on the image instantiator format. (Although, more correctly, it should probably depend on the image instance type.)

For example, pixmap image instances are specific to a device, but widget image instances are specific to a particular SXEmacs window because in order to display such a widget when two windows onto the same buffer want to display the widget, two separate underlying widgets must be created. That’s because a widget is actually a child window-system window, and all window-system windows have a unique existence on the screen. This means that the governing domain for a pixmap image instance will be some device (most likely, the only existing device), whereas the governing domain for a widget image instance will be some SXEmacs window.

If you specify an overly general domain (e.g. a frame when a window was wanted), an error is signaled. If you specify an overly specific domain (e.g. a window when a device was wanted), the corresponding general domain is fetched and used instead. For make-image-instance, it makes no difference whether you specify an overly specific domain or the properly general domain derived from it. However, it does matter when creating an image instance by instantiating a specifier or glyph (e.g. with glyph-image-instance), because the more specific domain causes spec lookup to start there and proceed to more general domains. (It would also matter when creating an image instance with an instantiator format of inherit, but we currently disallow this.)

If omitted, domain defaults to the selected window.

noerror controls what happens when the image cannot be generated. If nil, an error message is generated. If t, no messages are generated and this function returns nil. If anything else, a warning message is generated and this function returns nil.

Function: colorize-image-instance image-instance foreground background

This function makes the image instance be displayed in the given colors. Image instances come in two varieties: bitmaps, which are 1 bit deep which are rendered in the prevailing foreground and background colors; and pixmaps, which are of arbitrary depth (including 1) and which have the colors explicitly specified. This function converts a bitmap to a pixmap. If the image instance was a pixmap already, nothing is done (and nil is returned). Otherwise t is returned.

The following functions are

Function: image-instance-name image-instance

This function returns the name of the given image instance. The name is typically taken from the :file property of the instantiator if present, otherwise from the :data property.

Function: image-instance-domain image-instance

Return the governing domain of the given image-instance. The governing domain of an image instance is the domain that the image instance is specific to. It is NOT necessarily the domain that was given to the call to specifier-instance that resulted in the creation of this image instance. See make-image-instance for more information on governing domains.

Function: image-instance-string image-instance

This function returns the string of the given image instance. This will only be non-nil for text image instances.

Function: image-instance-file-name image-instance

This function returns the file name from which image-instance was read, if known.

Function: image-instance-mask-file-name image-instance

This function returns the file name from which image-instance’s mask was read, if known.

Pixmaps are considered to be three-dimensional. The height and width of the pixel array that is displayed, and the color depth of its pixels, are accessed with these functions.

Function: image-instance-depth image-instance

This function returns the depth of the image instance. This is 0 for a mono pixmap, or a positive integer for a color pixmap.

Function: image-instance-height image-instance

This function returns the height of the image instance, in pixels.

Function: image-instance-width image-instance

This function returns the width of the image instance, in pixels.

The hotspot is a point relative to the origin of the pixmap. When an image is used as a mouse pointer, the hotspot is the point on the image that sits over the location that the pointer points to. This is, for example, the tip of the arrow or the center of the crosshairs.

These functions access the coordinates of the hotspot. They simply return nil for a non-pointer image instance.

Function: image-instance-hotspot-x image-instance

This function returns the X coordinate of the image instance’s hotspot, if known.

Function: image-instance-hotspot-y image-instance

This function returns the Y coordinate of the image instance’s hotspot, if known.

Mono pixmaps and pointers may have their foreground and background colors set when instanced. Use these functions to access color information.

Function: image-instance-foreground image-instance

This function returns the foreground color of image-instance, if applicable. This will be a color instance or nil. (It will only be non-nil for colorized mono pixmaps and for pointers.)

Function: image-instance-background image-instance

This function returns the background color of image-instance, if applicable. This will be a color instance or nil. (It will only be non-nil for colorized mono pixmaps and for pointers.)