CVS update by vins MODIFIED: xemacs/man/lispref, glyphs.texi ...

User: vins Date: 05/02/23 02:54:36 Modified: xemacs/man/lispref Tag: release-21-4 extents.texi faces.texi glyphs.texi lispref.texi Log: Update glyphs documentation. Expand package name field in package-ui.el. Revision Changes Path No revision No revision 1.266.2.81 +5 -0 XEmacs/xemacs/lisp/ChangeLog Index: ChangeLog =================================================================== RCS file: /pack/xemacscvs/XEmacs/xemacs/lisp/ChangeLog,v retrieving revision 1.266.2.80 retrieving revision 1.266.2.81 diff -u -r1.266.2.80 -r1.266.2.81 --- ChangeLog 2005/02/19 22:02:00 1.266.2.80 +++ ChangeLog 2005/02/23 01:54:26 1.266.2.81 ＠＠ -1,3 +1,8 ＠＠ +2005-02-21 Norbert Koch <viteno(a)xemacs.org&gt; + + * package-ui.el (pui-list-packages): MF21.5, adapt to longer + package names, quell a byte-compiler warning, doc fix. + 2005-02-16 Aidan Kehoe <kehoea(a)parhasard.net&gt; * buffer.el (pop-to-buffer): 1.13.2.5 +12 -11 XEmacs/xemacs/lisp/package-ui.el Index: package-ui.el =================================================================== RCS file: /pack/xemacscvs/XEmacs/xemacs/lisp/package-ui.el,v retrieving revision 1.13.2.4 retrieving revision 1.13.2.5 diff -u -r1.13.2.4 -r1.13.2.5 --- package-ui.el 2004/06/22 01:49:47 1.13.2.4 +++ package-ui.el 2005/02/23 01:54:27 1.13.2.5 ＠＠ -509,14 +509,15 ＠＠ (defun pui-display-maintainer (&optional no-error event) "Display a package's maintainer in the minibuffer." (interactive) - (let (extent pkg-sym info maintainer) + (let (extent ;pkg-sym + info maintainer) (save-excursion (beginning-of-line) (if (setq extent (extent-at (point) (current-buffer) 'pui)) (progn - (setq pkg-sym (extent-property extent 'pui-package) - info (extent-property extent 'pui-info) - maintainer (package-get-info-prop info 'maintainer)) + (setq ;pkg-sym (extent-property extent 'pui-package) + info (extent-property extent 'pui-info) + maintainer (package-get-info-prop info 'maintainer)) (message (format "Maintainer: %s" maintainer))) (if no-error (clear-message nil) ＠＠ -564,7 +565,7 ＠＠ `\\[pui-toggle-package-delete-key]' to select/unselect the current package for removal. `\\[pui-add-required-packages]' to add any packages required by those selected. `\\[pui-install-selected-packages]' to install/delete selected packages. - `\\[pui-display-info]' to display additional information about the package in the modeline. + `\\[pui-display-info]' to display additional information about the package in the minibuffer. `\\[pui-display-maintainer]' to display the package's maintainer in the minibuffer `\\[pui-list-packages]' to refresh the package list. `\\[pui-toggle-verbosity-redisplay]' to toggle between a verbose and non-verbose display. ＠＠ -606,11 +607,11 ＠＠ ")) (if pui-list-verbose - (insert " Latest Installed - Package name Vers. Vers. Description + (insert " Latest Installed + Package name Vers. Vers. Description ") - (insert " Latest - Package name Vers. Description + (insert " Latest + Package name Vers. Description ")) (insert sep-string) (setq start (point)) ＠＠ -639,13 +640,13 ＠＠ ((numberp current-vers) (setq current-vers (format "%.2f" current-vers)))) (insert - (format "%s %-15s %-5.2f %-5s %s\n" + (format "%s %-20s %-5.2f %-5s %s\n" (car disp) pkg-sym (if (stringp version) (string-to-number version) version) current-vers desc))) - (insert (format "%s %-15s %-5s %s\n" + (insert (format "%s %-20s %-5s %s\n" (car disp) pkg-sym version desc))) (save-excursion No revision No revision 1.116.2.56 +10 -0 XEmacs/xemacs/man/ChangeLog Index: ChangeLog =================================================================== RCS file: /pack/xemacscvs/XEmacs/xemacs/man/ChangeLog,v retrieving revision 1.116.2.55 retrieving revision 1.116.2.56 diff -u -r1.116.2.55 -r1.116.2.56 --- ChangeLog 2005/02/06 19:23:42 1.116.2.55 +++ ChangeLog 2005/02/23 01:54:32 1.116.2.56 ＠＠ -1,3 +1,13 ＠＠ +2005-02-22 Stephen J. Turnbull <stephen(a)xemacs.org&gt; + + * lispref/glyphs.texi: Complete reorganization, some content updated. + * lispref/lispref.texi (Top): Update menu to match. + * lispref/extents.texi (Extent Properties): Update xref. + * lispref/faces.texi (Face Properties): Background pixmaps can be + used on GTK and MS Windows. + (Face Convenience Functions): Cross-reference glyph interface. + Background pixmap is an image specifier, not a glyph. + 2005-02-06 Vin Shelton <acs(a)xemacs.org&gt; * XEmacs 21.4.17 is released No revision No revision 1.9.2.2 +1 -1 XEmacs/xemacs/man/lispref/extents.texi Index: extents.texi =================================================================== RCS file: /pack/xemacscvs/XEmacs/xemacs/man/lispref/extents.texi,v retrieving revision 1.9.2.1 retrieving revision 1.9.2.2 diff -u -r1.9.2.1 -r1.9.2.2 --- extents.texi 2003/08/14 23:42:55 1.9.2.1 +++ extents.texi 2005/02/23 01:54:34 1.9.2.2 ＠＠ -555,7 +555,7 ＠＠ the extent. This takes precedence over the ＠code{text-pointer-glyph} and ＠code{nontext-pointer-glyph} variables. If for any reason this glyph is an invalid pointer, the standard glyphs will be used as -fallbacks. ＠xref{Mouse Pointer}. +fallbacks. ＠xref{External Glyphs}. ＠item detachable (Boolean) Whether this extent becomes detached when all of the text it 1.3.2.1 +10 -2 XEmacs/xemacs/man/lispref/faces.texi Index: faces.texi =================================================================== RCS file: /pack/xemacscvs/XEmacs/xemacs/man/lispref/faces.texi,v retrieving revision 1.3 retrieving revision 1.3.2.1 diff -u -r1.3 -r1.3.2.1 --- faces.texi 2001/04/12 18:22:13 1.3 +++ faces.texi 2005/02/23 01:54:34 1.3.2.1 ＠＠ -164,7 +164,7 ＠＠ ＠item background-pixmap The pixmap displayed in the background of the face. Only used by faces -on X devices. +on GUI devices, currently X11, GTK, and Microsoft Windows. ＠item underline Underline all text covered by this face. ＠＠ -373,6 +373,14 ＠＠ be a list of the form ＠code{(＠var{width} ＠var{height} ＠var{data})} where ＠var{width} and ＠var{height} are the size in pixels, and ＠var{data} is a string, containing the raw bits of the bitmap. + +Similarly to how the glyph's image specifier works ＠xref{Creating +Glyphs}, you don't create your own image specifier, but rather add +specifications to the existing one. Note that the image instance that is +generated in order to actually display the background pixmap is of type +＠code{mono-pixmap}, meaning that it's a two-color image and the +foreground and background of the image get filled in with the +corresponding colors from the face. (#### Is this still true?) ＠end deffn ＠deffn Command set-face-font face font &optional locale tag-set how-to-add ＠＠ -393,7 +401,7 ＠＠ ＠end defun ＠defun face-background-pixmap face &optional locale tag-set exact-p -This function return the background-pixmap glyph object of face +This function returns the background-pixmap image specifier of face ＠var{face}. ＠end defun 1.3.2.2 +1721 -1083XEmacs/xemacs/man/lispref/glyphs.texi Index: glyphs.texi =================================================================== RCS file: /pack/xemacscvs/XEmacs/xemacs/man/lispref/glyphs.texi,v retrieving revision 1.3.2.1 retrieving revision 1.3.2.2 diff -u -r1.3.2.1 -r1.3.2.2 --- glyphs.texi 2001/12/17 05:49:14 1.3.2.1 +++ glyphs.texi 2005/02/23 01:54:34 1.3.2.2 ＠＠ -1,740 +1,626 ＠＠ ＠c -*-texinfo-*- ＠c This is part of the XEmacs Lisp Reference Manual. ＠c Copyright (C) 1995, 1996 Ben Wing. +＠c Copyright (C) 2004 Free Software Foundation, Inc. ＠c See the file lispref.texi for copying conditions. ＠setfilename ../../info/glyphs.info ＠node Glyphs, Annotations, Faces and Window-System Objects, top ＠chapter Glyphs ＠cindex glyphs - A ＠dfn{glyph} is an object that is used for pixmaps, widgets and + A ＠dfn{glyph} is an object that is used for pixmaps, widgets, and images of all sorts, as well as for things that ``act'' like pixmaps, such as non-textual strings (＠dfn{annotations}) displayed in a buffer or in the margins. It is used in begin-glyphs and end-glyphs attached to extents, marginal and textual annotations, overlay arrows (＠code{overlay-arrow-*} variables), toolbar buttons, mouse pointers, frame icons, truncation and continuation markers, and the -like. (Basically, any place there is an image or something that acts -like an image, there will be a glyph object representing it.) +like. Basically, any place there is an image or something that acts +like an image, there will be a glyph object representing it. - The actual image that is displayed (as opposed to its position or -clipping) is defined by an ＠dfn{image specifier} object contained -within the glyph. The separation between an image specifier object -and a glyph object is made because the glyph includes other properties -than just the actual image: e.g. the face it is displayed in (for text -images), the alignment of the image (when it is in a buffer), etc. - ＠defun glyphp object This function returns ＠code{t} if ＠var{object} is a glyph. ＠end defun -＠menu -* Glyph Functions:: Functions for working with glyphs. -* Images:: Graphical images displayed in a frame. -* Glyph Types:: Each glyph has a particular type. -* Mouse Pointer:: Controlling the mouse pointer. -* Redisplay Glyphs:: Glyphs controlling various redisplay functions. -* Subwindows:: Inserting an externally-controlled subwindow - into a buffer. -* Glyph Examples:: Examples of how to work with glyphs. -＠end menu - -＠node Glyph Functions -＠section Glyph Functions - ＠menu -* Creating Glyphs:: Creating new glyphs. -* Glyph Properties:: Accessing and modifying a glyph's properties. -* Glyph Convenience Functions:: - Convenience functions for accessing particular - properties of a glyph. -* Glyph Dimensions:: Determining the height, width, etc. of a glyph. +* Glyph Intro:: Glyphs are abstract image specifications. +* Images:: Specifying the appearance of glyphs. +* Using Glyphs:: Creating and displaying glyphs. +* Manipulating Glyphs:: Getting and setting glyph properties. +* Glyph Examples:: Examples of how to work with glyphs. ＠end menu -＠node Creating Glyphs -＠subsection Creating Glyphs - -＠defun make-glyph &optional spec-list type -This function creates a new glyph object of type ＠var{type}. -＠var{spec-list} is used to initialize the glyph's image. It is -typically an image instantiator (a string or a vector; ＠ref{Image -Specifiers}), but can also be a list of such instantiators (each one in -turn is tried until an image is successfully produced), a cons of a -locale (frame, buffer, etc.) and an instantiator, a list of such conses, -or any other form accepted by ＠code{canonicalize-spec-list}. -＠xref{Specifiers}, for more information about specifiers. - -＠var{type} specifies the type of the glyph, which specifies in which -contexts the glyph can be used, and controls the allowable image types -into which the glyph's image can be instantiated. ＠var{type} should be -one of ＠code{buffer} (used for glyphs in an extent, the modeline, the -toolbar, or elsewhere in a buffer), ＠code{pointer} (used for the -mouse-pointer), or ＠code{icon} (used for a frame's icon), and defaults -to ＠code{buffer}. ＠xref{Glyph Types}. +＠node Glyph Intro +＠section Glyph Introduction -A glyph in XEmacs does ＠strong{NOT} refer to a single unit of textual -display (the XEmacs term for this is ＠dfn{rune}), but rather is an + In XEmacs, ``glyph'' does ＠strong{not} refer to a single unit of textual +display (the XEmacs term for that is ＠dfn{rune}, and runes are confined +to the internal implementation of redisplay), but rather is an object encapsulating a graphical element, such as an image or widget (an -element such as a button or text field; ＠dfn{widget} is the term for -this under X Windows, and it's called a ＠dfn{control} under MS Windows). +active GUI element such as a button or text entry field; X11 calls this a +＠dfn{widget}, while MS Windows uses the term ＠dfn{control}). This graphical element could appear in a buffer, a margin, a gutter, or -a toolbar, or as a mouse pointer or an icon, for example. +a toolbar, or even externally to XEmacs as a mouse pointer or an icon, +for example. -Creating a glyph using ＠code{make-glyph} does not specify ＠emph{where} -the glyph will be used, but it does specify ＠emph{what} the glyph will -look like. In particular, ＠var{spec-list} is used to specify this, and it's -used to initialize the glyph's ＠code{image} property, which is an image -specifier. (Note that ＠dfn{image} as used in the context of a glyph's -＠code{image} property or in the terms ＠dfn{image specifier}, ＠dfn{image -instantiator}, or ＠dfn{image instance} does not refer to what people -normally think of as an image (which in XEmacs is called a -＠dfn{pixmap}), but to any graphical element---a pixmap, a widget, or -even a block of text, when used in the places that call for a glyph.) -The format of the ＠var{spec-list} is typically an image instantiator (a string -or a vector; ＠ref{Image Specifiers}), but can also be a list of such -instantiators (each one in turn is tried until an image is successfully -produced), a cons of a locale (frame, buffer, etc.) and an -instantiator, a list of such conses, or any other form accepted by -＠code{canonicalize-spec-list}. ＠xref{Specifiers}, for more information -about specifiers. - -If you're not familiar with specifiers, you should be in order to -understand how glyphs work. The clearest introduction to specifiers -is in the Lispref manual, available under Info. (Choose -Help->Info->Info Contents on the menubar or type C-h i.) You can -also see ＠code{make-specifier} for a capsule summary. What's important to -keep in mind is that a specifier lets you set a different value for -any particular buffer, window, frame, device, or console. This allows -for a great deal of flexibility; in particular, only one global glyph -needs to exist for a particular purpose (e.g. the icon used to represent -an iconified frame, the mouse pointer used over particular areas of a -frame, etc.), and in these cases you do not create your own glyph, but -rather modify the existing one. + On the other hand, by contrast with GNU Emacs 21, an XEmacs glyph is +not ``just'' an image. The actual image that is displayed (as opposed +to its position or clipping) is defined by an ``image specifier'' object +contained within the glyph. The separation between an image specifier +object and a glyph object is made because the glyph includes other +properties than just the actual image: e.g. the face it is displayed in, +the alignment of the image, ＠emph{etc}. Also, an image specifier is +used in at least one place in XEmacs in lieu of a glyph, namely the +backing pixmap of a face. + + An image specifier is used because glyphs often have locale-specific +semantics. The most important example is semantics determined by the +display device: you can't usefully display a JPEG on stdout, or a color +image on a monochrome display. But because the image property is a +specifier in XEmacs, you can specify that a given glyph appear as a +monochrome image on monochrome displays, a color image on color +displays, and as a string on TTYs. (Specifying a string for the +＠code{tty} device locale would give behavior like the ＠code{ALT} +attribute of an ＠code{IMG} element in HTML.) Another is semantics +determined by the buffer or mode. (Unfortunately, currently there are +no compelling examples of this for glyphs.) + + All this means that only one global glyph needs to exist for a +particular purpose (e.g. the icon used to represent an iconified frame, +the mouse pointer used over particular areas of a frame, etc.). Often +you need not (and should not!) create your own glyph, but rather modify +an existing one. + + In working with glyphs it is important to keep in mind the distinction +between a locale and a domain. A ＠dfn{locale} is specified by the +programmer, and is an abstract link between a specification (for a +glyph, its visual appearance) and a displayable object. The displayable +object may be a buffer or a window, or an object containing buffers or +windows such as frame, device, or console. A ＠dfn{domain} is an actual +display context, which must be concrete enough to enable XEmacs to +identify the device type. (Buffers may be displayed in windows on +different devices, even simultaneously, so a buffer cannot be a domain. +Similarly, the global locale cannot be a domain.) ＠ref{Specifiers}, for +more information about specifier locales and domains. -As well as using ＠var{spec-list} to initialize the glyph, you can set -specifications using ＠code{set-glyph-image}. Note that, due to a -possibly questionable historical design decision, a glyph itself is not -actually a specifier, but rather is an object containing an image -specifier (as well as other, seldom-used properties). Therefore, you -cannot set or access specifications for the glyph's image by directly -using ＠code{set-specifier}, ＠code{specifier-instance} or the like on the -glyph; instead use them on ＠code{(glyph-image ＠var{glyph})} or use the -convenience functions ＠code{set-glyph-image}, -＠code{glyph-image-instance}, and ＠code{glyph-image}. -Once you have created a glyph, you specify where it will be used as -follows: +＠node Images +＠section Images -＠itemize ＠bullet -＠item -To insert a glyph into a buffer, create an extent in the buffer and then -use ＠code{set-extent-begin-glyph} or ＠code{set-extent-end-glyph} to set -a glyph to be displayed at the corresponding edge of the extent. (It is -common to create zero-width extents for this purpose.) +＠menu +* Image Specifiers:: Specifying an image's appearance. +* Image Instantiator Conversion:: Lazy realization of graphics. +* Image Instantiator Formats:: A catalog of image descriptors. +* Image Instances:: Classes of graphical objects. +＠end menu -＠item -To insert a glyph into the left or right margin of a buffer, first -make sure the margin is visible by setting a value for the specifiers -＠code{left-margin-width} or ＠code{right-margin-width}. (Not strictly necessary -when using margin glyphs with layout policy ＠code{whitespace}.) Then follow -the same procedure above for inserting a glyph in a buffer, and then -set a non-default layout policy for the glyph using -＠code{set-extent-begin-glyph-layout} or ＠code{set-extent-end-glyph-layout}. -Alternatively, use the high-level annotations API (see -＠code{make-annotation}). (In point of fact, you can also use the annotations -API for glyphs in a buffer, by setting a layout policy of ＠code{text}.) -＠item -To insert a glyph into the modeline, just put the glyph directly as one -of the modeline elements. (Unfortunately you can't currently put a begin -glyph or end glyph on one of the modeline extents---they're ignored.) +＠node Image Specifiers +＠subsection Image Specifiers +＠cindex image specifiers -＠item -To insert a glyph into a toolbar, specify it as part of a toolbar -instantiator (typically set on the specifier ＠code{default-toolbar}). -See ＠code{default-toolbar} for more information. (Note that it is -standard practice to use a symbol in place of the glyph list in the -toolbar instantiator; the symbol is evalled to get the glyph list. This -facilitates both creating the toolbar instantiator and modifying -individual glyphs in a toolbar later on. For example, you can change -the way that the Mail toolbar button looks by modifying the value of the -variable ＠code{toolbar-mail-icon} (in general, ＠code{toolbar-*-icon}) -and then calling ＠code{(set-specifier-dirty-flag default-toolbar)}. -(#### Unfortunately this doesn't quite work the way it should; the -change will appear in new frames, but not existing ones. + An image specifier is a description of the actual graphical +realization of a glyph. For example, a typical image description is +＠emph{the file system path to a PNG file}. Since redisplay doesn't know +about files, and in any case the image may need to be manipulated +((a)emph{e.g.}, a face's background pixmap must be clipped and tiled), the +PNG file must be converted internally to a window system bitmap or +pixmap object. We describe this process by writing that when XEmacs +displays the image, it ＠dfn{instantiates} the ＠dfn{image instantiator} +into an ＠dfn{image instance}. Image instances are an internal 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 Lisp strings or vectors. + +Furthermore the graphical realization will vary, and for some devices +may not even be a bitmapped graphic. These variations may be controlled +by the program by specifying different ＠dfn{image instantiators} in +different locales. This is implemented with an ＠dfn{image specifier}, +a specifier whose specifications are image instantiators. + +Image specifiers are rarely if ever found by themselves. However, an +image specifier results from calling ＠code{glyph-image} on a glyph, or +retrieving the ＠code{background-pixmap} property of a face, and you can +check if some random object is an image specifier. -＠item -To insert a glyph into a gutter, create or modify a gutter instantiator -(typically set on the specifier ＠code{default-gutter}). Gutter -instantiators consist of strings or lists of strings, so to insert a -glyph, create an extent over the string, and use -＠code{set-extent-begin-glyph} or ＠code{set-extent-end-glyph} to set a -glyph to be displayed at the corresponding edge of the extent, just like -for glyphs in a buffer. +＠defun image-specifier-p object +This function returns non-＠code{nil} if ＠var{object} is an image specifier. +＠end defun -＠item -To use a glyph as the icon for a frame, you do not actually create a new -glyph; rather, you change the specifications for the existing glyph -＠code{frame-icon-glyph}. (Remember that, because of the specifier nature -of glyphs, you can set different values for any particular buffer or -frame.) +＠defun make-image-specifier spec-list +This function creates a new image specifier object and initializes it +according to ＠var{spec-list}. ＠xref{Specifiers}. +＠end defun -＠item -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 ＠code{text-pointer-glyph} for the pointer used over -text, ＠code{modeline-pointer-glyph} for the pointer used over the -modeline, etc. Do an apropos over ＠code{*-pointer-glyph} to find all of -them. (Note also that you can temporarily set the mouse pointer to some -specific shape by using ＠code{set-frame-pointer}, which takes an image -instance, as obtained from calling ＠code{glyph-image-instance} on a glyph -of type ＠code{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 ＠code{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 ＠code{mode-motion-hook}, or ＠code{mouse-motion-handler} if you -really want to get low-level.) +This function exists mainly for completeness. In practice, you rarely, +if ever, need to actually create an image specifier. Instead, they are +implicitly created by the initialization of glyphs and faces, and the +specifier member of these objects cannot be changed after +initialization; you may only set the specifications it contains. -＠item -To use a glyph to control the shape of miscellaneous redisplay effects -such as the truncation and continuation markers, set the appropriate -existing glyph variables, as for icons and pointers above. See -＠code{continuation-glyph}, ＠code{control-arrow-glyph}, -＠code{hscroll-glyph}, ＠code{invisible-text-glyph}, -＠code{octal-escape-glyph}, and ＠code{truncation-glyph}. See also -＠code{overlay-arrow-string}, an odd redisplay leftover which can be set -to a glyph you created, and will cause the glyph to be displayed on top -of the text position specified in the marker stored in -＠code{overlay-arrow-position}. +Image instantiators come in many formats: ＠code{xbm}, ＠code{xpm}, +＠code{gif}, ＠code{jpeg}, etc. These denote the format of the data +describing the image. The resulting image instances also come in many +types---＠code{mono-pixmap}, ＠code{color-pixmap}, ＠code{text}, +＠code{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.) -＠item -To use a glyph in a display table (i.e. to control the appearance of any -individual character), create the appropriate character glyphs and then -set a specification for the specifier ＠code{current-display-table}, -which controls the appearance of characters. You can also set an -overriding display table for use with text displayed in a particular -face; see ＠code{set-face-display-table} and ＠code{make-display-table}. -#### Note: Display tables do not currently support general Mule -characters. They will be overhauled at some point to support this -and to provide other features required under Mule. +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, ＠code{xpm} can be instanced as ＠code{color-pixmap}, +＠code{mono-pixmap}, or ＠code{pointer}; whereas ＠code{cursor-font} can be +instanced only as ＠code{pointer}. On the other hand, a particular image +instance type can be generated by many different image instantiator +formats (e.g. ＠code{color-pixmap} can be generated by ＠code{xpm}, +＠code{gif}, ＠code{jpeg}, etc.). -＠item -To use a glyph as the background pixmap of a face: Note that the -background pixmap of a face is actually an image specifier -- probably -the only place in XEmacs where an image specifier occurs outside of a -glyph. Similarly to how the glyph's image specifier works, you don't -create your own image specifier, but rather add specifications to the -existing one (using ＠code{set-face-background-pixmap}). Note that the -image instance that is generated in order to actually display the -background pixmap is of type ＠code{mono-pixmap}, meaning that it's a -two-color image and the foreground and background of the image get -filled in with the corresponding colors from the face. -＠end itemize + ＠xref{Image Instances}, for a more detailed discussion of image +instance types. -It is extremely rare that you will ever have to specify a value for -＠var{type}, which should be one of ＠code{buffer} (used for glyphs in an -extent, the modeline, the toolbar, or elsewhere in a buffer), -＠code{pointer} (used for the mouse-pointer), or ＠code{icon} (used for a -frame's icon), and defaults to ＠code{buffer}. The only cases where it -needs to be specified is when creating icon or pointer glyphs, and in -both cases the necessary glyphs have already been created at startup and -are accessed through the appropriate variables, -e.g. ＠code{text-pointer-glyph} (or in general, ＠code{*-pointer-glyph}) -and ＠code{frame-icon-glyph}. ＠xref{Glyph Types}. -＠end defun + An image instantiator should be a string or a vector of the form -＠defun make-glyph-internal &optional type -This function creates a new, uninitialized glyph of type ＠var{type}. -＠end defun +＠example + ＠code{[＠var{format} ＠var{:keyword} ＠var{value} ...]} +＠end example -＠defun make-pointer-glyph &optional spec-list +i.e. a format symbol followed by zero or more alternating keyword-value +pairs. -Return a new ＠code{pointer-glyph} object with the specification list -＠var{spec-list}. This function is equivalent to calling -＠code{make-glyph} with a ＠var{type} of ＠code{pointer}. +The form of an instantiator can be checked with +＠code{valid-instantiator-p} with a ＠var{TYPE} of ＠code{image}, +＠ref{Specifier Validation Functions}. + +For a complete list of the format symbols and their usage, +＠ref{Image Instantiator Formats}. + +If the instantiator is a string, it will be converted into a vector by +looking it up according to the specs in the +＠code{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. -It is extremely unlikely that you will ever need to create a pointer -glyph. Instead, you probably want to be calling ＠code{set-glyph-image} -on an existing glyph, e.g. ＠code{text-pointer-glyph}. -＠end defun +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 ＠code{: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). -＠defun make-icon-glyph &optional spec-list +The available keywords are given below. Note that some keywords are +generally available (for example, the ＠code{:data} keyword may be used +with any format except ＠code{nothing}), while others are only available +for one format (＠code{resource-id} is unique to the +＠code{mswindows-resource} format). -Return a new ＠code{pointer-glyph} object with the specification list -＠var{spec-list}. This function is equivalent to calling -＠code{make-glyph} with a ＠var{type} of ＠code{icon}. +＠table ＠code +＠item :data +Inline image data. If available for a given format, it may be specified +directly by the program, or it may be a cache of file data previously +read. When present, it is used to instantiate the image in preference +to the file named by the ＠code{:file} property. + +The format of inline data is image-format-specific. For example, in +pixmap formats, the value should be a string, which is interpreted as an +octet-stream representing a bitmap or pixmap. But for text formats, +it's string containing the text to be displayed, and for resource +formats, it's a string containing the name of the resource. -It is extremely unlikely that you will ever need to create a pointer -glyph. Instead, you probably want to be calling ＠code{set-glyph-image} -on an existing glyph, e.g. ＠code{text-pointer-glyph}. -＠end defun +＠item :file +Data contained in a file. The value is the name of this file. If both +＠code{:data} and ＠code{:file} are specified, the image is created from +what is specified in ＠code{:data} and the string in ＠code{:file} becomes +the value of the ＠code{image-instance-file-name} function when applied +to the resulting image-instance. Note that there is nothing to stop a +program from changing either the ＠code{:file} or the ＠code{:data} +property, and there is no way to detect such mischief. This means that +the data will ＠emph{not} be automatically reread if you change the +＠code{file} property; you must force it by removing the ＠code{:data} +property. +＠c #### If there are ways to do this in-place, describe them. +(One way to do this is replacing the whole specification with a new +vector.) This keyword is not valid for instantiator formats +＠code{nothing}, ＠code{string}, ＠code{formatted-string}, +＠code{cursor-font}, ＠code{font}, and ＠code{autodetect}. -＠node Glyph Properties -＠subsection Glyph Properties +＠item :mask-data +Inline data for ＠code{xbm} and ＠code{xface}. This specifies a mask to +be used with the bitmap. Pixels which are not set in the mask will not +be written to the imaging device. The format is a list of width, +height, and bits, as for ＠code{:data}. -Each glyph has a list of properties, which control all of the aspects of -the glyph's appearance. The following symbols have predefined meanings: +＠item :mask-file +For ＠code{xbm} and ＠code{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 ＠samp{Mask} or +＠samp{msk} appended. For example, if you specify the XBM file +＠file{left_ptr} [usually located in ＠file{/usr/include/X11/bitmaps}], +the associated mask file ＠file{left_ptrmsk} will automatically be picked +up. -＠table ＠code -＠item image -The image used to display the glyph. +＠item :resource-id +Only for ＠code{mswindows-resource}. This must be either an integer +(which directly specifies a resource number) or a string. See the +description of ＠code{mswindows-resource} for valid strings. ＠xref{Image +Instantiator Formats}. -＠item baseline -Percent above baseline that glyph is to be displayed. Only for glyphs -displayed inside of a buffer. +＠item :foreground +＠itemx :background +For ＠code{xbm}, ＠code{xface}, ＠code{cursor-font}, and ＠code{font}. +These keywords allow you to explicitly specify foreground and background +colors. The value should be anything acceptable to +＠code{make-color-instance}. This will cause an external format that +would by default be instantiated as a ＠code{mono-pixmap} to instead be +instantiated as a two-color color-pixmap. This can be used to override +the colors specified by a glyph's face, for example. If the image is +instantiated as a pointer, they specify its foreground and/or +background, instead of the defaults of black and white. -＠item contrib-p -Whether the glyph contributes to the height of the line it's on. -Only for glyphs displayed inside of a buffer. +＠item :hotspot-x +＠itemx :hotspot-y +For ＠code{xbm} and ＠code{xface}. These keywords specify a hotspot if +the image is instantiated as a ＠code{pointer}. Note that if the XBM +image file specifies a hotspot, it will automatically be picked up if no +explicit hotspot is given. -＠item face -Face of this glyph (＠emph{not} a specifier). +＠item :color-symbols +Only for ＠code{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 ＠code{xpm-color-symbols} are +used to generate the alist. + +＠item :resource-type +Only for ＠code{mswindows-resource}. This must be a symbol, either +＠code{cursor}, ＠code{icon}, or ＠code{bitmap}, specifying the type of +resource to be retrieved. + +＠item :face +For ＠code{inherit} and the widget formats. This specifies the face to +inherit from. For widgets this specifies the face to use for display. +It defaults to gui-element-face. + +＠item :selected +＠itemx :active +＠itemx :suffix +＠itemx :keys +＠itemx :style +＠itemx :filter +＠itemx :config +＠itemx :included +＠itemx :key-sequence +＠itemx :accelerator +＠itemx :label +＠itemx :callback +These keywords, accepted as menu item specs, are also accepted by images +instantiated as ＠code{widget}. For their semantics, ＠ref{Menu Format}. ＠end table -＠defun set-glyph-property glyph property value &optional locale tag-set how-to-add -This function changes a property of a ＠var{glyph}. -For built-in properties, the actual value of the property is a specifier -and you cannot change this; but you can change the specifications within -the specifier, and that is what this function will do. For user-defined -properties, you can use this function to either change the actual value -of the property or, if this value is a specifier, change the -specifications within it. +＠node Image Instantiator Conversion +＠subsection Image Instantiator Conversion +＠cindex image instantiator conversion +＠cindex conversion of image instantiators -If ＠var{property} is a built-in property, the specifications to be added -to this property can be supplied in many different ways: +Conversion is applied to image instantiators at the time they are added +to an image specifier or at the time they are passed to +＠code{make-image-instance}. -＠itemize ＠bullet -＠item -If ＠var{value} is a simple instantiator (e.g. a string naming a pixmap -filename) or a list of instantiators, then the instantiator(s) will be -added as a specification of the property for the given ＠var{locale} -(which defaults to ＠code{global} if omitted). +＠defun set-console-type-image-conversion-list console-type list +This function sets the image-conversion-list for consoles of the given +＠var{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. -＠item -If ＠var{value} is a list of specifications (each of which is a cons of a -locale and a list of instantiators), then ＠var{locale} must be -＠code{nil} (it does not make sense to explicitly specify a locale in -this case), and specifications will be added as given. +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. +＠end defun -＠item -If ＠var{value} is a specifier (as would be returned by -＠code{glyph-property} if no ＠var{locale} argument is given), then some -or all of the specifications in the specifier will be added to the -property. In this case, the function is really equivalent to -＠code{copy-specifier} and ＠var{locale} has the same semantics (if it is -a particular locale, the specification for the locale will be copied; if -a locale type, specifications for all locales of that type will be -copied; if ＠code{nil} or ＠code{all}, then all specifications will be -copied). -＠end itemize +＠defun console-type-image-conversion-list console-type +This function returns the image-conversion-list for consoles of the given +＠var{console-type}. +＠end defun -＠var{how-to-add} should be either ＠code{nil} or one of the symbols -＠code{prepend}, ＠code{append}, ＠code{remove-tag-set-prepend}, -＠code{remove-tag-set-append}, ＠code{remove-locale}, -＠code{remove-locale-type}, or ＠code{remove-all}. See -＠code{copy-specifier} and ＠code{add-spec-to-specifier} for a description -of what each of these means. Most of the time, you do not need to worry -about this argument; the default behavior usually is fine. -In general, it is OK to pass an instance object (e.g. as returned by -＠code{glyph-property-instance}) as an instantiator in place of an actual -instantiator. In such a case, the instantiator used to create that -instance object will be used (for example, if you set a font-instance -object as the value of the ＠code{font} property, then the font name used -to create that object will be used instead). If some cases, however, -doing this conversion does not make sense, and this will be noted in the -documentation for particular types of instance objects. +＠node Image Instantiator Formats +＠subsection Image Instantiator Formats +＠cindex image instantiator formats + +The ＠dfn{format} field of an image instantiator should be a symbol +denoting a valid format. Which formats are valid will depend on the +features (such as image decoding libraries) available, on platform +support (MS Windows resource IDs make no sense on other platforms), and +on the locale. -If ＠var{property} is not a built-in property, then this function will -simply set its value if ＠var{locale} is ＠code{nil}. However, if -＠var{locale} is given, then this function will attempt to add -＠var{value} as the instantiator for the given ＠var{locale}, using -＠code{add-spec-to-specifier}. If the value of the property is not a -specifier, it will automatically be converted into a ＠code{generic} -specifier. -＠end defun +＠defun valid-image-instantiator-format-p format &optional locale +This function returns non-＠code{nil} if ＠var{format} is a valid image +instantiator format. -＠defun glyph-property glyph property &optional locale -This function returns ＠var{glyph}'s value of the given ＠var{property}. +If ＠var{locale} is non-＠code{nil} then the format is checked in that locale. +If ＠var{locale} is ＠code{nil} the current console is used. -If ＠var{locale} is omitted, the ＠var{glyph}'s actual value for -＠var{property} will be returned. For built-in properties, this will be -a specifier object of a type appropriate to the property (e.g. a font or -color specifier). For other properties, this could be anything. +Note that the return value for many formats listed above depends on +whether XEmacs was compiled with support for that format. +＠end defun -If ＠var{locale} is supplied, then instead of returning the actual value, -the specification(s) for the given locale or locale type will be -returned. This will only work if the actual value of ＠var{property} is -a specifier (this will always be the case for built-in properties, but -may or may not apply to user-defined properties). If the actual value -of ＠var{property} is not a specifier, this value will simply be returned -regardless of ＠var{locale}. +＠defun image-instantiator-format-list +This function returns a list of valid image-instantiator formats. +＠end defun -The return value will be a list of instantiators (e.g. vectors -specifying pixmap data), or a list of specifications, each of which is a -cons of a locale and a list of instantiators. Specifically, if -＠var{locale} is a particular locale (a buffer, window, frame, device, or -＠code{global}), a list of instantiators for that locale will be -returned. Otherwise, if ＠var{locale} is a locale type (one of the -symbols ＠code{buffer}, ＠code{window}, ＠code{frame}, or ＠code{device}), -the specifications for all locales of that type will be returned. -Finally, if ＠var{locale} is ＠code{all}, the specifications for all -locales of all types will be returned. +Here is a table of image-instantiator formats, giving the keywords that +are usable with each, and the kinds of instances that may result. -The specifications in a specifier determine what the value of -＠var{property} will be in a particular ＠dfn{domain} or set of -circumstances, which is typically a particular Emacs window along with -the buffer it contains and the frame and device it lies within. The -value is derived from the instantiator associated with the most specific -locale (in the order buffer, window, frame, device, and ＠code{global}) -that matches the domain in question. In other words, given a domain -(i.e. an Emacs window, usually), the specifier for ＠var{property} will -first be searched for a specification whose locale is the buffer -contained within that window; then for a specification whose locale is -the window itself; then for a specification whose locale is the frame -that the window is contained within; etc. The first instantiator that -is valid for the domain (usually this means that the instantiator is -recognized by the device [i.e. the X server or TTY device] that the -domain is on). The function ＠code{glyph-property-instance} actually does -all this, and is used to determine how to display the glyph. -＠end defun +＠table ＠code +＠item nothing +Don't display anything; no keywords are valid for this format. Can only be +instanced as ＠code{nothing}. -＠defun glyph-property-instance glyph property &optional domain default no-fallback -This function returns the instance of ＠var{glyph}'s ＠var{property} in the -specified ＠var{domain}. +＠item string +Display this image as a text string. Can only be instanced +as ＠code{text}, although support for instancing as ＠code{mono-pixmap} +should be added. The valid keyword is ＠code{:data}. The value should +be a string, and it is interpreted as a string of characters. -Under most circumstances, ＠var{domain} will be a particular window, and -the returned instance describes how the specified property actually is -displayed for that window and the particular buffer in it. Note that -this may not be the same as how the property appears when the buffer is -displayed in a different window or frame, or how the property appears in -the same window if you switch to another buffer in that window; and in -those cases, the returned instance would be different. +＠item formatted-string +Display this image as a text string with replaceable fields, +similar to a modeline format string. The valid keyword is ＠code{:data}. +The value should be a string, and it is interpreted as a string of +characters containing format sequences. -The returned instance is an image-instance object, and you can query it -using the appropriate image instance functions. For example, you could use -＠code{image-instance-depth} to find out the depth (number of color -planes) of a pixmap displayed in a particular window. The results might -be different from the results you would get for another window (perhaps -the user specified a different image for the frame that window is on; or -perhaps the same image was specified but the window is on a different X -server, and that X server has different color capabilities from this -one). +Not currently implemented. -＠var{domain} defaults to the selected window if omitted. +＠item xbm +An X bitmap; available only if X support was compiled into this XEmacs. -＠var{domain} can be a frame or device, instead of a window. The value -returned for such a domain is used in special circumstances when a -more specific domain does not apply; for example, a frame value might be -used for coloring a toolbar, which is conceptually attached to a frame -rather than a particular window. The value is also useful in -determining what the value would be for a particular window within the -frame or device, if it is not overridden by a more specific -specification. +If used in a buffer glyph, icon glyph, or face background pixmap, it +will be instantiated as ＠code{mono-pixmap} unless the ＠code{:foreground} +or ＠code{:background} keywords are present. In the latter case it will +be instantiated as ＠code{color-pixmap} with the two specified colors. +＠c #### Check this. +(Probably if ＠code{:foreground} or ＠code{:background} is omitted, it +defaults to black or white respectively.) If used in a pointer glyph, +it will be instantiated as an ＠code{pointer}. -If ＠var{property} does not name a built-in property, its value will -simply be returned unless it is a specifier object, in which case it -will be instanced using ＠code{specifier-instance}. +The valid keywords and their values are +＠table ＠code +＠item :data +A list containing the height and width of the bitmap as integers, and +a string interpreted as a bit vector according to the X11 standard XBM +bitmap format, in that order. +＠item :file +The name of a file containing standard XBM-format data. If it contains +a hotspot specification, it will be parsed and used if the hotspot is +not explicitly specified. +＠item :mask-data +A list containing the height and width of the bitmap as integers, and +a string interpreted as a bit vector according to the X11 standard XBM +bitmap format, in that order. This bitmap is interpreted as the +clipping region for the bitmap contained in the ＠code{:data} property. +＠item :mask-file +The name of a file containing standard XBM-format data. Interpreted as +the clipping region for the bitmap contained in the ＠code{:data} property. +＠item :foreground +＠itemx :background +These keywords allow you to explicitly specify foreground and background +colors. The values should be acceptable to ＠code{make-color-instance}. +＠item :hotspot-x +＠itemx :hotspot-y +Integers denoting the hotspot (mouse pointer position), with (0,0) at +the top left corner. If given, these override any specification in the +XBM file. +＠end table -Optional arguments ＠var{default} and ＠var{no-fallback} are the same as -in ＠code{specifier-instance}. ＠xref{Specifiers}. -＠end defun +＠item xpm +An XPM pixmap; only available if XPM support was compiled into this XEmacs. -＠defun remove-glyph-property glyph property &optional locale tag-set exact-p -This function removes a property from a glyph. For built-in properties, -this is analogous to ＠code{remove-specifier}. ＠xref{Specifiers, -remove-specifier-p}, for the meaning of the ＠var{locale}, ＠var{tag-set}, -and ＠var{exact-p} arguments. -＠end defun +Can be instanced as ＠code{color-pixmap}, ＠code{mono-pixmap}, or +＠code{pointer}. -＠node Glyph Convenience Functions -＠subsection Glyph Convenience Functions +XPM is an add-on library for X that was designed to rectify the +shortcomings of the XBM format. Many icons and labels used in the +XEmacs GUI are still distributed in XPM format (although we are moving +to standardize on the PNG format). It is therefore highly desirable +that XPM be available in your XEmacs. + +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 XEmacs FTP site and mirrors, as +well as from most sites that distribute X11. - The following functions are provided for working with specific -properties of a glyph. Note that these are exactly like calling -the general functions described above and passing in the -appropriate value for ＠var{property}. +The valid keywords and their values are +＠table ＠code +＠item :data +A string interpreted as the contents of a standard XPM file. +＠item :file +The name of a file containing standard XPM-format data. If it contains +a hotspot specification, it will be parsed and used if the hotspot is +not explicitly specified. +＠c #### Does XPM provide for a hotspot? +＠item :hotspot-x +＠itemx :hotspot-y +Integers denoting the hotspot (mouse pointer position), with (0,0) at +the top left corner. If given, these override any specification in the +XBM file. +＠c #### Check this. +(This may not be true. The original documentation doesn't mention them +in connection with XPM, but a pointer needs a hotspot.) +＠item :color-symbols +An alist that maps the one- or two-character strings that specify +symbolic color names in the XPM file to the actual color to be used for +that symbolic color (in the form of a string acceptable as a color +instantiator, ＠ref{Color Specifiers}, or a color-specifier object). +If this is not specified, the contents of ＠code{xpm-color-symbols} are +used to generate the alist. +＠end table - Remember that if you want to determine the ``value'' of a -specific glyph property, you probably want to use the ＠code{*-instance} -functions. For example, to determine whether a glyph contributes -to its line height, use ＠code{glyph-contrib-p-instance}, not -＠code{glyph-contrib-p}. (The latter will return a boolean specifier -or a list of specifications, and you probably aren't concerned with -these.) +＠item xface +An X-Face bitmap, used to encode people's faces in e-mail messages; +only available if X-Face support was compiled into this XEmacs. -＠defun glyph-image glyph &optional locale -This function is equivalent to calling ＠code{glyph-property} with -a property of ＠code{image}. The return value will be an image -specifier if ＠var{locale} is ＠code{nil} or omitted; otherwise, -it will be a specification or list of specifications. -＠end defun +Will be instanced as ＠code{mono-pixmap}, ＠code{color-pixmap}, or +＠code{pointer}, depending on the target instance type and the presence +of color keywords. -＠defun set-glyph-image glyph spec &optional locale tag-set how-to-add -This function is equivalent to calling ＠code{set-glyph-property} with -a property of ＠code{image}. -＠end defun +The valid keywords and their values are +＠table ＠code +＠item :data +A list containing the height and width of the bitmap as integers, and +a string interpreted as a bit vector according to the X11 standard XBM +bitmap format, in that order. +＠item :file +The name of a file containing standard XBM-format data. If it contains +a hotspot specification, it will be parsed and used if the hotspot is +not explicitly specified. +＠item :mask-data +A list containing the height and width of the bitmap as integers, and +a string interpreted as a bit vector according to the X11 standard XBM +bitmap format, in that order. This bitmap is interpreted as the +clipping region for the bitmap contained in the ＠code{:data} property. +＠item :mask-file +The name of a file containing standard XBM-format data. Interpreted as +the clipping region for the bitmap contained in the ＠code{:data} property. +＠item :foreground +＠itemx :background +These keywords allow you to explicitly specify foreground and background +colors. The values should be acceptable to ＠code{make-color-instance}. +＠item :hotspot-x +＠itemx :hotspot-y +Integers denoting the hotspot (mouse pointer position), with (0,0) at +the top left corner. If given, these override any specification in the +XBM file. +＠end table -＠defun glyph-image-instance glyph &optional domain default no-fallback -This function returns the instance of ＠var{glyph}'s image in the given -＠var{domain}, and is equivalent to calling -＠code{glyph-property-instance} with a property of ＠code{image}. The -return value will be an image instance. +＠item gif +＠itemx jpeg +＠itemx png +＠itemx tiff +These are GIF87- or GIF89-format, JPEG-format, PNG/GIF24-format, and +TIFF-format images, respectively. They are available only if +appropriate decoding support was built into XEmacs. 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. If you have development support (both the libraries and +the relevant C header files) available when XEmacs is built, the JPEG, +PNG, and TIFF libraries will automatically be detected (in the ``usual +places'') and linked into the build. -Normally ＠var{domain} will be a window or ＠code{nil} (meaning the -selected window), and an instance object describing how the image -appears in that particular window and buffer will be returned. -＠end defun +Note that PNG is the standard format for images distributed with XEmacs, +so it is highly recommended that PNG support be built in. -＠defun glyph-contrib-p glyph &optional locale -This function is equivalent to calling ＠code{glyph-property} with -a property of ＠code{contrib-p}. The return value will be a boolean -specifier if ＠var{locale} is ＠code{nil} or omitted; otherwise, -it will be a specification or list of specifications. -＠end defun +All of these instantiators will be instanced as ＠code{color-pixmap}. -＠defun set-glyph-contrib-p glyph spec &optional locale tag-set how-to-add -This function is equivalent to calling ＠code{set-glyph-property} with -a property of ＠code{contrib-p}. -＠end defun +The valid keywords and their values are +＠table ＠code +＠item :data +A string interpreted as the contents of a file containing data in the +appropriate standard format. +＠item :file +The name of a file containing standard-format data. +＠end table -＠defun glyph-contrib-p-instance glyph &optional domain default no-fallback -This function returns whether the glyph contributes to its line height -in the given ＠var{domain}, and is equivalent to calling -＠code{glyph-property-instance} with a property of ＠code{contrib-p}. The -return value will be either ＠code{nil} or ＠code{t}. (Normally ＠var{domain} -will be a window or ＠code{nil}, meaning the selected window.) -＠end defun +＠item cursor-font +Most window systems provide a set of standard cursors, which in X11 is +called a cursor font. Can only be instanced as ＠code{pointer}. This +should probably be fixed. + +The valid keyword is ＠code{:data}. Its value should be a string +containing one of the standard cursor-font names, such as ＠samp{watch} +or ＠samp{right_ptr} under X. More specifically, in the X Window System +it may be any of the standard cursor names from appendix B of the Xlib +manual, provided in the file ＠file{<X11/cursorfont.h>} by most +distributions, minus the ＠samp{XC_} prefix. For MS Windows, use +＠code{mswindows-resource} instantiator format, not ＠code{cursor-font}. +Other window systems may have different lists. -＠defun glyph-baseline glyph &optional locale -This function is equivalent to calling ＠code{glyph-property} with a -property of ＠code{baseline}. The return value will be a specifier if -＠var{locale} is ＠code{nil} or omitted; otherwise, it will be a -specification or list of specifications. -＠end defun +＠item font +A glyph from a font; i.e. the name of a font, and glyph index into it +of the form ＠samp{＠var{font} fontname index [[mask-font] mask-index]}. +Only if X support was compiled into this XEmacs. Currently can only be +instanced as ＠code{pointer}. This should probably be fixed. +＠c #### The above description is not very helpful, so it's not obvious +＠c how to instantiate a font image. -＠defun set-glyph-baseline glyph spec &optional locale tag-set how-to-add -This function is equivalent to calling ＠code{set-glyph-property} with -a property of ＠code{baseline}. -＠end defun +＠item 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. Can be instanced as ＠code{pointer} or +＠code{color-pixmap}. -＠defun glyph-baseline-instance glyph &optional domain default no-fallback -This function returns the instance of ＠var{glyph}'s baseline value in -the given ＠var{domain}, and is equivalent to calling -＠code{glyph-property-instance} with a property of ＠code{baseline}. The -return value will be an integer or ＠code{nil}. +The valid keywords and their values are -Normally ＠var{domain} will be a window or ＠code{nil} (meaning the -selected window), and an instance object describing the baseline value -appears in that particular window and buffer will be returned. -＠end defun +＠table ＠code +＠item :resource-type +A string naming the type (＠code{cursor}, ＠code{bitmap}, or ＠code{icon}) +of the resource. Required. +＠item :file +A string containing the name of the file containing the resource (often +an executable). If a system resource, ＠code{:file} should be omitted. +＠item :resource-id +A string containing the name of a resource. Required if ＠code{:file} +is not specified. -＠defun glyph-face glyph -This function returns the face of ＠var{glyph}. (Remember, this is -not a specifier, but a simple property.) -＠end defun +This must be either an integer (which directly specifies a resource +number) or a string. Valid strings are -＠defun set-glyph-face glyph face -This function changes the face of ＠var{glyph} to ＠var{face}. -＠end defun +For bitmaps: -＠node Glyph Dimensions -＠subsection Glyph Dimensions +"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". -＠defun glyph-width glyph &optional window -This function returns the width of ＠var{glyph} on ＠var{window}. This -may not be exact as it does not take into account all of the context -that redisplay will. -＠end defun +For cursors: -＠defun glyph-ascent glyph &optional window -This function returns the ascent value of ＠var{glyph} on ＠var{window}. -This may not be exact as it does not take into account all of the -context that redisplay will. -＠end defun - -＠defun glyph-descent glyph &optional window -This function returns the descent value of ＠var{glyph} on ＠var{window}. -This may not be exact as it does not take into account all of the -context that redisplay will. -＠end defun - -＠defun glyph-height glyph &optional window -This function returns the height of ＠var{glyph} on ＠var{window}. (This -is equivalent to the sum of the ascent and descent values.) This may -not be exact as it does not take into account all of the context that -redisplay will. -＠end defun - -＠node Images -＠section Images - -＠menu -* Image Specifiers:: Specifying how an image will appear. -* Image Instantiator Conversion:: - Conversion is applied to image instantiators - at the time they are added to an - image specifier or at the time they - are passed to ＠code{make-image-instance}. -* Image Instances:: What an image specifier gets instanced as. -＠end menu - -＠node Image Specifiers -＠subsection Image Specifiers -＠cindex image specifiers - - An image specifier is used to describe the actual image of a glyph. -It works like other specifiers (＠pxref{Specifiers}), in that it contains -a number of specifications describing how the image should appear in a -variety of circumstances. These specifications are called ＠dfn{image -instantiators}. When XEmacs wants to display the image, it instantiates -the image into an ＠dfn{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.) - -＠defun image-specifier-p object -This function returns non-＠code{nil} if ＠var{object} is an image specifier. -Usually, an image specifier results from calling ＠code{glyph-image} on -a glyph. -＠end defun - -＠defun make-image-specifier spec-list -This function creates a new image specifier object and initializes it -according to ＠var{spec-list}. ＠xref{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 -＠code{image} property of a glyph) is created automatically when a glyph -is created and need not (and cannot, for that matter) ever be changed -(＠pxref{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. -＠end defun - - Image instantiators come in many formats: ＠code{xbm}, ＠code{xpm}, -＠code{gif}, ＠code{jpeg}, etc. This describes the format of the data -describing the image. The resulting image instances also come in many -types---＠code{mono-pixmap}, ＠code{color-pixmap}, ＠code{text}, -＠code{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, ＠code{xpm} can be instanced as ＠code{color-pixmap}, -＠code{mono-pixmap}, or ＠code{pointer}; whereas ＠code{cursor-font} can be -instanced only as ＠code{pointer}), and a particular image instance type -can be generated by many different image instantiator formats (e.g. -＠code{color-pixmap} can be generated by ＠code{xpm}, ＠code{gif}, -＠code{jpeg}, etc.). - - ＠xref{Image Instances}, for a more detailed discussion of image -instance types. - - An image instantiator should be a string or a vector of the form +"normal", "ibeam", "wait", "cross", "up", "sizenwse", +"sizenesw", "sizewe", "sizens", "sizeall", and "no". -＠example - ＠code{[＠var{format} ＠var{:keyword} ＠var{value} ...]} -＠end example +For icons: -i.e. a format symbol followed by zero or more alternating keyword-value -pairs. The ＠dfn{format} field should be a symbol, one of +"sample", "hand", "ques", "bang", "note", and "winlogo". +＠end table -＠table ＠code -＠item nothing -Don't display anything; no keywords are valid for this. Can only be -instanced as ＠code{nothing}. -＠item string -Display this image as a text string. Can only be instanced -as ＠code{text}, although support for instancing as ＠code{mono-pixmap} -should be added. -＠item formatted-string -Display this image as a text string with replaceable fields, -similar to a modeline format string; not currently implemented. -＠item xbm -An X bitmap; only if X support was compiled into this XEmacs. Can be -instanced as ＠code{mono-pixmap}, ＠code{color-pixmap}, or -＠code{pointer}. -＠item xpm -An XPM pixmap; only if XPM support was compiled into this XEmacs. Can -be instanced as ＠code{color-pixmap}, ＠code{mono-pixmap}, or -＠code{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. -＠item 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 ＠code{mono-pixmap}, ＠code{color-pixmap}, or ＠code{pointer}. -＠item gif -A GIF87 or GIF89 image; only if GIF support was compiled into this -XEmacs. Can be instanced as ＠code{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. -＠item jpeg -A JPEG-format image; only if JPEG support was compiled into this -XEmacs. Can be instanced as ＠code{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. -＠item png -A PNG/GIF24 image; only if PNG support was compiled into this XEmacs. -Can be instanced as ＠code{color-pixmap}. -＠item tiff -A TIFF-format image; only if TIFF support was compiled into this XEmacs. -＠item cursor-font -One of the standard cursor-font names, such as ＠samp{watch} or -＠samp{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 ＠file{<X11/cursorfont.h>}] minus the ＠samp{XC_} prefix. On -other window systems, the valid names will be specific to the type of -window system. Can only be instanced as ＠code{pointer}. -＠item font -A glyph from a font; i.e. the name of a font, and glyph index into it -of the form ＠samp{＠var{font} fontname index [[mask-font] mask-index]}. -Only if X support was compiled into this XEmacs. Currently can only be -instanced as ＠code{pointer}, although this should probably be fixed. -＠item 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 ＠code{pointer} or ＠code{color-pixmap}. ＠item subwindow An embedded windowing system window. Can only be instanced as -＠code{subwindow}. +＠code{subwindow}. Not implemented. +＠c #### Check status of subwindows ... I thought Andy implemented them. + ＠item button A button widget; either a push button, radio button or toggle button. Can only be instanced as ＠code{widget}. + ＠item combo-box A drop list of selectable items in a widget, for editing text. Can only be instanced as ＠code{widget}. + ＠item edit-field A text editing widget. Can only be instanced as ＠code{widget}. + ＠item label A static, text-only, widget; for displaying text. Can only be instanced as ＠code{widget}. + ＠item layout A widget for controlling the positioning of children underneath it. Through the use of nested layouts, a widget hierarchy can be created ＠＠ -742,20 +628,25 ＠＠ arrangement; all of this is counted as one ＠dfn{glyph} and could appear in many of the places that expect a single glyph. Can only be instanced as ＠code{widget}. + ＠item native-layout -＠c #### Document me better! The native version of a layout widget. Can only be instanced as ＠code{widget}. + ＠item progress-gauge A sliding widget, for showing progress. Can only be instanced as ＠code{widget}. + ＠item tab-control A tab widget; a series of user selectable tabs. Can only be instanced as ＠code{widget}. + ＠item tree-view A folding widget. Can only be instanced as ＠code{widget}. + ＠item scrollbar A scrollbar widget. Can only be instanced as ＠code{widget}. + ＠item 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, ＠＠ -766,135 +657,14 ＠＠ 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. + ＠item inherit Inherit from the background-pixmap property of a face. Can only be instanced as ＠code{mono-pixmap}. ＠end table - -The valid keywords are: - -＠table ＠code -＠item :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 ＠code{nothing}. - -＠item :file -Data is contained in a file. The value is the name of this file. If -both ＠code{:data} and ＠code{:file} are specified, the image is created -from what is specified in ＠code{:data} and the string in ＠code{:file} -becomes the value of the ＠code{image-instance-file-name} function when -applied to the resulting image-instance. This keyword is not valid for -instantiator formats ＠code{nothing}, ＠code{string}, -＠code{formatted-string}, ＠code{cursor-font}, ＠code{font}, and -＠code{autodetect}. - -＠item :foreground -＠itemx :background -For ＠code{xbm}, ＠code{xface}, ＠code{cursor-font}, and ＠code{font}. -These keywords allow you to explicitly specify foreground and background -colors. The argument should be anything acceptable to -＠code{make-color-instance}. This will cause what would be a -＠code{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. - -＠item :mask-data -For ＠code{xbm} and ＠code{xface}. This specifies a mask to be used with the -bitmap. The format is a list of width, height, and bits, like for -＠code{:data}. - -＠item :mask-file -For ＠code{xbm} and ＠code{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 ＠samp{Mask} or -＠samp{msk} appended. For example, if you specify the XBM file -＠file{left_ptr} [usually located in ＠file{/usr/include/X11/bitmaps}], -the associated mask file ＠file{left_ptrmsk} will automatically be picked -up. - -＠item :hotspot-x -＠itemx :hotspot-y -For ＠code{xbm} and ＠code{xface}. These keywords specify a hotspot if -the image is instantiated as a ＠code{pointer}. Note that if the XBM -image file specifies a hotspot, it will automatically be picked up if no -explicit hotspot is given. - -＠item :color-symbols -Only for ＠code{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 ＠code{xpm-color-symbols} are -used to generate the alist. -＠item :resource-id -Only for ＠code{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". -＠item :resource-type -Only for ＠code{mswindows-resource}. This must be a symbol, either -＠code{cursor}, ＠code{icon}, or ＠code{bitmap}, specifying the type of -resource to be retrieved. -＠item :face -Only for ＠code{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. -＠end table - -Keywords accepted as menu item specs are also accepted by widgets. -These are ＠code{:selected}, ＠code{:active}, ＠code{:suffix}, -＠code{:keys}, ＠code{:style}, ＠code{:filter}, ＠code{:config}, -＠code{:included}, ＠code{:key-sequence}, ＠code{:accelerator}, -＠code{:label} and ＠code{: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 -＠code{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 ＠code{: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). - -＠defun valid-image-instantiator-format-p format &optional locale -This function returns non-＠code{nil} if ＠var{format} is a valid image -instantiator format. - -If ＠var{locale} is non-＠code{nil} then the format is checked in that locale. -If ＠var{locale} is ＠code{nil} the current console is used. - -Note that the return value for many formats listed above depends on -whether XEmacs was compiled with support for that format. -＠end defun - -＠defun image-instantiator-format-list -This function return a list of valid image-instantiator formats. -＠end defun +There are two convenience variables for use with the XBM and XPM image +formats. ＠defvar xpm-color-symbols This variable holds definitions of logical color-names used when reading ＠＠ -919,293 +689,1280 ＠＠ first). ＠end defvar -＠node Image Instantiator Conversion -＠subsection Image Instantiator Conversion -＠cindex image instantiator conversion -＠cindex conversion of image instantiators -＠defun set-console-type-image-conversion-list console-type list -This function sets the image-conversion-list for consoles of the given -＠var{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. +＠node Image Instances +＠subsection Image Instances +＠cindex image instances -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. + 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. + +＠defun image-instance-p object +This function returns non-＠code{nil} if ＠var{object} is an image instance. ＠end defun + +＠menu +* Image Instance Types:: Each image instances has a particular type. +* Image Instance Functions:: Functions for working with image instances. +＠end menu + + +＠node Image Instance Types +＠subsubsection Image Instance Types +＠cindex 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 + +＠table ＠code +＠item nothing +Nothing is displayed. + +＠item 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. + +＠item 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). +＠item color-pixmap + +Displayed as a color pixmap. + +＠item pointer +Used as the mouse pointer for a window. + +＠item 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. +＠c #### Check status of subwindows ... I thought Andy implemented them. + +＠item widget +An active GUI element implemented as a ``widget'' or ``control'' of the +underlying window system. +＠end table + +The following functions are used to check whether an image instance type +is valid in the running XEmacs. + +＠defun valid-image-instance-type-p type +This function returns non-＠code{nil} if ＠var{type} is a valid image +instance type. +＠end defun + +＠defun image-instance-type-list +This function returns a list of the valid image instance types. +＠end defun + +The following functions are used to determine the type of an image +instance. + +＠defun image-instance-type image-instance +Return the type of the given image instance. The return +value will be one of ＠code{nothing}, ＠code{text}, ＠code{mono-pixmap}, +＠code{color-pixmap}, ＠code{pointer}, ＠code{subwindow}, or ＠code{widget}. +＠c #### Check status of subwindows ... I thought Andy implemented them. +＠end defun + +＠defun text-image-instance-p object +Return non-＠code{nil} if ＠var{object} is an image instance of type +＠code{text}. +＠end defun + +＠defun mono-pixmap-image-instance-p object +Return non-＠code{nil} if ＠var{object} is an image instance of type +＠code{mono-pixmap}. +＠end defun + +＠defun color-pixmap-image-instance-p object +Return non-＠code{nil} if ＠var{object} is an image instance of type +＠code{color-pixmap}. +＠end defun + +＠defun pointer-image-instance-p object +Return non-＠code{nil} if ＠var{object} is an image instance of type +＠code{pointer}. +＠end defun + +＠defun subwindow-image-instance-p object +Return non-＠code{nil} if ＠var{object} is an image instance of type +＠code{subwindow}. +＠c #### Check status of subwindows ... I thought Andy implemented them. +＠end defun + +＠defun nothing-image-instance-p object +Return non-＠code{nil} if ＠var{object} is an image instance of type +＠code{nothing}. +＠end defun + +＠defun widget-image-instance-p object +Return non-＠code{nil} if ＠var{object} is an image instance of type +＠code{widget}. +＠end defun + + +＠node Image Instance Functions +＠subsubsection Image Instance Functions + +＠defun make-image-instance data &optional domain dest-types noerror +This function creates a new image-instance object. + +＠var{data} is an image instantiator, which describes the image +(＠pxref{Image Specifiers}). + +＠var{dest-types} should be a list of allowed image instance types that +can be generated. The ＠var{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 + +＠table ＠code +＠item XBM +＠c #### check xface +＠itemx xface +＠code{mono-pixmap}, then ＠code{color-pixmap}, then ＠code{pointer}. + +＠item XPM +＠itemx GIF +＠itemx JPEG +＠itemx PNG +＠itemx TIFF +＠code{color-pixmap}, then ＠code{mono-pixmap}, then ＠code{pointer}. + +＠item string +＠itemx formatted-string formats +＠code{text}, then ＠code{mono-pixmap} (not currently implemented), then +＠code{color-pixmap} (not currently implemented). + +＠item mswindows-resource +For pointer resources, ＠code{pointer}. + +For the others, ＠code{color-pixmap}. +＠end table + +＠c #### So what? This is a reference manual, list them, you lazy bastard! +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 ＠code{make-image-instance} +repeatedly until it succeeds, passing less and less preferred +destination types each time. + +If ＠var{dest-types} is omitted, all possible types are allowed. + +＠var{domain} specifies the domain to which the image instance will be +attached. This domain is termed the ＠dfn{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 ＠var{domain} (e.g. a frame when a +window was wanted), an error is signaled. If you specify an overly +specific ＠var{domain} (e.g. a window when a device was wanted), the +corresponding general domain is fetched and used instead. For +＠code{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 +＠code{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 ＠code{inherit}, but we currently disallow this.) +＠c #### We should fix that. + +If omitted, ＠var{domain} defaults to the selected window. + +＠var{noerror} controls what happens when the image cannot be generated. +If ＠code{nil}, an error message is generated. If ＠code{t}, no messages +are generated and this function returns ＠code{nil}. If anything else, a +warning message is generated and this function returns ＠code{nil}. +＠end defun + +＠defun 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 ＠code{nil} is returned). Otherwise ＠code{t} is +returned. +＠end defun + +The following functions are + +＠defun image-instance-name image-instance +This function returns the name of the given image instance. The name is +typically taken from the ＠code{:file} property of the instantiator if +present, otherwise from the ＠code{:data} property. +＠end defun + +＠defun image-instance-domain image-instance +Return the governing domain of the given ＠var{image-instance}. The +governing domain of an image instance is the domain that the image +instance is specific to. It is ＠emph{NOT} necessarily the domain that +was given to the call to ＠code{specifier-instance} that resulted in the +creation of this image instance. See ＠code{make-image-instance} for +more information on governing domains. +＠end defun + +＠defun image-instance-string image-instance +This function returns the string of the given image instance. This will +only be non-＠code{nil} for text image instances. +＠end defun + +＠defun image-instance-file-name image-instance +This function returns the file name from which ＠var{image-instance} was +read, if known. +＠end defun + +＠defun image-instance-mask-file-name image-instance +This function returns the file name from which ＠var{image-instance}'s +mask was read, if known. +＠end defun + +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. + +＠defun 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. +＠end defun + +＠defun image-instance-height image-instance +This function returns the height of the image instance, in pixels. +＠end defun + +＠defun image-instance-width image-instance +This function returns the width of the image instance, in pixels. +＠end defun + +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 ＠code{nil} for a non-pointer image instance. + +＠defun image-instance-hotspot-x image-instance +This function returns the X coordinate of the image instance's hotspot, +if known. +＠end defun + +＠defun image-instance-hotspot-y image-instance +This function returns the Y coordinate of the image instance's hotspot, +if known. +＠end defun + +Mono pixmaps and pointers may have their foreground and background +colors set when instanced. Use these functions to access color +information. + +＠defun image-instance-foreground image-instance +This function returns the foreground color of ＠var{image-instance}, if +applicable. This will be a color instance or ＠code{nil}. (It will only +be non-＠code{nil} for colorized mono pixmaps and for pointers.) +＠end defun + +＠defun image-instance-background image-instance +This function returns the background color of ＠var{image-instance}, if +applicable. This will be a color instance or ＠code{nil}. (It will only +be non-＠code{nil} for colorized mono pixmaps and for pointers.) +＠end defun + + +＠node Using Glyphs +＠section Using Glyphs + +Glyph usage is unfortunately somewhat arcane. (For discussion of +rationale, ＠ref{Glyphs,,,Internals}.) Because they are not ``text,'' +they cannot be inserted directly into a buffer. Instead, they are +values of properties of extents attached to buffers or strings, values +of global variables such as mouse pointers, or as a component of a +complex data structure such as a toolbar initializer. Although these +uses could probably streamlined, each structure has its own +requirements. Since glyphs are very flexible, it is possible to create +applications like the ＠file{edit-toolbar} and ＠file{xpm-mode} libraries +which display glyphs in a buffer (for reference while editing) that are +normally used in a different context. + +Usage of glyphs can roughly be categorized as follows: + +＠table ＠strong +＠item Buffer glyphs +Glyphs that are inserted in a buffer may be used for their own sake (for +example, image display in ＠file{w3}), as an accurate representation of +text that can't be displayed in usual fonts (equation display in +＠file{preview-latex}), or as annotations (such as a marginal indication +of a bookmark). Glyphs are attached to buffers via extents. + +＠item Redisplay glyphs +Glyphs can be used to create XEmacs-specific ``fonts''. For example, +the character that indicates truncation of lines is implemented as the +＠code{truncation-glyph}. It is also possible to have XEmacs display a +certain character using a custom glyph, via display tables. + +＠item Frame glyphs +Glyphs are used to control the appearance of various other components of +the frame. They can be inserted in the modeline, like the favicons used +in Web browsers. They are used to specify the labels on toolbar +buttons. Finally, they can be inserted in the gutters. (The difference +between a glyph inserted in a gutter and a marginal annotation is that +the marginal annotation is tied to the text in the buffer. If the +buffer line scrolls out of view, the marginal annotation will, as well. +A gutter glyph does not move with the text.) + +Unfortunately, all these uses are special cases, and have their own +APIs, in contrast to glyphs in a buffer. + +＠item External glyphs +External glyphs simply allow a consistent API for images. The images +are then passed to external software such as the window system itself +(mouse cursor shapes) and the window manager (icons to represent +minimized windows). XEmacs has no role in managing their use. + +＠item Subwindow and widget glyphs +These do not constitute a context of use, but rather an important class of +glyph types. The difference between these and other glyphs is that +while their geometry is determined by XEmacs, their behavior is managed +separately, by internal mechanisms in the case of widgets, and +(possibly) by another process in the case of subwindows. +＠c #### Check status of subwindows ... I thought Andy implemented them. +＠end table + +Some simple concrete examples showing how to insert a glyph in a +buffer are presented later. ＠ref{Glyph Examples}. + +``Creating Glyphs'' explains how to create glyphs. Creating a glyph +using ＠code{make-glyph} does not specify ＠emph{where} the glyph will be +used, it only specifies ＠emph{what} the glyph will look like. The next +four sections explain how to embed glyphs in different display +contexts. Finally, the last two sections explain the special +considerations of using glyphs whose behavior is not determined by the +code creating them, but by the glyph itself (a ``widget'' in X11 or +``control'' in MS Windows or Aqua), or even by a separate process. + +＠menu +* Creating Glyphs:: Creating new glyphs. +* Buffer Glyphs:: Annotations are glyphs that appear in a buffer. +* Redisplay Glyphs:: Glyphs controlling various redisplay functions. +* Frame Glyphs:: Displaying glyphs in GUI components of the frame. +* External Glyphs:: Icons and mouse pointers for the window system. +* Native GUI Widgets:: Complex active elements treated as a single glyph. +* Subwindows:: Externally-controlled subwindows in buffers. +＠c #### Check status of subwindows ... I thought Andy implemented them. +＠end menu + +＠node Creating Glyphs +＠subsection Creating Glyphs + +＠defun make-glyph &optional spec-list type +This function creates a new glyph object of type ＠var{type}. + +The optional ＠var{spec-list} is used to initialize the glyph's image. +It can be any spec-list of ＠dfn{image instantiator} accepted by +＠code{canonicalize-spec-list}, ＠ref{Adding Specifications}. An +individual image instantiator may be a string, which is converted to a +vector according to ＠code{console-type-image-conversion-list}, or a +vector. The vector's first element specifies the ＠emph{external} format +of the data, such as a string, a PNG file, or an MS Windows resource. +This is followed by properties (keyword-value pairs) specifying such +information as the name of a file containing an image, or pixmap data +directly. ＠xref{Image Specifiers}. + +The optional ＠var{type} specifies the type of the glyph. ＠var{type} +should be one of ＠code{buffer} (used for glyphs in an extent, the +modeline, the toolbar, or elsewhere in a frame), ＠code{pointer} (used +for the mouse-pointer), or ＠code{icon} (used for a frame's icon), and +defaults to ＠code{buffer}. +＠end defun + +＠var{spec-list} is the initializer for the glyph's ＠code{image} +property, which is an image specifier. (Note that ＠dfn{image} as used +in the context of a glyph's ＠code{image} property or in the terms +＠dfn{image specifier}, ＠dfn{image instantiator}, or ＠dfn{image instance} +does not refer to what people normally think of as an image (which in +XEmacs is called a ＠dfn{pixmap}), but to any graphical element---a +pixmap, a widget, or even a block of text, when used in the places that +call for a glyph.) + +The most common form of ＠var{spec-list} is a single image instantiator. +(＠strong{Compatibility note:} in GNU Emacs 21, a string used to +instantiate an image is interpreted as the name of an image file, which +is searched for and instantiated.) The conversion controlled by +＠code{console-type-image-conversion-list} typically attempts to look up +the string as a file name in XEmacs's data directory path, and if this +fails, defaults to displaying the string as a text image instance +((a)emph{i.e.}. the string itself. + +Fine control of a particular specification is provided by using a vector +as the image instantiator. More complicated instantiators allow lists +of instantiators to be specified (which are tried in order), or mappings +from locales to lists of instantiators, ＠emph{etc}. ＠xref{Specifiers}, +for more information about specification formats. + +As well as using ＠var{spec-list} to initialize the glyph, you can set +specifications using ＠code{set-glyph-image}. The glyph itself is not +actually a specifier, but rather is an object containing an image +specifier (as well as other properties seldom set by user code). +Therefore, you cannot set or access specifications for the glyph's image +by directly using ＠code{set-specifier}, ＠code{specifier-instance} or the +like on the glyph; instead use them on ＠code{(glyph-image ＠var{glyph})} +or use the convenience functions ＠code{set-glyph-image}, +＠code{glyph-image-instance}, and ＠code{glyph-image}. + +Glyph types reflect the fact that glyphs are used in contexts like +pointers and window manager icons, which are defined by external +programs such as the window system or window manager. These require +somewhat different ＠emph{internal} format, which is opaque to the user. + +It is extremely rare that you will ever have to specify a value for +＠var{type}, which should be one of ＠code{buffer} (used for glyphs in an +extent, the modeline, the toolbar, or elsewhere in a buffer), +＠code{pointer} (used for the mouse-pointer), or ＠code{icon} (used for a +frame's icon), and defaults to ＠code{buffer}. The only cases where it +needs to be specified is when creating icon or pointer glyphs, and in +both cases the necessary glyphs have already been created at startup and +are accessed through the appropriate variables, +e.g. ＠code{text-pointer-glyph} (or in general, any +＠samp{*-pointer-glyph}) and ＠code{frame-icon-glyph}. User code should +never need to create ＠code{pointer} or ＠code{icon} glyphs. ＠xref{Glyph +Types}. + +There are a few other glyph creation functions, normally used only +internally or at XEmacs initialization. + +＠defun make-glyph-internal &optional type +This function creates a new, uninitialized glyph of type ＠var{type}. +＠end defun + +＠defun make-pointer-glyph &optional spec-list + +Return a new ＠code{pointer-glyph} object with the specification list +＠var{spec-list}. This function is equivalent to calling +＠code{make-glyph} with a ＠var{type} of ＠code{pointer}. +＠end defun + +＠code{make-pointer-glyph} is normally used only by XEmacs initialization +code. It is extremely unlikely that you will ever need to create a +pointer glyph. Instead, you probably want to be calling +＠code{set-glyph-image} on an existing glyph, +e.g. ＠code{text-pointer-glyph}. + +＠defun make-icon-glyph &optional spec-list + +Return a new ＠code{icon-glyph} object with the specification list +＠var{spec-list}. This function is equivalent to calling +＠code{make-glyph} with a ＠var{type} of ＠code{icon}. +＠end defun + +＠code{make-icon-glyph} is normally used only by XEmacs initialization +code. It is extremely unlikely that you will ever need to create a icon +glyph. Instead, you probably want to be calling ＠code{set-glyph-image} +on the existing glyph, ＠code{frame-icon-glyph}. + + +＠node Buffer Glyphs +＠subsection Buffer Glyphs + +Creating a glyph using ＠code{make-glyph} does not specify ＠emph{where} +the glyph will be used, it only specifies ＠emph{what} the glyph will +look like. Once you have created a glyph, you specify where it will be +used by attaching it to an extent as a ＠emph{begin-glyph} or +＠emph{end-glyph}. + +＠table ＠code +＠item buffer text +To insert a glyph into a buffer, create an extent in the buffer and then +use ＠code{set-extent-begin-glyph} or ＠code{set-extent-end-glyph} to set +a glyph to be displayed at the corresponding edge of the extent. (It is +common to create zero-width extents for this purpose.) + +＠item margins +To insert a glyph into the left or right margin of a buffer, first +make sure the margin is visible by setting a value for the specifiers +＠code{left-margin-width} or ＠code{right-margin-width}. (Not strictly necessary +when using margin glyphs with layout policy ＠code{whitespace}.) Follow +the same procedure above for inserting a glyph in a buffer, then +set a non-default layout policy for the glyph using +＠code{set-extent-begin-glyph-layout} or ＠code{set-extent-end-glyph-layout}. +Alternatively, use the high-level annotations API (see +＠code{make-annotation}). (In fact, you can also use the annotations +API for glyphs in a buffer, by setting a layout policy of ＠code{text}.) + +＠end table + + +＠node Redisplay Glyphs +＠subsection Redisplay Glyphs + +To use a glyph to control the shape of miscellaneous redisplay effects +such as the truncation and continuation markers, set the appropriate +existing glyph variables with ＠code{set-glyph-image}. See +＠code{continuation-glyph}, ＠code{control-arrow-glyph}, +＠code{hscroll-glyph}, ＠code{invisible-text-glyph}, +＠code{octal-escape-glyph}, and ＠code{truncation-glyph}. See also +＠code{overlay-arrow-string}, an odd redisplay leftover which can be set +to a glyph you created, and will cause the glyph to be displayed on top +of the text position specified in the marker stored in +＠code{overlay-arrow-position}. + +To use a glyph in a display table (i.e. to control the appearance of any +individual character), create the appropriate character glyphs and then +set a specification for the specifier ＠code{current-display-table}, +which controls the appearance of characters. You can also set an +overriding display table for use with text displayed in a particular +face; see ＠code{set-face-display-table} and ＠code{make-display-table}. +#### Note: Display tables do not currently support general Mule +characters. They will be overhauled at some point to support this +and to provide other features required under Mule. ＠ref{Display Tables}. + +Glyphs are not actually used as the background pixmaps of faces, but the +API is similar. The +background pixmap of a face is actually an image specifier -- probably +the only place in XEmacs where an image specifier occurs outside of a +glyph. If you would like to use a glyph's image as a background pixmap, +you can extract it with ＠code{glyph-image}, and then add it to a face. +＠xref{Face Convenience Functions}. + +＠defvr Glyph truncation-glyph +This variable specifies what is displayed at the end of truncated lines. +＠end defvr + +＠defvr Glyph continuation-glyph +This variable specifies what is displayed at the end of wrapped lines. +＠end defvr + +＠defvr Glyph octal-escape-glyph +This variable specifies what to prefix character codes displayed in octal +with. +＠end defvr + +＠defvr Glyph hscroll-glyph +This variable specifies what to display at the beginning of horizontally +scrolled lines. +＠end defvr + +＠defvr 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 ＠code{selective-display-ellipses} or +＠code{buffer-invisibility-spec}). Normally this is three dots (``...''). +＠end defvr + +＠defvr Glyph control-arrow-glyph +This variable specifies what to use as an arrow for control characters. +＠end defvr + + +＠node Frame Glyphs +＠subsection Frame Glyphs + +There are also a number of special objects whose appearance is specified +by a glyph. Most of these a global objects that you update with +＠code{set-glyph-image}, such as mouse pointers. Frame icons, toolbar +button icons, and the modeline are the main non-text objects which +accept glyphs as elements. + +＠table ＠code +＠item modeline +A glyph may be displayed in the modeline by inserting the glyph as one +of the elements of the modeline format. (Unfortunately you can't +currently put a begin glyph or end glyph on one of the modeline +extents---they're ignored.) + +＠item toolbar +To insert a glyph into a toolbar, specify it as the icon part of a toolbar +button, which in turn must be part of a toolbar instantiator (typically +set on the specifier ＠code{default-toolbar}). +See ＠code{default-toolbar} for more information. (As a convenience, you +may use a symbol in place of the glyph list in the toolbar button +instantiator; the symbol is evalled to get the glyph list. This +facilitates both creating the toolbar instantiator and modifying +individual glyphs in a toolbar later on. For example, you can change +the way that the Mail toolbar button looks by modifying the value of the +variable ＠code{toolbar-mail-icon} (in general, ＠code{toolbar-*-icon}) +and then calling ＠code{(set-specifier-dirty-flag default-toolbar)}. +(#### Unfortunately this doesn't quite work the way it should; the +change will appear in new frames, but not existing ones, because once an +image has been displayed the pixmap replaces the symbol for those domains.) + +＠item gutter +To insert a glyph into a gutter, use +＠code{set-extent-begin-glyph} or ＠code{set-extent-end-glyph} to set a +glyph to be displayed at the corresponding edge of extent in a string, +similar to the way you insert glyphs in a buffer. Then insert the +string into the gutter ＠ref{Specifying a Gutter}. Glyphs that are +frequently used in this way are ＠code{tab control} and ＠code{progress +bar} glyphs. + +＠end table + + +＠node External Glyphs +＠subsection External Glyphs +＠cindex frame icon +＠cindex icon, frame +＠cindex mouse cursor +＠cindex cursor (mouse) +＠cindex pointer (mouse) +＠cindex mouse pointer + +There are two special kinds of glyph that are not displayed by XEmacs. +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 ＠xref{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 +＠code{frame-icon-glyph} with ＠code{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 ＠code{text-pointer-glyph} for the pointer used over +text, ＠code{modeline-pointer-glyph} for the pointer used over the +modeline, etc. Do an apropos over ＠samp{pointer-glyph} to find all of +them. (Note also that you can temporarily set the mouse pointer to some +specific shape by using ＠code{set-frame-pointer}, which takes an image +instance, as obtained from calling ＠code{glyph-image-instance} on a glyph +of type ＠code{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 ＠code{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 ＠code{mode-motion-hook}, or ＠code{mouse-motion-handler} if you +really want to get low-level.) + +You should use ＠code{set-glyph-image} to set the following variables, +＠emph{not} ＠code{setq}. + +＠defvr Glyph text-pointer-glyph +This variable specifies the shape of the mouse pointer when over text. +＠end defvr + +＠defvr 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, +＠code{text-pointer-glyph} is used. +＠end defvr + +＠defvr Glyph modeline-pointer-glyph +This variable specifies the shape of the mouse pointer when over the modeline. +If unspecified in a particular domain, ＠code{nontext-pointer-glyph} is used. +＠end defvr + +＠defvr 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, +＠code{text-pointer-glyph} is used. +＠end defvr + +＠defvr 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 ＠code{gc-message}. +＠end defvr + +＠defvr 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. +＠end defvr + +＠defvr 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. +＠end defvr + +＠defvr 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. +＠end defvr + +＠defvr Glyph toolbar-pointer-glyph +This variable specifies the shape of the mouse pointer when over a +toolbar. If unspecified in a particular domain, +＠code{nontext-pointer-glyph} is used. +＠end defvr + +Internally, these variables are implemented in +＠code{default-mouse-motion-handler}, and thus only take effect when the +mouse moves. That function calls ＠code{set-frame-pointer}, which sets +the current mouse pointer for a frame. + +＠defun set-frame-pointer frame image-instance +This function sets the mouse pointer of ＠var{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.) +＠end defun + + +＠node Native GUI Widgets +＠subsection Native GUI Widgets +＠cindex native widget + +A ``native widget'' is a primitive GUI object defined either by the host +GUI platform or an external toolkit, and accessed from Lisp as a +``glyph.'' + +＠menu +* Introduction to Widgets:: Native widgets provide tight integration of + GUI features with the platform GUI. +* Lisp API to Native Widgets:: Native widgets are glyphs. +* Layouts:: Specifying composite widgets from Lisp. +* Primitive Widgets:: Catalogue of available native widgets. +＠end menu + +＠node Introduction to Widgets +＠subsubsection Introduction to Native Widgets and Subwindow Glyphs + +Traditionally Emacsen have hidden the GUI apparatus from the Lisp +programmer, but in XEmacs 21.4 the ability to embed autonomous GUI +objects, called ＠dfn{native widgets}, in text was added to Lisp. They +are handled as ＠emph{glyphs}. Unlike traditional XEmacs +glyphs such images and strings, native widgets are opaque to XEmacs, and +must be able to redraw themselves because they are implemented as +subwindows, not as graphics drawn by XEmacs into the text window. + +Primitive widgets are coded in C using the underlying GUI toolkit, and +thus are beyond the scope of the ＠emph{XEmacs Lisp Reference Manual}. +However, composite widgets can be created in Lisp using ``layouts,'' +which are horizontal or vertical arrays of subwidgets. For example, the +search dialog is formatted using layouts. + +＠node Lisp API to Native Widgets +＠subsubsection Lisp API to Native Widgets + +Native widgets are manipulated as ＠emph{glyphs} (＠pxref{Glyphs}). Thus +they are created using ＠code{make-glyph}, with a format of one of the +widget types and a ＠code{:data} property specific to the widget being +instanced. + +However, there is a technical difference between widgets and other kinds +of glyphs that is theoretically important. Because widgets +are active (that is, they can respond to user input events themselves), +it is possible for the user to become aware that two appearances of the +``same'' glyph are actually separate instances. For example, if a user +changes an image glyph from red to blue, and the buffer containing the +glyph appears in more than one window, the user will perceive all the +appearances to change from red to blue simultaneously. However, suppose +the glyph is a button glyph (＠emph{e.g.}, as used in the Customize +buffer for the Set, Save, and Done buttons). Then if the Customize +buffer appears in several windows at the same time, and the user clicks +on the button, she will only perceive the button to be depressed in the +window where she clicked the button. + +It seems from this example that it is unlikely to be a problem in +practice. When the user is faced with an active widget, it seems likely +that attention will focus on the widget being manipulated, and having +other instances of the widget respond simultaneously might be more +disconcerting than the actual case. + +＠node Layouts +＠subsubsection Layouts + +An XEmacs ＠dfn{layout} is a one-dimensional array of glyphs. It is 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. +＠c #### Fix me! +(There are also ＠dfn{native layouts}, but these are undocumented, as are +their uses.) + +A layout descriptor is an image instantiator, ＠emph{i.e.}, a vector of +the form ＠samp{[FORMAT KEY-1 VALUE-1 KEY-2 VALUE-2 ...]} with format +＠code{layout}, and properties + +＠c #### need defaults for these +＠table ＠code +＠item :orientation +Specifies the orientation of the contained array of glyphs. The value +must be one of the symbols ＠code{horizontal} or ＠code{vertical}. + +＠item :horizontally-justify +Specifies the horizontal justification of the items in the array. The +value must be one of the symbols ＠code{:right}, ＠code{:center}, or +＠code{:left}. + +＠item :vertically-justify +Specifies the vertical justification of the items in the array. The +value must be one of the symbols ＠code{:top}, ＠code{:center}, or +＠code{:bottom}. + +＠item :justify +Specifies justification. #### not understood. + +＠item :border +A glyph to place in the border. The value must be an image +instantiator. + +＠item :items +The glyphs controlled by the layout. The value must be a list of image +instantiators. +＠end table + +Here is the specification of the search dialog widget created by +＠code{make-search-dialog} in the ＠file{dialog-items} library, which +makes use of recursive layouts. + +＠example +(make-glyph + `[layout + :orientation horizontal + :vertically-justify top + :horizontally-justify center + :border [string :data "Search"] + :items + ([layout :orientation vertical + :justify top ; implies left also + :items + ([string :data "Search for:"] + [button :descriptor "Match Case" + :style toggle + :selected (not case-fold-search) + :callback (setq case-fold-search + (not case-fold-search))] + [button :descriptor "Regular Expression" + :style toggle + :selected search-dialog-regexp + :callback (setq search-dialog-regexp + (not search-dialog-regexp))] + [button :descriptor "Forwards" + :style radio + :selected search-dialog-direction + :callback (setq search-dialog-direction t)] + [button :descriptor "Backwards" + :style radio + :selected (not search-dialog-direction) + :callback (setq search-dialog-direction nil)] + )] + [layout :orientation vertical + :vertically-justify top + :horizontally-justify right + :items + ([edit-field :width 15 :descriptor "" :active t + :initial-focus t] + [button :width 10 :descriptor "Find Next" + :callback-ex + (lambda (image-instance event) + (search-dialog-callback ,parent + image-instance + event))] + [button :width 10 :descriptor "Cancel" + :callback-ex + (lambda (image-instance event) + (isearch-dehighlight) + (delete-frame + (event-channel event)))])])]) +＠end example + +＠node Primitive Widgets +＠subsubsection Primitive Widgets + +＠c #### the following table should be replaced with a menu of nodes +＠table ＠code +＠item button +A button widget; either a push button, radio button or toggle +button. + +＠item combo-box +A drop list of selectable items in a widget, for editing text. + +＠item edit-field +A text editing widget. + +＠item label +A static, text-only, widget; for displaying text. + +＠item progress-gauge +A sliding widget, for showing progress. -＠defun console-type-image-conversion-list console-type -This function returns the image-conversion-list for consoles of the given -＠var{console-type}. -＠end defun +＠item tab-control +A tab widget; a series of user selectable tabs. -＠node Image Instances -＠subsection Image Instances -＠cindex image instances +＠item tree-view +A folding widget. - Image-instance objects encapsulate the way a particular image (pixmap, -etc.) is displayed on a particular device. +＠item scrollbar +A scrollbar widget. (#### Probably not the same as the scrollbar +controlling an Emacs window.) +＠end table - 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. -＠defun image-instance-p object -This function returns non-＠code{nil} if ＠var{object} is an image instance. +＠node Subwindows +＠subsection Subwindows + +Subwindows are not currently implemented. +＠c #### Check status of subwindows ... I thought Andy implemented them. + +＠defun subwindowp object +This function returns non-＠code{nil} if ＠var{object} is a subwindow. ＠end defun + +＠node Manipulating Glyphs +＠section Manipulating Glyphs + + Each glyphs has properties that may be accessed. Most of these can +also be set after the glyph is initialized, with the exception of the +glyph's type. This is not a real restriction, as it is almost never +useful to create glyphs of types other than ＠code{buffer}. + ＠menu -* Image Instance Types:: Each image instances has a particular type. -* Image Instance Functions:: Functions for working with image instances. +* Glyph Properties:: Accessing and modifying a glyph's properties. +* Glyph Convenience Functions:: Accessing particular properties of a glyph. +* Glyph Dimensions:: Determining the height, width, etc. of a glyph. +* Glyph Types:: Each glyph has a particular type. ＠end menu -＠node Image Instance Types -＠subsubsection Image Instance Types -＠cindex 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. +＠node Glyph Properties +＠subsection Glyph Properties - The valid image instance types are +Each glyph has a list of properties, which control all of the aspects of +the glyph's appearance. The following symbols have predefined meanings: ＠table ＠code -＠item nothing -Nothing is displayed. +＠item image +The image used to display the glyph. -＠item 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. +＠item baseline +Percent above baseline that glyph is to be displayed. Only for glyphs +displayed inside of a buffer. -＠item 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). -＠item color-pixmap +＠item contrib-p +Whether the glyph contributes to the height of the line it's on. +Only for glyphs displayed inside of a buffer. -Displayed as a color pixmap. +＠item face +Face of this glyph (＠emph{not} a specifier). +＠end table -＠item pointer -Used as the mouse pointer for a window. +＠defun set-glyph-property glyph property value &optional locale tag-set how-to-add +This function changes a property of a ＠var{glyph}. -＠item 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. -＠end table +For built-in properties, the actual value of the property is a specifier +and you cannot change this; but you can change the specifications within +the specifier, and that is what this function will do. The glyph face +is an exception; it is a face name (a symbol) or a face object, not a +specifier. (The face properties themselves are typically specifiers.) +For user-defined properties, you can use this function to either change +the actual value of the property or, if this value is a specifier, +change the specifications within it. -＠defun valid-image-instance-type-p type -This function returns non-＠code{nil} if ＠var{type} is a valid image -instance type. -＠end defun +If ＠var{property} is a built-in property, the specifications to be added +to this property can be supplied in many different ways: -＠defun image-instance-type-list -This function returns a list of the valid image instance types. -＠end defun +＠itemize ＠bullet +＠item +If ＠var{value} is a simple instantiator (e.g. a string naming a pixmap +filename) or a list of instantiators, then the instantiator(s) will be +added as a specification of the property for the given ＠var{locale} +(which defaults to ＠code{global} if omitted). -＠defun image-instance-type image-instance -This function returns the type of the given image instance. The return -value will be one of ＠code{nothing}, ＠code{text}, ＠code{mono-pixmap}, -＠code{color-pixmap}, ＠code{pointer}, or ＠code{subwindow}. -＠end defun +＠item +If ＠var{value} is a list of specifications (each of which is a cons of a +locale and a list of instantiators), then ＠var{locale} must be +＠code{nil} (it does not make sense to explicitly specify a locale in +this case), and specifications will be added as given. -＠defun text-image-instance-p object -This function returns non-＠code{nil} if ＠var{object} is an image -instance of type ＠code{text}. -＠end defun +＠item +If ＠var{value} is a specifier (as would be returned by +＠code{glyph-property} if no ＠var{locale} argument is given), then some +or all of the specifications in the specifier will be added to the +property. In this case, the function is really equivalent to +＠code{copy-specifier} and ＠var{locale} has the same semantics (if it is +a particular locale, the specification for the locale will be copied; if +a locale type, specifications for all locales of that type will be +copied; if ＠code{nil} or ＠code{all}, then all specifications will be +copied). +＠end itemize -＠defun mono-pixmap-image-instance-p object -This function returns non-＠code{nil} if ＠var{object} is an image -instance of type ＠code{mono-pixmap}. -＠end defun +＠var{how-to-add} should be either ＠code{nil} or one of the symbols +＠code{prepend}, ＠code{append}, ＠code{remove-tag-set-prepend}, +＠code{remove-tag-set-append}, ＠code{remove-locale}, +＠code{remove-locale-type}, or ＠code{remove-all}. See +＠code{copy-specifier} and ＠code{add-spec-to-specifier} for a description +of what each of these means. Most of the time, you do not need to worry +about this argument; the default behavior usually is fine. -＠defun color-pixmap-image-instance-p object -This function returns non-＠code{nil} if ＠var{object} is an image -instance of type ＠code{color-pixmap}. -＠end defun +In general, it is OK to pass an instance object (e.g. as returned by +＠code{glyph-property-instance}) as an instantiator in place of an actual +instantiator. In such a case, the instantiator used to create that +instance object will be used (for example, if you set a font-instance +object as the value of the ＠code{font} property, then the font name used +to create that object will be used instead). In some cases, however, +doing this conversion does not make sense, and this will be noted in the +documentation for particular types of instance objects. -＠defun pointer-image-instance-p object -This function returns non-＠code{nil} if ＠var{object} is an image -instance of type ＠code{pointer}. +If ＠var{property} is not a built-in property, then this function will +simply set its value if ＠var{locale} is ＠code{nil}. However, if +＠var{locale} is given, then this function will attempt to add +＠var{value} as the instantiator for the given ＠var{locale}, using +＠code{add-spec-to-specifier}. If the value of the property is not a +specifier, it will automatically be converted into a ＠code{generic} +specifier. ＠end defun -＠defun subwindow-image-instance-p object -This function returns non-＠code{nil} if ＠var{object} is an image -instance of type ＠code{subwindow}. -＠end defun +＠defun glyph-property glyph property &optional locale +This function returns ＠var{glyph}'s value of the given ＠var{property}. -＠defun nothing-image-instance-p object -This function returns non-＠code{nil} if ＠var{object} is an image -instance of type ＠code{nothing}. -＠end defun +If ＠var{locale} is omitted, the ＠var{glyph}'s actual value for +＠var{property} will be returned. For built-in properties, this will be +a specifier object of a type appropriate to the property (e.g. a font or +color specifier). For other properties, this could be anything. -＠defun widget-image-instance-p object -Return ＠code{t} if ＠var{object} is an image instance of type ＠code{widget}. +If ＠var{locale} is supplied, then instead of returning the actual value, +the specification(s) for the given locale or locale type will be +returned. This will only work if the actual value of ＠var{property} is +a specifier (this will always be the case for built-in properties, but +may or may not apply to user-defined properties). If the actual value +of ＠var{property} is not a specifier, this value will simply be returned +regardless of ＠var{locale}. + +The return value will be a list of instantiators (e.g. vectors +specifying pixmap data), or a list of specifications, each of which is a +cons of a locale and a list of instantiators. Specifically, if +＠var{locale} is a particular locale (a buffer, window, frame, device, or +＠code{global}), a list of instantiators for that locale will be +returned. Otherwise, if ＠var{locale} is a locale type (one of the +symbols ＠code{buffer}, ＠code{window}, ＠code{frame}, or ＠code{device}), +the specifications for all locales of that type will be returned. +Finally, if ＠var{locale} is ＠code{all}, the specifications for all +locales of all types will be returned. + +The specifications in a specifier determine what the value of +＠var{property} will be in a particular ＠dfn{domain} or set of +circumstances, which is typically a particular Emacs window along with +the buffer it contains and the frame and device it lies within. The +value is derived from the instantiator associated with the most specific +locale (in the order buffer, window, frame, device, and ＠code{global}) +that matches the domain in question. In other words, given a domain +(i.e. an Emacs window, usually), the specifier for ＠var{property} will +first be searched for a specification whose locale is the buffer +contained within that window; then for a specification whose locale is +the window itself; then for a specification whose locale is the frame +that the window is contained within; etc. The first instantiator that +is valid for the domain (usually this means that the instantiator is +recognized by the device [i.e. the X server or TTY device] that the +domain is on). The function ＠code{glyph-property-instance} actually does +all this, and is used to determine how to display the glyph. ＠end defun -＠node Image Instance Functions -＠subsubsection Image Instance Functions +＠defun glyph-property-instance glyph property &optional domain default no-fallback +This function returns the instance of ＠var{glyph}'s ＠var{property} in the +specified ＠var{domain}. -＠defun make-image-instance data &optional domain dest-types noerror -This function creates a new image-instance object. +Under most circumstances, ＠var{domain} will be a particular window, and +the returned instance describes how the specified property actually is +displayed for that window and the particular buffer in it. Note that +this may not be the same as how the property appears when the buffer is +displayed in a different window or frame, or how the property appears in +the same window if you switch to another buffer in that window; and in +those cases, the returned instance would be different. -＠var{data} is an image instantiator, which describes the image -(＠pxref{Image Specifiers}). +The returned instance is an image-instance object, and you can query it +using the appropriate image instance functions. For example, you could use +＠code{image-instance-depth} to find out the depth (number of color +planes) of a pixmap displayed in a particular window. The results might +be different from the results you would get for another window (perhaps +the user specified a different image for the frame that window is on; or +perhaps the same image was specified but the window is on a different X +server, and that X server has different color capabilities from this +one). -＠var{dest-types} should be a list of allowed image instance types that -can be generated. The ＠var{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 ＠code{mono-pixmap}, followed by -＠code{color-pixmap}, followed by ＠code{pointer}. For the other normal -image formats, the most natural types are ＠code{color-pixmap}, followed -by ＠code{mono-pixmap}, followed by ＠code{pointer}. For the string and -formatted-string formats, the most natural types are ＠code{text}, -followed by ＠code{mono-pixmap} (not currently implemented), followed by -＠code{color-pixmap} (not currently implemented). For MS Windows -resources, the most natural type for pointer resources is -＠code{pointer}, and for the others it's ＠code{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 ＠code{make-image-instance} repeatedly until it -succeeds, passing less and less preferred destination types each time. +＠var{domain} defaults to the selected window if omitted. -If ＠var{dest-types} is omitted, all possible types are allowed. +＠var{domain} can be a frame or device, instead of a window. The value +returned for such a domain is used in special circumstances when a +more specific domain does not apply; for example, a frame value might be +used for coloring a toolbar, which is conceptually attached to a frame +rather than a particular window. The value is also useful in +determining what the value would be for a particular window within the +frame or device, if it is not overridden by a more specific +specification. -＠var{domain} specifies the domain to which the image instance will be -attached. This domain is termed the ＠dfn{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 ＠var{property} does not name a built-in property, its value will +simply be returned unless it is a specifier object, in which case it +will be instanced using ＠code{specifier-instance}. -If you specify an overly general ＠var{domain} (e.g. a frame when a -window was wanted), an error is signaled. If you specify an overly -specific ＠var{domain} (e.g. a window when a device was wanted), the -corresponding general domain is fetched and used instead. For -＠code{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 -＠code{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 ＠code{inherit}, but we currently disallow this. #### We should -fix this.) -n -If omitted, ＠var{domain} defaults to the selected window. +Optional arguments ＠var{default} and ＠var{no-fallback} are the same as +in ＠code{specifier-instance}. ＠xref{Specifiers}. +＠end defun -＠var{noerror} controls what happens when the image cannot be generated. -If ＠code{nil}, an error message is generated. If ＠code{t}, no messages -are generated and this function returns ＠code{nil}. If anything else, a -warning message is generated and this function returns ＠code{nil}. +＠defun remove-glyph-property glyph property &optional locale tag-set exact-p +This function removes a property from a glyph. For built-in properties, +this is analogous to ＠code{remove-specifier}. ＠xref{Specifiers, +remove-specifier-p}, for the meaning of the ＠var{locale}, ＠var{tag-set}, +and ＠var{exact-p} arguments. ＠end defun -＠defun 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 ＠code{nil} is returned). Otherwise ＠code{t} is -returned. + +＠node Glyph Convenience Functions +＠subsection Glyph Convenience Functions + + The following functions are provided for working with specific +properties of a glyph. Note that these are exactly like calling +the general functions described above and passing in the +appropriate value for ＠var{property}. + + Remember that if you want to determine the ``value'' of a +specific glyph property, you probably want to use the ＠code{*-instance} +functions. For example, to determine whether a glyph contributes +to its line height, use ＠code{glyph-contrib-p-instance}, not +＠code{glyph-contrib-p}. (The latter will return a boolean specifier +or a list of specifications, and you probably aren't concerned with +these.) + +＠defun glyph-image glyph &optional locale +This function is equivalent to calling ＠code{glyph-property} with +a property of ＠code{image}. The return value will be an image +specifier if ＠var{locale} is ＠code{nil} or omitted; otherwise, +it will be a specification or list of specifications. ＠end defun -＠defun image-instance-name image-instance -This function returns the name of the given image instance. +＠defun set-glyph-image glyph spec &optional locale tag-set how-to-add +This function is equivalent to calling ＠code{set-glyph-property} with +a property of ＠code{image}. ＠end defun -＠defun image-instance-domain image-instance +＠defun glyph-image-instance glyph &optional domain default no-fallback +This function returns the instance of ＠var{glyph}'s image in the given +＠var{domain}, and is equivalent to calling +＠code{glyph-property-instance} with a property of ＠code{image}. The +return value will be an image instance. -Return the governing domain of the given ＠var{image-instance}. The -governing domain of an image instance is the domain that the image -instance is specific to. It is ＠emph{NOT} necessarily the domain that -was given to the call to ＠code{specifier-instance} that resulted in the -creation of this image instance. See ＠code{make-image-instance} for -more information on governing domains. +Normally ＠var{domain} will be a window or ＠code{nil} (meaning the +selected window), and an instance object describing how the image +appears in that particular window and buffer will be returned. ＠end defun +＠defun glyph-contrib-p glyph &optional locale +This function is equivalent to calling ＠code{glyph-property} with +a property of ＠code{contrib-p}. The return value will be a boolean +specifier if ＠var{locale} is ＠code{nil} or omitted; otherwise, +it will be a specification or list of specifications. +＠end defun -＠defun image-instance-string image-instance -This function returns the string of the given image instance. This will -only be non-＠code{nil} for text image instances. +＠defun set-glyph-contrib-p glyph spec &optional locale tag-set how-to-add +This function is equivalent to calling ＠code{set-glyph-property} with +a property of ＠code{contrib-p}. ＠end defun -＠defun image-instance-file-name image-instance -This function returns the file name from which ＠var{image-instance} was -read, if known. +＠defun glyph-contrib-p-instance glyph &optional domain default no-fallback +This function returns whether the glyph contributes to its line height +in the given ＠var{domain}, and is equivalent to calling +＠code{glyph-property-instance} with a property of ＠code{contrib-p}. The +return value will be either ＠code{nil} or ＠code{t}. (Normally ＠var{domain} +will be a window or ＠code{nil}, meaning the selected window.) ＠end defun -＠defun image-instance-mask-file-name image-instance -This function returns the file name from which ＠var{image-instance}'s -mask was read, if known. +＠defun glyph-baseline glyph &optional locale +This function is equivalent to calling ＠code{glyph-property} with a +property of ＠code{baseline}. The return value will be a specifier if +＠var{locale} is ＠code{nil} or omitted; otherwise, it will be a +specification or list of specifications. ＠end defun -＠defun 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. +＠defun set-glyph-baseline glyph spec &optional locale tag-set how-to-add +This function is equivalent to calling ＠code{set-glyph-property} with +a property of ＠code{baseline}. ＠end defun -＠defun image-instance-height image-instance -This function returns the height of the image instance, in pixels. +＠defun glyph-baseline-instance glyph &optional domain default no-fallback +This function returns the instance of ＠var{glyph}'s baseline value in +the given ＠var{domain}, and is equivalent to calling +＠code{glyph-property-instance} with a property of ＠code{baseline}. The +return value will be an integer or ＠code{nil}. + +Normally ＠var{domain} will be a window or ＠code{nil} (meaning the +selected window), and an instance object describing the baseline value +appears in that particular window and buffer will be returned. ＠end defun -＠defun image-instance-width image-instance -This function returns the width of the image instance, in pixels. +＠defun glyph-face glyph +This function returns the face of ＠var{glyph}. (Remember, this is +not a specifier, but a simple property.) ＠end defun -＠defun 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. +＠defun set-glyph-face glyph face +This function changes the face of ＠var{glyph} to ＠var{face}. +＠end defun + + +＠node Glyph Dimensions +＠subsection Glyph Dimensions -This will always be ＠code{nil} for a non-pointer image instance. +＠defun glyph-width glyph &optional window +This function returns the width of ＠var{glyph} on ＠var{window}. This +may not be exact as it does not take into account all of the context +that redisplay will. ＠end defun -＠defun image-instance-hotspot-y image-instance -This function returns the Y coordinate of the image instance's hotspot, -if known. +＠defun glyph-ascent glyph &optional window +This function returns the ascent value of ＠var{glyph} on ＠var{window}. +This may not be exact as it does not take into account all of the +context that redisplay will. ＠end defun -＠defun image-instance-foreground image-instance -This function returns the foreground color of ＠var{image-instance}, if -applicable. This will be a color instance or ＠code{nil}. (It will only -be non-＠code{nil} for colorized mono pixmaps and for pointers.) +＠defun glyph-descent glyph &optional window +This function returns the descent value of ＠var{glyph} on ＠var{window}. +This may not be exact as it does not take into account all of the +context that redisplay will. ＠end defun -＠defun image-instance-background image-instance -This function returns the background color of ＠var{image-instance}, if -applicable. This will be a color instance or ＠code{nil}. (It will only -be non-＠code{nil} for colorized mono pixmaps and for pointers.) +＠defun glyph-height glyph &optional window +This function returns the height of ＠var{glyph} on ＠var{window}. (This +is equivalent to the sum of the ascent and descent values.) This may +not be exact as it does not take into account all of the context that +redisplay will. ＠end defun ＠node Glyph Types -＠section Glyph Types +＠subsection 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 ＠＠ -1221,6 +1978,7 ＠＠ extent, in the modeline, and in the toolbar. Their image can be instantiated as ＠code{nothing}, ＠code{mono-pixmap}, ＠code{color-pixmap}, ＠code{text}, and ＠code{subwindow}. +＠c #### Check status of subwindows ... I thought Andy implemented them. ＠item ＠code{pointer} glyphs can be used to specify the mouse pointer. Their ＠＠ -1261,126 +2019,6 ＠＠ ＠code{pointer}. ＠end defun -＠node Mouse Pointer -＠section Mouse Pointer -＠cindex mouse cursor -＠cindex cursor (mouse) -＠cindex pointer (mouse) -＠cindex 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 ＠code{set-glyph-image} to set the following variables, -＠emph{not} ＠code{setq}. - -＠defvr Glyph text-pointer-glyph -This variable specifies the shape of the mouse pointer when over text. -＠end defvr - -＠defvr 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, -＠code{text-pointer-glyph} is used. -＠end defvr - -＠defvr Glyph modeline-pointer-glyph -This variable specifies the shape of the mouse pointer when over the modeline. -If unspecified in a particular domain, ＠code{nontext-pointer-glyph} is used. -＠end defvr - -＠defvr 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, -＠code{text-pointer-glyph} is used. -＠end defvr - -＠defvr 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 ＠code{gc-message}. -＠end defvr - -＠defvr 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. -＠end defvr - -＠defvr 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. -＠end defvr - -＠defvr 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. -＠end defvr - -＠defvr Glyph toolbar-pointer-glyph -This variable specifies the shape of the mouse pointer when over a -toolbar. If unspecified in a particular domain, -＠code{nontext-pointer-glyph} is used. -＠end defvr - -Internally, these variables are implemented in -＠code{default-mouse-motion-handler}, and thus only take effect when the -mouse moves. That function calls ＠code{set-frame-pointer}, which sets -the current mouse pointer for a frame. - -＠defun set-frame-pointer frame image-instance -This function sets the mouse pointer of ＠var{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.) -＠end defun - -＠node Redisplay Glyphs -＠section Redisplay Glyphs - -＠defvr Glyph truncation-glyph -This variable specifies what is displayed at the end of truncated lines. -＠end defvr - -＠defvr Glyph continuation-glyph -This variable specifies what is displayed at the end of wrapped lines. -＠end defvr - -＠defvr Glyph octal-escape-glyph -This variable specifies what to prefix character codes displayed in octal -with. -＠end defvr - -＠defvr Glyph hscroll-glyph -This variable specifies what to display at the beginning of horizontally -scrolled lines. -＠end defvr - -＠defvr 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 ＠code{selective-display-ellipses} or -＠code{buffer-invisibility-spec}). Normally this is three dots (``...''). -＠end defvr - -＠defvr Glyph control-arrow-glyph -This variable specifies what to use as an arrow for control characters. -＠end defvr - -＠node Subwindows -＠section Subwindows - -Subwindows are not currently implemented. - -＠defun subwindowp object -This function returns non-＠code{nil} if ＠var{object} is a subwindow. -＠end defun ＠node Glyph Examples ＠section Glyph Examples ＠＠ -1454,7 +2092,7 ＠＠ ;; current buffer. Any existing glyph at this location is replaced. (defun insert-glyph (gl) "Insert a glyph at the left edge of point." - (let ( (prop 'myimage) ;; myimage is an arbitrary name, chosen + (let ( (prop 'myimage) ;; myimage is an arbitrary name, chosen ;; to (hopefully) not conflict with any ;; other properties. Change it if ;; necessary. 1.13.2.5 +41 -23 XEmacs/xemacs/man/lispref/lispref.texi Index: lispref.texi =================================================================== RCS file: /pack/xemacscvs/XEmacs/xemacs/man/lispref/lispref.texi,v retrieving revision 1.13.2.4 retrieving revision 1.13.2.5 diff -u -r1.13.2.4 -r1.13.2.5 --- lispref.texi 2005/01/20 03:40:15 1.13.2.4 +++ lispref.texi 2005/02/23 01:54:35 1.13.2.5 ＠＠ -994,38 +994,56 ＠＠ Glyphs -* Glyph Functions:: Functions for working with glyphs. -* Images:: Graphical images displayed in a frame. -* Glyph Types:: Each glyph has a particular type. -* Mouse Pointer:: Controlling the mouse pointer. -* Redisplay Glyphs:: Glyphs controlling various redisplay functions. -* Subwindows:: Inserting an externally-controlled subwindow - into a buffer. -* Glyph Examples:: Examples of how to work with glyphs. +* Glyph Intro:: Glyphs are abstract image specifications. +* Images:: Specifying the appearance of glyphs. +* Using Glyphs:: Creating and displaying glyphs. +* Manipulating Glyphs:: Getting and setting glyph properties. +* Glyph Examples:: Examples of how to work with glyphs. -Glyph Functions +Images -* Creating Glyphs:: Creating new glyphs. -* Glyph Properties:: Accessing and modifying a glyph's properties. -* Glyph Convenience Functions:: - Convenience functions for accessing particular - properties of a glyph. -* Glyph Dimensions:: Determining the height, width, etc. of a glyph. +* Image Specifiers:: Specifying an image's appearance. +* Image Instantiator Conversion:: Lazy realization of graphics. +* Image Instantiator Formats:: A catalog of image descriptors. +* Image Instances:: Classes of graphical objects. -Images +Image Instances + +* Image Instance Types:: Each image instances has a particular type. +* Image Instance Functions:: Functions for working with image instances. -* Image Specifiers:: Specifying how an image will appear. -* Image Instantiator Conversion:: - Conversion is applied to image instantiators - at the time they are added to an - image specifier or at the time they - are passed to ＠code{make-image-instance}. -* Image Instances:: What an image specifier gets instanced as. +Using Glyphs + Image Instances * Image Instance Types:: Each image instances has a particular type. * Image Instance Functions:: Functions for working with image instances. + +Using Glyphs + +* Creating Glyphs:: Creating new glyphs. +* Buffer Glyphs:: Annotations are glyphs that appear in a buffer. +* Redisplay Glyphs:: Glyphs controlling various redisplay functions. +* Frame Glyphs:: Displaying glyphs in GUI components of the frame. +* External Glyphs:: Icons and mouse pointers for the window system. +* Native GUI Widgets:: Complex active elements treated as a single glyph. +* Subwindows:: Externally-controlled subwindows in buffers. + +Native GUI Widgets + +* Introduction to Widgets:: Native widgets provide tight integration of + GUI features with the platform GUI. +* Lisp API to Native Widgets:: Native widgets are glyphs. +* Layouts:: Specifying composite widgets from Lisp. +* Primitive Widgets:: Catalogue of available native widgets. + +Manipulating Glyphs + +* Glyph Properties:: Accessing and modifying a glyph's properties. +* Glyph Convenience Functions:: Accessing particular properties of a glyph. +* Glyph Dimensions:: Determining the height, width, etc. of a glyph. +* Glyph Types:: Each glyph has a particular type. Annotations