CVS update by stephent MODIFIED: xemacs/man/lispref ...
19 years, 1 month
CVS Monitor
CVS Monitor
User: stephent
Date: 05/02/23 16:33:38
Modified: xemacs/man/lispref searching.texi
Log:
document \c <87650jz411.fsf(a)tleepslib.sk.tsukuba.ac.jp>
Revision Changes Path
1.290 +6 -1 XEmacs/xemacs/man/ChangeLog
Index: ChangeLog
===================================================================
RCS file: /pack/xemacscvs/XEmacs/xemacs/man/ChangeLog,v
retrieving revision 1.289
retrieving revision 1.290
diff -u -r1.289 -r1.290
--- ChangeLog 2005/02/22 07:16:11 1.289
+++ ChangeLog 2005/02/23 15:33:32 1.290
＠＠ -1,3 +1,9 ＠＠
+2005-02-23 Aidan Kehoe <kehoea(a)parhasard.net>
+
+ * lispref/searching.texi (Syntax of Regexps):
+ Mention the \c and \C regular expression constructs; cross
+ reference to the Category Table documentation.
+
2005-02-22 Stephen J. Turnbull <stephen(a)xemacs.org>
* internals/internals.texi (The version.sh Script): New node.
＠＠ -8,7 +14,6 ＠＠
Add or update references to the version.sh node and/or file.
(XEmacs from the Perspective of Building): Improve text.
-
2005-02-19 Stephen J. Turnbull <stephen(a)xemacs.org>
1.13 +13 -0 XEmacs/xemacs/man/lispref/searching.texi
Index: searching.texi
===================================================================
RCS file: /pack/xemacscvs/XEmacs/xemacs/man/lispref/searching.texi,v
retrieving revision 1.12
retrieving revision 1.13
diff -u -r1.12 -r1.13
--- searching.texi 2004/09/08 10:32:55 1.12
+++ searching.texi 2005/02/23 15:33:38 1.13
＠＠ -516,6 +516,19 ＠＠
＠item \S＠var{code}
＠cindex ＠samp{\S} in regexp
matches any character whose syntax is not ＠var{code}.
+
+＠item \c＠var{category}
+＠cindex ＠samp{\c} in regexp
+matches any character in ＠var{category}. Only available under Mule,
+categories, and category tables, are further described in ＠ref{Category
+Tables}. They are a mechanism for constructing classes of characters
+that can be local to a buffer, and that do not require complicated []
+expressions every time they are referenced.
+
+＠item \C＠var{category}
+＠cindex ＠samp{\C} in regexp
+matches any character outside ＠var{category}. ＠xref{Category Tables},
+again, and note that this is only available under Mule.
＠end table
The following regular expression constructs match the empty string---that is,
- 1 participants
- 0 comments
CVS update by vins MODIFIED: xemacs/man/lispref, glyphs.texi ...
19 years, 1 month
CVS Monitor
CVS Monitor
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>
+
+ * 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>
* 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>
+
+ * 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>
* 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
- 1 participants
- 0 comments
CVS update by ben MODIFIED: xemacs/lisp ...
19 years, 1 month
CVS Monitor
CVS Monitor
User: ben
Date: 05/02/23 00:38:52
Modified: xemacs/lisp ChangeLog glyphs.el
Log:
Update glyph documentation
glyphs.el: Update documentation of `make-glyph' and `make-image-specifier'
to more clearly document image instantiators and describe how
errors are handled in make-glyph. Also fix symbol references in
doc strings to use `symbol' format, not 'symbol.
Revision Changes Path
1.644 +20 -0 XEmacs/xemacs/lisp/ChangeLog
Index: ChangeLog
===================================================================
RCS file: /pack/xemacscvs/XEmacs/xemacs/lisp/ChangeLog,v
retrieving revision 1.643
retrieving revision 1.644
diff -u -r1.643 -r1.644
--- ChangeLog 2005/02/22 07:16:06 1.643
+++ ChangeLog 2005/02/22 23:38:49 1.644
＠＠ -1,3 +1,23 ＠＠
+2005-02-21 Ben Wing <ben(a)xemacs.org>
+
+ * glyphs.el:
+ * glyphs.el (make-image-specifier):
+ * glyphs.el (glyph-property):
+ * glyphs.el (convert-glyph-property-into-specifier):
+ * glyphs.el (set-glyph-property):
+ * glyphs.el (glyph-image):
+ * glyphs.el (set-glyph-image):
+ * glyphs.el (glyph-contrib-p):
+ * glyphs.el (glyph-contrib-p-instance):
+ * glyphs.el (set-glyph-contrib-p):
+ * glyphs.el (glyph-baseline):
+ * glyphs.el (set-glyph-baseline):
+ * glyphs.el (make-glyph):
+ Update documentation of `make-glyph' and `make-image-specifier'
+ to more clearly document image instantiators and describe how
+ errors are handled in make-glyph. Also fix symbol references in
+ doc strings to use `symbol' format, not 'symbol.
+
2005-02-21 Stephen J. Turnbull <stephen(a)xemacs.org>
* about.el (about-xemacs):
1.8 +321 -160 XEmacs/xemacs/lisp/glyphs.el
Index: glyphs.el
===================================================================
RCS file: /pack/xemacscvs/XEmacs/xemacs/lisp/glyphs.el,v
retrieving revision 1.7
retrieving revision 1.8
diff -u -r1.7 -r1.8
--- glyphs.el 2001/04/12 18:21:21 1.7
+++ glyphs.el 2005/02/22 23:38:50 1.8
＠＠ -1,7 +1,7 ＠＠
;;; glyphs.el --- Lisp interface to C glyphs
;; Copyright (C) 1994, 1997 Free Software Foundation, Inc.
-;; Copyright (C) 1995, 1996, 2000 Ben Wing.
+;; Copyright (C) 1995, 1996, 2000, 2005 Ben Wing.
;; Author: Chuck Thompson <cthomp(a)cs.uiuc.edu>, Ben Wing <ben(a)xemacs.org>
;; Maintainer: XEmacs Development Team
＠＠ -47,149 +47,129 ＠＠
of instantiators. See `make-specifier' for more information about
specifiers.
-An image specifier is used for images (pixmaps, widgets and the like).
-It is used to describe the actual image in a glyph. It is instanced
-as an image-instance. Note that \"image\" as used in XEmacs does not
-actually refer to what the term \"image\" normally means (a picture,
-e.g. in .GIF or .JPG format, and called a \"pixmap\" in XEmacs), but
-includes all types of graphical elements, including pixmaps, widgets
-\(buttons, sliders, text fields, etc.) and even strings of text.
-
-Note that, in practice, you rarely, if ever, need to actually create
-an image specifier! (The function `make-image-specifier' exists mainly
-for completeness.) Pretty much the only use for image specifiers is to
-control how glyphs are displayed, and the image specifier associated
-with a glyph (the `image' property of a glyph) is created
-automatically when a glyph is created (see `make-glyph') and need not
-\(and cannot, for that matter) ever be changed. In fact, the design
-decision to create a separate image specifier type, rather than make
-glyphs themselves be specifiers, is debatable -- the other properties
-of glyphs are rarely used and could conceivably have been incorporated
-into the glyph's instantiator. The rarely used glyph types (buffer,
-pointer, icon) could also have been incorporated into the instantiator.
-
-Image instantiators come in many formats: `xbm', `xpm', `gif', `jpeg',
-etc. This describes the format of the data describing the image. The
-resulting image instances also come in many types -- `mono-pixmap',
-`color-pixmap', `text', `pointer', etc. This refers to the behavior of
-the image and the sorts of places it can appear. (For example, a
-color-pixmap image has fixed colors specified for it, while a
-mono-pixmap image comes in two unspecified shades \"foreground\" and
-\"background\" that are determined from the face of the glyph or
-surrounding text; a text image appears as a string of text and has an
-unspecified foreground, background, and font; a pointer image behaves
-like a mono-pixmap image but can only be used as a mouse pointer
-\[mono-pixmap images cannot be used as mouse pointers]; etc.) It is
-important to keep the distinction between image instantiator format and
-image instance type in mind. Typically, a given image instantiator
-format can result in many different image instance types (for example,
-`xpm' can be instanced as `color-pixmap', `mono-pixmap', or `pointer';
-whereas `cursor-font' can be instanced only as `pointer'), and a
-particular image instance type can be generated by many different
-image instantiator formats (e.g. `color-pixmap' can be generated by `xpm',
-`gif', `jpeg', etc.).
-
-See `make-image-instance' for a more detailed discussion of image
-instance types.
+The main purpose of this doc string is to describe the possible formats for
+image instantiators, as given as an argument to `make-glyph' or
+`set-glyph-image'.
An image instantiator should be a string or a vector of the form
[FORMAT :KEYWORD VALUE ...]
i.e. a format symbol followed by zero or more alternating keyword-value
-pairs. FORMAT should be one of
+pairs. The vector form of an image instantiator explicitly specifies the
+format of the image and other relevant properties. The string form
+specifies only a filename or gives inline data of an unspecified format,
+and XEmacs must guess the actual format. Once it has done this, it
+internally converts the instantiator into the vector format. This is
+described in more detail below.
+
+Following is a list of the possible values for FORMAT. After each
+description, the allowable keywords for the format are listed in brackets,
+followed by the possible image instance types that can be generated from
+this format. (Image instance types will be discussed below.)
-'nothing
+`nothing'
Don't display anything; no keywords are valid for this.
- Can only be instanced as `nothing'.
-'string
- Display this image as a text string. Can only be instanced
- as `text', although support for instancing as `mono-pixmap'
- and `color-pixmap' should be added.
-'formatted-string
- Display this image as a text string, with replaceable fields;
- not currently implemented. (It is, instead, equivalent to `string'.)
-'xbm
- An X bitmap; only if X or MS Windows support was compiled into this
- XEmacs. Can be instanced as `mono-pixmap', `color-pixmap', or `pointer'.
-'xpm
- An XPM pixmap; only if XPM support was compiled into this XEmacs.
- Can be instanced as `color-pixmap', `mono-pixmap', or `pointer'.
-'xface
- An X-Face bitmap, used to encode people's faces in e-mail messages;
- only if X-Face support was compiled into this XEmacs. Can be
- instanced as `mono-pixmap', `color-pixmap', or `pointer'.
-'gif
+ [] (nothing)
+`string'
+ Display this image as a text string. Support for instantiating as
+ `mono-pixmap' and `color-pixmap' should probably be added.
+ [:data] (text)
+`formatted-string'
+ Display this image as a text string, with replaceable fields.
+ Not currently implemented -- it's treated like `string'.
+ [:data] (text)
+`gif'
A GIF87 or GIF89 image; only if GIF support was compiled into this
- XEmacs. NOTE: only the first frame of animated gifs will be displayed.
- Can be instanced as `color-pixmap'.
-'jpeg
+ XEmacs. NOTE: Only the first frame of animated gifs will be displayed.
+ [:data, :file] (color-pixmap, pointer)
+`jpeg'
A JPEG image; only if JPEG support was compiled into this XEmacs.
- Can be instanced as `color-pixmap'.
-'png
+ [:data, :file] (color-pixmap, pointer)
+`png'
A PNG image; only if PNG support was compiled into this XEmacs.
- Can be instanced as `color-pixmap'.
-'tiff
+ [:data, :file] (color-pixmap, pointer)
+`tiff'
A TIFF image; only if TIFF support was compiled into this XEmacs.
- Can be instanced as `color-pixmap'.
-'bmp
+ [:data, :file] (color-pixmap, pointer)
+`bmp'
A MS Windows BMP image; only if MS Windows support was compiled into
- this XEmacs. Can be instanced as `color-pixmap'.
-'cursor-font
- One of the standard cursor-font names, such as \"watch\" or
- \"right_ptr\" under X. Under X, this is, more specifically, any
+ this XEmacs.
+ [:data, :file] (color-pixmap, pointer)
+`xbm'
+ An X bitmap; exists if any window-system support was compiled into this
+ XEmacs.
+ [:data, :file, :foreground, :background, :mask-data, :mask-file,
+ :hotspot-x, :hotspot-y] (mono-pixmap, color-pixmap, pointer)
+`xpm'
+ An XPM pixmap; only if XPM support was compiled into this XEmacs.
+ [:data, :file, :color-symbols] (mono-pixmap, color-pixmap, pointer)
+`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.
+ [:data, :file, :foreground, :background, :mask-data, :mask-file,
+ :hotspot-x, :hotspot-y] (mono-pixmap, color-pixmap, pointer)
+`cursor-font'
+ X and GTK only. One of the standard cursor-font names, such as \"watch\"
+ or \"right_ptr\" under X. Under X, this is, more specifically, any
of the standard cursor names from appendix B of the Xlib manual
[also known as the file <X11/cursorfont.h>] minus the XC_ prefix.
On other window systems, the valid names will be specific to the
- type of window system. Can only be instanced as `pointer'.
-'mswindows-resource
+ type of window system.
+ [:data, :foreground, :background] (pointer)
+`mswindows-resource'
An MS Windows pointer resource. Specifies a resource to retrieve
directly from the system (an OEM resource) or from a file, particularly
an executable file. If the resource is to be retrieved from a file, use
:file and optionally :resource-id. Otherwise use :resource-id. Always
specify :resource-type to specify the type (cursor, bitmap or icon) of
- the resource. Possible values for :resource-id are listed below. Can
- be instanced as `pointer' or `color-pixmap'.
-'font
+ the resource. Possible values for :resource-id are listed below.
+ [:file, :resource-type, :resource-id] (pointer, color-pixmap)
+`font'
A glyph from a font; i.e. the name of a font, and glyph index into it
of the form \"FONT fontname index [[mask-font] mask-index]\".
- Currently can only be instanced as `pointer', although this should
+ Currently can only be instantiated as `pointer', although this should
probably be fixed.
-'subwindow
- An embedded windowing system window. Can only be instanced as
- `subwindow'.
-'button
+ [:data, :foreground, :background] (pointer)
+`subwindow'
+ An embedded windowing system window.
+ [:pixel-width, :pixel-height] (subwindow)
+`button'
A button widget; either a push button, radio button or toggle button.
- Can only be instanced as `widget'.
-'combo-box
+ [WIDGET-KEYWORDS, GUI-KEYWORDS, :image] (widget)
+`combo-box'
A drop list of selectable items in a widget, for editing text.
- Can only be instanced as `widget'.
-'edit-field
- A text editing widget. Can only be instanced as `widget'.
-'label
- A static, text-only, widget; for displaying text. Can only be instanced
- as `widget'.
-'layout
+ [GUI-KEYWORDS, :width, :height, :pixel-width, :face, :items] (widget)
+`edit-field'
+ A text editing widget.
+ [WIDGET-KEYWORDS, GUI-KEYWORDS] (widget)
+`label'
+ A static, text-only, widget; for displaying text.
+ [WIDGET-KEYWORDS, :descriptor] (widget)
+`layout'
A widget for controlling the positioning of children underneath it.
Through the use of nested layouts, a widget hierarchy can be created
which can have the appearance of any standard dialog box or similar
arrangement; all of this is counted as one \"glyph\" and could appear
- in many of the places that expect a single glyph. Can only be instanced
- as `widget'.
-'native-layout
+ in many of the places that expect a single glyph.
+ [WIDGET-KEYWORDS, GUI-KEYWORDS, :orientation, :justify, :vertically-justify,
+ :horizontally-justify, :border, :margin-width, :items] (widget)
+`native-layout'
The native version of a layout widget. #### Document me better!
- Can only be instanced as `widget'.
-'progress-gauge
- A sliding widget, for showing progress. Can only be instanced as
- `widget'.
-'tab-control
- A tab widget; a series of user selectable tabs. Can only be instanced
- as `widget'.
-'tree-view
- A folding widget. Can only be instanced as `widget'.
-'scrollbar
- A scrollbar widget. Can only be instanced as `widget'.
-'autodetect
+ [WIDGET-KEYWORDS, GUI-KEYWORDS] (widget)
+`progress-gauge'
+ A sliding widget, for showing progress.
+ [WIDGET-KEYWORDS, GUI-KEYWORDS, :value] (widget)
+`tab-control'
+ A tab widget; a series of user selectable tabs.
+ [WIDGET-KEYWORDS, GUI-KEYWORDS, :orientation, :items] (widget)
+`tree-view'
+ A folding widget.
+ [WIDGET-KEYWORDS, GUI-KEYWORDS, :items] (widget)
+`scrollbar'
+ A scrollbar widget.
+ [GUI-KEYWORDS, :pixel-width, :face, :items] (widget)
+`autodetect'
XEmacs tries to guess what format the data is in. If X support
exists, the data string will be checked to see if it names a filename.
If so, and this filename contains XBM or XPM data, the appropriate
＠＠ -198,11 +178,11 ＠＠
is one of the allowable image-instance types and the string names a
valid cursor-font name, the image will be created as a pointer.
Otherwise, the image will be displayed as text. If no X support
- exists, the image will always be displayed as text. Can be instanced as
- `mono-pixmap', `color-pixmap', `pointer', or `text'.
-'inherit
- Inherit from the background-pixmap property of a face. Can only be
- instanced as `mono-pixmap'.
+ exists, the image will always be displayed as text.
+ [:data] (mono-pixmap, color-pixmap, pointer, text)
+`inherit'
+ Inherit from the background-pixmap property of a face.
+ [:face] (mono-pixmap)
The valid keywords are:
＠＠ -264,7 +244,7 ＠＠
\"lfarrowi\", \"size\", \"btsize\", \"check\", \"checkboxes\", and
\"btncorners\".
- -- For cursors:
+ -- For pointers:
\"normal\", \"ibeam\", \"wait\", \"cross\", \"up\", \"sizenwse\",
\"sizenesw\", \"sizewe\", \"sizens\", \"sizeall\", and \"no\".
＠＠ -273,18 +253,28 ＠＠
\"sample\", \"hand\", \"ques\", \"bang\", \"note\", and \"winlogo\".
:resource-type
- Only for `mswindows-resource'. This must be a symbol, either `cursor',
- `icon', or `bitmap', specifying the type of resource to be retrieved.
+ Only for `mswindows-resource'. This must be a symbol, either `cursor'
+ (i.e. pointer), `icon', or `bitmap', specifying the type of resource to
+ be retrieved.
:face
Only for `inherit'. This specifies the face to inherit from.
For widgets this also specifies the face to use for display. It defaults
to gui-element-face.
+:pixel-width, :pixel-height
+ Width and height of element, in pixels. For `subwindow', the values
+ must be integers. For widgets, the values can be integers or
+ expressions that evaluate to integers.
-Keywords accepted as menu item specs are also accepted by widgets.
+\[WIDGET-KEYWORDS] stands for the standard keywords accepted by widgets:
These are `:selected', `:active', `:suffix', `:keys', `:style',
`:filter', `:config', `:included', `:key-sequence', `:accelerator',
-`:label' and `:callback'.
+`:label', `:callback', `:initial-focus', and `:descriptor'.
+#### Document me.
+\[GUI-KEYWORDS] stands for keywords accepted by many widgets.
+These are `:width', `:height', `:pixel-width', `:pixel-height', and `:face'.
+#### Document me.
+
If instead of a vector, the instantiator is a string, it will be
converted into a vector by looking it up according to the specs in the
`console-type-image-conversion-list' (q.v.) for the console type of
＠＠ -299,7 +289,148 ＠＠
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).
-"
+
+NOTE: In practice, you rarely, if ever, need to actually
+create an image specifier! (The function `make-image-specifier' exists
+mainly for completeness.) Pretty much the only use for image specifiers is
+to control how glyphs are displayed, and the image specifier associated
+with a glyph (the `image' property of a glyph) is created automatically
+when a glyph is created (see `make-glyph') and need not \(and cannot, for
+that matter) ever be changed. 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.
+
+An image specifier is used for images (pixmaps, widgets and the like). It
+is used to describe the actual image in a glyph. It is instantiated \(see
+`specifier-instance') as an image-instance. Note that \"image\" as used in
+XEmacs does not actually refer to what the term \"image\" normally means (a
+picture, e.g. in .GIF or .JPG format, and called a \"pixmap\" in XEmacs),
+but includes all types of graphical elements, including pixmaps, widgets
+\(buttons, sliders, text fields, etc.) and even strings of text.
+
+There is an important distinction to be made between image instantiators
+and image instances, and \"image instantiator formats\" and \"image
+instance types\", analogous to the distinction between source and
+destination. An image instantiator describes the source data for an image.
+An image instance encapsulates the resulting window-system object used to
+display the image. Image instantiator formats are the formats of the
+source: This includes familiar and less-familiar graphics formats such as
+`gif', `jpeg', `png' and `xpm'; widget types such as `button', `edit-field'
+and `combo-box'; and other beasts such as `string' (plain text, which could
+potentially behave like text when placed in a buffer, such as wrapping),
+`font' (a single character from a particular font, specified by the index
+into the font), etc. Image instance types are the (destination) types of
+the resulting image instance. Different image instance types correspond to
+fundamentally different appearance and behaviors for the resulting image,
+specifically:
+
+-- `color-pixmap' (a color image);
+-- `mono-pixmap' (a \"monochrome\" image, technically a two-color image
+ that comes in two unspecified shades \"foreground\" and \"background\",
+ determined from the face [see `make-face'] of the glyph or surrounding
+ text);
+-- `text' (a string of text appearing somewhere in a buffer's text or
+ margins, which has an unspecified foreground, background, and font
+ derived from the surrounding text or other external property and which
+ behaves in many respects like an image but can wrap across the end of a
+ line to the beginning of the next);
+-- `pointer' (the mouse pointer for a window; this is a combination of a
+ rectangular pixmap image, a monochrome mask that specifies the
+ transparency of the image [i.e. in which places the underlying screen
+ image can show through, and how much of it], and a \"hotspot\" that
+ indicates which pixel in the pointer's image is considered the actual
+ pointer location -- for example, this will be located near the tip of
+ an arrow, in the middle of a crosshairs, somewhere along an i-beam, etc.);
+-- `widget' (a window-system object or \"widget\" that interacts with the
+ user, such as a button, edit-field or combo-box);
+-- `subwindow' (a rectangular area that another program can draw into);
+-- `nothing' (no display).
+
+There is not a one-to-one mapping between source (image instantiator)
+formats and destination (image instance) types. For example, the source
+format `xpm' can generate the image instance types `color-pixmap',
+`mono-pixmap', or `pointer', and the image instance type `color-pixmap' can
+be generated by any of `gif', `jpeg', `png', `tiff', `xpm', `xbm' and
+`xface'.
+
+In general, the user or programmer specifies the image instantiator format,
+while the appropriate image instance type is determined automatically by
+XEmacs from the image instantiator format, from the data in the
+instantiator and from the particular situation the image (and the glyph
+that holds it) is being used in. (However, it's possible to explicitly
+create image instances and control their types; see `make-image-instance'.)
+For example, a glyph used to specify the shape of a mouse pointer can only
+result in `pointer'-type image instances, and a glyph used for an icon can
+only result in `color-pixmap' image instances. A glyph used in a buffer
+can potentially result in any image instance type except for `pointer', but
+particular instantiator formats have only a limited set of image instance
+types they will support. Here is an example of how the image instance type
+for an `xpm' instantiator (which can potentially support `color-pixmap',
+`mono-pixmap', or `pointer') is determined:
+
+1. If the glyph is being used for a mouse pointer (hence its `glyph-type'
+ is `pointer'), it can be instantiated only a `pointer'-type image instance.
+2. If the glyph is being used for an icon (hence its `glyph-type' is `icon'),
+ it can be instantiated only a `color-pixmap'-type image instance.
+3. Otherwise, the glyph is being used somewhere inside a frame (`glyph-type'
+ of `buffer') and any image instance type except `pointer' can be
+ supported. In this case, this means `color-pixmap' or `mono-pixmap'.
+ Which one will result depends on the particular data being processed,
+ since XPM images can specify whether they are color or mono.
+
+Note again that \"mono\" does *NOT* simply mean \"an image with two
+colors\". The latter image has two prespecified colors, e.g. red and blue
+or black and white, and will always appear with those colors, no matter
+what the context. A mono image has two *unspecified* colors, symbolically
+named \"foreground\" and \"background\", and the actual values for those
+colors depends on context. A mono pixmap displayed among text will take
+its foreground and background from that of the text and hence blend in
+nicely; a two-color color pixmap won't do that.
+
+Note also that `color-pixmap' image instances can be generated from the
+supported pixmap formats that are inherently mono (i.e. `xbm' and `xface')
+by specifying :foreground and :background values.
+
+A table of the various image instantiator formats and the possible
+destination (image instance) types that can be generated from them is as
+follows:
+
+
+ color-pixmap mono-pixmap text pointer widget subwindow noth.
+-------------------------------------------------------------------------------
+nothing +
+string +
+formatted-string +
+xbm + + +
+xpm + + +
+xface + + +
+gif + +
+jpeg + +
+png + +
+tiff + +
+bmp + +
+cursor-font +
+mswindows-resource + +
+font +
+subwindow +
+button +
+combo-box +
+edit-field +
+label +
+layout +
+native-layout +
+progress-gauge +
+tab-control +
+tree-view +
+scrollbar +
+autodetect + + + +
+inherit +
+
+See `make-image-instance' for a more detailed discussion of image
+instance types."
(make-specifier-and-init 'image spec-list))
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; glyphs
＠＠ -328,11 +459,11 ＠＠
specifying a font or color name), or a list of specifications, each
of which is a cons of a locale and a list of instantiators.
Specifically, if LOCALE is a particular locale (a buffer, window,
- frame, device, or 'global), a list of instantiators for that locale
+ frame, device, or `global'), a list of instantiators for that locale
will be returned. Otherwise, if LOCALE is a locale type (one of
- the symbols 'buffer, 'window, 'frame, 'device, 'device-class, or
- 'device-type), the specifications for all locales of that type will
- be returned. Finally, if LOCALE is 'all, the specifications for all
+ the symbols `buffer', `window', `frame', `device', `device-class', or
+ `device-type'), the specifications for all locales of that type will
+ be returned. Finally, if LOCALE is `all', the specifications for all
locales of all types will be returned.
The specifications in a specifier determine what the value of
＠＠ -340,7 +471,7 ＠＠
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 'global)
+ locale (in the order buffer, window, frame, device, and `global')
that matches the domain in question. In other words, given a domain
(i.e. an Emacs window, usually), the specifier for PROPERTY will first
be searched for a specification whose locale is the buffer contained
＠＠ -368,7 +499,7 ＠＠
;; if a user-property does not have a specifier but a
;; locale was specified, put a specifier there.
;; If there was already a value there, convert it to a
- ;; specifier with the value as its 'global instantiator.
+ ;; specifier with the value as its `global' instantiator.
(if (not (specifierp specifier))
(let ((new-specifier (make-specifier 'generic)))
(if (or (not (null specifier))
＠＠ -436,7 +567,7 ＠＠
-- If VALUE is a simple instantiator (e.g. a string naming a font or
color) or a list of instantiators, then the instantiator(s) will
be added as a specification of the property for the given LOCALE
- (which defaults to 'global if omitted).
+ (which defaults to `global' if omitted).
-- If VALUE is a list of specifications (each of which is a cons of
a locale and a list of instantiators), then LOCALE must be nil
(it does not make sense to explicitly specify a locale in this
＠＠ -448,12 +579,12 ＠＠
`copy-specifier' and 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 nil or 'all, then all
+ that type will be copied; if nil or `all', then all
specifications will be copied).
-HOW-TO-ADD should be either nil or one of the symbols 'prepend,
- 'append, 'remove-tag-set-prepend, 'remove-tag-set-append, 'remove-locale,
- 'remove-locale-type, or 'remove-all. See `copy-specifier' and
+HOW-TO-ADD should be either nil or one of the symbols `prepend',
+ `append', `remove-tag-set-prepend', `remove-tag-set-append', `remove-locale',
+ `remove-locale-type', or `remove-all.' See `copy-specifier' and
`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.
＠＠ -462,7 +593,7 ＠＠
by `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 'font
+ you set a font-instance object as the value of the `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
＠＠ -473,7 +604,7 ＠＠
given, then this function will attempt to add VALUE as the
instantiator for the given LOCALE, using `add-spec-to-specifier'.
If the value of the property is not a specifier, it will
- automatically be converted into a 'generic specifier.
+ automatically be converted into a `generic' specifier.
The following symbols have predefined meanings:
＠＠ -527,7 +658,7 ＠＠
LOCALE may be a locale (the instantiators for that particular locale
will be returned), a locale type (the specifications for all locales
- of that type will be returned), 'all (all specifications will be
+ of that type will be returned), `all' (all specifications will be
returned), or nil (the actual specifier object will be returned).
See `glyph-property' for more information."
＠＠ -561,10 +692,10 ＠＠
object.
If SPEC is an alist, LOCALE must be omitted. If SPEC is a
- specifier object, LOCALE can be a locale, a locale type, 'all,
+ specifier object, LOCALE can be a locale, a locale type, `all',
or nil; see `copy-specifier' for its semantics. Otherwise LOCALE
specifies the locale under which the specified instantiator(s)
- will be added, and defaults to 'global.
+ will be added, and defaults to `global.'
See `set-glyph-property' for more information."
; (interactive (glyph-interactive "image"))
＠＠ -575,17 +706,17 ＠＠
LOCALE may be a locale (the instantiators for that particular locale
will be returned), a locale type (the specifications for all locales
- of that type will be returned), 'all (all specifications will be
+ of that type will be returned), `all' (all specifications will be
returned), or nil (the actual specifier object will be returned).
See `glyph-property' for more information."
(glyph-property glyph 'contrib-p locale))
(defun glyph-contrib-p-instance (glyph &optional domain default no-fallback)
- "Return the instance of GLYPH's 'contrib-p property in DOMAIN.
+ "Return the instance of GLYPH's `contrib-p' property in DOMAIN.
Normally DOMAIN will be a window or nil (meaning the selected window),
- and an instance object describing what the 'contrib-p property is in
+ and an instance object describing what the `contrib-p' property is in
that particular window and buffer will be returned.
See `glyph-property-instance' for more information."
＠＠ -599,10 +730,10 ＠＠
locale to an instantiator list), or a boolean specifier object.
If SPEC is an alist, LOCALE must be omitted. If SPEC is a
- specifier object, LOCALE can be a locale, a locale type, 'all,
+ specifier object, LOCALE can be a locale, a locale type, `all',
or nil; see `copy-specifier' for its semantics. Otherwise LOCALE
specifies the locale under which the specified instantiator(s)
- will be added, and defaults to 'global.
+ will be added, and defaults to `global.'
See `set-glyph-property' for more information."
; (interactive (glyph-interactive "contrib-p"))
＠＠ -613,7 +744,7 ＠＠
LOCALE may be a locale (the instantiators for that particular locale
will be returned), a locale type (the specifications for all locales
- of that type will be returned), 'all (all specifications will be
+ of that type will be returned), `all' (all specifications will be
returned), or nil (the actual specifier object will be returned).
See `glyph-property' for more information."
＠＠ -638,10 +769,10 ＠＠
locale to an instantiator list), or a generic specifier object.
If SPEC is an alist, LOCALE must be omitted. If SPEC is a
- specifier object, LOCALE can be a locale, a locale type, 'all,
+ specifier object, LOCALE can be a locale, a locale type, `all',
or nil; see `copy-specifier' for its semantics. Otherwise LOCALE
specifies the locale under which the specified instantiator(s)
- will be added, and defaults to 'global.
+ will be added, and defaults to `global.'
See `set-glyph-property' for more information."
; (interactive (glyph-interactive "baseline"))
＠＠ -668,13 +799,46 ＠＠
normally think of as an image (which in XEmacs is called a
\"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 SPEC-LIST is typically an image instantiator (a
-string or a vector; see `make-image-specifier' for a detailed description
-of the valid image instantiators), 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
-`canonicalize-spec-list'.
+
+SPEC-LIST is typically an image instantiator, describing the source for the
+image data. This is either a vector of the form [FORMAT :KEYWORD DATA ...],
+for example
+
+ [jpeg :file \"/user/john/images/myimage.jpg\"]
+
+or
+
+ [xbm :data \"/* XPM */\nstatic char * copy[] = {\n...\"]
+
+or it is a string, either giving a file name or directly specifying inline
+data. See `make-image-specifier' for a detailed description of valid image
+instantiators. If the instantiator is a string, XEmacs will convert it
+into vector form by trying to guess whether a file name or inline data is
+intended, and what kind of data is inline or in the file. Usually it does
+a pretty good job. See `console-type-image-conversion-list' for details of
+how this works.
+
+If the instantiator specifies data from a file, the data will be read in
+when `make-glyph' is called and substituted inline into the instantiator,
+using the :data keyword. This means that the file must exist when the
+glyph is created, but does not need to exist afterwards (e.g. it may safely
+be a temporary file).
+
+When errors occur in the process of reading image data from a file
+\(e.g. the file does not exist or the data is of the wrong format or
+corrupted), no Lisp error will currently be signalled. Instead, the
+instantiator is skipped and warnings will be issued at level `debug'. \(A
+glyph with no instantiators in it cannot be displayed.) Normally, such
+warnings are ignored entirely, but you can change this by setting
+`log-warning-minimum-level'. This is useful if you're trying to debug why
+particular instantiators are not being processed. (#### We should probably
+provide a way of getting errors in such circumstances, or even make this
+the default behavior.)
+
+Technically, SPEC-LIST can also be a list of image 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 `canonicalize-spec-list'.
If you're not familiar with specifiers, you should be in order to
understand how glyphs work. The clearest introduction to specifiers
＠＠ -734,7 +898,7 ＠＠
value of the variable `toolbar-mail-icon' (in general, `toolbar-*-icon')
and then calling `(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.
+ change will appear in new frames, but not existing ones.)
-- To insert a glyph into a gutter, create or modify a gutter instantiator
(typically set on the specifier `default-gutter'). Gutter instantiators
＠＠ -781,9 +945,6 ＠＠
which controls the appearance of characters. You can also set an
overriding display table for use with text displayed in a particular
face; see `set-face-display-table' and `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.
-- 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
＠＠ -972,7 +1133,7 ＠＠
(set-glyph-image (symbol-value harg) value))))
;; It might or might not be garbage, but it's rude. Make these
-;; 'compatible instead of 'obsolete. -slb
+;; `compatible' instead of `obsolete.' -slb
(defun define-obsolete-pointer-glyph (old new)
(define-compatible-variable-alias old new)
(dontusethis-set-symbol-value-handler
- 1 participants
- 0 comments
CVS update by viteno MODIFIED: xemacs ...
19 years, 1 month
CVS Monitor
CVS Monitor
User: viteno
Date: 05/02/22 23:52:04
Modified: xemacs version.sh
Log:
Update xemacs_extra_name.
Revision Changes Path
1.1076 +1 -1 XEmacs/xemacs/version.sh
Index: version.sh
===================================================================
RCS file: /pack/xemacscvs/XEmacs/xemacs/version.sh,v
retrieving revision 1.1075
retrieving revision 1.1076
diff -u -r1.1075 -r1.1076
--- version.sh 2005/02/22 07:16:01 1.1075
+++ version.sh 2005/02/22 22:52:03 1.1076
＠＠ -8,5 +8,5 ＠＠
infodock_major_version=4
infodock_minor_version=0
infodock_build_version=8
-xemacs_extra_name="(+CVS-20050221)"
+xemacs_extra_name="(+CVS-20050222)"
xemacs_release_date="2005-02-18"
- 1 participants
- 0 comments
CVS update by adrian MODIFIED: xemacs/nt ...
19 years, 1 month
CVS Monitor
CVS Monitor
User: adrian
Date: 05/02/22 23:34:24
Modified: xemacs/nt ChangeLog xemacs.mak
Log:
xemacs-21.5-clean: Don't copy removed BUGS in install target of xemacs.mak
-------------------- ChangeLog entries follow: --------------------
nt/ChangeLog addition:
2005-02-22 Adrian Aichner <adrian(a)xemacs.org>
* xemacs.mak (install): Don't copy BUGS, which has been removed.
Revision Changes Path
1.183 +4 -0 XEmacs/xemacs/nt/ChangeLog
Index: ChangeLog
===================================================================
RCS file: /pack/xemacscvs/XEmacs/xemacs/nt/ChangeLog,v
retrieving revision 1.182
retrieving revision 1.183
diff -u -r1.182 -r1.183
--- ChangeLog 2005/02/18 06:30:15 1.182
+++ ChangeLog 2005/02/22 22:34:23 1.183
＠＠ -1,3 +1,7 ＠＠
+2005-02-22 Adrian Aichner <adrian(a)xemacs.org>
+
+ * xemacs.mak (install): Don't copy BUGS, which has been removed.
+
2005-02-18 Stephen J. Turnbull <stephen(a)xemacs.org>
* XEmacs 21.5.19 "chives" is released.
1.113 +0 -1 XEmacs/xemacs/nt/xemacs.mak
Index: xemacs.mak
===================================================================
RCS file: /pack/xemacscvs/XEmacs/xemacs/nt/xemacs.mak,v
retrieving revision 1.112
retrieving revision 1.113
diff -u -r1.112 -r1.113
--- xemacs.mak 2005/01/31 20:08:52 1.112
+++ xemacs.mak 2005/02/22 22:34:23 1.113
＠＠ -1457,7 +1457,6 ＠＠
＠echo Installing in $(INSTALL_DIR) ...
＠echo PlaceHolder > PlaceHolder
＠$(COPY) $(SRCROOT)\PROBLEMS "$(INSTALL_DIR)\"
- ＠$(COPY) $(SRCROOT)\BUGS "$(INSTALL_DIR)\"
＠$(COPY) $(SRCROOT)\README "$(INSTALL_DIR)\"
＠$(COPY) $(SRCROOT)\COPYING "$(INSTALL_DIR)\"
＠$(COPY) $(SRCROOT)\Installation "$(INSTALL_DIR)\"
- 1 participants
- 0 comments
CVS update by simon MODIFIED: packages/xemacs-packages/mail-lib ...
19 years, 1 month
CVS Monitor
CVS Monitor
User: simon
Date: 05/02/22 15:01:29
Modified: packages/xemacs-packages/mail-lib browse-url.el ChangeLog
Log:
* browse-url.el (browse-url-netscape-new-window-is-tab): New
variable.
(browse-url-netscape): Use it. Doc fix. Reported by "Johann
'Myrkraverk' Oskarsson" <myrkraverk(a)users.sourceforget.net>.
Revision Changes Path
1.34 +30 -16 XEmacs/packages/xemacs-packages/mail-lib/browse-url.el
Index: browse-url.el
===================================================================
RCS file: /pack/xemacscvs/XEmacs/packages/xemacs-packages/mail-lib/browse-url.el,v
retrieving revision 1.33
retrieving revision 1.34
diff -u -r1.33 -r1.34
--- browse-url.el 2003/12/07 05:18:47 1.33
+++ browse-url.el 2005/02/22 14:01:27 1.34
＠＠ -1,6 +1,6 ＠＠
;;; browse-url.el --- pass a URL to a WWW browser
-;; Copyright (C) 1995, 96, 97, 98, 99, 2000, 2001, 2002, 2003
+;; Copyright (C) 1995, 96, 97, 98, 99, 2000, 2001, 2002, 2003, 2005
;; Free Software Foundation, Inc.
;; Author: Denis Howe <dbh(a)doc.ic.ac.uk>
＠＠ -403,6 +403,13 ＠＠
:type 'boolean
:group 'browse-url)
+(defcustom browse-url-netscape-new-window-is-tab nil
+ "*Whether to open up new windows in a tab or a new window.
+If non-nil, then open the URL in a new tab rather than a new window if
+`browse-url-netscape' is asked to open it in a new window."
+ :type 'boolean
+ :group 'browse-url)
+
;;;###autoload
(defcustom browse-url-new-window-flag nil
"*If non-nil, always open a new browser window with appropriate browsers.
＠＠ -863,6 +870,10 ＠＠
random existing one. A non-nil interactive prefix argument reverses
the effect of `browse-url-new-window-flag'.
+If `browse-url-netscape-new-window-is-tab' is non-nil, then
+whenever a document would otherwise be loaded in a new window, it
+is loaded in a new tab in an existing window instead.
+
When called non-interactively, optional second argument NEW-WINDOW is
used instead of `browse-url-new-window-flag'."
(interactive (browse-url-interactive-arg "URL: "))
＠＠ -872,21 +883,24 ＠＠
(setq url (replace-match
(format "%%%x" (string-to-char (match-string 0 url))) t t url)))
(let* ((process-environment (browse-url-process-environment))
- (process (apply 'start-process
- (concat "netscape " url) nil
- browse-url-netscape-program
- (append
- browse-url-netscape-arguments
- (if (eq (console-type) 'mswindows) ;; XEmacs change
- (list url)
- (append
- (if new-window '("-noraise"))
- (list "-remote"
- (concat "openURL(" url
- (if (browse-url-maybe-new-window
- new-window)
- ",new-window")
- ")"))))))))
+ (process
+ (apply 'start-process
+ (concat "netscape " url) nil
+ browse-url-netscape-program
+ (append
+ browse-url-netscape-arguments
+ (if (eq (console-type) 'mswindows) ;; XEmacs change
+ (list url)
+ (append
+ (if new-window '("-noraise"))
+ (list "-remote"
+ (concat "openURL(" url
+ (if (browse-url-maybe-new-window
+ new-window)
+ (if browse-url-mozilla-new-window-is-tab
+ ",new-tab"
+ ",new-window"))
+ ")"))))))))
(set-process-sentinel process
`(lambda (process change)
(browse-url-netscape-sentinel process ,url)))))
1.153 +7 -0 XEmacs/packages/xemacs-packages/mail-lib/ChangeLog
Index: ChangeLog
===================================================================
RCS file: /pack/xemacscvs/XEmacs/packages/xemacs-packages/mail-lib/ChangeLog,v
retrieving revision 1.152
retrieving revision 1.153
diff -u -r1.152 -r1.153
--- ChangeLog 2004/11/30 05:55:51 1.152
+++ ChangeLog 2005/02/22 14:01:28 1.153
＠＠ -1,3 +1,10 ＠＠
+2005-02-22 Simon Josefsson <jas(a)extundo.com>
+
+ * browse-url.el (browse-url-netscape-new-window-is-tab): New
+ variable.
+ (browse-url-netscape): Use it. Doc fix. Reported by "Johann
+ 'Myrkraverk' Oskarsson" <myrkraverk(a)users.sourceforget.net>.
+
2004-11-30 Norbert Koch <viteno(a)xemacs.org>
* Makefile (VERSION): XEmacs package 1.70 released.
- 1 participants
- 0 comments
CVS update by stephent MODIFIED: xemacs/lwlib ...
19 years, 1 month
CVS Monitor
CVS Monitor
User: stephent
Date: 05/02/22 14:03:21
Modified: xemacs/lwlib Tag: sjt-xft ChangeLog xlwtabs.c
Log:
suppress debug output
Revision Changes Path
No revision
No revision
1.758.2.12 +4 -0 XEmacs/xemacs/src/ChangeLog
Index: ChangeLog
===================================================================
RCS file: /pack/xemacscvs/XEmacs/xemacs/src/ChangeLog,v
retrieving revision 1.758.2.11
retrieving revision 1.758.2.12
diff -u -r1.758.2.11 -r1.758.2.12
--- ChangeLog 2005/02/22 10:17:35 1.758.2.11
+++ ChangeLog 2005/02/22 13:03:08 1.758.2.12
＠＠ -1,3 +1,7 ＠＠
+2005-02-22 Stephen J. Turnbull <stephen(a)xemacs.org>
+
+ * xft-fonts.c (debug_xft): Suppress all debug output for now.
+
2005-02-21 Stephen J. Turnbull <stephen(a)xemacs.org>
* emacs.c (xemacs-release-date): New version info variable.
1.1.2.7 +2 -2 XEmacs/xemacs/src/Attic/xft-fonts.c
Index: xft-fonts.c
===================================================================
RCS file: /pack/xemacscvs/XEmacs/xemacs/src/Attic/xft-fonts.c,v
retrieving revision 1.1.2.6
retrieving revision 1.1.2.7
diff -u -r1.1.2.6 -r1.1.2.7
--- xft-fonts.c 2005/02/11 15:50:43 1.1.2.6
+++ xft-fonts.c 2005/02/22 13:03:12 1.1.2.7
＠＠ -46,8 +46,8 ＠＠
#include "objects-x-impl.h"
#include "xft-fonts.h"
-int debug_xft = 1; /* This enables lots of obnoxious messages.
- Setting it to 2 enables even more. */
+int debug_xft = 0; /* Set to 1 enables lots of obnoxious messages.
+ Setting it to 2 or 3 enables even more. */
/* #### TO DO ####
. The "x-xft-*" and "x_xft_*" nomenclature is mostly redundant, especially
No revision
No revision
1.64.2.5 +4 -0 XEmacs/xemacs/lwlib/ChangeLog
Index: ChangeLog
===================================================================
RCS file: /pack/xemacscvs/XEmacs/xemacs/lwlib/ChangeLog,v
retrieving revision 1.64.2.4
retrieving revision 1.64.2.5
diff -u -r1.64.2.4 -r1.64.2.5
--- ChangeLog 2005/02/22 10:17:33 1.64.2.4
+++ ChangeLog 2005/02/22 13:03:20 1.64.2.5
＠＠ -1,3 +1,7 ＠＠
+2005-02-22 Stephen J. Turnbull <stephen(a)xemacs.org>
+
+ * xlwtabs.c(debug_tabs): Suppress debug output for now.
+
2005-02-18 Stephen J. Turnbull <stephen(a)xemacs.org>
* xlwtabs.c (TabsGeometryManager,TabsQueryGeometry): Improve comments.
1.4.2.7 +1 -1 XEmacs/xemacs/lwlib/xlwtabs.c
Index: xlwtabs.c
===================================================================
RCS file: /pack/xemacscvs/XEmacs/xemacs/lwlib/xlwtabs.c,v
retrieving revision 1.4.2.6
retrieving revision 1.4.2.7
diff -u -r1.4.2.6 -r1.4.2.7
--- xlwtabs.c 2005/02/22 10:17:34 1.4.2.6
+++ xlwtabs.c 2005/02/22 13:03:20 1.4.2.7
＠＠ -418,7 +418,7 ＠＠
-static int debug_tabs = 1; /* increase for more verbosity */
+static int debug_tabs = 0; /* increase for more verbosity */
#ifdef USE_XFT_TABS
/* #### duplicated from xlwmenu.c -- CLEAN THIS SHIT UP!
- 1 participants
- 0 comments
CVS update by stephent MODIFIED: xemacs/src/s ...
19 years, 2 months
CVS Monitor
CVS Monitor
User: stephent
Date: 05/02/22 12:05:07
Modified: xemacs/src/s freebsd.h
Log:
FreeBSD 6 deprecates -lxpg4 <87mztw6elp.fsf(a)tleepslib.sk.tsukuba.ac.jp>
Revision Changes Path
1.794 +4 -0 XEmacs/xemacs/src/ChangeLog
Index: ChangeLog
===================================================================
RCS file: /pack/xemacscvs/XEmacs/xemacs/src/ChangeLog,v
retrieving revision 1.793
retrieving revision 1.794
diff -u -r1.793 -r1.794
--- ChangeLog 2005/02/22 07:16:14 1.793
+++ ChangeLog 2005/02/22 11:04:57 1.794
＠＠ -1,3 +1,7 ＠＠
+2005-01-06 Andrey Slusar <anrays(a)gmail.com>
+
+ * s/freebsd.h: fix build on the FreeBSD 6
+
2005-02-21 Stephen J. Turnbull <stephen(a)xemacs.org>
* emacs.c (xemacs-release-date): New version info variable.
1.23 +1 -1 XEmacs/xemacs/src/s/freebsd.h
Index: freebsd.h
===================================================================
RCS file: /pack/xemacscvs/XEmacs/xemacs/src/s/freebsd.h,v
retrieving revision 1.22
retrieving revision 1.23
diff -u -r1.22 -r1.23
--- freebsd.h 2002/03/13 08:53:22 1.22
+++ freebsd.h 2005/02/22 11:05:06 1.23
＠＠ -29,7 +29,7 ＠＠
#ifndef __FreeBSD_version
#include <osreldate.h>
#endif
-#if __FreeBSD_version >= 199701
+#if __FreeBSD_version >= 199701 && __FreeBSD_version < 600006
#define LIBS_SYSTEM "-lutil -lxpg4"
#else
#define LIBS_SYSTEM "-lutil"
- 1 participants
- 0 comments
CVS update by stephent MODIFIED: xemacs/src ...
19 years, 2 months
CVS Monitor
CVS Monitor
User: stephent
Date: 05/02/22 11:17:42
Modified: xemacs/src Tag: sjt-xft ChangeLog config.h.in emacs.c
Log:
autoconf fiddling; work on xlwtabs.c
Revision Changes Path
No revision
No revision
1.418.2.9 +11 -0 XEmacs/xemacs/ChangeLog
Index: ChangeLog
===================================================================
RCS file: /pack/xemacscvs/XEmacs/xemacs/ChangeLog,v
retrieving revision 1.418.2.8
retrieving revision 1.418.2.9
diff -u -r1.418.2.8 -r1.418.2.9
--- ChangeLog 2005/02/20 14:00:45 1.418.2.8
+++ ChangeLog 2005/02/22 10:16:50 1.418.2.9
＠＠ -1,3 +1,14 ＠＠
+2005-02-21 Stephen J. Turnbull <stephen(a)xemacs.org>
+
+ * version.sh (XEMACS_RELEASE_DATE): New version info variable.
+
+ * configure.in (XEMACS_RELEASE_DATE):
+ * configure.ac (XEMACS_RELEASE_DATE):
+ Use it.
+
+ * configure.ac (sound):
+ AC_DEFINE_UNQUOTED seems OK, if it's not m4-quoted.
+
2005-02-20 Stephen J. Turnbull <stephen(a)xemacs.org>
* configure.ac (athena): Spells as 3d, not xaw3d, in declaration.
1.232.2.6 +104 -26 XEmacs/xemacs/configure
Index: configure
===================================================================
RCS file: /pack/xemacscvs/XEmacs/xemacs/configure,v
retrieving revision 1.232.2.5
retrieving revision 1.232.2.6
diff -u -r1.232.2.5 -r1.232.2.6
--- configure 2005/02/11 12:19:31 1.232.2.5
+++ configure 2005/02/22 10:16:50 1.232.2.6
＠＠ -1669,7 +1669,68 ＠＠
{ echo "Error:" --enable-mule, NOT --with-mule >&2; exit 1; }
fi;
+# Check whether --with-menubars or --without-menubars was given.
+if test "${with_menubars+set}" = set; then
+ withval="$with_menubars"
+ { echo "Error:" --enable-menubars, NOT --with-menubars >&2; exit 1; }
+fi;
+
+# Check whether --with-scrollbars or --without-scrollbars was given.
+if test "${with_scrollbars+set}" = set; then
+ withval="$with_scrollbars"
+ { echo "Error:" --enable-scrollbars, NOT --with-scrollbars >&2; exit 1; }
+fi;
+
+# Check whether --with-dialogs or --without-dialogs was given.
+if test "${with_dialogs+set}" = set; then
+ withval="$with_dialogs"
+ { echo "Error:" --enable-dialogs, NOT --with-dialogs >&2; exit 1; }
+fi;
+
+# Check whether --with-widgets or --without-widgets was given.
+if test "${with_widgets+set}" = set; then
+ withval="$with_widgets"
+ { echo "Error:" --enable-widgets, NOT --with-widgets >&2; exit 1; }
+fi;
+
+# Check whether --with-sound or --without-sound was given.
+if test "${with_sound+set}" = set; then
+ withval="$with_sound"
+ { echo "Error:" --enable-sound, NOT --with-sound >&2; exit 1; }
+fi;
+
+# Check whether --with-default-eol-detection or --without-default-eol-detection was given.
+if test "${with_default_eol_detection+set}" = set; then
+ withval="$with_default_eol_detection"
+ { echo "Error:" --enable-default-eol-detection, NOT --with-default-eol-detection >&2; exit 1; }
+fi;
+
+# Check whether --with-clash-detection or --without-clash-detection was given.
+if test "${with_clash_detection+set}" = set; then
+ withval="$with_clash_detection"
+ { echo "Error:" --enable-clash-detection, NOT --with-clash-detection >&2; exit 1; }
+fi;
+
+# Check whether --with-database or --without-database was given.
+if test "${with_database+set}" = set; then
+ withval="$with_database"
+ { echo "Error:" --enable-database, NOT --with-database >&2; exit 1; }
+fi;
+# Check whether --with-modules or --without-modules was given.
+if test "${with_modules+set}" = set; then
+ withval="$with_modules"
+ { echo "Error:" --enable-modules, NOT --with-modules >&2; exit 1; }
+fi;
+
+# Check whether --with-toolbars or --without-toolbars was given.
+if test "${with_toolbars+set}" = set; then
+ withval="$with_toolbars"
+ { echo "Error:" --enable-toolbars, NOT --with-toolbars >&2; exit 1; }
+fi;
+
+
+
# Check whether --with-prefix or --without-prefix was given.
if test "${with_prefix+set}" = set; then
withval="$with_prefix"
＠＠ -2926,6 +2987,12 ＠＠
_ACEOF
fi
+if test "$xemacs_release_date" != ""; then
+ cat >>confdefs.h <<_ACEOF
+#define XEMACS_RELEASE_DATE "$xemacs_release_date"
+_ACEOF
+
+fi
cat >>confdefs.h <<_ACEOF
#define EMACS_VERSION "$version"
_ACEOF
＠＠ -33748,27 +33815,13 ＠＠
fi
if test `eval echo '${'$as_ac_Header'}'` = yes; then
- sound_found=yes
- need_miscplay=yes
- extra_objs="$extra_objs linuxplay.o" && if test "$extra_verbose" = "yes"; then
- echo " xemacs will be linked with \"linuxplay.o\""
- fi
- cat >>confdefs.h <<_ACEOF
-#define SOUNDCARD_H_FILE "${dir}/soundcard.h"
-_ACEOF
- break
-fi
-
-
- done
- fi
-
- if test "$sound_found" = "yes"; then
- enable_sound_native=yes
-
- if test "$opsys" = "netbsd" ; then
- echo "$as_me:$LINENO: checking for _oss_ioctl in -lossaudio" >&5
+ sound_found=yes
+ case "$canonical" in
+ *netbsd* )
+ # #### this is probably not the right way to do this
+ # we should port to native NetBSD stuff
+ echo "$as_me:$LINENO: checking for _oss_ioctl in -lossaudio" >&5
echo $ECHO_N "checking for _oss_ioctl in -lossaudio... $ECHO_C" >&6
if test "${ac_cv_lib_ossaudio__oss_ioctl+set}" = set; then
echo $ECHO_N "(cached) $ECHO_C" >&6
＠＠ -33833,16 +33886,41 ＠＠
echo "$as_me:$LINENO: result: $ac_cv_lib_ossaudio__oss_ioctl" >&5
echo "${ECHO_T}$ac_cv_lib_ossaudio__oss_ioctl" >&6
if test $ac_cv_lib_ossaudio__oss_ioctl = yes; then
- native_sound_lib="-lossaudio"
+ native_sound_lib=-lossaudio
+ { echo "$as_me:$LINENO: WARNING: Using NetBSD-deprecated -lossaudio" >&5
+echo "$as_me: WARNING: Using NetBSD-deprecated -lossaudio" >&2;}
+else
+ sound_found=no
fi
- fi
+ ;;
+ esac
+ break
+fi
+
+
+ done
+
+ if test "$sound_found" = "yes"; then
+ need_miscplay=yes
+ extra_objs="$extra_objs linuxplay.o" && if test "$extra_verbose" = "yes"; then
+ echo " xemacs will be linked with \"linuxplay.o\""
+ fi
+ cat >>confdefs.h <<_ACEOF
+#define SOUNDCARD_H_FILE "${dir}/soundcard.h"
+_ACEOF
+
+ fi
+ fi
+
+ if test "$sound_found" = "yes"; then
+ enable_sound_native=yes
else
- if test "$enable_sound_native" = "yes" ; then
- { echo "$as_me:$LINENO: WARNING: No native libraries found. Disabling native sound support." >&5
+ if test "$enable_sound_native" = "yes" ; then
+ { echo "$as_me:$LINENO: WARNING: No native libraries found. Disabling native sound support." >&5
echo "$as_me: WARNING: No native libraries found. Disabling native sound support." >&2;}
- fi
- enable_sound_native=no
+ fi
+ enable_sound_native=no
fi
fi
1.1.14.7 +5 -3 XEmacs/xemacs/configure.ac
Index: configure.ac
===================================================================
RCS file: /pack/xemacscvs/XEmacs/xemacs/configure.ac,v
retrieving revision 1.1.14.6
retrieving revision 1.1.14.7
diff -u -r1.1.14.6 -r1.1.14.7
--- configure.ac 2005/02/20 14:00:45 1.1.14.6
+++ configure.ac 2005/02/22 10:17:07 1.1.14.7
＠＠ -1064,6 +1064,9 ＠＠
if test "$xemacs_extra_name" != ""; then
AC_DEFINE_UNQUOTED(XEMACS_EXTRA_NAME, "$xemacs_extra_name")
fi
+if test "$xemacs_release_date" != ""; then
+ AC_DEFINE_UNQUOTED(XEMACS_RELEASE_DATE, "$xemacs_release_date")
+fi
AC_DEFINE_UNQUOTED(EMACS_VERSION, "$version")
if test "$with_infodock" = "yes"; then
＠＠ -4807,7 +4810,7 ＠＠
dnl Check for Linux/BSD native sound (also on recent Cygwins)
if test -z "$sound_found"; then
for dir in "machine" "sys" "linux"; do
- AC_CHECK_HEADER(${dir}/soundcard.h, [
+ AC_CHECK_HEADER([${dir}/soundcard.h], [
sound_found=yes
case "$canonical" in
*netbsd* )
＠＠ -4827,8 +4830,7 ＠＠
if test "$sound_found" = "yes"; then
need_miscplay=yes
XE_ADD_OBJS(linuxplay.o)
- dnl I don't understand, but autoconf chokes on AC_DEFINE_UNQUOTED here
- AC_DEFINE(SOUNDCARD_H_FILE, "${dir}/soundcard.h")
+ AC_DEFINE_UNQUOTED(SOUNDCARD_H_FILE, ["${dir}/soundcard.h"])
fi
fi
1.233.2.4 +3 -0 XEmacs/xemacs/configure.in
Index: configure.in
===================================================================
RCS file: /pack/xemacscvs/XEmacs/xemacs/configure.in,v
retrieving revision 1.233.2.3
retrieving revision 1.233.2.4
diff -u -r1.233.2.3 -r1.233.2.4
--- configure.in 2004/12/11 05:12:28 1.233.2.3
+++ configure.in 2005/02/22 10:17:07 1.233.2.4
＠＠ -1062,6 +1062,9 ＠＠
if test "$xemacs_extra_name" != ""; then
AC_DEFINE_UNQUOTED(XEMACS_EXTRA_NAME, "$xemacs_extra_name")
fi
+if test "$xemacs_release_date" != ""; then
+ AC_DEFINE_UNQUOTED(XEMACS_RELEASE_DATE, "$xemacs_release_date")
+fi
AC_DEFINE_UNQUOTED(EMACS_VERSION, "$version")
if test "$with_infodock" = "yes"; then
1.984.2.3 +1 -0 XEmacs/xemacs/version.sh
Index: version.sh
===================================================================
RCS file: /pack/xemacscvs/XEmacs/xemacs/version.sh,v
retrieving revision 1.984.2.2
retrieving revision 1.984.2.3
diff -u -r1.984.2.2 -r1.984.2.3
--- version.sh 2005/02/01 15:46:18 1.984.2.2
+++ version.sh 2005/02/22 10:17:08 1.984.2.3
＠＠ -9,3 +9,4 ＠＠
infodock_minor_version=0
infodock_build_version=8
xemacs_extra_name="(+Xft+CVS-20041209)"
+xemacs_release_date="2004-10-22"
No revision
No revision
1.599.2.3 +5 -0 XEmacs/xemacs/lisp/ChangeLog
Index: ChangeLog
===================================================================
RCS file: /pack/xemacscvs/XEmacs/xemacs/lisp/ChangeLog,v
retrieving revision 1.599.2.2
retrieving revision 1.599.2.3
diff -u -r1.599.2.2 -r1.599.2.3
--- ChangeLog 2005/02/04 16:05:54 1.599.2.2
+++ ChangeLog 2005/02/22 10:17:27 1.599.2.3
＠＠ -1,3 +1,8 ＠＠
+2005-02-21 Stephen J. Turnbull <stephen(a)xemacs.org>
+
+ * about.el (about-xemacs):
+ Compute release date from xemacs-release-date.
+
2005-02-03 Eric Knauel <eric(a)xemacs.org>
* fontconfig.el (fc-try-font):
1.63.2.1 +22 -2 XEmacs/xemacs/lisp/about.el
Index: about.el
===================================================================
RCS file: /pack/xemacscvs/XEmacs/xemacs/lisp/about.el,v
retrieving revision 1.63
retrieving revision 1.63.2.1
diff -u -r1.63 -r1.63.2.1
--- about.el 2004/11/07 12:03:58 1.63
+++ about.el 2005/02/22 10:17:29 1.63.2.1
＠＠ -376,8 +376,28 ＠＠
(t (format "%d.%d"
emacs-major-version
emacs-minor-version))))
- (emacs-about-version (format "version %s of September 2004"
- emacs-short-version)))
+ (emacs-release-date
+ (if (and (boundp 'xemacs-release-date)
+ (stringp xemacs-release-date)
+ (string-match "^\\([0-9]\\{4\\}\\)-\\([0-9][0-9]\\)-"
+ xemacs-release-date))
+ (format "%s %s"
+ (aref [ "January" "February" "March" "April"
+ "May" "June" "July" "August"
+ "September" "October" "November" "December" ]
+ (1- (string-to-number
+ (match-string 2 xemacs-release-date))))
+ (match-string 1 xemacs-release-date))
+ "February 2005 (defaulted in about.el)"))
+ (emacs-variant-info (if (and xemacs-extra-name
+ (stringp xemacs-extra-name)
+ (< 0 (length xemacs-extra-name)))
+ (format " %s" xemacs-extra-name)
+ ""))
+ (emacs-about-version (format "version %s of %s%s"
+ emacs-short-version
+ emacs-release-date
+ emacs-variant-info)))
(widget-insert (about-center emacs-about-version))
(widget-create 'link :help-echo "What's new in XEmacs"
:action 'about-news
No revision
No revision
1.64.2.4 +13 -0 XEmacs/xemacs/lwlib/ChangeLog
Index: ChangeLog
===================================================================
RCS file: /pack/xemacscvs/XEmacs/xemacs/lwlib/ChangeLog,v
retrieving revision 1.64.2.3
retrieving revision 1.64.2.4
diff -u -r1.64.2.3 -r1.64.2.4
--- ChangeLog 2005/02/01 15:46:38 1.64.2.3
+++ ChangeLog 2005/02/22 10:17:33 1.64.2.4
＠＠ -1,3 +1,16 ＠＠
+2005-02-18 Stephen J. Turnbull <stephen(a)xemacs.org>
+
+ * xlwtabs.c (TabsGeometryManager,TabsQueryGeometry): Improve comments.
+ (debug_tabs): New variable, substitute for debug_xft globally.
+ (TabsGeometryManager): Substitute "request" for "req".
+
+2005-02-11 Stephen J. Turnbull <stephen(a)xemacs.org>
+
+ * xlwtabs.c (PreferredSize3): Let TabLayout choose constraints.
+ (TabLayout): Default size to current size. Fix header comment.
+ (TabsGeometryManager): Comment on redesigning internal API.
+ (TabsGeometryManager): Fix typo in format string.
+
2005-01-27 Stephen J. Turnbull <stephen(a)xemacs.org>
* xlwtabs.c (DrawTab):
1.4.2.6 +73 -53 XEmacs/xemacs/lwlib/xlwtabs.c
Index: xlwtabs.c
===================================================================
RCS file: /pack/xemacscvs/XEmacs/xemacs/lwlib/xlwtabs.c,v
retrieving revision 1.4.2.5
retrieving revision 1.4.2.6
diff -u -r1.4.2.5 -r1.4.2.6
--- xlwtabs.c 2005/02/01 15:46:39 1.4.2.5
+++ xlwtabs.c 2005/02/22 10:17:34 1.4.2.6
＠＠ -417,9 +417,10 ＠＠
((TabsConstraints)((tab)->core.constraints))->tabs.visible)
-#ifdef USE_XFT_TABS
-extern int debug_xft; /* from lwlib-face.c */
+static int debug_tabs = 1; /* increase for more verbosity */
+
+#ifdef USE_XFT_TABS
/* #### duplicated from xlwmenu.c -- CLEAN THIS SHIT UP!
Undeclared so define at top. */
#define MINL(x,y) ((((unsigned long) (x)) < ((unsigned long) (y))) \
＠＠ -829,9 +830,9 ＠＠
* Return status, with preferred size in PREFERRED.
*
* According to the X Toolkit Intrinsics manual
- * XtGeometryYes = accept request without change
+ * XtGeometryYes = accept INTENDED without change
* XtGeometryNo = request to stay _exactly_ the same
- * XtGeometryAlmost = request consideration of preference
+ * XtGeometryAlmost = suggest PREFERRED as a compromise
* and the PREFERRED argument must be filled in completely (ie, any fields
* whose bits are set in the request_mode mask must correspond to the
* preferred geometry, which must be consistent with the return value).
＠＠ -849,7 +850,7 ＠＠
static XtGeometryResult
TabsQueryGeometry (Widget w,
XtWidgetGeometry *intended,
- XtWidgetGeometry *preferred)
+ XtWidgetGeometry *preferred) /* RETURN */
{
TabsWidget tw = (TabsWidget) w;
XtGeometryMask mode = intended->request_mode;
＠＠ -885,12 +886,18 ＠＠
/*
* Geometry Manager; called when TAB (a child) wants to be resized.
+ *
+ * According to the X Toolkit Intrinsics manual
+ * XtGeometryDone = accept REQUEST and do it (#### check this)
+ * XtGeometryYes = accept REQUEST without change
+ * XtGeometryNo = refuse REQUEST (ie, stay _exactly_ the same)
+ * XtGeometryAlmost = suggest REPLY as a compromise
*/
static XtGeometryResult
TabsGeometryManager (Widget tab,
- XtWidgetGeometry *req,
- XtWidgetGeometry *reply)
+ XtWidgetGeometry *request,
+ XtWidgetGeometry *reply) /* RETURN */
{
TabsWidget control = (TabsWidget) XtParent(tab);
Dimension s = SHADWID;
＠＠ -905,31 +912,31 ＠＠
#### This is the wrong way to do this. If other parts of the
request can be satisfied, should return XtGeometryAlmost. */
- if (((req->request_mode & CWX) && req->x != tab->core.x) ||
- ((req->request_mode & CWY) && req->y != tab->core.y) ||
+ if (((request->request_mode & CWX) && request->x != tab->core.x) ||
+ ((request->request_mode & CWY) && request->y != tab->core.y) ||
!constraint->tabs.resizable)
return XtGeometryNo;
/* Make all three fields in the request valid */
- if (!(req->request_mode & CWWidth))
- req->width = tab->core.width;
- if (!(req->request_mode & CWHeight))
- req->height = tab->core.height;
- if (!(req->request_mode & CWBorderWidth))
- req->border_width = tab->core.border_width;
+ if (!(request->request_mode & CWWidth))
+ request->width = tab->core.width;
+ if (!(request->request_mode & CWHeight))
+ request->height = tab->core.height;
+ if (!(request->request_mode & CWBorderWidth))
+ request->border_width = tab->core.border_width;
#ifndef DONT_DEBUG_REQUESTS
#define DBG_REQUEST_PRINT(field,size) \
do { \
- if (req->field > size) \
+ if (request->field > size) \
{ \
if (++debug_count == debug_mask) \
{ \
debug_mask <<= 1; \
fprintf (stderr, "ridiculous request #%d: field %d > %d\n", \
- debug_count, req->field, size); \
+ debug_count, request->field, size); \
} \
- req->field = tab->core.field; \
+ request->field = tab->core.field; \
} \
} while (0)
＠＠ -943,14 +950,14 ＠＠
/* #### this is NONSENSE, isn't it?
AFAICT XtMakeGeometryRequest would already have returned
XtGeometryYes in this case. */
- if (req->width == tab->core.width &&
- req->height == tab->core.height &&
- req->border_width == tab->core.border_width)
+ if (request->width == tab->core.width &&
+ request->height == tab->core.height &&
+ request->border_width == tab->core.border_width)
return XtGeometryNo;
#endif
- rw = req->width + 2 * req->border_width;
- rh = req->height + 2 * req->border_width;
+ rw = request->width + 2 * request->border_width;
+ rh = request->height + 2 * request->border_width;
/* find out how big the children want to be now */
MaxChild (control, tab, rw, rh);
＠＠ -974,7 +981,7 ＠＠
* for another day.
*/
- if (req->request_mode & (CWWidth | CWHeight | CWBorderWidth))
+ if (request->request_mode & (CWWidth | CWHeight | CWBorderWidth))
{
Dimension cw,ch ; /* children's preferred size */
Dimension aw,ah ; /* available size we can give child */
＠＠ -986,7 +993,13 ＠＠
ch = control->tabs.max_ch ;
/* find out what *my* resulting preferred size would be */
-
+ /* #### this whole API is wrong; what should happen is
+ 1. app should hint as to #rows and/or aspect ratio
+ 2. tab control should attempt to layout in current space
+ 3. if not all tabs fit, should request resize to achieve
+ layout hints
+ Probably can and should cache preferred size in widget, with
+ cache cleared when labels or core size changes. */
PreferredSize2(control, cw, ch, &wid, &hgt) ;
/* Would my size change? If so, ask to be resized. */
＠＠ -1006,7 +1019,7 ＠＠
* offer the child a compromise, then make this a query only.
*/
- if( (req->request_mode & XtCWQueryOnly) || rw < cw || rh < ch )
+ if( (request->request_mode & XtCWQueryOnly) || rw < cw || rh < ch )
myrequest.request_mode |= XtCWQueryOnly ;
result = XtMakeGeometryRequest ((Widget) control,
＠＠ -1062,7 +1075,7 ＠＠
int n = control->composite.num_children;
ah = control->tabs.tab_height;
fprintf (stderr, "Kludging around %d != 1 rows, #children = %d,"
- " total height %d, using %d\n.",
+ " total height %d, using %d.\n",
check_nrows, n, th, ah);
}
＠＠ -1076,13 +1089,13 ＠＠
/* Acceptable. If this wasn't a query, change *all* children
* to this size.
*/
- if( req->request_mode & XtCWQueryOnly )
+ if( request->request_mode & XtCWQueryOnly )
return XtGeometryYes ;
else
{
Widget *childP = control->composite.children;
int i,bw;
- tab->core.border_width = req->border_width;
+ tab->core.border_width = request->border_width;
for(i = TabsNumChildren (control); --i >= 0; ++childP)
if (TabVisible (*childP))
{
＠＠ -1104,9 +1117,9 ＠＠
/* Cannot grant child's request. Describe what we *can* do
* and return counter-offer.
*/
- reply->width = aw - 2 * req->border_width ;
- reply->height = ah - 2 * req->border_width ;
- reply->border_width = req->border_width ;
+ reply->width = aw - 2 * request->border_width ;
+ reply->height = ah - 2 * request->border_width ;
+ reply->border_width = request->border_width ;
reply->request_mode = CWWidth | CWHeight | CWBorderWidth ;
return XtGeometryAlmost ;
}
＠＠ -1580,9 +1593,7 ＠＠
GC gc ;
int x,y ;
-#ifdef USE_XFT_TABS
- if (debug_xft > 1) fprintf (stderr, "DrawTab called.\n");
-#endif
+ if (debug_tabs > 1) fprintf (stderr, "DrawTab called.\n");
if( !XtIsRealized((Widget)tw))
return ;
＠＠ -1606,10 +1617,10 ＠＠
visual_info_from_widget ((Widget) tw, &visual, &ignored);
colorBG = xft_convert_color (dpy, cmap, visual,
tw->core.background_pixel, 0);
+#endif
- if (debug_xft > 2)
+ if (debug_tabs > 2)
fprintf (stderr, "(Re)drawing labels.\n");
-#endif
if (XtIsSensitive(child))
{
＠＠ -1679,7 +1690,7 ＠＠
/* #### unnecessary? for the moment, give visual extent */
/* draw background rect */
#if 1
- if (debug_xft > 2)
+ if (debug_tabs > 2)
{
fprintf (stderr, "background color: pixel=%08lx, r=%04x,"
" g=%04x, b=%04x, alpha=%04x.\n",
＠＠ -1698,7 +1709,7 ＠＠
glyphinfo.width, glyphinfo.height);
#endif
/* draw text */
- if (debug_xft > 2)
+ if (debug_tabs > 2)
{
FcValue name;
FcValue size;
＠＠ -1959,10 +1970,10 ＠＠
+ tw->tabs.renderFont->ascent
/* #### how can this subtraction be correct? */
- tw->tabs.renderFont->descent)/2;
- if (debug_xft > 2)
+ if (debug_tabs > 2)
fprintf (stderr, "tab: height=%d, width=%d, baseline=%d.\n",
tw->tabs.tab_height, tab->tabs.width, tab->tabs.l_y);
- if (debug_xft > 1)
+ if (debug_tabs > 1)
fprintf (stderr, "font: height=%d, ascent=%d, descent=%d.\n",
tw->tabs.renderFont->height,
tw->tabs.renderFont->ascent,
＠＠ -1987,6 +1998,7 ＠＠
*
* TODO: if they require more than two rows and the total height:width
* ratio is more than 2:1, then try something else.
+ * Gaak! This is actually already done in PreferredSize()!
*
* TODO SOONER: for reasons unclear, some applications (specifically
* XEmacs) give a nominal geometry (in the core record) which doesn't
＠＠ -1994,7 +2006,7 ＠＠
* This results in bizarre values for DISPLAY_ROWS and REPLY_HEIGHT.
* Specify a way to say "tell me what you really want" (eg, with WID
* and/or HGT == 0 or == Dimension_MAX), and use it where appropriate.
- * LATE-BREAKING LOSE: This is happening in PreferredSize()!
+ * LATE-BREAKING LOSE: This happens in PreferredSize(), not XEmacs!
*
* TODO EVEN SOONER: some applications lay out the tab control by
* repeatedly querying until a fixed width and height has been filled
＠＠ -2003,15 +2015,15 ＠＠
static int
TabLayout(TabsWidget tw,
- Dimension wid,
- Dimension hgt,
+ Dimension wid, /* if 0, use core.width as guess */
+ Dimension hgt, /* if 0, use core.height as guess */
Dimension *reply_height, Bool query_only)
{
int i, row, done = 0, display_rows = 0 ;
int num_children = tw->composite.num_children ;
Widget *childP ;
Dimension w ;
- Position x,y ;
+ Position x,y ; /* #### gaak, these are dimensions! */
TabsConstraints tab ;
/* Algorithm: loop through children, assign X positions. If a tab
＠＠ -2026,20 +2038,25 ＠＠
row = 0 ;
x = INDENT ;
y = 0 ;
- wid -= INDENT ;
-#ifdef USE_XFT_TABS
- if (debug_xft > 0)
+ /* If wid or hgt is 0, we want to guess our own dimensions.
+ Currently the guessing functions are broken....
+ #### When PreferredSize*() get fixed, fix this too. */
+ if (debug_tabs > 0)
+ fprintf (stderr, "arg=%d,", wid);
+ wid = (wid ? wid : tw->core.width) - INDENT ;
+ hgt = hgt ? hgt : tw->core.height;
+ if (debug_tabs > 0)
fprintf (stderr, "wid=%d: x,w,y=", wid);
-#endif
for(i=num_children, childP=tw->composite.children; --i >= 0; ++childP)
if( XtIsManaged(*childP) )
{
tab = (TabsConstraints) (*childP)->core.constraints ;
w = tab->tabs.width ;
- if (debug_xft > 0)
+ if (debug_tabs > 0)
fprintf (stderr, "%d,%d,%d;", x, w, y);
if( x + w > wid ) { /* new row */
+ /* #### algorithm is not robust to wid < child's width */
++row;
x = INDENT ;
y += tw->tabs.tab_height ;
＠＠ -2059,7 +2076,7 ＠＠
tab->tabs.visible = 1;
}
- if (debug_xft > 0)
+ if (debug_tabs > 0)
fprintf (stderr, "\n");
/* If there was only one row, increase the height by TABDELTA */
if( ++display_rows == 1 )
＠＠ -2086,7 +2103,7 ＠＠
tw->tabs.realRows = row;
}
- if (debug_xft > 0 && (row > 1 || display_rows > 1))
+ if (debug_tabs > 0 && (row > 1 || display_rows > 1))
fprintf (stderr, "tab: %d display rows, #children = %d,"
" total height %d, total rows %d%s.\n",
display_rows, num_children, y, row,
＠＠ -2299,7 +2316,10 ＠＠
int nrows ;
if( tw->composite.num_children > 0 )
- nrows = TabLayout(tw, wid, hgt, &th, True) ;
+ /* used to be wid, hgt not 0, 0 but that's obviously wrong
+ since TabLayout wants dimensions of control parent but
+ wid, hgt are dimensions of some child */
+ nrows = TabLayout(tw, 0, 0, &th, True) ;
else {
th = 0 ;
nrows = 0 ;
No revision
No revision
1.758.2.11 +9 -0 XEmacs/xemacs/src/ChangeLog
Index: ChangeLog
===================================================================
RCS file: /pack/xemacscvs/XEmacs/xemacs/src/ChangeLog,v
retrieving revision 1.758.2.10
retrieving revision 1.758.2.11
diff -u -r1.758.2.10 -r1.758.2.11
--- ChangeLog 2005/02/21 08:43:29 1.758.2.10
+++ ChangeLog 2005/02/22 10:17:35 1.758.2.11
＠＠ -1,5 +1,14 ＠＠
2005-02-21 Stephen J. Turnbull <stephen(a)xemacs.org>
+ * emacs.c (xemacs-release-date): New version info variable.
+ * config.h.in (XEMACS_RELEASE_DATE): New config.h macro.
+
+ * emacs.c (inhibit-early-packages):
+ (inhibit-all-packages):
+ (xemacs-extra-name): Improve docstrings.
+
+2005-02-21 Stephen J. Turnbull <stephen(a)xemacs.org>
+
* objects-x.c (x_finalize_font_instance): Improve debug message.
2005-02-20 Stephen J. Turnbull <stephen(a)xemacs.org>
1.95.2.4 +1 -0 XEmacs/xemacs/src/config.h.in
Index: config.h.in
===================================================================
RCS file: /pack/xemacscvs/XEmacs/xemacs/src/config.h.in,v
retrieving revision 1.95.2.3
retrieving revision 1.95.2.4
diff -u -r1.95.2.3 -r1.95.2.4
--- config.h.in 2005/02/01 15:46:52 1.95.2.3
+++ config.h.in 2005/02/22 10:17:38 1.95.2.4
＠＠ -110,6 +110,7 ＠＠
#undef EMACS_VERSION
#undef XEMACS_CODENAME
#undef XEMACS_EXTRA_NAME
+#undef XEMACS_RELEASE_DATE
/* InfoDock versions, not used with XEmacs */
#undef INFODOCK_MAJOR_VERSION
#undef INFODOCK_MINOR_VERSION
1.150.2.3 +25 -6 XEmacs/xemacs/src/emacs.c
Index: emacs.c
===================================================================
RCS file: /pack/xemacscvs/XEmacs/xemacs/src/emacs.c,v
retrieving revision 1.150.2.2
retrieving revision 1.150.2.3
diff -u -r1.150.2.2 -r1.150.2.3
--- emacs.c 2004/12/10 06:43:48 1.150.2.2
+++ emacs.c 2005/02/22 10:17:38 1.150.2.3
＠＠ -460,6 +460,7 ＠＠
Lisp_Object Vemacs_beta_version;
Lisp_Object Vxemacs_codename;
Lisp_Object Vxemacs_extra_name;
+Lisp_Object Vxemacs_release_date;
#ifdef INFODOCK
Lisp_Object Vinfodock_major_version;
Lisp_Object Vinfodock_minor_version;
＠＠ -4116,15 +4117,31 ＠＠
Vxemacs_codename = build_string (XEMACS_CODENAME);
DEFVAR_LISP ("xemacs-extra-name", &Vxemacs_extra_name /*
-Extra string to maybe put into the version string.
+Arbitrary string to place in the version string after the codename.
-Usually used to denote an XEmacs built from a CVS checkout between
-releases. In that case its value would be \"(+CVS)\".
+Appropriate surrounding whitespace will be added, but typically looks best
+if enclosed in parentheses.
+
+A standard use is to indicate the date version.sh was last updated from
+the CVS mainline, where it is automatically given a value similar to
+\"(+CVS-20050221)\". Developers may also use it to indicate particular
+branches, etc.
*/ );
#ifdef XEMACS_EXTRA_NAME
Vxemacs_extra_name = build_string (XEMACS_EXTRA_NAME);
#endif
+ DEFVAR_LISP ("xemacs-release-date", &Vxemacs_release_date /*
+ISO 8601 format date string giving the date of latest release in series.
+
+The time may optionally be given. The time zone may not be given, and
+is (implicitly) UTC. Currently not included in the version string.
+*/ );
+#ifndef XEMACS_RELEASE_DATE
+#define XEMACS_RELEASE_DATE "2005-02-18 (defaulted in emacs.c)"
+#endif
+ Vxemacs_release_date = build_string (XEMACS_RELEASE_DATE);
+
/* Lisp variables which contain command line flags.
The portable dumper stomps on these; they must be saved and restored
＠＠ -4139,12 +4156,14 ＠＠
*/ );
DEFVAR_BOOL ("inhibit-early-packages", &inhibit_early_packages /*
-Set to non-nil when the early packages should not be respected at startup.
+Set to non-nil when the early packages should be ignored at startup.
+Early package directories will not be added to `load-path', nor set up as
+autoloads, nothing.
*/ );
DEFVAR_BOOL ("inhibit-all-packages", &inhibit_all_packages /*
-Set to non-nil when the no packages should not be respected at startup.
-XEmacs will utterly ignore the packages -- not in load-path, not set up as
+Set to non-nil when all packages should be ignored at startup.
+Package directories will not be added to `load-path', nor set up as
autoloads, nothing.
*/ );
- 1 participants
- 0 comments
CVS update by viteno ADDED: xemacs-builds/viteno update-version.sh
19 years, 2 months
CVS Monitor
CVS Monitor
User: viteno
Date: 05/02/22 10:51:00
Added: xemacs-builds/viteno update-version.sh
Log:
Script, which updates the version script of betas, to be run on
sunsite.dk daily.
Revision Changes Path
1.1 XEmacs/xemacs-builds/viteno/update-version.sh
Index: update-version.sh
===================================================================
#!/usr/bin/bash
## Copyright (C) 2002, 2003 Steve Youngs
## This program is free software; you can redistribute it and/or modify
## it under the terms of the GNU General Public License as published by
## the Free Software Foundation; either version 2 of the License, or
## (at your option) any later version.
## This program is distributed in the hope that it will be useful,
## but WITHOUT ANY WARRANTY; without even the implied warranty of
## MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
## GNU General Public License for more details.
## You should have received a copy of the GNU General Public License
## along with this program; if not, write to the Free Software
## Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
### Commentary:
#
# Just a tiny little script that updates 'xemacs_extra_name' in
# version.sh for XEmacs beta. It also runs `make-src-depends' and
# commits ./src/depend.
### Code:
# Add a time-stamp and underline it
D=$(date)
echo $D
echo $D | sed 's/./-/g'
CVS=/coll/local/bin/cvs
PERL=/coll/local/bin/perl
REPOSITORY=${HOME}/XEmacs/
SAFE=${HOME}/tools/safe
cd ${REPOSITORY}
$CVS -Q up -Pd
if [ $? -eq 0 ]; then
sed 's/xemacs_extra_name=.*/xemacs_extra_name="(+CVS-'"`date +%Y%m%d`"')"/' \
version.sh | $SAFE version.sh
fi
$CVS -Q ci -m "Update xemacs_extra_name." ./version.sh
# Update src dependencies
cd ${REPOSITORY}/src
$PERL ./make-src-depend > ./depend
$CVS -Q ci -m "Update src depends" ./depend
# empty line at the end to separate entries
echo
exit 0
### update-version.sh ends here.
- 1 participants
- 0 comments