+File: lispref.info, Node: Image Specifiers, Next: Image Instantiator Conversion, Up: Images
+
+Image Specifiers
+----------------
+
+ An image specifier is used to describe the actual image of a glyph.
+It works like other specifiers (*note Specifiers::), in that it contains
+a number of specifications describing how the image should appear in a
+variety of circumstances. These specifications are called "image
+instantiators". When XEmacs wants to display the image, it instantiates
+the image into an "image instance". Image instances are their own
+primitive object type (similar to font instances and color instances),
+describing how the image appears in a particular domain. (On the other
+hand, image instantiators, which are just descriptions of how the image
+should appear, are represented using strings or vectors.)
+
+ - Function: image-specifier-p object
+ This function returns non-`nil' if OBJECT is an image specifier.
+ Usually, an image specifier results from calling `glyph-image' on
+ a glyph.
+
+ - Function: make-image-specifier spec-list
+ This function creates a new image specifier object and initializes
+ it according to SPEC-LIST. *Note Specifiers::.
+
+ Note that, in practice, you rarely, if ever, need to actually
+ create an image specifier! (This function exists mainly for
+ completeness.) Pretty much the only use for image specifiers is to
+ control how glyphs are displayed, and the image specifier
+ associated with a glyph (the `image' property of a glyph) is
+ created automatically when a glyph is created and need not (and
+ cannot, for that matter) ever be changed (*note Glyphs::). In
+ fact, the design decision to create a separate image specifier
+ type, rather than make glyphs themselves be specifiers, is
+ debatable--the other properties of glyphs are rarely used and could
+ conceivably have been incorporated into the glyph's instantiator.
+ The rarely used glyph types (buffer, pointer, icon) could also
+ have been incorporated into the instantiator.
+
+ Image instantiators come in many formats: `xbm', `xpm', `gif',
+`jpeg', etc. This describes the format of the data describing the
+image. The resulting image instances also come in many
+types--`mono-pixmap', `color-pixmap', `text', `pointer', etc. This
+refers to the behavior of the image and the sorts of places it can
+appear. (For example, a color-pixmap image has fixed colors specified
+for it, while a mono-pixmap image comes in two unspecified shades
+"foreground" and "background" that are determined from the face of the
+glyph or surrounding text; a text image appears as a string of text and
+has an unspecified foreground, background, and font; a pointer image
+behaves like a mono-pixmap image but can only be used as a mouse
+pointer [mono-pixmap images cannot be used as mouse pointers]; etc.) It
+is important to keep the distinction between image instantiator format
+and image instance type in mind. Typically, a given image instantiator
+format can result in many different image instance types (for example,
+`xpm' can be instanced as `color-pixmap', `mono-pixmap', or `pointer';
+whereas `cursor-font' can be instanced only as `pointer'), and a
+particular image instance type can be generated by many different image
+instantiator formats (e.g. `color-pixmap' can be generated by `xpm',
+`gif', `jpeg', etc.).
+
+ *Note Image Instances::, for a more detailed discussion of image
+instance types.
+
+ An image instantiator should be a string or a vector of the form
+
+ `[FORMAT :KEYWORD VALUE ...]'
+
+ i.e. a format symbol followed by zero or more alternating
+keyword-value pairs. The "format" field should be a symbol, one of
+
+`nothing'
+ Don't display anything; no keywords are valid for this. Can only
+ be instanced as `nothing'.
+
+`string'
+ Display this image as a text string. Can only be instanced as
+ `text', although support for instancing as `mono-pixmap' should be
+ added.
+
+`formatted-string'
+ Display this image as a text string with replaceable fields,
+ similar to a modeline format string; not currently implemented.
+
+`xbm'
+ An X bitmap; only if X support was compiled into this XEmacs. Can
+ be instanced as `mono-pixmap', `color-pixmap', or `pointer'.
+
+`xpm'
+ An XPM pixmap; only if XPM support was compiled into this XEmacs.
+ Can be instanced as `color-pixmap', `mono-pixmap', or `pointer'.
+ XPM is an add-on library for X that was designed to rectify the
+ shortcomings of the XBM format. Most implementations of X include
+ the XPM library as a standard part. If your vendor does not, it
+ is highly recommended that you download it and install it. You
+ can get it from the standard XEmacs FTP site, among other places.
+
+`xface'
+ An X-Face bitmap, used to encode people's faces in e-mail messages;
+ only if X-Face support was compiled into this XEmacs. Can be
+ instanced as `mono-pixmap', `color-pixmap', or `pointer'.
+
+`gif'
+ A GIF87 or GIF89 image; only if GIF support was compiled into this
+ XEmacs. Can be instanced as `color-pixmap'. Note that XEmacs
+ includes GIF decoding functions as a standard part of it, so if
+ you have X support, you will normally have GIF support, unless you
+ explicitly disable it at configure time.
+
+`jpeg'
+ A JPEG-format image; only if JPEG support was compiled into this
+ XEmacs. Can be instanced as `color-pixmap'. If you have the JPEG
+ libraries present on your system when XEmacs is built, XEmacs will
+ automatically detect this and use them, unless you explicitly
+ disable it at configure time.
+
+`png'
+ A PNG/GIF24 image; only if PNG support was compiled into this
+ XEmacs. Can be instanced as `color-pixmap'.
+
+`tiff'
+ A TIFF-format image; only if TIFF support was compiled into this
+ XEmacs.
+
+`cursor-font'
+ One of the standard cursor-font names, such as `watch' or
+ `right_ptr' under X. Under X, this is, more specifically, any of
+ the standard cursor names from appendix B of the Xlib manual [also
+ known as the file `<X11/cursorfont.h>'] minus the `XC_' prefix. On
+ other window systems, the valid names will be specific to the type
+ of window system. Can only be instanced as `pointer'.
+
+`font'
+ A glyph from a font; i.e. the name of a font, and glyph index into
+ it of the form `FONT fontname index [[mask-font] mask-index]'.
+ Only if X support was compiled into this XEmacs. Currently can
+ only be instanced as `pointer', although this should probably be
+ fixed.
+
+`mswindows-resource'
+ An MS Windows pointer resource. Specifies a resource to retrieve
+ directly from the system (an OEM resource) or from a file,
+ particularly an executable file. If the resource is to be
+ retrieved from a file, use :file and optionally :resource-id.
+ Otherwise use :resource-id. Always specify :resource-type to
+ specify the type (cursor, bitmap or icon) of the resource.
+ Possible values for :resource-id are listed below. Can be
+ instanced as `pointer' or `color-pixmap'.
+
+`subwindow'
+ An embedded windowing system window. Can only be instanced as
+ `subwindow'.
+
+`button'
+ A button widget; either a push button, radio button or toggle
+ button. Can only be instanced as `widget'.
+
+`combo-box'
+ A drop list of selectable items in a widget, for editing text.
+ Can only be instanced as `widget'.
+
+`edit-field'
+ A text editing widget. Can only be instanced as `widget'.
+
+`label'
+ A static, text-only, widget; for displaying text. Can only be
+ instanced as `widget'.
+
+`layout'
+ A widget for controlling the positioning of children underneath it.
+ Through the use of nested layouts, a widget hierarchy can be
+ created which can have the appearance of any standard dialog box
+ or similar arrangement; all of this is counted as one "glyph" and
+ could appear in many of the places that expect a single glyph.
+ Can only be instanced as `widget'.
+
+`native-layout'
+ The native version of a layout widget. Can only be instanced as
+ `widget'.
+
+`progress-gauge'
+ A sliding widget, for showing progress. Can only be instanced as
+ `widget'.
+
+`tab-control'
+ A tab widget; a series of user selectable tabs. Can only be
+ instanced as `widget'.
+
+`tree-view'
+ A folding widget. Can only be instanced as `widget'.
+
+`scrollbar'
+ A scrollbar widget. Can only be instanced as `widget'.
+
+`autodetect'
+ XEmacs tries to guess what format the data is in. If X support
+ exists, the data string will be checked to see if it names a
+ filename. If so, and this filename contains XBM or XPM data, the
+ appropriate sort of pixmap or pointer will be created. [This
+ includes picking up any specified hotspot or associated mask
+ file.] Otherwise, if `pointer' is one of the allowable
+ image-instance types and the string names a valid cursor-font
+ name, the image will be created as a pointer. Otherwise, the
+ image will be displayed as text. If no X support exists, the
+ image will always be displayed as text.
+
+`inherit'
+ Inherit from the background-pixmap property of a face. Can only be
+ instanced as `mono-pixmap'.
+
+ The valid keywords are:
+
+`:data'
+ Inline data. For most formats above, this should be a string. For
+ XBM images, this should be a list of three elements: width,
+ height, and a string of bit data. This keyword is not valid for
+ instantiator format `nothing'.
+
+`:file'
+ Data is contained in a file. The value is the name of this file.
+ If both `:data' and `:file' are specified, the image is created
+ from what is specified in `:data' and the string in `:file'
+ becomes the value of the `image-instance-file-name' function when
+ applied to the resulting image-instance. This keyword is not
+ valid for instantiator formats `nothing', `string',
+ `formatted-string', `cursor-font', `font', and `autodetect'.
+
+`:foreground'
+`:background'
+ For `xbm', `xface', `cursor-font', and `font'. These keywords
+ allow you to explicitly specify foreground and background colors.
+ The argument should be anything acceptable to
+ `make-color-instance'. This will cause what would be a
+ `mono-pixmap' to instead be colorized as a two-color color-pixmap,
+ and specifies the foreground and/or background colors for a pointer
+ instead of black and white.
+
+`:mask-data'
+ For `xbm' and `xface'. This specifies a mask to be used with the
+ bitmap. The format is a list of width, height, and bits, like for
+ `:data'.
+
+`:mask-file'
+ For `xbm' and `xface'. This specifies a file containing the mask
+ data. If neither a mask file nor inline mask data is given for an
+ XBM image, and the XBM image comes from a file, XEmacs will look
+ for a mask file with the same name as the image file but with
+ `Mask' or `msk' appended. For example, if you specify the XBM file
+ `left_ptr' [usually located in `/usr/include/X11/bitmaps'], the
+ associated mask file `left_ptrmsk' will automatically be picked up.
+
+`:hotspot-x'
+`:hotspot-y'
+ For `xbm' and `xface'. These keywords specify a hotspot if the
+ image is instantiated as a `pointer'. Note that if the XBM image
+ file specifies a hotspot, it will automatically be picked up if no
+ explicit hotspot is given.
+
+`:color-symbols'
+ Only for `xpm'. This specifies an alist that maps strings that
+ specify symbolic color names to the actual color to be used for
+ that symbolic color (in the form of a string or a color-specifier
+ object). If this is not specified, the contents of
+ `xpm-color-symbols' are used to generate the alist.
+
+`:resource-id'
+ Only for `mswindows-resource'. This must be either an integer
+ (which directly specifies a resource number) or a string. Valid
+ strings are
+
+ For bitmaps:
+
+ "close", "uparrow", "dnarrow", "rgarrow", "lfarrow", "reduce",
+ "zoom", "restore", "reduced", "zoomd", "restored", "uparrowd",
+ "dnarrowd", "rgarrowd", "lfarrowd", "mnarrow", "combo",
+ "uparrowi", "dnarrowi", "rgarrowi", "lfarrowi", "size", "btsize",
+ "check", "checkboxes", and "btncorners".
+
+ For cursors:
+
+ "normal", "ibeam", "wait", "cross", "up", "sizenwse", "sizenesw",
+ "sizewe", "sizens", "sizeall", and "no".
+
+ For icons:
+
+ "sample", "hand", "ques", "bang", "note", and "winlogo".
+
+`:resource-type'
+ Only for `mswindows-resource'. This must be a symbol, either
+ `cursor', `icon', or `bitmap', specifying the type of resource to
+ be retrieved.
+
+`:face'
+ Only for `inherit'. This specifies the face to inherit from. For
+ widgets this also specifies the face to use for display. It
+ defaults to gui-element-face.
+
+ Keywords accepted as menu item specs are also accepted by widgets.
+These are `:selected', `:active', `:suffix', `:keys', `:style',
+`:filter', `:config', `:included', `:key-sequence', `:accelerator',
+`:label' and `:callback'.
+
+ If instead of a vector, the instantiator is a string, it will be
+converted into a vector by looking it up according to the specs in the
+`console-type-image-conversion-list' for the console type of the domain
+(usually a window; sometimes a frame or device) over which the image is
+being instantiated.
+
+ If the instantiator specifies data from a file, the data will be
+read in at the time that the instantiator is added to the image
+specifier (which may be well before the image is actually displayed),
+and the instantiator will be converted into one of the inline-data
+forms, with the filename retained using a `:file' keyword. This
+implies that the file must exist when the instantiator is added to the
+image, but does not need to exist at any other time (e.g. it may safely
+be a temporary file).
+
+ - Function: valid-image-instantiator-format-p format
+ This function returns non-`nil' if FORMAT is a valid image
+ instantiator format. Note that the return value for many formats
+ listed above depends on whether XEmacs was compiled with support
+ for that format.
+
+ - Function: image-instantiator-format-list
+ This function return a list of valid image-instantiator formats.
+
+ - Variable: xpm-color-symbols
+ This variable holds definitions of logical color-names used when
+ reading XPM files. Elements of this list should be of the form
+ `(COLOR-NAME FORM-TO-EVALUATE)'. The COLOR-NAME should be a
+ string, which is the name of the color to define; the
+ FORM-TO-EVALUATE should evaluate to a color specifier object, or a
+ string to be passed to `make-color-instance' (*note Colors::). If
+ a loaded XPM file references a symbolic color called COLOR-NAME,
+ it will display as the computed color instead.
+
+ The default value of this variable defines the logical color names
+ `"foreground"' and `"background"' to be the colors of the
+ `default' face.
+
+ - Variable: x-bitmap-file-path
+ A list of the directories in which X bitmap files may be found.
+ If nil, this is initialized from the `"*bitmapFilePath"' resource.
+ This is used by the `make-image-instance' function (however, note
+ that if the environment variable `XBMLANGPATH' is set, it is
+ consulted first).
+
+\1f
+File: lispref.info, Node: Image Instantiator Conversion, Next: Image Instances, Prev: Image Specifiers, Up: Images
+
+Image Instantiator Conversion
+-----------------------------
+
+ - Function: set-console-type-image-conversion-list console-type list
+ This function sets the image-conversion-list for consoles of the
+ given CONSOLE-TYPE. The image-conversion-list specifies how image
+ instantiators that are strings should be interpreted. Each
+ element of the list should be a list of two elements (a regular
+ expression string and a vector) or a list of three elements (the
+ preceding two plus an integer index into the vector). The string
+ is converted to the vector associated with the first matching
+ regular expression. If a vector index is specified, the string
+ itself is substituted into that position in the vector.
+
+ Note: The conversion above is applied when the image instantiator
+ is added to an image specifier, not when the specifier is actually
+ instantiated. Therefore, changing the image-conversion-list only
+ affects newly-added instantiators. Existing instantiators in
+ glyphs and image specifiers will not be affected.
+
+ - Function: console-type-image-conversion-list console-type
+ This function returns the image-conversion-list for consoles of
+ the given CONSOLE-TYPE.
+
+\1f
+File: lispref.info, Node: Image Instances, Prev: Image Instantiator Conversion, Up: Images
+
+Image Instances
+---------------
+
+ Image-instance objects encapsulate the way a particular image
+(pixmap, etc.) is displayed on a particular device.
+
+ In most circumstances, you do not need to directly create image
+instances; use a glyph instead. However, it may occasionally be useful
+to explicitly create image instances, if you want more control over the
+instantiation process.
+
+ - Function: image-instance-p object
+ This function returns non-`nil' if OBJECT is an image instance.
+
+* Menu:
+
+* Image Instance Types:: Each image instances has a particular type.
+* Image Instance Functions:: Functions for working with image instances.
+
+\1f
+File: lispref.info, Node: Image Instance Types, Next: Image Instance Functions, Up: Image Instances
+
+Image Instance Types
+....................
+
+ Image instances come in a number of different types. The type of an
+image instance specifies the nature of the image: Whether it is a text
+string, a mono pixmap, a color pixmap, etc.
+
+ The valid image instance types are
+
+`nothing'
+ Nothing is displayed.
+
+`text'
+ Displayed as text. The foreground and background colors and the
+ font of the text are specified independent of the pixmap.
+ Typically these attributes will come from the face of the
+ surrounding text, unless a face is specified for the glyph in
+ which the image appears.
+
+`mono-pixmap'
+ Displayed as a mono pixmap (a pixmap with only two colors where the
+ foreground and background can be specified independent of the
+ pixmap; typically the pixmap assumes the foreground and background
+ colors of the text around it, unless a face is specified for the
+ glyph in which the image appears).
+
+`color-pixmap'
+ Displayed as a color pixmap.
+
+`pointer'
+ Used as the mouse pointer for a window.
+
+`subwindow'
+ A child window that is treated as an image. This allows (e.g.)
+ another program to be responsible for drawing into the window.
+ Not currently implemented.
+
+ - Function: valid-image-instance-type-p type
+ This function returns non-`nil' if TYPE is a valid image instance
+ type.
+
+ - Function: image-instance-type-list
+ This function returns a list of the valid image instance types.
+
+ - Function: image-instance-type image-instance
+ This function returns the type of the given image instance. The
+ return value will be one of `nothing', `text', `mono-pixmap',
+ `color-pixmap', `pointer', or `subwindow'.
+
+ - Function: text-image-instance-p object
+ This function returns non-`nil' if OBJECT is an image instance of
+ type `text'.
+
+ - Function: mono-pixmap-image-instance-p object
+ This function returns non-`nil' if OBJECT is an image instance of
+ type `mono-pixmap'.
+
+ - Function: color-pixmap-image-instance-p object
+ This function returns non-`nil' if OBJECT is an image instance of
+ type `color-pixmap'.
+
+ - Function: pointer-image-instance-p object
+ This function returns non-`nil' if OBJECT is an image instance of
+ type `pointer'.
+
+ - Function: subwindow-image-instance-p object
+ This function returns non-`nil' if OBJECT is an image instance of
+ type `subwindow'.
+
+ - Function: nothing-image-instance-p object
+ This function returns non-`nil' if OBJECT is an image instance of
+ type `nothing'.
+
+ - Function: widget-image-instance-p object
+ Return t if OBJECT is an image instance of type `widget'.
+
+\1f
+File: lispref.info, Node: Image Instance Functions, Prev: Image Instance Types, Up: Image Instances
+
+Image Instance Functions
+........................
+
+ - Function: make-image-instance data &optional domain dest-types
+ no-error
+ This function creates a new image-instance object.
+
+ DATA is an image instantiator, which describes the image (*note
+ 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. (For XBM,
+ the most natural types are `mono-pixmap', followed by
+ `color-pixmap', followed by `pointer'. For the other normal image
+ formats, the most natural types are `color-pixmap', followed by
+ `mono-pixmap', followed by `pointer'. For the string and
+ formatted-string formats, the most natural types are `text',
+ followed by `mono-pixmap' (not currently implemented), followed by
+ `color-pixmap' (not currently implemented). For MS Windows
+ resources, the most natural type for pointer resources is
+ `pointer', and for the others it's `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, just 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 XEmacs 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
+ XEmacs 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.
+ #### We should fix this.) n If omitted, DOMAIN defaults to the
+ selected window.
+
+ NO-ERROR 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.
+
+ - Function: image-instance-name image-instance
+ This function returns the name of the given image instance.
+
+ - 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.
+
+ - 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.
+
+ - Function: image-instance-hotspot-x image-instance
+ This function returns the X coordinate of the image instance's
+ hotspot, if known. This 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.
+
+ This will always be `nil' for a non-pointer image instance.
+
+ - Function: image-instance-hotspot-y image-instance
+ This function returns the Y coordinate of the image instance's
+ hotspot, if known.
+
+ - 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.)
+
+\1f
+File: lispref.info, Node: Glyph Types, Next: Mouse Pointer, Prev: Images, Up: Glyphs
+
+Glyph Types
+===========
+
+ Each glyph has a particular type, which controls how the glyph's
+image is generated. Each glyph type has a corresponding list of
+allowable image instance types that can be generated. When you call
+`glyph-image-instance' to retrieve the image instance of a glyph,
+XEmacs does the equivalent of calling `make-image-instance' and passing
+in DEST-TYPES the list of allowable image instance types for the
+glyph's type.
+
+ * `buffer' glyphs can be used as the begin-glyph or end-glyph of an
+ extent, in the modeline, and in the toolbar. Their image can be
+ instantiated as `nothing', `mono-pixmap', `color-pixmap', `text',
+ and `subwindow'.
+
+ * `pointer' glyphs can be used to specify the mouse pointer. Their
+ image can be instantiated as `pointer'.
+
+ * `icon' glyphs can be used to specify the icon used when a frame is
+ iconified. Their image can be instantiated as `mono-pixmap' and
+ `color-pixmap'.
+
+ - Function: glyph-type glyph
+ This function returns the type of the given glyph. The return
+ value will be a symbol, one of `buffer', `pointer', or `icon'.
+
+ - Function: valid-glyph-type-p glyph-type
+ Given a GLYPH-TYPE, this function returns non-`nil' if it is valid.
+
+ - Function: glyph-type-list
+ This function returns a list of valid glyph types.
+
+ - Function: buffer-glyph-p object
+ This function returns non-`nil' if OBJECT is a glyph of type
+ `buffer'.
+
+ - Function: icon-glyph-p object
+ This function returns non-`nil' if OBJECT is a glyph of type
+ `icon'.
+
+ - Function: pointer-glyph-p object
+ This function returns non-`nil' if OBJECT is a glyph of type
+ `pointer'.
+
+\1f
+File: lispref.info, Node: Mouse Pointer, Next: Redisplay Glyphs, Prev: Glyph Types, Up: Glyphs
+
+Mouse Pointer
+=============
+
+ 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.
+
+ 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 XEmacs
+ is busy. If unspecified in a particular domain, the pointer is
+ not changed when XEmacs 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.)
+
+\1f
+File: lispref.info, Node: Redisplay Glyphs, Next: Subwindows, Prev: Mouse Pointer, Up: Glyphs
+
+Redisplay Glyphs
+================
+
+ - Glyph: truncation-glyph
+ This variable specifies what is displayed at the end of truncated
+ lines.
+
+ - Glyph: continuation-glyph
+ This variable specifies what is displayed at the end of wrapped
+ lines.
+
+ - Glyph: octal-escape-glyph
+ This variable specifies what to prefix character codes displayed
+ in octal with.
+
+ - Glyph: hscroll-glyph
+ This variable specifies what to display at the beginning of
+ horizontally scrolled lines.
+
+ - Glyph: invisible-text-glyph
+ This variable specifies what to use to indicate the presence of
+ invisible text. This is the glyph that is displayed when an
+ ellipsis is called for, according to `selective-display-ellipses'
+ or `buffer-invisibility-spec'). Normally this is three dots
+ ("...").
+
+ - Glyph: control-arrow-glyph
+ This variable specifies what to use as an arrow for control
+ characters.
+
+\1f
+File: lispref.info, Node: Subwindows, Prev: Redisplay Glyphs, Up: Glyphs
+
+Subwindows
+==========
+
+ Subwindows are not currently implemented.
+
+ - Function: subwindowp object
+ This function returns non-`nil' if OBJECT is a subwindow.
+
+\1f
+File: lispref.info, Node: Annotations, Next: Display, Prev: Glyphs, Up: Top
+
+Annotations
+***********
+
+ An "annotation" is a pixmap or string that is not part of a buffer's
+text but is displayed next to a particular location in a buffer.
+Annotations can be displayed intermixed with text, in any whitespace at
+the beginning or end of a line, or in a special area at the left or
+right side of the frame called a "margin", whose size is controllable.
+Annotations are implemented using extents (*note Extents::); but you
+can work with annotations without knowing how extents work.
+
+* Menu:
+
+* Annotation Basics:: Introduction to annotations.
+* Annotation Primitives:: Creating and deleting annotations.
+* Annotation Properties:: Retrieving and changing the characteristics
+ of an annotation.
+* Margin Primitives:: Controlling the size of the margins.
+* Locating Annotations:: Looking for annotations in a buffer.
+* Annotation Hooks:: Hooks called at certain times during an
+ annotation's lifetime.
+
+\1f
projects / chise / xemacs-chise.git- / blobdiff