-This is ../info/lispref.info, produced by makeinfo version 4.6 from
+This is ../info/lispref.info, produced by makeinfo version 4.8 from
lispref/lispref.texi.
INFO-DIR-SECTION XEmacs Editor
Foundation instead of in the original English.
\1f
+File: lispref.info, Node: Face Properties, Next: Face Convenience Functions, Prev: Basic Face Functions, Up: Faces
+
+49.1.3 Face Properties
+----------------------
+
+You can examine and modify the properties of an existing face with the
+following functions.
+
+ The following symbols have predefined meanings:
+
+`foreground'
+ The foreground color of the face.
+
+`background'
+ The background color of the face.
+
+`font'
+ The font used to display text covered by this face.
+
+`display-table'
+ The display table of the face.
+
+`background-pixmap'
+ The pixmap displayed in the background of the face. Only used by
+ faces on GUI devices, currently X11, GTK, and Microsoft Windows.
+
+`underline'
+ Underline all text covered by this face.
+
+`highlight'
+ Highlight all text covered by this face. Only used by faces on TTY
+ devices.
+
+`dim'
+ Dim all text covered by this face. Only used by faces on TTY
+ devices.
+
+`blinking'
+ Blink all text covered by this face. Only used by faces on TTY
+ devices.
+
+`reverse'
+ Reverse the foreground and background colors. Only used by faces
+ on TTY devices.
+
+`doc-string'
+ Description of what the face's normal use is. NOTE: This is not a
+ specifier, unlike all the other built-in properties, and cannot
+ contain locale-specific values.
+
+ -- Function: set-face-property face property value &optional locale
+ tag-set how-to-add
+ This function changes a property of a FACE.
+
+ 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.
+
+ If PROPERTY is a built-in property, the specifications to be added
+ to this property can be supplied in many different ways:
+
+ 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).
+
+ 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 case), and specifications will be added as given.
+
+ If VALUE is a specifier (as would be returned by
+ `face-property' if no 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 `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 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 `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 `face-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' 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.
+
+ If PROPERTY is not a built-in property, then this function will
+ simply set its value if LOCALE is `nil'. However, if LOCALE is
+ 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.
+
+ -- Function: remove-face-property face property &optional locale
+ tag-set exact-p
+ This function removes a property of a FACE.
+
+ For built-in properties, this is analogous to `remove-specifier'.
+ For more information, *Note Other Specification Functions::.
+
+ When PROPERTY is not a built-in property, this function will just
+ remove its value if LOCALE is `nil' or `all'. However, if LOCALE
+ is other than that, this function will attempt to remove VALUE as
+ the instantiator for the given LOCALE with `remove-specifier'. If
+ the value of the property is not a specifier, it will be converted
+ into a `generic' specifier automatically.
+
+ -- Function: face-property face property &optional locale tag-set
+ exact-p
+ This function returns FACE's value of the given PROPERTY.
+
+ If LOCALE is omitted, the FACE's actual value for 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.
+
+ If 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 PROPERTY is
+ a specifier (this will always be the case for built-in properties,
+ but not or not may apply to user-defined properties). If the
+ actual value of PROPERTY is not a specifier, this value will
+ simply be returned regardless of LOCALE.
+
+ The return value will be a list of instantiators (e.g. strings
+ 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 will be returned. Otherwise, if LOCALE is a locale type
+ (one of the symbols `buffer', `window', `frame', or `device'), 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
+ PROPERTY will be in a particular "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 `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 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
+ `face-property-instance' actually does all this, and is used to
+ determine how to display the face.
+
+ -- Function: face-property-instance face property &optional domain
+ default no-fallback
+ This function returns the instance of FACE's PROPERTY in the
+ specified DOMAIN.
+
+ Under most circumstances, 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.
+
+ The returned instance will typically be a color-instance,
+ font-instance, or pixmap-instance object, and you can query it
+ using the appropriate object-specific functions. For example, you
+ could use `color-instance-rgb-components' to find out the RGB
+ (red, green, and blue) components of how the `background' property
+ of the `highlight' face is 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 color for
+ the frame that window is on; or perhaps the same color was
+ specified but the window is on a different X server, and that X
+ server has different RGB values for the color from this one).
+
+ DOMAIN defaults to the selected window if omitted.
+
+ DOMAIN can be a frame or device, instead of a window. The value
+ returned for a 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 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 `specifier-instance'.
+
+ Optional arguments DEFAULT and NO-FALLBACK are the same as in
+ `specifier-instance'. *Note Specifiers::.
+
+\1f
+File: lispref.info, Node: Face Convenience Functions, Next: Other Face Display Functions, Prev: Face Properties, Up: Faces
+
+49.1.4 Face Convenience Functions
+---------------------------------
+
+ -- Command: set-face-foreground face color &optional locale tag-set
+ how-to-add
+ -- Command: set-face-background face color &optional locale tag-set
+ how-to-add
+ These functions set the foreground (respectively, background)
+ color of face FACE to COLOR. The argument COLOR should be a
+ string (the name of a color) or a color object as returned by
+ `make-color' (*note Colors::).
+
+ -- Command: set-face-background-pixmap face pixmap &optional locale
+ tag-set how-to-add
+ This function sets the background pixmap of face FACE to PIXMAP.
+ The argument PIXMAP should be a string (the name of a bitmap or
+ pixmap file; the directories listed in the variable
+ `x-bitmap-file-path' will be searched) or a glyph object as
+ returned by `make-glyph' (*note Glyphs::). The argument may also
+ be a list of the form `(WIDTH HEIGHT DATA)' where WIDTH and HEIGHT
+ are the size in pixels, and DATA is a string, containing the raw
+ bits of the bitmap.
+
+ Similarly to how the glyph's image specifier works *Note 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 `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?)
+
+ -- Command: set-face-font face font &optional locale tag-set how-to-add
+ This function sets the font of face FACE. The argument FONT
+ should be a string or a font object as returned by `make-font'
+ (*note Fonts::).
+
+ -- Command: set-face-underline-p face underline-p &optional locale
+ tag-set how-to-add
+ This function sets the underline property of face FACE.
+
+ -- Function: face-foreground face &optional locale tag-set exact-p
+ -- Function: face-background face &optional locale tag-set exact-p
+ These functions return the foreground (respectively, background)
+ color specifier of face FACE. *Note Colors::.
+
+ -- Function: face-background-pixmap face &optional locale tag-set
+ exact-p
+ This function returns the background-pixmap image specifier of face
+ FACE.
+
+ -- Function: face-font face &optional locale tag-set exact-p
+ This function returns the font specifier of face FACE. (Note:
+ This is not the same as the function `face-font' in FSF Emacs.)
+
+ *Note Fonts::.
+
+ -- Function: face-font-name face &optional domain
+ This function returns the name of the font of face FACE, or `nil'
+ if it is unspecified. This is basically equivalent to `(font-name
+ (face-font FACE) DOMAIN)' except that it does not cause an error
+ if FACE's font is `nil'. (This function is named `face-font' in
+ FSF Emacs.)
+
+ -- Function: face-underline-p face &optional locale
+ This function returns the underline property of face FACE.
+
+ -- Function: face-foreground-instance face &optional domain
+ -- Function: face-background-instance face &optional domain
+ These functions return the foreground (respectively, background)
+ color specifier of face FACE. *Note Colors::.
+
+ -- Function: face-background-pixmap-instance face &optional domain
+ This function return the background-pixmap glyph object of face
+ FACE.
+
+ -- Function: face-font-instance face &optional domain
+ This function returns the font specifier of face FACE. *Note
+ Fonts::.
+
+\1f
+File: lispref.info, Node: Other Face Display Functions, Prev: Face Convenience Functions, Up: Faces
+
+49.1.5 Other Face Display Functions
+-----------------------------------
+
+ -- Command: invert-face face &optional locale
+ Swap the foreground and background colors of face FACE. If the
+ face doesn't specify both foreground and background, then its
+ foreground and background are set to the default background and
+ foreground.
+
+ -- Function: face-equal face1 face2 &optional domain
+ This returns `t' if the faces FACE1 and FACE2 will display in the
+ same way. DOMAIN is as in `face-property-instance'.
+
+ -- Function: face-differs-from-default-p face &optional domain
+ This returns `t' if the face FACE displays differently from the
+ default face. DOMAIN is as in `face-property-instance'.
+
+\1f
+File: lispref.info, Node: Fonts, Next: Colors, Prev: Faces, Up: Faces and Window-System Objects
+
+49.2 Fonts
+==========
+
+This section describes how to work with font specifier and font
+instance objects, which encapsulate fonts in the window system.
+
+* Menu:
+
+* Font Specifiers:: Specifying how a font will appear.
+* Font Instances:: What a font specifier gets instanced as.
+* Font Instance Names:: The name of a font instance.
+* Font Instance Size:: The size of a font instance.
+* Font Instance Characteristics:: Display characteristics of font instances.
+* Font Convenience Functions:: Convenience functions that automatically
+ instance and retrieve the properties
+ of a font specifier.
+
+\1f
+File: lispref.info, Node: Font Specifiers, Next: Font Instances, Up: Fonts
+
+49.2.1 Font Specifiers
+----------------------
+
+ -- Function: font-specifier-p object
+ This predicate returns `t' if OBJECT is a font specifier, and
+ `nil' otherwise.
+
+ -- Function: make-font-specifier spec-list
+ Return a new `font' specifier object with the given specification
+ list. SPEC-LIST can be a list of specifications (each of which is
+ a cons of a locale and a list of instantiators), a single
+ instantiator, or a list of instantiators. *Note Specifiers::, for
+ more information about specifiers.
+
+ Valid instantiators for font specifiers are:
+
+ * A string naming a font (e.g. under X this might be
+ "-*-courier-medium-r-*-*-*-140-*-*-*-*-iso8859-*" for a
+ 14-point upright medium-weight Courier font).
+
+ * A font instance (use that instance directly if the device
+ matches, or use the string that generated it).
+
+ * A vector of no elements (only on TTY's; this means to set no
+ font at all, thus using the "natural" font of the terminal's
+ text).
+
+ * A vector of one element (a face to inherit from).
+
+\1f
+File: lispref.info, Node: Font Instances, Next: Font Instance Names, Prev: Font Specifiers, Up: Fonts
+
+49.2.2 Font Instances
+---------------------
+
+ -- Function: font-instance-p object
+ This predicate returns `t' if OBJECT is a font instance, and `nil'
+ otherwise.
+
+ -- Function: make-font-instance name &optional device noerror
+ This function creates a new font-instance object of the specified
+ name. DEVICE specifies the device this object applies to and
+ defaults to the selected device. An error is signalled if the
+ font is unknown or cannot be allocated; however, if NOERROR is
+ non-`nil', `nil' is simply returned in this case.
+
+ The returned object is a normal, first-class lisp object. The way
+ you "deallocate" the font is the way you deallocate any other lisp
+ object: you drop all pointers to it and allow it to be garbage
+ collected. When these objects are GCed, the underlying X data is
+ deallocated as well.
+
+\1f
+File: lispref.info, Node: Font Instance Names, Next: Font Instance Size, Prev: Font Instances, Up: Fonts
+
+49.2.3 Font Instance Names
+--------------------------
+
+ -- Function: list-fonts pattern &optional device
+ This function returns a list of font names matching the given
+ pattern. DEVICE specifies which device to search for names, and
+ defaults to the currently selected device.
+
+ -- Function: font-instance-name font-instance
+ This function returns the name used to allocate FONT-INSTANCE.
+
+ -- Function: font-instance-truename font-instance
+ This function returns the canonical name of the given font
+ instance. Font names are patterns which may match any number of
+ fonts, of which the first found is used. This returns an
+ unambiguous name for that font (but not necessarily its only
+ unambiguous name).
+
+\1f
File: lispref.info, Node: Font Instance Size, Next: Font Instance Characteristics, Prev: Font Instance Names, Up: Fonts
-Font Instance Size
-------------------
+49.2.4 Font Instance Size
+-------------------------
- - Function: x-font-size font
+ -- Function: x-font-size font
This function returns the nominal size of the given font. This is
done by parsing its name, so it's likely to lose. X fonts can be
specified (by the user) in either pixels or 10ths of points, and
this returns the first one it finds, so you have to decide which
units the returned value is measured in yourself ...
- - Function: x-find-larger-font font &optional device
+ -- Function: x-find-larger-font font &optional device
This function loads a new, slightly larger version of the given
font (or font name). Returns the font if it succeeds, `nil'
otherwise. If scalable fonts are available, this returns a font
which is 1 point larger. Otherwise, it returns the next larger
version of this font that is defined.
- - Function: x-find-smaller-font font &optional device
+ -- Function: x-find-smaller-font font &optional device
This function loads a new, slightly smaller version of the given
font (or font name). Returns the font if it succeeds, `nil'
otherwise. If scalable fonts are available, this returns a font
\1f
File: lispref.info, Node: Font Instance Characteristics, Next: Font Convenience Functions, Prev: Font Instance Size, Up: Fonts
-Font Instance Characteristics
------------------------------
+49.2.5 Font Instance Characteristics
+------------------------------------
- - Function: font-instance-properties font-instance
+ -- Function: font-instance-properties font-instance
This function returns the properties (an alist or `nil') of
FONT-INSTANCE.
- - Function: x-make-font-bold font &optional device
+ -- Function: x-make-font-bold font &optional device
Given an X font specification, this attempts to make a "bold" font.
If it fails, it returns `nil'.
- - Function: x-make-font-unbold font &optional device
+ -- Function: x-make-font-unbold font &optional device
Given an X font specification, this attempts to make a non-bold
font. If it fails, it returns `nil'.
- - Function: x-make-font-italic font &optional device
+ -- Function: x-make-font-italic font &optional device
Given an X font specification, this attempts to make an "italic"
font. If it fails, it returns `nil'.
- - Function: x-make-font-unitalic font &optional device
+ -- Function: x-make-font-unitalic font &optional device
Given an X font specification, this attempts to make a non-italic
font. If it fails, it returns `nil'.
- - Function: x-make-font-bold-italic font &optional device
+ -- Function: x-make-font-bold-italic font &optional device
Given an X font specification, this attempts to make a
"bold-italic" font. If it fails, it returns `nil'.
\1f
File: lispref.info, Node: Font Convenience Functions, Prev: Font Instance Characteristics, Up: Fonts
-Font Convenience Functions
---------------------------
+49.2.6 Font Convenience Functions
+---------------------------------
- - Function: font-name font &optional domain
+ -- Function: font-name font &optional domain
This function returns the name of the FONT in the specified
DOMAIN, if any. FONT should be a font specifier object and DOMAIN
is normally a window and defaults to the selected window if
omitted. This is equivalent to using `specifier-instance' and
applying `font-instance-name' to the result.
- - Function: font-truename font &optional domain
+ -- Function: font-truename font &optional domain
This function returns the truename of the FONT in the specified
DOMAIN, if any. FONT should be a font specifier object and DOMAIN
is normally a window and defaults to the selected window if
omitted. This is equivalent to using `specifier-instance' and
applying `font-instance-truename' to the result.
- - Function: font-properties font &optional domain
+ -- Function: font-properties font &optional domain
This function returns the properties of the FONT in the specified
DOMAIN, if any. FONT should be a font specifier object and DOMAIN
is normally a window and defaults to the selected window if
\1f
File: lispref.info, Node: Colors, Prev: Fonts, Up: Faces and Window-System Objects
-Colors
-======
+49.3 Colors
+===========
* Menu:
\1f
File: lispref.info, Node: Color Specifiers, Next: Color Instances, Up: Colors
-Color Specifiers
-----------------
+49.3.1 Color Specifiers
+-----------------------
- - Function: color-specifier-p object
+ -- Function: color-specifier-p object
This function returns non-`nil' if OBJECT is a color specifier.
- - Function: make-color-specifier spec-list
+ -- Function: make-color-specifier spec-list
Return a new `color' specifier object with the given specification
list. SPEC-LIST can be a list of specifications (each of which is
a cons of a locale and a list of instantiators), a single
used for; if this specifier is not part of a face, the
instantiator would not be valid).
- - Function: make-face-boolean-specifier spec-list
+ -- Function: make-face-boolean-specifier spec-list
Return a new `face-boolean' specifier object with the given spec
list. SPEC-LIST can be a list of specifications (each of which is
a cons of a locale and a list of instantiators), a single
\1f
File: lispref.info, Node: Color Instances, Next: Color Instance Properties, Prev: Color Specifiers, Up: Colors
-Color Instances
----------------
+49.3.2 Color Instances
+----------------------
A "color-instance object" is an object describing the way a color
specifier is instanced in a particular domain. Functions such as
color of the `default' face is displayed in the next window after the
selected one.
- - Function: color-instance-p object
+ -- Function: color-instance-p object
This function returns non-`nil' if OBJECT is a color-instance.
\1f
File: lispref.info, Node: Color Instance Properties, Next: Color Convenience Functions, Prev: Color Instances, Up: Colors
-Color Instance Properties
--------------------------
+49.3.3 Color Instance Properties
+--------------------------------
- - Function: color-instance-name color-instance
+ -- Function: color-instance-name color-instance
This function returns the name used to allocate COLOR-INSTANCE.
- - Function: color-instance-rgb-components color-instance
+ -- Function: color-instance-rgb-components color-instance
This function returns a three element list containing the red,
green, and blue color components of COLOR-INSTANCE.
\1f
File: lispref.info, Node: Color Convenience Functions, Prev: Color Instance Properties, Up: Colors
-Color Convenience Functions
----------------------------
+49.3.4 Color Convenience Functions
+----------------------------------
- - Function: color-name color &optional domain
+ -- Function: color-name color &optional domain
This function returns the name of the COLOR in the specified
DOMAIN, if any. COLOR should be a color specifier object and
DOMAIN is normally a window and defaults to the selected window if
omitted. This is equivalent to using `specifier-instance' and
applying `color-instance-name' to the result.
- - Function: color-rgb-components color &optional domain
+ -- Function: color-rgb-components color &optional domain
This function returns the RGB components of the COLOR in the
specified DOMAIN, if any. COLOR should be a color specifier
object and DOMAIN is normally a window and defaults to the
\1f
File: lispref.info, Node: Glyphs, Next: Annotations, Prev: Faces and Window-System Objects, Up: Top
-Glyphs
-******
+50 Glyphs
+*********
-A "glyph" is an object that is used for pixmaps, widgets and images of
+A "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 ("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
(`overlay-arrow-*' variables), toolbar buttons, mouse pointers, frame
-icons, truncation and continuation markers, and the like. (Basically,
+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.)
+will be a glyph object representing it.
- 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 (for text
-images), the alignment of the image (when it is in a buffer), etc.
-
- - Function: glyphp object
+ -- Function: glyphp object
This function returns `t' if OBJECT is a glyph.
* 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.
+* 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.
\1f
-File: lispref.info, Node: Glyph Functions, Next: Images, Up: Glyphs
-
-Glyph Functions
-===============
+File: lispref.info, Node: Glyph Intro, Next: Images, Up: Glyphs
-* Menu:
+50.1 Glyph Introduction
+=======================
-* 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.
+In XEmacs, "glyph" does *not* refer to a single unit of textual display
+(the XEmacs term for that is "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
+active GUI element such as a button or text entry field; X11 calls this
+a "widget", while MS Windows uses the term "control"). This graphical
+element could appear in a buffer, a margin, a gutter, or a toolbar, or
+even externally to XEmacs as a mouse pointer or an icon, for example.
+
+ 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, _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 `tty'
+device locale would give behavior like the `ALT' attribute of an `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 "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 "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.) *Note Specifiers::,
+for more information about specifier locales and domains.
\1f
-File: lispref.info, Node: Creating Glyphs, Next: Glyph Properties, Up: Glyph Functions
+File: lispref.info, Node: Images, Next: Using Glyphs, Prev: Glyph Intro, Up: Glyphs
-Creating Glyphs
----------------
+50.2 Images
+===========
- - Function: make-glyph &optional spec-list type
- This function creates a new glyph object of type TYPE.
+* Menu:
- SPEC-LIST is used to initialize the glyph's image. It is
- typically an image instantiator (a string or a vector; *Note 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
- `canonicalize-spec-list'. *Note Specifiers::, for more
- information about specifiers.
-
- 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. TYPE
- should be one of `buffer' (used for glyphs in an extent, the
- modeline, the toolbar, or elsewhere in a buffer), `pointer' (used
- for the mouse-pointer), or `icon' (used for a frame's icon), and
- defaults to `buffer'. *Note Glyph Types::.
-
- A glyph in XEmacs does *NOT* refer to a single unit of textual
- display (the XEmacs term for this is "rune"), but rather is an
- object encapsulating a graphical element, such as an image or
- widget (an element such as a button or text field; "widget" is the
- term for this under X Windows, and it's called a "control" under
- MS Windows). 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.
-
- Creating a glyph using `make-glyph' does not specify _where_ the
- glyph will be used, but it does specify _what_ the glyph will look
- like. In particular, SPEC-LIST is used to specify this, and it's
- used to initialize the glyph's `image' property, which is an image
- specifier. (Note that "image" as used in the context of a glyph's
- `image' property or in the terms "image specifier", "image
- instantiator", or "image instance" does not refer to what people
- 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; *Note 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 `canonicalize-spec-list'. *Note
- 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 `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.
-
- As well as using SPEC-LIST to initialize the glyph, you can set
- specifications using `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 `set-specifier', `specifier-instance' or
- the like on the glyph; instead use them on `(glyph-image GLYPH)'
- or use the convenience functions `set-glyph-image',
- `glyph-image-instance', and `glyph-image'.
-
- Once you have created a glyph, you specify where it will be used as
- follows:
-
- * To insert a glyph into a buffer, create an extent in the
- buffer and then use `set-extent-begin-glyph' or
- `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.)
-
- * 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 `left-margin-width' or `right-margin-width'.
- (Not strictly necessary when using margin glyphs with layout
- policy `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
- `set-extent-begin-glyph-layout' or
- `set-extent-end-glyph-layout'. Alternatively, use the
- high-level annotations API (see `make-annotation'). (In point
- of fact, you can also use the annotations API for glyphs in a
- buffer, by setting a layout policy of `text'.)
-
- * 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.)
-
- * To insert a glyph into a toolbar, specify it as part of a
- toolbar instantiator (typically set on the specifier
- `default-toolbar'). See `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
- `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.
-
- * To insert a glyph into a gutter, create or modify a gutter
- instantiator (typically set on the specifier
- `default-gutter'). Gutter instantiators consist of strings
- or lists of strings, so to insert a glyph, create an extent
- over the string, and use `set-extent-begin-glyph' or
- `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.
-
- * 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 `frame-icon-glyph'. (Remember that,
- because of the specifier nature of glyphs, you can set
- different values for any particular buffer or frame.)
-
- * To use a glyph as the mouse pointer, in general you do not
- create a new glyph, but rather you change the specifications
- of various existing glyphs, such as `text-pointer-glyph' for
- the pointer used over text, `modeline-pointer-glyph' for the
- pointer used over the modeline, etc. Do an apropos over
- `*-pointer-glyph' to find all of them. (Note also that you
- can temporarily set the mouse pointer to some specific shape
- by using `set-frame-pointer', which takes an image instance,
- as obtained from calling `glyph-image-instance' on a glyph of
- type `pointer' - either one of the above-mentioned variables
- or one you created yourself. (See below for what it means to
- create a glyph of type `pointer'.) This pointer will last
- only until the next mouse motion event is processed or
- certain other things happen, such as creating or deleting a
- window. (In fact, the above-mentioned pointer glyph variables
- are implemented as part of the default handler for mouse
- motion events. If you want to customize this behavior, take a
- look at `mode-motion-hook', or `mouse-motion-handler' if you
- really want to get low-level.)
-
- * 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 `continuation-glyph',
- `control-arrow-glyph', `hscroll-glyph',
- `invisible-text-glyph', `octal-escape-glyph', and
- `truncation-glyph'. See also `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
- `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 `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 `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 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 `set-face-background-pixmap'). Note that
- the image instance that is generated in order to actually
- display the background pixmap is of type `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.
-
- It is extremely rare that you will ever have to specify a value for
- TYPE, which should be one of `buffer' (used for glyphs in an
- extent, the modeline, the toolbar, or elsewhere in a buffer),
- `pointer' (used for the mouse-pointer), or `icon' (used for a
- frame's icon), and defaults to `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.
- `text-pointer-glyph' (or in general, `*-pointer-glyph') and
- `frame-icon-glyph'. *Note Glyph Types::.
-
- - Function: make-glyph-internal &optional type
- This function creates a new, uninitialized glyph of type TYPE.
+* 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.
- - Function: make-pointer-glyph &optional spec-list
- Return a new `pointer-glyph' object with the specification list
- SPEC-LIST. This function is equivalent to calling `make-glyph'
- with a TYPE of `pointer'.
+\1f
+File: lispref.info, Node: Image Specifiers, Next: Image Instantiator Conversion, Up: Images
- It is extremely unlikely that you will ever need to create a
- pointer glyph. Instead, you probably want to be calling
- `set-glyph-image' on an existing glyph, e.g. `text-pointer-glyph'.
+50.2.1 Image Specifiers
+-----------------------
- - Function: make-icon-glyph &optional spec-list
- Return a new `pointer-glyph' object with the specification list
- SPEC-LIST. This function is equivalent to calling `make-glyph'
- with a TYPE of `icon'.
+An image specifier is a description of the actual graphical realization
+of a glyph. For example, a typical image description is _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 (_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 "instantiates" the "image instantiator" into an "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 "image instantiators" in
+different locales. This is implemented with an "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 `glyph-image' on a glyph, or
+retrieving the `background-pixmap' property of a face, and you can
+check if some random object is an image specifier.
+
+ -- Function: image-specifier-p object
+ This function returns non-`nil' if OBJECT is an image specifier.
- It is extremely unlikely that you will ever need to create a
- pointer glyph. Instead, you probably want to be calling
- `set-glyph-image' on an existing glyph, e.g. `text-pointer-glyph'.
+ -- Function: make-image-specifier spec-list
+ This function creates a new image specifier object and initializes
+ it according to SPEC-LIST. *Note Specifiers::.
-\1f
-File: lispref.info, Node: Glyph Properties, Next: Glyph Convenience Functions, Prev: Creating Glyphs, Up: Glyph Functions
+ 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.
-Glyph Properties
-----------------
+ Image instantiators come in many formats: `xbm', `xpm', `gif',
+`jpeg', etc. These denote 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'.
+On the other hand, 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.).
-Each glyph has a list of properties, which control all of the aspects of
-the glyph's appearance. The following symbols have predefined meanings:
+ *Note Image Instances::, for a more detailed discussion of image
+instance types.
-`image'
- The image used to display the glyph.
+ An image instantiator should be a string or a vector of the form
-`baseline'
- Percent above baseline that glyph is to be displayed. Only for
- glyphs displayed inside of a buffer.
+ `[FORMAT :KEYWORD VALUE ...]'
-`contrib-p'
- Whether the glyph contributes to the height of the line it's on.
- Only for glyphs displayed inside of a buffer.
+ i.e. a format symbol followed by zero or more alternating
+keyword-value pairs.
-`face'
- Face of this glyph (_not_ a specifier).
+ The form of an instantiator can be checked with
+`valid-instantiator-p' with a TYPE of `image', *Note Specifier
+Validation Functions::.
- - Function: set-glyph-property glyph property value &optional locale
- tag-set how-to-add
- This function changes a property of a GLYPH.
+ For a complete list of the format symbols and their usage, *Note
+Image Instantiator Formats::.
- 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.
+ If the instantiator is a string, it will be converted into a vector
+by looking it up according to the specs in the
+`console-type-image-conversion-list' for the console type of the domain
+(usually a window; sometimes a frame or device) over which the image is
+being instantiated.
+
+ If the instantiator specifies data from a file, the data will be
+read in at the time that the instantiator is added to the image
+specifier (which may be well before the image is actually displayed),
+and the instantiator will be converted into one of the inline-data
+forms, with the filename retained using a `:file' keyword. This
+implies that the file must exist when the instantiator is added to the
+image, but does not need to exist at any other time (e.g. it may safely
+be a temporary file).
+
+ The available keywords are given below. Note that some keywords are
+generally available (for example, the `:data' keyword may be used with
+any format except `nothing'), while others are only available for one
+format (`resource-id' is unique to the `mswindows-resource' format).
+
+`: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 `: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.
+
+`:file'
+ Data contained in a file. The value is the name of this file. If
+ both `:data' and `:file' are specified, the image is created from
+ what is specified in `:data' and the string in `:file' becomes the
+ value of the `image-instance-file-name' function when applied to
+ the resulting image-instance. Note that there is nothing to stop a
+ program from changing either the `:file' or the `:data' property,
+ and there is no way to detect such mischief. This means that the
+ data will _not_ be automatically reread if you change the `file'
+ property; you must force it by removing the `:data' property.
+ (One way to do this is replacing the whole specification with a new
+ vector.) This keyword is not valid for instantiator formats
+ `nothing', `string', `formatted-string', `cursor-font', `font',
+ and `autodetect'.
+
+`:mask-data'
+ Inline data for `xbm' and `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 `:data'.
+
+`:mask-file'
+ For `xbm' and `xface'. This specifies a file containing the mask
+ data. If neither a mask file nor inline mask data is given for an
+ XBM image, and the XBM image comes from a file, XEmacs will look
+ for a mask file with the same name as the image file but with
+ `Mask' or `msk' appended. For example, if you specify the XBM file
+ `left_ptr' [usually located in `/usr/include/X11/bitmaps'], the
+ associated mask file `left_ptrmsk' will automatically be picked up.
+
+`:resource-id'
+ Only for `mswindows-resource'. This must be either an integer
+ (which directly specifies a resource number) or a string. See the
+ description of `mswindows-resource' for valid strings. *Note
+ Image Instantiator Formats::.
+
+`:foreground'
+`:background'
+ For `xbm', `xface', `cursor-font', and `font'. These keywords
+ allow you to explicitly specify foreground and background colors.
+ The value should be anything acceptable to `make-color-instance'.
+ This will cause an external format that would by default be
+ instantiated as a `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.
+
+`:hotspot-x'
+`:hotspot-y'
+ For `xbm' and `xface'. These keywords specify a hotspot if the
+ image is instantiated as a `pointer'. Note that if the XBM image
+ file specifies a hotspot, it will automatically be picked up if no
+ explicit hotspot is given.
+
+`:color-symbols'
+ Only for `xpm'. This specifies an alist that maps strings that
+ specify symbolic color names to the actual color to be used for
+ that symbolic color (in the form of a string or a color-specifier
+ object). If this is not specified, the contents of
+ `xpm-color-symbols' are used to generate the alist.
+
+`:resource-type'
+ Only for `mswindows-resource'. This must be a symbol, either
+ `cursor', `icon', or `bitmap', specifying the type of resource to
+ be retrieved.
+
+`:face'
+ For `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.
+
+`:selected'
+`:active'
+`:suffix'
+`:keys'
+`:style'
+`:filter'
+`:config'
+`:included'
+`:key-sequence'
+`:accelerator'
+`:label'
+`:callback'
+ These keywords, accepted as menu item specs, are also accepted by
+ images instantiated as `widget'. For their semantics, *Note Menu
+ Format::.
+
+\1f
+File: lispref.info, Node: Image Instantiator Conversion, Next: Image Instantiator Formats, Prev: Image Specifiers, Up: Images
+
+50.2.2 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
+`make-image-instance'.
+
+ -- Function: set-console-type-image-conversion-list console-type list
+ This function sets the image-conversion-list for consoles of the
+ given CONSOLE-TYPE. The image-conversion-list specifies how image
+ instantiators that are strings should be interpreted. Each
+ element of the list should be a list of two elements (a regular
+ expression string and a vector) or a list of three elements (the
+ preceding two plus an integer index into the vector). The string
+ is converted to the vector associated with the first matching
+ regular expression. If a vector index is specified, the string
+ itself is substituted into that position in the vector.
+
+ Note: The conversion above is applied when the image instantiator
+ is added to an image specifier, not when the specifier is actually
+ instantiated. Therefore, changing the image-conversion-list only
+ affects newly-added instantiators. Existing instantiators in
+ glyphs and image specifiers will not be affected.
+
+ -- Function: console-type-image-conversion-list console-type
+ This function returns the image-conversion-list for consoles of
+ the given CONSOLE-TYPE.
+
+\1f
+File: lispref.info, Node: Image Instantiator Formats, Next: Image Instances, Prev: Image Instantiator Conversion, Up: Images
+
+50.2.3 Image Instantiator Formats
+---------------------------------
+
+The "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.
+
+ -- Function: valid-image-instantiator-format-p format &optional locale
+ This function returns non-`nil' if FORMAT is a valid image
+ instantiator format.
+
+ If LOCALE is non-`nil' then the format is checked in that locale.
+ If LOCALE is `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.
+
+ -- Function: image-instantiator-format-list
+ This function returns a list of valid image-instantiator formats.
+
+ Here is a table of image-instantiator formats, giving the keywords
+that are usable with each, and the kinds of instances that may result.
+
+`nothing'
+ Don't display anything; no keywords are valid for this format.
+ Can only be instanced as `nothing'.
+
+`string'
+ Display this image as a text string. Can only be instanced as
+ `text', although support for instancing as `mono-pixmap' should be
+ added. The valid keyword is `:data'. The value should be a
+ string, and it is interpreted as a string of characters.
+
+`formatted-string'
+ Display this image as a text string with replaceable fields,
+ similar to a modeline format string. The valid keyword is `:data'.
+ The value should be a string, and it is interpreted as a string of
+ characters containing format sequences.
+
+ Not currently implemented.
+
+`xbm'
+ An X bitmap; available only if X support was compiled into this
+ XEmacs.
+
+ If used in a buffer glyph, icon glyph, or face background pixmap,
+ it will be instantiated as `mono-pixmap' unless the `:foreground'
+ or `:background' keywords are present. In the latter case it will
+ be instantiated as `color-pixmap' with the two specified colors.
+ (Probably if `:foreground' or `:background' is omitted, it
+ defaults to black or white respectively.) If used in a pointer
+ glyph, it will be instantiated as an `pointer'.
+
+ The valid keywords and their values are
+ `: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.
+
+ `: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.
+
+ `: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 `:data' property.
+
+ `:mask-file'
+ The name of a file containing standard XBM-format data.
+ Interpreted as the clipping region for the bitmap contained
+ in the `:data' property.
+
+ `:foreground'
+ `:background'
+ These keywords allow you to explicitly specify foreground and
+ background colors. The values should be acceptable to
+ `make-color-instance'.
+
+ `:hotspot-x'
+ `: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.
+
+`xpm'
+ An XPM pixmap; only available if XPM support was compiled into
+ this XEmacs.
+
+ Can be instanced as `color-pixmap', `mono-pixmap', or `pointer'.
+
+ XPM is an add-on library for X that was designed to rectify the
+ shortcomings of the XBM format. 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 valid keywords and their values are
+ `:data'
+ A string interpreted as the contents of a standard XPM file.
+
+ `: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.
+
+ `:hotspot-x'
+ `: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. (This may not be true. The
+ original documentation doesn't mention them in connection
+ with XPM, but a pointer needs a hotspot.)
+
+ `: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, *Note Color
+ Specifiers::, or a color-specifier object). If this is not
+ specified, the contents of `xpm-color-symbols' are used to
+ generate the alist.
+
+`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.
+
+ Will be instanced as `mono-pixmap', `color-pixmap', or `pointer',
+ depending on the target instance type and the presence of color
+ keywords.
+
+ The valid keywords and their values are
+ `: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.
+
+ `: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.
+
+ `: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 `:data' property.
+
+ `:mask-file'
+ The name of a file containing standard XBM-format data.
+ Interpreted as the clipping region for the bitmap contained
+ in the `:data' property.
+
+ `:foreground'
+ `:background'
+ These keywords allow you to explicitly specify foreground and
+ background colors. The values should be acceptable to
+ `make-color-instance'.
+
+ `:hotspot-x'
+ `: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.
+
+`gif'
+`jpeg'
+`png'
+`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.
+
+ Note that PNG is the standard format for images distributed with
+ XEmacs, so it is highly recommended that PNG support be built in.
+
+ All of these instantiators will be instanced as `color-pixmap'.
+
+ The valid keywords and their values are
+ `:data'
+ A string interpreted as the contents of a file containing
+ data in the appropriate standard format.
+
+ `:file'
+ The name of a file containing standard-format data.
+
+`cursor-font'
+ Most window systems provide a set of standard cursors, which in
+ X11 is called a cursor font. Can only be instanced as `pointer'.
+ This should probably be fixed.
+
+ The valid keyword is `:data'. Its value should be a string
+ containing one of the standard cursor-font names, such as `watch'
+ or `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 `<X11/cursorfont.h>' by most
+ distributions, minus the `XC_' prefix. For MS Windows, use
+ `mswindows-resource' instantiator format, not `cursor-font'.
+ Other window systems may have different lists.
+
+`font'
+ A glyph from a font; i.e. the name of a font, and glyph index into
+ it of the form `FONT fontname index [[mask-font] mask-index]'.
+ Only if X support was compiled into this XEmacs. Currently can
+ only be instanced as `pointer'. This should probably be fixed.
+
+`mswindows-resource'
+ An MS Windows pointer resource. Specifies a resource to retrieve
+ directly from the system (an OEM resource) or from a file,
+ particularly an executable file. Can be instanced as `pointer' or
+ `color-pixmap'.
+
+ The valid keywords and their values are
+
+ `:resource-type'
+ A string naming the type (`cursor', `bitmap', or `icon') of
+ the resource. Required.
+
+ `:file'
+ A string containing the name of the file containing the
+ resource (often an executable). If a system resource,
+ `:file' should be omitted.
+
+ `:resource-id'
+ A string containing the name of a resource. Required if
+ `:file' is not specified.
+
+ 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".
+
+`subwindow'
+ An embedded windowing system window. Can only be instanced as
+ `subwindow'. Not implemented.
+
+`button'
+ A button widget; either a push button, radio button or toggle
+ button. Can only be instanced as `widget'.
+
+`combo-box'
+ A drop list of selectable items in a widget, for editing text.
+ Can only be instanced as `widget'.
+
+`edit-field'
+ A text editing widget. Can only be instanced as `widget'.
+
+`label'
+ A static, text-only, widget; for displaying text. Can only be
+ instanced as `widget'.
+
+`layout'
+ A widget for controlling the positioning of children underneath it.
+ Through the use of nested layouts, a widget hierarchy can be
+ created which can have the appearance of any standard dialog box
+ or similar arrangement; all of this is counted as one "glyph" and
+ could appear in many of the places that expect a single glyph.
+ Can only be instanced as `widget'.
+
+`native-layout'
+ The native version of a layout widget. Can only be instanced as
+ `widget'.
+
+`progress-gauge'
+ A sliding widget, for showing progress. Can only be instanced as
+ `widget'.
+
+`tab-control'
+ A tab widget; a series of user selectable tabs. Can only be
+ instanced as `widget'.
+
+`tree-view'
+ A folding widget. Can only be instanced as `widget'.
+
+`scrollbar'
+ A scrollbar widget. Can only be instanced as `widget'.
+
+`autodetect'
+ XEmacs tries to guess what format the data is in. If X support
+ exists, the data string will be checked to see if it names a
+ filename. If so, and this filename contains XBM or XPM data, the
+ appropriate sort of pixmap or pointer will be created. [This
+ includes picking up any specified hotspot or associated mask
+ file.] Otherwise, if `pointer' is one of the allowable
+ image-instance types and the string names a valid cursor-font
+ name, the image will be created as a pointer. Otherwise, the
+ image will be displayed as text. If no X support exists, the
+ image will always be displayed as text.
+
+`inherit'
+ Inherit from the background-pixmap property of a face. Can only be
+ instanced as `mono-pixmap'.
+
+ There are two convenience variables for use with the XBM and XPM
+image formats.
+
+ -- Variable: xpm-color-symbols
+ This variable holds definitions of logical color-names used when
+ reading XPM files. Elements of this list should be of the form
+ `(COLOR-NAME FORM-TO-EVALUATE)'. The COLOR-NAME should be a
+ string, which is the name of the color to define; the
+ FORM-TO-EVALUATE should evaluate to a color specifier object, or a
+ string to be passed to `make-color-instance' (*note Colors::). If
+ a loaded XPM file references a symbolic color called COLOR-NAME,
+ it will display as the computed color instead.
+
+ The default value of this variable defines the logical color names
+ `"foreground"' and `"background"' to be the colors of the
+ `default' face.
+
+ -- Variable: x-bitmap-file-path
+ A list of the directories in which X bitmap files may be found.
+ If `nil', this is initialized from the `"*bitmapFilePath"'
+ resource. This is used by the `make-image-instance' function
+ (however, note that if the environment variable `XBMLANGPATH' is
+ set, it is consulted first).
+
+\1f
+File: lispref.info, Node: Image Instances, Prev: Image Instantiator Formats, Up: Images
+
+50.2.4 Image Instances
+----------------------
+
+Image-instance objects encapsulate the way a particular image (pixmap,
+etc.) is displayed on a particular device.
+
+ In most circumstances, you do not need to directly create image
+instances; use a glyph instead. However, it may occasionally be useful
+to explicitly create image instances, if you want more control over the
+instantiation process.
+
+ -- Function: image-instance-p object
+ This function returns non-`nil' if OBJECT is an image instance.
+
+* Menu:
+
+* Image Instance Types:: Each image instances has a particular type.
+* Image Instance Functions:: Functions for working with image instances.
+
+\1f
+File: lispref.info, Node: Image Instance Types, Next: Image Instance Functions, Up: Image Instances
- If PROPERTY is a built-in property, the specifications to be added
- to this property can be supplied in many different ways:
+50.2.4.1 Image Instance Types
+.............................
- * If 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 LOCALE (which defaults to `global' if
- omitted).
+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.
- * 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 case), and specifications will be added as given.
+ The valid image instance types are
- * If VALUE is a specifier (as would be returned by
- `glyph-property' if no 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 `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 specifications will be copied).
+`nothing'
+ Nothing is displayed.
- 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.
+`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.
- In general, it is OK to pass an instance object (e.g. as returned
- 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' 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.
+`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).
- If PROPERTY is not a built-in property, then this function will
- simply set its value if LOCALE is `nil'. However, if LOCALE is
- 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.
+`color-pixmap'
+ Displayed as a color pixmap.
- - Function: glyph-property glyph property &optional locale
- This function returns GLYPH's value of the given PROPERTY.
+`pointer'
+ Used as the mouse pointer for a window.
- If LOCALE is omitted, the GLYPH's actual value for 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.
+`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.
- If 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 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 PROPERTY is not a specifier, this value will
- simply be returned regardless of LOCALE.
+`widget'
+ An active GUI element implemented as a "widget" or "control" of the
+ underlying window system.
- 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 LOCALE is a particular locale (a buffer, window,
- 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', or `device'), 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 following functions are used to check whether an image instance
+type is valid in the running XEmacs.
- The specifications in a specifier determine what the value of
- PROPERTY will be in a particular "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 `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 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
- `glyph-property-instance' actually does all this, and is used to
- determine how to display the glyph.
+ -- Function: valid-image-instance-type-p type
+ This function returns non-`nil' if TYPE is a valid image instance
+ type.
- - Function: glyph-property-instance glyph property &optional domain
- default no-fallback
- This function returns the instance of GLYPH's PROPERTY in the
- specified DOMAIN.
+ -- Function: image-instance-type-list
+ This function returns a list of the valid image instance types.
- Under most circumstances, 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.
+ The following functions are used to determine the type of an image
+instance.
- The returned instance is an image-instance object, and you can
- query it using the appropriate image instance functions. For
- example, you could use `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).
+ -- Function: image-instance-type image-instance
+ Return the type of the given image instance. The return value
+ will be one of `nothing', `text', `mono-pixmap', `color-pixmap',
+ `pointer', `subwindow', or `widget'.
- DOMAIN defaults to the selected window if omitted.
+ -- Function: text-image-instance-p object
+ Return non-`nil' if OBJECT is an image instance of type `text'.
- 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.
+ -- Function: mono-pixmap-image-instance-p object
+ Return non-`nil' if OBJECT is an image instance of type
+ `mono-pixmap'.
- If 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 `specifier-instance'.
+ -- Function: color-pixmap-image-instance-p object
+ Return non-`nil' if OBJECT is an image instance of type
+ `color-pixmap'.
- Optional arguments DEFAULT and NO-FALLBACK are the same as in
- `specifier-instance'. *Note Specifiers::.
+ -- Function: pointer-image-instance-p object
+ Return non-`nil' if OBJECT is an image instance of type `pointer'.
- - Function: 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 `remove-specifier'. *Note
- remove-specifier-p: Specifiers, for the meaning of the LOCALE,
- TAG-SET, and EXACT-P arguments.
+ -- Function: subwindow-image-instance-p object
+ Return non-`nil' if OBJECT is an image instance of type
+ `subwindow'.
+
+ -- Function: nothing-image-instance-p object
+ Return non-`nil' if OBJECT is an image instance of type `nothing'.
+
+ -- Function: widget-image-instance-p object
+ Return non-`nil' if OBJECT is an image instance of type `widget'.
\1f
-File: lispref.info, Node: Glyph Convenience Functions, Next: Glyph Dimensions, Prev: Glyph Properties, Up: Glyph Functions
+File: lispref.info, Node: Image Instance Functions, Prev: Image Instance Types, Up: Image Instances
-Glyph Convenience Functions
----------------------------
+50.2.4.2 Image Instance 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 PROPERTY.
+ -- Function: make-image-instance data &optional domain dest-types
+ noerror
+ This function creates a new image-instance object.
- Remember that if you want to determine the "value" of a specific
-glyph property, you probably want to use the `*-instance' functions.
-For example, to determine whether a glyph contributes to its line
-height, use `glyph-contrib-p-instance', not `glyph-contrib-p'. (The
-latter will return a boolean specifier or a list of specifications, and
-you probably aren't concerned with these.)
+ DATA is an image instantiator, which describes the image (*note
+ Image Specifiers::).
- - Function: glyph-image glyph &optional locale
- This function is equivalent to calling `glyph-property' with a
- property of `image'. The return value will be an image specifier
- if LOCALE is `nil' or omitted; otherwise, it will be a
- specification or list of specifications.
+ DEST-TYPES should be a list of allowed image instance types that
+ can be generated. The DEST-TYPES list is unordered. If multiple
+ destination types are possible for a given instantiator, the "most
+ natural" type for the instantiator's format is chosen. These are
- - Function: set-glyph-image glyph spec &optional locale tag-set
- how-to-add
- This function is equivalent to calling `set-glyph-property' with a
- property of `image'.
+ `XBM'
+ `xface'
+ `mono-pixmap', then `color-pixmap', then `pointer'.
- - Function: glyph-image-instance glyph &optional domain default
- no-fallback
- This function returns the instance of GLYPH's image in the given
- DOMAIN, and is equivalent to calling `glyph-property-instance'
- with a property of `image'. The return value will be an image
- instance.
+ `XPM'
+ `GIF'
+ `JPEG'
+ `PNG'
+ `TIFF'
+ `color-pixmap', then `mono-pixmap', then `pointer'.
- Normally DOMAIN will be a window or `nil' (meaning the selected
- window), and an instance object describing how the image appears
- in that particular window and buffer will be returned.
+ `string'
+ `formatted-string formats'
+ `text', then `mono-pixmap' (not currently implemented), then
+ `color-pixmap' (not currently implemented).
- - Function: glyph-contrib-p glyph &optional locale
- This function is equivalent to calling `glyph-property' with a
- property of `contrib-p'. The return value will be a boolean
- specifier if LOCALE is `nil' or omitted; otherwise, it will be a
- specification or list of specifications.
+ `mswindows-resource'
+ For pointer resources, `pointer'.
- - Function: set-glyph-contrib-p glyph spec &optional locale tag-set
- how-to-add
- This function is equivalent to calling `set-glyph-property' with a
- property of `contrib-p'.
+ For the others, `color-pixmap'.
- - Function: glyph-contrib-p-instance glyph &optional domain default
- no-fallback
- This function returns whether the glyph contributes to its line
- height in the given DOMAIN, and is equivalent to calling
- `glyph-property-instance' with a property of `contrib-p'. The
- return value will be either `nil' or `t'. (Normally DOMAIN will be
- a window or `nil', meaning the selected window.)
+ The other formats can only be instantiated as one type.
- - Function: glyph-baseline glyph &optional locale
- This function is equivalent to calling `glyph-property' with a
- property of `baseline'. The return value will be a specifier if
- LOCALE is `nil' or omitted; otherwise, it will be a specification
- or list of specifications.
+ If you want to control more specifically the order of the types
+ into which an image is instantiated, call `make-image-instance'
+ repeatedly until it succeeds, passing less and less preferred
+ destination types each time.
+
+ If DEST-TYPES is omitted, all possible types are allowed.
+
+ DOMAIN specifies the domain to which the image instance will be
+ attached. This domain is termed the "governing domain". The type
+ of the governing domain depends on the image instantiator format.
+ (Although, more correctly, it should probably depend on the image
+ instance type.) For example, pixmap image instances are specific
+ to a device, but widget image instances are specific to a
+ particular XEmacs window because in order to display such a widget
+ when two windows onto the same buffer want to display the widget,
+ two separate underlying widgets must be created. (That's because
+ a widget is actually a child window-system window, and all
+ window-system windows have a unique existence on the screen.)
+ This means that the governing domain for a pixmap image instance
+ will be some device (most likely, the only existing device),
+ whereas the governing domain for a widget image instance will be
+ some XEmacs window.
+
+ If you specify an overly general DOMAIN (e.g. a frame when a
+ window was wanted), an error is signaled. If you specify an overly
+ specific DOMAIN (e.g. a window when a device was wanted), the
+ corresponding general domain is fetched and used instead. For
+ `make-image-instance', it makes no difference whether you specify
+ an overly specific domain or the properly general domain derived
+ from it. However, it does matter when creating an image instance
+ by instantiating a specifier or glyph (e.g. with
+ `glyph-image-instance'), because the more specific domain causes
+ spec lookup to start there and proceed to more general domains.
+ (It would also matter when creating an image instance with an
+ instantiator format of `inherit', but we currently disallow this.)
+
+ If omitted, DOMAIN defaults to the selected window.
+
+ NOERROR controls what happens when the image cannot be generated.
+ If `nil', an error message is generated. If `t', no messages are
+ generated and this function returns `nil'. If anything else, a
+ warning message is generated and this function returns `nil'.
+
+ -- Function: colorize-image-instance image-instance foreground
+ background
+ This function makes the image instance be displayed in the given
+ colors. Image instances come in two varieties: bitmaps, which are
+ 1 bit deep which are rendered in the prevailing foreground and
+ background colors; and pixmaps, which are of arbitrary depth
+ (including 1) and which have the colors explicitly specified.
+ This function converts a bitmap to a pixmap. If the image
+ instance was a pixmap already, nothing is done (and `nil' is
+ returned). Otherwise `t' is returned.
+
+ The following functions are
+
+ -- Function: image-instance-name image-instance
+ This function returns the name of the given image instance. The
+ name is typically taken from the `:file' property of the
+ instantiator if present, otherwise from the `:data' property.
+
+ -- Function: image-instance-domain image-instance
+ Return the governing domain of the given IMAGE-INSTANCE. The
+ governing domain of an image instance is the domain that the image
+ instance is specific to. It is _NOT_ necessarily the domain that
+ was given to the call to `specifier-instance' that resulted in the
+ creation of this image instance. See `make-image-instance' for
+ more information on governing domains.
+
+ -- Function: image-instance-string image-instance
+ This function returns the string of the given image instance.
+ This will only be non-`nil' for text image instances.
+
+ -- Function: image-instance-file-name image-instance
+ This function returns the file name from which IMAGE-INSTANCE was
+ read, if known.
+
+ -- Function: image-instance-mask-file-name image-instance
+ This function returns the file name from which IMAGE-INSTANCE's
+ mask was read, if known.
- - Function: set-glyph-baseline glyph spec &optional locale tag-set
- how-to-add
- This function is equivalent to calling `set-glyph-property' with a
- property of `baseline'.
+ Pixmaps are considered to be three-dimensional. The height and
+width of the pixel array that is displayed, and the color depth of its
+pixels, are accessed with these functions.
- - Function: glyph-baseline-instance glyph &optional domain default
- no-fallback
- This function returns the instance of GLYPH's baseline value in
- the given DOMAIN, and is equivalent to calling
- `glyph-property-instance' with a property of `baseline'. The
- return value will be an integer or `nil'.
+ -- Function: image-instance-depth image-instance
+ This function returns the depth of the image instance. This is 0
+ for a mono pixmap, or a positive integer for a color pixmap.
- Normally DOMAIN will be a window or `nil' (meaning the selected
- window), and an instance object describing the baseline value
- appears in that particular window and buffer will be returned.
+ -- Function: image-instance-height image-instance
+ This function returns the height of the image instance, in pixels.
- - Function: glyph-face glyph
- This function returns the face of GLYPH. (Remember, this is not a
- specifier, but a simple property.)
+ -- Function: image-instance-width image-instance
+ This function returns the width of the image instance, in pixels.
- - Function: set-glyph-face glyph face
- This function changes the face of GLYPH to FACE.
+ 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.
-\1f
-File: lispref.info, Node: Glyph Dimensions, Prev: Glyph Convenience Functions, Up: Glyph Functions
+ These functions access the coordinates of the hotspot. They simply
+return `nil' for a non-pointer image instance.
-Glyph Dimensions
-----------------
+ -- Function: image-instance-hotspot-x image-instance
+ This function returns the X coordinate of the image instance's
+ hotspot, if known.
- - Function: glyph-width glyph &optional window
- This function returns the width of GLYPH on WINDOW. This may not
- be exact as it does not take into account all of the context that
- redisplay will.
+ -- Function: image-instance-hotspot-y image-instance
+ This function returns the Y coordinate of the image instance's
+ hotspot, if known.
- - Function: glyph-ascent glyph &optional window
- This function returns the ascent value of GLYPH on WINDOW. This
- may not be exact as it does not take into account all of the
- context that redisplay will.
+ Mono pixmaps and pointers may have their foreground and background
+colors set when instanced. Use these functions to access color
+information.
- - Function: glyph-descent glyph &optional window
- This function returns the descent value of GLYPH on WINDOW. This
- may not be exact as it does not take into account all of the
- context that redisplay will.
+ -- Function: image-instance-foreground image-instance
+ This function returns the foreground color of IMAGE-INSTANCE, if
+ applicable. This will be a color instance or `nil'. (It will only
+ be non-`nil' for colorized mono pixmaps and for pointers.)
- - Function: glyph-height glyph &optional window
- This function returns the height of GLYPH on 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.
+ -- Function: image-instance-background image-instance
+ This function returns the background color of IMAGE-INSTANCE, if
+ applicable. This will be a color instance or `nil'. (It will only
+ be non-`nil' for colorized mono pixmaps and for pointers.)
\1f
-File: lispref.info, Node: Images, Next: Glyph Types, Prev: Glyph Functions, Up: Glyphs
+File: lispref.info, Node: Using Glyphs, Next: Manipulating Glyphs, Prev: Images, Up: Glyphs
+
+50.3 Using Glyphs
+=================
-Images
-======
+Glyph usage is unfortunately somewhat arcane. (For discussion of
+rationale, *Note Glyphs: (Internals)Glyphs.) 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 `edit-toolbar' and `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:
+
+*Buffer glyphs*
+ Glyphs that are inserted in a buffer may be used for their own
+ sake (for example, image display in `w3'), as an accurate
+ representation of text that can't be displayed in usual fonts
+ (equation display in `preview-latex'), or as annotations (such as
+ a marginal indication of a bookmark). Glyphs are attached to
+ buffers via extents.
+
+*Redisplay glyphs*
+ Glyphs can be used to create XEmacs-specific "fonts". For example,
+ the character that indicates truncation of lines is implemented as
+ the `truncation-glyph'. It is also possible to have XEmacs
+ display a certain character using a custom glyph, via display
+ tables.
+
+*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.
+
+*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.
+
+*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.
+
+ Some simple concrete examples showing how to insert a glyph in a
+buffer are presented later. *Note Glyph Examples::.
+
+ "Creating Glyphs" explains how to create glyphs. Creating a glyph
+using `make-glyph' does not specify _where_ the glyph will be used, it
+only specifies _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:
-* 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 `make-image-instance'.
-* Image Instances:: What an image specifier gets instanced as.
+* 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.
\1f
-File: lispref.info, Node: Image Specifiers, Next: Image Instantiator Conversion, Up: Images
+File: lispref.info, Node: Creating Glyphs, Next: Buffer Glyphs, Up: Using Glyphs
-Image Specifiers
-----------------
-
-An image specifier is used to describe the actual image of a glyph. It
-works like other specifiers (*note Specifiers::), in that it contains a
-number of specifications describing how the image should appear in a
-variety of circumstances. These specifications are called "image
-instantiators". When XEmacs wants to display the image, it instantiates
-the image into an "image instance". Image instances are their own
-primitive object type (similar to font instances and color instances),
-describing how the image appears in a particular domain. (On the other
-hand, image instantiators, which are just descriptions of how the image
-should appear, are represented using strings or vectors.)
-
- - Function: image-specifier-p object
- This function returns non-`nil' if OBJECT is an image specifier.
- Usually, an image specifier results from calling `glyph-image' on
- a glyph.
+50.3.1 Creating Glyphs
+----------------------
- - Function: make-image-specifier spec-list
- This function creates a new image specifier object and initializes
- it according to SPEC-LIST. *Note Specifiers::.
-
- Note that, in practice, you rarely, if ever, need to actually
- create an image specifier! (This function exists mainly for
- completeness.) Pretty much the only use for image specifiers is to
- control how glyphs are displayed, and the image specifier
- associated with a glyph (the `image' property of a glyph) is
- created automatically when a glyph is created and need not (and
- cannot, for that matter) ever be changed (*note Glyphs::). In
- fact, the design decision to create a separate image specifier
- type, rather than make glyphs themselves be specifiers, is
- debatable--the other properties of glyphs are rarely used and could
- conceivably have been incorporated into the glyph's instantiator.
- The rarely used glyph types (buffer, pointer, icon) could also
- have been incorporated into the instantiator.
+ -- Function: make-glyph &optional spec-list type
+ This function creates a new glyph object of type TYPE.
- 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.).
+ The optional SPEC-LIST is used to initialize the glyph's image.
+ It can be any spec-list of "image instantiator" accepted by
+ `canonicalize-spec-list', *Note Adding Specifications::. An
+ individual image instantiator may be a string, which is converted
+ to a vector according to `console-type-image-conversion-list', or a
+ vector. The vector's first element specifies the _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. *Note Image Specifiers::.
+
+ The optional TYPE specifies the type of the glyph. TYPE should be
+ one of `buffer' (used for glyphs in an extent, the modeline, the
+ toolbar, or elsewhere in a frame), `pointer' (used for the
+ mouse-pointer), or `icon' (used for a frame's icon), and defaults
+ to `buffer'.
+
+ SPEC-LIST is the initializer for the glyph's `image' property, which
+is an image specifier. (Note that "image" as used in the context of a
+glyph's `image' property or in the terms "image specifier", "image
+instantiator", or "image instance" does not refer to what people
+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 most common form of SPEC-LIST is a single image instantiator.
+(*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
+`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
+(_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, _etc_. *Note
+Specifiers::, for more information about specification formats.
+
+ As well as using SPEC-LIST to initialize the glyph, you can set
+specifications using `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 `set-specifier', `specifier-instance' or the like on
+the glyph; instead use them on `(glyph-image GLYPH)' or use the
+convenience functions `set-glyph-image', `glyph-image-instance', and
+`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 _internal_ format, which is opaque to the user.
+
+ It is extremely rare that you will ever have to specify a value for
+TYPE, which should be one of `buffer' (used for glyphs in an extent,
+the modeline, the toolbar, or elsewhere in a buffer), `pointer' (used
+for the mouse-pointer), or `icon' (used for a frame's icon), and
+defaults to `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. `text-pointer-glyph' (or in general, any
+`*-pointer-glyph') and `frame-icon-glyph'. User code should never need
+to create `pointer' or `icon' glyphs. *Note Glyph Types::.
+
+ There are a few other glyph creation functions, normally used only
+internally or at XEmacs initialization.
+
+ -- Function: make-glyph-internal &optional type
+ This function creates a new, uninitialized glyph of type TYPE.
- *Note Image Instances::, for a more detailed discussion of image
-instance types.
+ -- Function: make-pointer-glyph &optional spec-list
+ Return a new `pointer-glyph' object with the specification list
+ SPEC-LIST. This function is equivalent to calling `make-glyph'
+ with a TYPE of `pointer'.
- An image instantiator should be a string or a vector of the form
+ `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
+`set-glyph-image' on an existing glyph, e.g. `text-pointer-glyph'.
- `[FORMAT :KEYWORD VALUE ...]'
+ -- Function: make-icon-glyph &optional spec-list
+ Return a new `icon-glyph' object with the specification list
+ SPEC-LIST. This function is equivalent to calling `make-glyph'
+ with a TYPE of `icon'.
- i.e. a format symbol followed by zero or more alternating
-keyword-value pairs. The "format" field should be a symbol, one of
+ `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 `set-glyph-image' on
+the existing glyph, `frame-icon-glyph'.
-`nothing'
- Don't display anything; no keywords are valid for this. Can only
- be instanced as `nothing'.
+\1f
+File: lispref.info, Node: Buffer Glyphs, Next: Redisplay Glyphs, Prev: Creating Glyphs, Up: Using Glyphs
-`string'
- Display this image as a text string. Can only be instanced as
- `text', although support for instancing as `mono-pixmap' should be
- added.
+50.3.2 Buffer Glyphs
+--------------------
-`formatted-string'
- Display this image as a text string with replaceable fields,
- similar to a modeline format string; not currently implemented.
+Creating a glyph using `make-glyph' does not specify _where_ the glyph
+will be used, it only specifies _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 _begin-glyph_ or _end-glyph_.
+
+`buffer text'
+ To insert a glyph into a buffer, create an extent in the buffer
+ and then use `set-extent-begin-glyph' or `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.)
+
+`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 `left-margin-width' or `right-margin-width'. (Not
+ strictly necessary when using margin glyphs with layout policy
+ `whitespace'.) Follow the same procedure above for inserting a
+ glyph in a buffer, then set a non-default layout policy for the
+ glyph using `set-extent-begin-glyph-layout' or
+ `set-extent-end-glyph-layout'. Alternatively, use the high-level
+ annotations API (see `make-annotation'). (In fact, you can also
+ use the annotations API for glyphs in a buffer, by setting a
+ layout policy of `text'.)
-`xbm'
- An X bitmap; only if X support was compiled into this XEmacs. Can
- be instanced as `mono-pixmap', `color-pixmap', or `pointer'.
-`xpm'
- An XPM pixmap; only if XPM support was compiled into this XEmacs.
- Can be instanced as `color-pixmap', `mono-pixmap', or `pointer'.
- XPM is an add-on library for X that was designed to rectify the
- shortcomings of the XBM format. Most implementations of X include
- the XPM library as a standard part. If your vendor does not, it
- is highly recommended that you download it and install it. You
- can get it from the standard XEmacs FTP site, among other places.
+\1f
+File: lispref.info, Node: Redisplay Glyphs, Next: Frame Glyphs, Prev: Buffer Glyphs, Up: Using Glyphs
-`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'.
+50.3.3 Redisplay Glyphs
+-----------------------
-`gif'
- A GIF87 or GIF89 image; only if GIF support was compiled into this
- XEmacs. Can be instanced as `color-pixmap'. Note that XEmacs
- includes GIF decoding functions as a standard part of it, so if
- you have X support, you will normally have GIF support, unless you
- explicitly disable it at configure time.
+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 `set-glyph-image'. See
+`continuation-glyph', `control-arrow-glyph', `hscroll-glyph',
+`invisible-text-glyph', `octal-escape-glyph', and `truncation-glyph'.
+See also `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
+`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 `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 `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. *Note 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
+`glyph-image', and then add it to a face. *Note Face Convenience
+Functions::.
+
+ -- Glyph: truncation-glyph
+ This variable specifies what is displayed at the end of truncated
+ lines.
-`jpeg'
- A JPEG-format image; only if JPEG support was compiled into this
- XEmacs. Can be instanced as `color-pixmap'. If you have the JPEG
- libraries present on your system when XEmacs is built, XEmacs will
- automatically detect this and use them, unless you explicitly
- disable it at configure time.
+ -- Glyph: continuation-glyph
+ This variable specifies what is displayed at the end of wrapped
+ lines.
-`png'
- A PNG/GIF24 image; only if PNG support was compiled into this
- XEmacs. Can be instanced as `color-pixmap'.
+ -- Glyph: octal-escape-glyph
+ This variable specifies what to prefix character codes displayed
+ in octal with.
-`tiff'
- A TIFF-format image; only if TIFF support was compiled into this
- XEmacs.
+ -- Glyph: hscroll-glyph
+ This variable specifies what to display at the beginning of
+ horizontally scrolled lines.
-`cursor-font'
- One of the standard cursor-font names, such as `watch' or
- `right_ptr' under X. Under X, this is, more specifically, any of
- the standard cursor names from appendix B of the Xlib manual [also
- known as the file `<X11/cursorfont.h>'] minus the `XC_' prefix. On
- other window systems, the valid names will be specific to the type
- of window system. Can only be instanced as `pointer'.
+ -- Glyph: invisible-text-glyph
+ This variable specifies what to use to indicate the presence of
+ invisible text. This is the glyph that is displayed when an
+ ellipsis is called for, according to `selective-display-ellipses'
+ or `buffer-invisibility-spec'). Normally this is three dots
+ ("...").
-`font'
- A glyph from a font; i.e. the name of a font, and glyph index into
- it of the form `FONT fontname index [[mask-font] mask-index]'.
- Only if X support was compiled into this XEmacs. Currently can
- only be instanced as `pointer', although this should probably be
- fixed.
+ -- Glyph: control-arrow-glyph
+ This variable specifies what to use as an arrow for control
+ characters.
-`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'.
+\1f
+File: lispref.info, Node: Frame Glyphs, Next: External Glyphs, Prev: Redisplay Glyphs, Up: Using Glyphs
+
+50.3.4 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
+`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.
+
+`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.)
+
+`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 `default-toolbar').
+ See `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 `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, because once an image has been displayed the pixmap
+ replaces the symbol for those domains.)
+
+`gutter'
+ To insert a glyph into a gutter, use `set-extent-begin-glyph' or
+ `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
+ *Note Specifying a Gutter::. Glyphs that are frequently used in
+ this way are `tab control' and `progress bar' glyphs.
-`subwindow'
- An embedded windowing system window. Can only be instanced as
- `subwindow'.
-`button'
- A button widget; either a push button, radio button or toggle
- button. Can only be instanced as `widget'.
+\1f
+File: lispref.info, Node: External Glyphs, Next: Native GUI Widgets, Prev: Frame Glyphs, Up: Using Glyphs
-`combo-box'
- A drop list of selectable items in a widget, for editing text.
- Can only be instanced as `widget'.
+50.3.5 External Glyphs
+----------------------
-`edit-field'
- A text editing widget. Can only be instanced as `widget'.
+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 *Note Glyph Types::.
+
+ You may use a glyph as the icon for a frame. Do not create a new
+glyph; instead, change the specifications for the existing glyph
+`frame-icon-glyph' with `set-glyph-image'. This is a unique,
+predefined object. Although the natural usage is to set specifications
+for the global locale or a frame locale, you can also arrange for a
+special icon when a frame's selected window displays a particular buffer
+by using a buffer locale.
+
+ The shape of the mouse pointer when over a particular section of a
+frame is controlled using various glyph variables. Since the image of
+a glyph is a specifier, it can be controlled on a per-buffer,
+per-frame, per-window, or per-device basis.
+
+ To use a glyph as the mouse pointer, in general you do not create a
+new glyph, but rather you change the specifications of various existing
+glyphs, such as `text-pointer-glyph' for the pointer used over text,
+`modeline-pointer-glyph' for the pointer used over the modeline, etc.
+Do an apropos over `pointer-glyph' to find all of them. (Note also
+that you can temporarily set the mouse pointer to some specific shape
+by using `set-frame-pointer', which takes an image instance, as
+obtained from calling `glyph-image-instance' on a glyph of type
+`pointer' - either one of the above-mentioned variables or one you
+created yourself. (See below for what it means to create a glyph of
+type `pointer'.) This pointer will last only until the next mouse
+motion event is processed or certain other things happen, such as
+creating or deleting a window. (In fact, the above-mentioned pointer
+glyph variables are implemented as part of the default handler for
+mouse motion events. If you want to customize this behavior, take a
+look at `mode-motion-hook', or `mouse-motion-handler' if you really
+want to get low-level.)
-`label'
- A static, text-only, widget; for displaying text. Can only be
- instanced as `widget'.
+ You should use `set-glyph-image' to set the following variables,
+_not_ `setq'.
-`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'.
+ -- Glyph: text-pointer-glyph
+ This variable specifies the shape of the mouse pointer when over
+ text.
-`native-layout'
- The native version of a layout widget. Can only be instanced as
- `widget'.
+ -- Glyph: nontext-pointer-glyph
+ This variable specifies the shape of the mouse pointer when over a
+ buffer, but not over text. If unspecified in a particular domain,
+ `text-pointer-glyph' is used.
-`progress-gauge'
- A sliding widget, for showing progress. Can only be instanced as
- `widget'.
+ -- Glyph: modeline-pointer-glyph
+ This variable specifies the shape of the mouse pointer when over
+ the modeline. If unspecified in a particular domain,
+ `nontext-pointer-glyph' is used.
-`tab-control'
- A tab widget; a series of user selectable tabs. Can only be
- instanced as `widget'.
+ -- Glyph: selection-pointer-glyph
+ This variable specifies the shape of the mouse pointer when over a
+ selectable text region. If unspecified in a particular domain,
+ `text-pointer-glyph' is used.
-`tree-view'
- A folding widget. Can only be instanced as `widget'.
+ -- Glyph: gc-pointer-glyph
+ This variable specifies the shape of the mouse pointer when a
+ garbage collection is in progress. If the selected window is on a
+ window system and this glyph specifies a value (i.e. a pointer
+ image instance) in the domain of the selected window, the pointer
+ will be changed as specified during garbage collection.
+ Otherwise, a message will be printed in the echo area, as
+ controlled by `gc-message'.
-`scrollbar'
- A scrollbar widget. Can only be instanced as `widget'.
+ -- 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.
-`autodetect'
- XEmacs tries to guess what format the data is in. If X support
- exists, the data string will be checked to see if it names a
- filename. If so, and this filename contains XBM or XPM data, the
- appropriate sort of pixmap or pointer will be created. [This
- includes picking up any specified hotspot or associated mask
- file.] Otherwise, if `pointer' is one of the allowable
- image-instance types and the string names a valid cursor-font
- name, the image will be created as a pointer. Otherwise, the
- image will be displayed as text. If no X support exists, the
- image will always be displayed as text.
+ -- 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.
-`inherit'
- Inherit from the background-pixmap property of a face. Can only be
- instanced as `mono-pixmap'.
+ -- 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.
- The valid keywords are:
+ -- Glyph: toolbar-pointer-glyph
+ This variable specifies the shape of the mouse pointer when over a
+ toolbar. If unspecified in a particular domain,
+ `nontext-pointer-glyph' is used.
-`:data'
- Inline data. For most formats above, this should be a string. For
- XBM images, this should be a list of three elements: width,
- height, and a string of bit data. This keyword is not valid for
- instantiator format `nothing'.
+ Internally, these variables are implemented in
+`default-mouse-motion-handler', and thus only take effect when the
+mouse moves. That function calls `set-frame-pointer', which sets the
+current mouse pointer for a frame.
-`:file'
- Data is contained in a file. The value is the name of this file.
- If both `:data' and `:file' are specified, the image is created
- from what is specified in `:data' and the string in `:file'
- becomes the value of the `image-instance-file-name' function when
- applied to the resulting image-instance. This keyword is not
- valid for instantiator formats `nothing', `string',
- `formatted-string', `cursor-font', `font', and `autodetect'.
+ -- Function: set-frame-pointer frame image-instance
+ This function sets the mouse pointer of FRAME to the given pointer
+ image instance. You should not call this function directly. (If
+ you do, the pointer will change again the next time the mouse
+ moves.)
-`:foreground'
-`:background'
- For `xbm', `xface', `cursor-font', and `font'. These keywords
- allow you to explicitly specify foreground and background colors.
- The argument should be anything acceptable to
- `make-color-instance'. This will cause what would be a
- `mono-pixmap' to instead be colorized as a two-color color-pixmap,
- and specifies the foreground and/or background colors for a pointer
- instead of black and white.
+\1f
+File: lispref.info, Node: Native GUI Widgets, Next: Subwindows, Prev: External Glyphs, Up: Using Glyphs
-`:mask-data'
- For `xbm' and `xface'. This specifies a mask to be used with the
- bitmap. The format is a list of width, height, and bits, like for
- `:data'.
+50.3.6 Native GUI Widgets
+-------------------------
-`:mask-file'
- For `xbm' and `xface'. This specifies a file containing the mask
- data. If neither a mask file nor inline mask data is given for an
- XBM image, and the XBM image comes from a file, XEmacs will look
- for a mask file with the same name as the image file but with
- `Mask' or `msk' appended. For example, if you specify the XBM file
- `left_ptr' [usually located in `/usr/include/X11/bitmaps'], the
- associated mask file `left_ptrmsk' will automatically be picked up.
+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."
-`:hotspot-x'
-`:hotspot-y'
- For `xbm' and `xface'. These keywords specify a hotspot if the
- image is instantiated as a `pointer'. Note that if the XBM image
- file specifies a hotspot, it will automatically be picked up if no
- explicit hotspot is given.
+* Menu:
-`:color-symbols'
- Only for `xpm'. This specifies an alist that maps strings that
- specify symbolic color names to the actual color to be used for
- that symbolic color (in the form of a string or a color-specifier
- object). If this is not specified, the contents of
- `xpm-color-symbols' are used to generate the alist.
+* 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.
-`:resource-id'
- Only for `mswindows-resource'. This must be either an integer
- (which directly specifies a resource number) or a string. Valid
- strings are
+\1f
+File: lispref.info, Node: Introduction to Widgets, Next: Lisp API to Native Widgets, Up: Native GUI Widgets
- For bitmaps:
+50.3.6.1 Introduction to Native Widgets and Subwindow Glyphs
+............................................................
- "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".
+Traditionally Emacsen have hidden the GUI apparatus from the Lisp
+programmer, but in XEmacs 21.4 the ability to embed autonomous GUI
+objects, called "native widgets", in text was added to Lisp. They are
+handled as _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.
- For cursors:
+ Primitive widgets are coded in C using the underlying GUI toolkit,
+and thus are beyond the scope of the _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.
- "normal", "ibeam", "wait", "cross", "up", "sizenwse", "sizenesw",
- "sizewe", "sizens", "sizeall", and "no".
+\1f
+File: lispref.info, Node: Lisp API to Native Widgets, Next: Layouts, Prev: Introduction to Widgets, Up: Native GUI Widgets
+
+50.3.6.2 Lisp API to Native Widgets
+...................................
+
+Native widgets are manipulated as _glyphs_ (*note Glyphs::). Thus they
+are created using `make-glyph', with a format of one of the widget
+types and a `: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 (_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.
- For icons:
+\1f
+File: lispref.info, Node: Layouts, Next: Primitive Widgets, Prev: Lisp API to Native Widgets, Up: Native GUI Widgets
+
+50.3.6.3 Layouts
+................
+
+An XEmacs "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. (There are also "native
+layouts", but these are undocumented, as are their uses.)
+
+ A layout descriptor is an image instantiator, _i.e._, a vector of
+the form `[FORMAT KEY-1 VALUE-1 KEY-2 VALUE-2 ...]' with format
+`layout', and properties
+
+`:orientation'
+ Specifies the orientation of the contained array of glyphs. The
+ value must be one of the symbols `horizontal' or `vertical'.
+
+`:horizontally-justify'
+ Specifies the horizontal justification of the items in the array.
+ The value must be one of the symbols `:right', `:center', or
+ `:left'.
+
+`:vertically-justify'
+ Specifies the vertical justification of the items in the array.
+ The value must be one of the symbols `:top', `:center', or
+ `:bottom'.
+
+`:justify'
+ Specifies justification. #### not understood.
+
+`:border'
+ A glyph to place in the border. The value must be an image
+ instantiator.
+
+`:items'
+ The glyphs controlled by the layout. The value must be a list of
+ image instantiators.
+
+ Here is the specification of the search dialog widget created by
+`make-search-dialog' in the `dialog-items' library, which makes use of
+recursive layouts.
+
+ (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)))])])])
- "sample", "hand", "ques", "bang", "note", and "winlogo".
+\1f
+File: lispref.info, Node: Primitive Widgets, Prev: Layouts, Up: Native GUI Widgets
-`:resource-type'
- Only for `mswindows-resource'. This must be a symbol, either
- `cursor', `icon', or `bitmap', specifying the type of resource to
- be retrieved.
+50.3.6.4 Primitive Widgets
+..........................
-`: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.
+`button'
+ A button widget; either a push button, radio button or toggle
+ button.
- Keywords accepted as menu item specs are also accepted by widgets.
-These are `:selected', `:active', `:suffix', `:keys', `:style',
-`:filter', `:config', `:included', `:key-sequence', `:accelerator',
-`:label' and `:callback'.
+`combo-box'
+ A drop list of selectable items in a widget, for editing text.
- If instead of a vector, the instantiator is a string, it will be
-converted into a vector by looking it up according to the specs in the
-`console-type-image-conversion-list' for the console type of the domain
-(usually a window; sometimes a frame or device) over which the image is
-being instantiated.
+`edit-field'
+ A text editing widget.
- If the instantiator specifies data from a file, the data will be
-read in at the time that the instantiator is added to the image
-specifier (which may be well before the image is actually displayed),
-and the instantiator will be converted into one of the inline-data
-forms, with the filename retained using a `:file' keyword. This
-implies that the file must exist when the instantiator is added to the
-image, but does not need to exist at any other time (e.g. it may safely
-be a temporary file).
+`label'
+ A static, text-only, widget; for displaying text.
- - Function: valid-image-instantiator-format-p format &optional locale
- This function returns non-`nil' if FORMAT is a valid image
- instantiator format.
+`progress-gauge'
+ A sliding widget, for showing progress.
- If LOCALE is non-`nil' then the format is checked in that locale.
- If LOCALE is `nil' the current console is used.
+`tab-control'
+ A tab widget; a series of user selectable tabs.
- Note that the return value for many formats listed above depends on
- whether XEmacs was compiled with support for that format.
+`tree-view'
+ A folding widget.
- - Function: image-instantiator-format-list
- This function return a list of valid image-instantiator formats.
+`scrollbar'
+ A scrollbar widget. (#### Probably not the same as the scrollbar
+ controlling an Emacs window.)
- - Variable: xpm-color-symbols
- This variable holds definitions of logical color-names used when
- reading XPM files. Elements of this list should be of the form
- `(COLOR-NAME FORM-TO-EVALUATE)'. The COLOR-NAME should be a
- string, which is the name of the color to define; the
- FORM-TO-EVALUATE should evaluate to a color specifier object, or a
- string to be passed to `make-color-instance' (*note Colors::). If
- a loaded XPM file references a symbolic color called COLOR-NAME,
- it will display as the computed color instead.
+\1f
+File: lispref.info, Node: Subwindows, Prev: Native GUI Widgets, Up: Using Glyphs
- The default value of this variable defines the logical color names
- `"foreground"' and `"background"' to be the colors of the
- `default' face.
+50.3.7 Subwindows
+-----------------
- - Variable: x-bitmap-file-path
- A list of the directories in which X bitmap files may be found.
- If `nil', this is initialized from the `"*bitmapFilePath"'
- resource. This is used by the `make-image-instance' function
- (however, note that if the environment variable `XBMLANGPATH' is
- set, it is consulted first).
+Subwindows are not currently implemented.
+
+ -- Function: subwindowp object
+ This function returns non-`nil' if OBJECT is a subwindow.
\1f
-File: lispref.info, Node: Image Instantiator Conversion, Next: Image Instances, Prev: Image Specifiers, Up: Images
+File: lispref.info, Node: Manipulating Glyphs, Next: Glyph Examples, Prev: Using Glyphs, Up: Glyphs
-Image Instantiator Conversion
------------------------------
+50.4 Manipulating Glyphs
+========================
- - Function: set-console-type-image-conversion-list console-type list
- This function sets the image-conversion-list for consoles of the
- given CONSOLE-TYPE. The image-conversion-list specifies how image
- instantiators that are strings should be interpreted. Each
- element of the list should be a list of two elements (a regular
- expression string and a vector) or a list of three elements (the
- preceding two plus an integer index into the vector). The string
- is converted to the vector associated with the first matching
- regular expression. If a vector index is specified, the string
- itself is substituted into that position in the vector.
+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 `buffer'.
- 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.
+* Menu:
- - Function: console-type-image-conversion-list console-type
- This function returns the image-conversion-list for consoles of
- the given CONSOLE-TYPE.
+* 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.
\1f
-File: lispref.info, Node: Image Instances, Prev: Image Instantiator Conversion, Up: Images
+File: lispref.info, Node: Glyph Properties, Next: Glyph Convenience Functions, Up: Manipulating Glyphs
-Image Instances
----------------
+50.4.1 Glyph Properties
+-----------------------
-Image-instance objects encapsulate the way a particular image (pixmap,
-etc.) is displayed on a particular device.
+Each glyph has a list of properties, which control all of the aspects of
+the glyph's appearance. The following symbols have predefined meanings:
- 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.
+`image'
+ The image used to display the glyph.
- - Function: image-instance-p object
- This function returns non-`nil' if OBJECT is an image instance.
+`baseline'
+ Percent above baseline that glyph is to be displayed. Only for
+ glyphs displayed inside of a buffer.
-* Menu:
+`contrib-p'
+ Whether the glyph contributes to the height of the line it's on.
+ Only for glyphs displayed inside of a buffer.
-* Image Instance Types:: Each image instances has a particular type.
-* Image Instance Functions:: Functions for working with image instances.
+`face'
+ Face of this glyph (_not_ a specifier).
-\1f
-File: lispref.info, Node: Image Instance Types, Next: Image Instance Functions, Up: Image Instances
+ -- Function: set-glyph-property glyph property value &optional locale
+ tag-set how-to-add
+ This function changes a property of a GLYPH.
-Image Instance Types
-....................
+ 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.
-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.
+ If PROPERTY is a built-in property, the specifications to be added
+ to this property can be supplied in many different ways:
- The valid image instance types are
+ * If 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 LOCALE (which defaults to `global' if
+ omitted).
-`nothing'
- Nothing is displayed.
+ * 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 case), and specifications will be added as given.
-`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.
+ * If VALUE is a specifier (as would be returned by
+ `glyph-property' if no 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 `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 specifications will be copied).
-`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).
+ 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.
-`color-pixmap'
- Displayed as a color pixmap.
+ In general, it is OK to pass an instance object (e.g. as returned
+ 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' 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.
-`pointer'
- Used as the mouse pointer for a window.
+ If PROPERTY is not a built-in property, then this function will
+ simply set its value if LOCALE is `nil'. However, if LOCALE is
+ 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.
-`subwindow'
- A child window that is treated as an image. This allows (e.g.)
- another program to be responsible for drawing into the window.
- Not currently implemented.
+ -- Function: glyph-property glyph property &optional locale
+ This function returns GLYPH's value of the given PROPERTY.
- - Function: valid-image-instance-type-p type
- This function returns non-`nil' if TYPE is a valid image instance
- type.
+ If LOCALE is omitted, the GLYPH's actual value for 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.
- - Function: image-instance-type-list
- This function returns a list of the valid image instance types.
+ If 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 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 PROPERTY is not a specifier, this value will
+ simply be returned regardless of 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 LOCALE is a particular locale (a buffer, window,
+ 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', or `device'), 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
+ PROPERTY will be in a particular "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 `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 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
+ `glyph-property-instance' actually does all this, and is used to
+ determine how to display the glyph.
- - Function: image-instance-type image-instance
- This function returns the type of the given image instance. The
- return value will be one of `nothing', `text', `mono-pixmap',
- `color-pixmap', `pointer', or `subwindow'.
+ -- Function: glyph-property-instance glyph property &optional domain
+ default no-fallback
+ This function returns the instance of GLYPH's PROPERTY in the
+ specified DOMAIN.
- - Function: text-image-instance-p object
- This function returns non-`nil' if OBJECT is an image instance of
- type `text'.
+ Under most circumstances, 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.
- - Function: mono-pixmap-image-instance-p object
- This function returns non-`nil' if OBJECT is an image instance of
- type `mono-pixmap'.
+ The returned instance is an image-instance object, and you can
+ query it using the appropriate image instance functions. For
+ example, you could use `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).
- - Function: color-pixmap-image-instance-p object
- This function returns non-`nil' if OBJECT is an image instance of
- type `color-pixmap'.
+ DOMAIN defaults to the selected window if omitted.
- - Function: pointer-image-instance-p object
- This function returns non-`nil' if OBJECT is an image instance of
- type `pointer'.
+ 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.
- - Function: subwindow-image-instance-p object
- This function returns non-`nil' if OBJECT is an image instance of
- type `subwindow'.
+ If 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 `specifier-instance'.
- - Function: nothing-image-instance-p object
- This function returns non-`nil' if OBJECT is an image instance of
- type `nothing'.
+ Optional arguments DEFAULT and NO-FALLBACK are the same as in
+ `specifier-instance'. *Note Specifiers::.
- - Function: widget-image-instance-p object
- Return `t' if OBJECT is an image instance of type `widget'.
+ -- Function: 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 `remove-specifier'. *Note
+ remove-specifier-p: Specifiers, for the meaning of the LOCALE,
+ TAG-SET, and EXACT-P arguments.
\1f
-File: lispref.info, Node: Image Instance Functions, Prev: Image Instance Types, Up: Image Instances
+File: lispref.info, Node: Glyph Convenience Functions, Next: Glyph Dimensions, Prev: Glyph Properties, Up: Manipulating Glyphs
-Image Instance Functions
-........................
+50.4.2 Glyph Convenience Functions
+----------------------------------
- - Function: make-image-instance data &optional domain dest-types
- noerror
- This function creates a new image-instance object.
+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 PROPERTY.
- DATA is an image instantiator, which describes the image (*note
- Image Specifiers::).
+ Remember that if you want to determine the "value" of a specific
+glyph property, you probably want to use the `*-instance' functions.
+For example, to determine whether a glyph contributes to its line
+height, use `glyph-contrib-p-instance', not `glyph-contrib-p'. (The
+latter will return a boolean specifier or a list of specifications, and
+you probably aren't concerned with these.)
- DEST-TYPES should be a list of allowed image instance types that
- can be generated. The DEST-TYPES list is unordered. If multiple
- destination types are possible for a given instantiator, the "most
- natural" type for the instantiator's format is chosen. (For XBM,
- the most natural types are `mono-pixmap', followed by
- `color-pixmap', followed by `pointer'. For the other normal image
- formats, the most natural types are `color-pixmap', followed by
- `mono-pixmap', followed by `pointer'. For the string and
- formatted-string formats, the most natural types are `text',
- followed by `mono-pixmap' (not currently implemented), followed by
- `color-pixmap' (not currently implemented). For MS Windows
- resources, the most natural type for pointer resources is
- `pointer', and for the others it's `color-pixmap'. The other
- formats can only be instantiated as one type. (If you want to
- control more specifically the order of the types into which an
- image is instantiated, just call `make-image-instance' repeatedly
- until it succeeds, passing less and less preferred destination
- types each time.
+ -- Function: glyph-image glyph &optional locale
+ This function is equivalent to calling `glyph-property' with a
+ property of `image'. The return value will be an image specifier
+ if LOCALE is `nil' or omitted; otherwise, it will be a
+ specification or list of specifications.
- If DEST-TYPES is omitted, all possible types are allowed.
+ -- Function: set-glyph-image glyph spec &optional locale tag-set
+ how-to-add
+ This function is equivalent to calling `set-glyph-property' with a
+ property of `image'.
- DOMAIN specifies the domain to which the image instance will be
- attached. This domain is termed the "governing domain". The type
- of the governing domain depends on the image instantiator format.
- (Although, more correctly, it should probably depend on the image
- instance type.) For example, pixmap image instances are specific
- to a device, but widget image instances are specific to a
- particular XEmacs window because in order to display such a widget
- when two windows onto the same buffer want to display the widget,
- two separate underlying widgets must be created. (That's because a
- widget is actually a child window-system window, and all
- window-system windows have a unique existence on the screen.) This
- means that the governing domain for a pixmap image instance will
- be some device (most likely, the only existing device), whereas
- the governing domain for a widget image instance will be some
- XEmacs window.
+ -- Function: glyph-image-instance glyph &optional domain default
+ no-fallback
+ This function returns the instance of GLYPH's image in the given
+ DOMAIN, and is equivalent to calling `glyph-property-instance'
+ with a property of `image'. The return value will be an image
+ instance.
- If you specify an overly general DOMAIN (e.g. a frame when a
- window was wanted), an error is signaled. If you specify an overly
- specific DOMAIN (e.g. a window when a device was wanted), the
- corresponding general domain is fetched and used instead. For
- `make-image-instance', it makes no difference whether you specify
- an overly specific domain or the properly general domain derived
- from it. However, it does matter when creating an image instance
- by instantiating a specifier or glyph (e.g. with
- `glyph-image-instance'), because the more specific domain causes
- spec lookup to start there and proceed to more general domains. (It
- would also matter when creating an image instance with an
- instantiator format of `inherit', but we currently disallow this.
- #### We should fix this.) n If omitted, DOMAIN defaults to the
- selected window.
+ Normally DOMAIN will be a window or `nil' (meaning the selected
+ window), and an instance object describing how the image appears
+ in that particular window and buffer will be returned.
- NOERROR controls what happens when the image cannot be generated.
- If `nil', an error message is generated. If `t', no messages are
- generated and this function returns `nil'. If anything else, a
- warning message is generated and this function returns `nil'.
+ -- Function: glyph-contrib-p glyph &optional locale
+ This function is equivalent to calling `glyph-property' with a
+ property of `contrib-p'. The return value will be a boolean
+ specifier if LOCALE is `nil' or omitted; otherwise, it will be a
+ specification or list of specifications.
- - Function: colorize-image-instance image-instance foreground
- background
- This function makes the image instance be displayed in the given
- colors. Image instances come in two varieties: bitmaps, which are
- 1 bit deep which are rendered in the prevailing foreground and
- background colors; and pixmaps, which are of arbitrary depth
- (including 1) and which have the colors explicitly specified.
- This function converts a bitmap to a pixmap. If the image
- instance was a pixmap already, nothing is done (and `nil' is
- returned). Otherwise `t' is returned.
+ -- Function: set-glyph-contrib-p glyph spec &optional locale tag-set
+ how-to-add
+ This function is equivalent to calling `set-glyph-property' with a
+ property of `contrib-p'.
- - Function: image-instance-name image-instance
- This function returns the name of the given image instance.
+ -- Function: glyph-contrib-p-instance glyph &optional domain default
+ no-fallback
+ This function returns whether the glyph contributes to its line
+ height in the given DOMAIN, and is equivalent to calling
+ `glyph-property-instance' with a property of `contrib-p'. The
+ return value will be either `nil' or `t'. (Normally DOMAIN will be
+ a window or `nil', meaning the selected window.)
- - Function: image-instance-domain image-instance
- Return the governing domain of the given IMAGE-INSTANCE. The
- governing domain of an image instance is the domain that the image
- instance is specific to. It is _NOT_ necessarily the domain that
- was given to the call to `specifier-instance' that resulted in the
- creation of this image instance. See `make-image-instance' for
- more information on governing domains.
+ -- Function: glyph-baseline glyph &optional locale
+ This function is equivalent to calling `glyph-property' with a
+ property of `baseline'. The return value will be a specifier if
+ LOCALE is `nil' or omitted; otherwise, it will be a specification
+ or list of specifications.
- - Function: image-instance-string image-instance
- This function returns the string of the given image instance.
- This will only be non-`nil' for text image instances.
+ -- Function: set-glyph-baseline glyph spec &optional locale tag-set
+ how-to-add
+ This function is equivalent to calling `set-glyph-property' with a
+ property of `baseline'.
- - Function: image-instance-file-name image-instance
- This function returns the file name from which IMAGE-INSTANCE was
- read, if known.
+ -- Function: glyph-baseline-instance glyph &optional domain default
+ no-fallback
+ This function returns the instance of GLYPH's baseline value in
+ the given DOMAIN, and is equivalent to calling
+ `glyph-property-instance' with a property of `baseline'. The
+ return value will be an integer or `nil'.
- - Function: image-instance-mask-file-name image-instance
- This function returns the file name from which IMAGE-INSTANCE's
- mask was read, if known.
+ Normally DOMAIN will be a window or `nil' (meaning the selected
+ window), and an instance object describing the baseline value
+ appears in that particular window and buffer will be returned.
- - Function: image-instance-depth image-instance
- This function returns the depth of the image instance. This is 0
- for a mono pixmap, or a positive integer for a color pixmap.
+ -- Function: glyph-face glyph
+ This function returns the face of GLYPH. (Remember, this is not a
+ specifier, but a simple property.)
- - Function: image-instance-height image-instance
- This function returns the height of the image instance, in pixels.
+ -- Function: set-glyph-face glyph face
+ This function changes the face of GLYPH to FACE.
- - Function: image-instance-width image-instance
- This function returns the width of the image instance, in pixels.
+\1f
+File: lispref.info, Node: Glyph Dimensions, Next: Glyph Types, Prev: Glyph Convenience Functions, Up: Manipulating Glyphs
- - Function: image-instance-hotspot-x image-instance
- This function returns the X coordinate of the image instance's
- hotspot, if known. This is a point relative to the origin of the
- pixmap. When an image is used as a mouse pointer, the hotspot is
- the point on the image that sits over the location that the
- pointer points to. This is, for example, the tip of the arrow or
- the center of the crosshairs.
+50.4.3 Glyph Dimensions
+-----------------------
- This will always be `nil' for a non-pointer image instance.
+ -- Function: glyph-width glyph &optional window
+ This function returns the width of GLYPH on WINDOW. This may not
+ be exact as it does not take into account all of the context that
+ redisplay will.
- - Function: image-instance-hotspot-y image-instance
- This function returns the Y coordinate of the image instance's
- hotspot, if known.
+ -- Function: glyph-ascent glyph &optional window
+ This function returns the ascent value of GLYPH on WINDOW. This
+ may not be exact as it does not take into account all of the
+ context that redisplay will.
- - Function: image-instance-foreground image-instance
- This function returns the foreground color of IMAGE-INSTANCE, if
- applicable. This will be a color instance or `nil'. (It will only
- be non-`nil' for colorized mono pixmaps and for pointers.)
+ -- Function: glyph-descent glyph &optional window
+ This function returns the descent value of GLYPH on WINDOW. This
+ may not be exact as it does not take into account all of the
+ context that redisplay will.
- - Function: image-instance-background image-instance
- This function returns the background color of IMAGE-INSTANCE, if
- applicable. This will be a color instance or `nil'. (It will only
- be non-`nil' for colorized mono pixmaps and for pointers.)
+ -- Function: glyph-height glyph &optional window
+ This function returns the height of GLYPH on 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.
\1f
-File: lispref.info, Node: Glyph Types, Next: Mouse Pointer, Prev: Images, Up: Glyphs
+File: lispref.info, Node: Glyph Types, Prev: Glyph Dimensions, Up: Manipulating Glyphs
-Glyph Types
-===========
+50.4.4 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
iconified. Their image can be instantiated as `mono-pixmap' and
`color-pixmap'.
- - Function: glyph-type glyph
+ -- Function: glyph-type glyph
This function returns the type of the given glyph. The return
value will be a symbol, one of `buffer', `pointer', or `icon'.
- - Function: valid-glyph-type-p glyph-type
+ -- Function: valid-glyph-type-p glyph-type
Given a GLYPH-TYPE, this function returns non-`nil' if it is valid.
- - Function: glyph-type-list
+ -- Function: glyph-type-list
This function returns a list of valid glyph types.
- - Function: buffer-glyph-p object
+ -- Function: buffer-glyph-p object
This function returns non-`nil' if OBJECT is a glyph of type
`buffer'.
- - Function: icon-glyph-p object
+ -- Function: icon-glyph-p object
This function returns non-`nil' if OBJECT is a glyph of type
`icon'.
- - Function: pointer-glyph-p object
+ -- Function: pointer-glyph-p object
This function returns non-`nil' if OBJECT is a glyph of type
`pointer'.
\1f
-File: lispref.info, Node: Mouse Pointer, Next: Redisplay Glyphs, Prev: Glyph Types, Up: Glyphs
-
-Mouse Pointer
-=============
-
-The shape of the mouse pointer when over a particular section of a frame
-is controlled using various glyph variables. Since the image of a glyph
-is a specifier, it can be controlled on a per-buffer, per-frame,
-per-window, or per-device basis.
-
- You should use `set-glyph-image' to set the following variables,
-_not_ `setq'.
-
- - Glyph: text-pointer-glyph
- This variable specifies the shape of the mouse pointer when over
- text.
-
- - Glyph: nontext-pointer-glyph
- This variable specifies the shape of the mouse pointer when over a
- buffer, but not over text. If unspecified in a particular domain,
- `text-pointer-glyph' is used.
-
- - Glyph: modeline-pointer-glyph
- This variable specifies the shape of the mouse pointer when over
- the modeline. If unspecified in a particular domain,
- `nontext-pointer-glyph' is used.
-
- - Glyph: selection-pointer-glyph
- This variable specifies the shape of the mouse pointer when over a
- selectable text region. If unspecified in a particular domain,
- `text-pointer-glyph' is used.
-
- - Glyph: gc-pointer-glyph
- This variable specifies the shape of the mouse pointer when a
- garbage collection is in progress. If the selected window is on a
- window system and this glyph specifies a value (i.e. a pointer
- image instance) in the domain of the selected window, the pointer
- will be changed as specified during garbage collection.
- Otherwise, a message will be printed in the echo area, as
- controlled by `gc-message'.
-
- - Glyph: busy-pointer-glyph
- This variable specifies the shape of the mouse pointer when XEmacs
- is busy. If unspecified in a particular domain, the pointer is
- not changed when XEmacs is busy.
-
- - Glyph: menubar-pointer-glyph
- This variable specifies the shape of the mouse pointer when over
- the menubar. If unspecified in a particular domain, the
- window-system-provided default pointer is used.
-
- - Glyph: scrollbar-pointer-glyph
- This variable specifies the shape of the mouse pointer when over a
- scrollbar. If unspecified in a particular domain, the
- window-system-provided default pointer is used.
-
- - Glyph: toolbar-pointer-glyph
- This variable specifies the shape of the mouse pointer when over a
- toolbar. If unspecified in a particular domain,
- `nontext-pointer-glyph' is used.
-
- Internally, these variables are implemented in
-`default-mouse-motion-handler', and thus only take effect when the
-mouse moves. That function calls `set-frame-pointer', which sets the
-current mouse pointer for a frame.
-
- - Function: set-frame-pointer frame image-instance
- This function sets the mouse pointer of FRAME to the given pointer
- image instance. You should not call this function directly. (If
- you do, the pointer will change again the next time the mouse
- moves.)
-
-\1f
-File: lispref.info, Node: Redisplay Glyphs, Next: Subwindows, Prev: Mouse Pointer, Up: Glyphs
-
-Redisplay Glyphs
-================
-
- - Glyph: truncation-glyph
- This variable specifies what is displayed at the end of truncated
- lines.
-
- - Glyph: continuation-glyph
- This variable specifies what is displayed at the end of wrapped
- lines.
-
- - Glyph: octal-escape-glyph
- This variable specifies what to prefix character codes displayed
- in octal with.
-
- - Glyph: hscroll-glyph
- This variable specifies what to display at the beginning of
- horizontally scrolled lines.
-
- - Glyph: invisible-text-glyph
- This variable specifies what to use to indicate the presence of
- invisible text. This is the glyph that is displayed when an
- ellipsis is called for, according to `selective-display-ellipses'
- or `buffer-invisibility-spec'). Normally this is three dots
- ("...").
-
- - Glyph: control-arrow-glyph
- This variable specifies what to use as an arrow for control
- characters.
-
-\1f
-File: lispref.info, Node: Subwindows, Next: Glyph Examples, Prev: Redisplay Glyphs, Up: Glyphs
-
-Subwindows
-==========
-
-Subwindows are not currently implemented.
-
- - Function: subwindowp object
- This function returns non-`nil' if OBJECT is a subwindow.
-
-\1f
-File: lispref.info, Node: Glyph Examples, Prev: Subwindows, Up: Glyphs
+File: lispref.info, Node: Glyph Examples, Prev: Manipulating Glyphs, Up: Glyphs
-Glyph Examples
-==============
+50.5 Glyph Examples
+===================
For many applications, displaying graphics is a simple process: you
create a glyph, and then you insert it into a buffer.
;; Display the glyph by storing it as the extent's "begin-glyph".
(set-extent-property extent 'begin-glyph gl)
))
-
+
;; You can then use this function like:
(insert-glyph (make-glyph [jpeg :file "/tmp/file1.jpg"]))
;; This will insert the glyph at point.
-
+
;; Here's an example of how to insert two glyphs side-by-side, at point
;; (using the above code):
(progn
\1f
File: lispref.info, Node: Annotations, Next: Display, Prev: Glyphs, Up: Top
-Annotations
-***********
+51 Annotations
+**************
An "annotation" is a pixmap or string that is not part of a buffer's
text but is displayed next to a particular location in a buffer.
\1f
File: lispref.info, Node: Annotation Basics, Next: Annotation Primitives, Up: Annotations
-Annotation Basics
-=================
+51.1 Annotation Basics
+======================
Marginal annotations are notes associated with a particular location in
a buffer. They may be displayed in a margin created on the left-hand or
\1f
File: lispref.info, Node: Annotation Primitives, Next: Annotation Properties, Prev: Annotation Basics, Up: Annotations
-Annotation Primitives
-=====================
+51.2 Annotation Primitives
+==========================
- - Function: make-annotation glyph &optional position layout buffer
+ -- Function: make-annotation glyph &optional position layout buffer
with-event d-glyph rightp
This function creates a marginal annotation at position POSITION in
BUFFER. The annotation is displayed using GLYPH, which should be
The newly created annotation is returned.
- - Function: delete-annotation annotation
+ -- Function: delete-annotation annotation
This function removes ANNOTATION from its buffer. This does not
modify the buffer text.
- - Function: annotationp annotation
+ -- Function: annotationp annotation
This function returns `t' if ANNOTATION is an annotation, `nil'
otherwise.
\1f
File: lispref.info, Node: Annotation Properties, Next: Margin Primitives, Prev: Annotation Primitives, Up: Annotations
-Annotation Properties
-=====================
+51.3 Annotation Properties
+==========================
- - Function: annotation-glyph annotation
+ -- Function: annotation-glyph annotation
This function returns the glyph object used to display ANNOTATION.
- - Function: set-annotation-glyph annotation glyph &optional layout side
+ -- Function: set-annotation-glyph annotation glyph &optional layout
+ side
This function sets the glyph of ANNOTATION to GLYPH, which should
be a glyph object. If LAYOUT is non-`nil', set the layout policy
of ANNOTATION to LAYOUT. If SIDE is `left' or `right', change the
side of the buffer at which the annotation is displayed to the
given side. The new value of `annotation-glyph' is returned.
- - Function: annotation-down-glyph annotation
+ -- Function: annotation-down-glyph annotation
This function returns the glyph used to display ANNOTATION when
the left mouse button is depressed on the annotation.
- - Function: set-annotation-down-glyph annotation glyph
+ -- Function: set-annotation-down-glyph annotation glyph
This function returns the glyph used to display ANNOTATION when
the left mouse button is depressed on the annotation to GLYPH,
which should be a glyph object.
- - Function: annotation-face annotation
+ -- Function: annotation-face annotation
This function returns the face associated with ANNOTATION.
- - Function: set-annotation-face annotation face
+ -- Function: set-annotation-face annotation face
This function sets the face associated with ANNOTATION to FACE.
- - Function: annotation-layout annotation
+ -- Function: annotation-layout annotation
This function returns the layout policy of ANNOTATION.
- - Function: set-annotation-layout annotation layout
+ -- Function: set-annotation-layout annotation layout
This function sets the layout policy of ANNOTATION to LAYOUT.
- - Function: annotation-side annotation
+ -- Function: annotation-side annotation
This function returns the side of the buffer that ANNOTATION is
displayed on. Return value is a symbol, either `left' or `right'.
- - Function: annotation-data annotation
+ -- Function: annotation-data annotation
This function returns the data associated with ANNOTATION.
- - Function: set-annotation-data annotation data
+ -- Function: set-annotation-data annotation data
This function sets the data field of ANNOTATION to DATA. DATA is
returned.
- - Function: annotation-action annotation
+ -- Function: annotation-action annotation
This function returns the action associated with ANNOTATION.
- - Function: set-annotation-action annotation action
+ -- Function: set-annotation-action annotation action
This function sets the action field of ANNOTATION to ACTION.
ACTION is returned..
- - Function: annotation-menu annotation
+ -- Function: annotation-menu annotation
This function returns the menu associated with ANNOTATION.
- - Function: set-annotation-menu annotation menu
+ -- Function: set-annotation-menu annotation menu
This function sets the menu associated with ANNOTATION to MENU.
This menu will be displayed when the right mouse button is pressed
over the annotation.
- - Function: annotation-visible annotation
+ -- Function: annotation-visible annotation
This function returns `t' if there is enough available space to
display ANNOTATION, `nil' otherwise.
- - Function: annotation-width annotation
+ -- Function: annotation-width annotation
This function returns the width of ANNOTATION in pixels.
- - Function: hide-annotation annotation
+ -- Function: hide-annotation annotation
This function removes ANNOTATION's glyph, making it invisible.
- - Function: reveal-annotation annotation
+ -- Function: reveal-annotation annotation
This function restores ANNOTATION's glyph, making it visible.
\1f
File: lispref.info, Node: Locating Annotations, Next: Annotation Hooks, Prev: Margin Primitives, Up: Annotations
-Locating Annotations
-====================
+51.4 Locating Annotations
+=========================
- - Function: annotations-in-region start end buffer
+ -- Function: annotations-in-region start end buffer
This function returns a list of all annotations in BUFFER which
are between START and END inclusively.
- - Function: annotations-at &optional position buffer
+ -- Function: annotations-at &optional position buffer
This function returns a list of all annotations at POSITION in
BUFFER. If POSITION is `nil' point is used. If BUFFER is `nil'
the current buffer is used.
- - Function: annotation-list &optional buffer
+ -- Function: annotation-list &optional buffer
This function returns a list of all annotations in BUFFER. If
BUFFER is `nil', the current buffer is used.
- - Function: all-annotations
+ -- Function: all-annotations
This function returns a list of all annotations in all buffers in
existence.
\1f
File: lispref.info, Node: Margin Primitives, Next: Locating Annotations, Prev: Annotation Properties, Up: Annotations
-Margin Primitives
-=================
+51.5 Margin Primitives
+======================
The margin widths are controllable on a buffer-local, window-local,
frame-local, device-local, or device-type-local basis through the use
of specifiers. *Note Specifiers::.
- - Specifier: left-margin-width
+ -- Specifier: left-margin-width
This is a specifier variable controlling the width of the left
outside margin, in characters. Use `set-specifier' to change its
value.
- - Specifier: right-margin-width
+ -- Specifier: right-margin-width
This is a specifier variable controlling the width of the right
outside margin, in characters. Use `set-specifier' to change its
value.
- - Specifier: use-left-overflow
+ -- Specifier: use-left-overflow
If non-`nil', use the left outside margin as extra whitespace when
displaying `whitespace' and `inside-margin' annotations. Defaults
to `nil'. This is a specifier variable; use `set-specifier' to
change its value.
- - Specifier: use-right-overflow
+ -- Specifier: use-right-overflow
If non-`nil', use the right outside margin as extra whitespace when
displaying `whitespace' and `inside-margin' annotations. Defaults
to `nil'. This is a specifier variable; use `set-specifier' to
change its value.
- - Function: window-left-margin-pixel-width &optional window
+ -- Function: window-left-margin-pixel-width &optional window
This function returns the width in pixels of the left outside
margin of WINDOW. If WINDOW is `nil', the selected window is
assumed.
- - Function: window-right-margin-pixel-width &optional window
+ -- Function: window-right-margin-pixel-width &optional window
This function returns the width in pixels of the right outside
margin of WINDOW. If WINDOW is `nil', the selected window is
assumed.
\1f
File: lispref.info, Node: Annotation Hooks, Prev: Locating Annotations, Up: Annotations
-Annotation Hooks
-================
+51.6 Annotation Hooks
+=====================
The following three hooks are provided for use with the marginal
annotations:
\1f
File: lispref.info, Node: Display, Next: Hash Tables, Prev: Annotations, Up: Top
-Emacs Display
-*************
+52 Emacs Display
+****************
This chapter describes a number of other features related to the display
that XEmacs presents to the user.
\1f
File: lispref.info, Node: Refresh Screen, Next: Truncation, Up: Display
-Refreshing the Screen
-=====================
+52.1 Refreshing the Screen
+==========================
The function `redraw-frame' redisplays the entire contents of a given
frame. *Note Frames::.
- - Function: redraw-frame &optional frame no-preempt
+ -- Function: redraw-frame &optional frame no-preempt
This function clears and redisplays frame FRAME.
FRAME defaults to the selected frame if omitted.
Even more powerful is `redraw-display':
- - Command: redraw-display &optional device
+ -- Command: redraw-display &optional device
This function redraws all frames on DEVICE marked as having their
image garbled. DEVICE defaults to the selected device. If DEVICE
is `t', all devices will have their frames checked.
using such a terminal, you might want to inhibit the redisplay on
resumption. *Note Suspending XEmacs::.
- - Variable: no-redraw-on-reenter
+ -- Variable: no-redraw-on-reenter
This variable controls whether XEmacs redraws the entire screen
after it has been suspended and resumed. Non-`nil' means yes,
`nil' means no.
`next-event' or `sit-for' is called; however, a display update will not
occur if there is input pending. *Note Command Loop::.
- - Function: force-cursor-redisplay &optional frame
+ -- Function: force-cursor-redisplay &optional frame
This function causes an immediate update of the cursor on FRAME,
which defaults to the selected frame.
\1f
File: lispref.info, Node: Truncation, Next: The Echo Area, Prev: Refresh Screen, Up: Display
-Truncation
-==========
+52.2 Truncation
+===============
When a line of text extends beyond the right edge of a window, the line
can either be truncated or continued on the next line. When a line is
line precisely at the right margin, not at a word boundary. *Note
Filling::.
- - User Option: truncate-lines
+ -- User Option: truncate-lines
This buffer-local variable controls how XEmacs displays lines that
extend beyond the right edge of the window. If it is non-`nil',
then XEmacs does not display continuation lines; rather each line
then truncation is always used for side-by-side windows (within one
frame) regardless of the value of `truncate-lines'.
- - User Option: default-truncate-lines
+ -- User Option: default-truncate-lines
This variable is the default value for `truncate-lines', for
buffers that do not have local values for it.
- - User Option: truncate-partial-width-windows
+ -- User Option: truncate-partial-width-windows
This variable controls display of lines that extend beyond the
right edge of the window, in side-by-side windows (*note Splitting
Windows::). If it is non-`nil', these lines are truncated;
\1f
File: lispref.info, Node: The Echo Area, Next: Warnings, Prev: Truncation, Up: Display
-The Echo Area
-=============
+52.3 The Echo Area
+==================
The "echo area" is used for displaying messages made with the `message'
primitive, and for echoing keystrokes. It is not the same as the
functions with `t' as the stream (*note Output Functions::), or as
follows:
- - Function: message string &rest arguments
+ -- Function: message string &rest arguments
This function displays a one-line message in the echo area. The
argument STRING is similar to a C language `printf' control
string. See `format' in *Note String Conversion::, for the details
(minibuffer-depth))
-| Minibuffer depth is 0.
=> "Minibuffer depth is 0."
-
+
---------- Echo Area ----------
Minibuffer depth is 0.
---------- Echo Area ----------
programs may access these messages, or remove them as appropriate, via
the message stack.
- - Function: display-message label message &optional frame stdout-p
+ -- Function: display-message label message &optional frame stdout-p
This function displays MESSAGE (a string) labeled as LABEL, as
described above.
(display-message 'command "Mark set")
- - Function: lmessage label string &rest arguments
+ -- Function: lmessage label string &rest arguments
This function displays a message STRING with label LABEL. It is
similar to `message' in that it accepts a `printf'-like strings
and any number of arguments.
;; Display a command message.
(lmessage 'command "Comment column set to %d" comment-column)
-
+
;; Display a progress message.
(lmessage 'progress "Fontifying %s... (%d)" buffer percentage)
-
+
;; Display a message that should not be logged.
(lmessage 'no-log "Done")
- - Function: clear-message &optional label frame stdout-p no-restore
+ -- Function: clear-message &optional label frame stdout-p no-restore
This function remove any message with the given LABEL from the
message-stack, erasing it from the echo area if it's currently
displayed there.
Unless you need the return value or you need to specify a label,
you should just use `(message nil)'.
- - Function: current-message &optional frame
+ -- Function: current-message &optional frame
This function returns the current message in the echo area, or
`nil'. The FRAME argument is currently unused.
the ` *Message-Log*' buffer. Exactly which messages will be recorded
can be tuned using the following variables.
- - User Option: log-message-max-size
+ -- User Option: log-message-max-size
This variable specifies the maximum size of the ` *Message-log*'
buffer.
- - Variable: log-message-ignore-labels
+ -- Variable: log-message-ignore-labels
This variable specifies the labels whose messages will not be
logged. It should be a list of symbols.
- - Variable: log-message-ignore-regexps
+ -- Variable: log-message-ignore-regexps
This variable specifies the regular expressions matching messages
that will not be logged. It should be a list of regular
expressions.
ignored should label them with `progress', `prompt', or `no-log',
so they can be filtered by `log-message-ignore-labels'.
- - Variable: echo-keystrokes
+ -- Variable: echo-keystrokes
This variable determines how much time should elapse before command
characters echo. Its value must be a number, which specifies the
number of seconds to wait before echoing. If the user types a
If the value is zero, then command input is not echoed.
- - Variable: cursor-in-echo-area
+ -- Variable: cursor-in-echo-area
This variable controls where the cursor appears when a message is
displayed in the echo area. If it is non-`nil', then the cursor
appears at the end of the message. Otherwise, the cursor appears
\1f
File: lispref.info, Node: Warnings, Next: Invisible Text, Prev: The Echo Area, Up: Display
-Warnings
-========
+52.4 Warnings
+=============
XEmacs contains a facility for unified display of various warnings.
Unlike errors, warnings are displayed in the situations when XEmacs
displayed:
(1) (initialization/error) An error has occurred while loading ~/.emacs:
-
+
Symbol's value as variable is void: bogus-variable
-
+
To ensure normal operation, you should investigate the cause of the error
in your initialization file and remove it. Use the `-debug-init' option
to XEmacs to view a complete error backtrace.
`debug', `info', `notice', `warning', `error', `critical', `alert' and
`emergency'.
- - Function: display-warning class message &optional level
+ -- Function: display-warning class message &optional level
This function displays a warning message MESSAGE (a string).
CLASS should be a warning class symbol, as described above, or a
list of such symbols. LEVEL describes the warning priority level.
(display-warning 'resource
"Bad resource specification encountered:
something like
-
+
Emacs*foo: bar
-
+
You should replace the * with a . in order to get proper behavior when
you use the specifier and/or `set-face-*' functions.")
-
+
---------- Warning buffer ----------
(1) (resource/warning) Bad resource specification encountered:
something like
-
+
Emacs*foo: bar
-
+
You should replace the * with a . in order to get proper behavior when
you use the specifier and/or `set-face-*' functions.
---------- Warning buffer ----------
- - Function: lwarn class level message &rest args
+ -- Function: lwarn class level message &rest args
This function displays a formatted labeled warning message. As
above, CLASS should be the warning class symbol, or a list of such
symbols, and LEVEL should specify the warning priority level
"Error caught in `remove-message-hook': %s"
(error-message-string e))
- - Variable: log-warning-minimum-level
+ -- Variable: log-warning-minimum-level
This variable specifies the minimum level of warnings that should
be generated. Warnings with level lower than defined by this
variable are completely ignored, as if they never happened.
- - Variable: display-warning-minimum-level
+ -- Variable: display-warning-minimum-level
This variable specifies the minimum level of warnings that should
be displayed. Unlike `log-warning-minimum-level', setting this
function does not suppress warnings entirely--they are still
generated in the `*Warnings*' buffer, only they are not displayed
by default.
- - Variable: log-warning-suppressed-classes
+ -- Variable: log-warning-suppressed-classes
This variable specifies a list of classes that should not be
logged or displayed. If any of the class symbols associated with
a warning is the same as any of the symbols listed here, the
warning will be completely ignored, as it they never happened.
- - Variable: display-warning-suppressed-classes
+ -- Variable: display-warning-suppressed-classes
This variable specifies a list of classes that should not be
logged or displayed. If any of the class symbols associated with
a warning is the same as any of the symbols listed here, the
\1f
File: lispref.info, Node: Invisible Text, Next: Selective Display, Prev: Warnings, Up: Display
-Invisible Text
-==============
+52.5 Invisible Text
+===================
You can make characters "invisible", so that they do not appear on the
screen, with the `invisible' property. This can be either a text
very fast, much faster than scanning all the text in the buffer looking
for properties to change.
- - Variable: buffer-invisibility-spec
+ -- Variable: buffer-invisibility-spec
This variable specifies which kinds of `invisible' properties
actually make a character invisible.
\1f
File: lispref.info, Node: Selective Display, Next: Overlay Arrow, Prev: Invisible Text, Up: Display
-Selective Display
-=================
+52.6 Selective Display
+======================
"Selective display" is a pair of features that hide certain lines on
the screen.
in the file, it looks OK, with nothing invisible. The selective display
effect is seen only within XEmacs.
- - Variable: selective-display
+ -- Variable: selective-display
This buffer-local variable enables selective display. This means
that lines, or portions of lines, may be made invisible.
(setq selective-display nil)
=> nil
-
+
---------- Buffer: foo ----------
1 on this column
2on this column
2on this column
1 on this column
---------- Buffer: foo ----------
-
+
(setq selective-display 2)
=> 2
-
+
---------- Buffer: foo ----------
1 on this column
2on this column
1 on this column
---------- Buffer: foo ----------
- - Variable: selective-display-ellipses
+ -- Variable: selective-display-ellipses
If this buffer-local variable is non-`nil', then XEmacs displays
`...' at the end of a line that is followed by invisible text.
This example is a continuation of the previous one.
(setq selective-display-ellipses t)
=> t
-
+
---------- Buffer: foo ----------
1 on this column
2on this column ...
\1f
File: lispref.info, Node: Overlay Arrow, Next: Temporary Displays, Prev: Selective Display, Up: Display
-The Overlay Arrow
-=================
+52.7 The Overlay Arrow
+======================
The "overlay arrow" is useful for directing the user's attention to a
particular line in a buffer. For example, in the modes used for
interface to debuggers, the overlay arrow indicates the line of code
about to be executed.
- - Variable: overlay-arrow-string
+ -- Variable: overlay-arrow-string
This variable holds the string to display to call attention to a
particular line, or `nil' if the arrow feature is not in use.
Despite its name, the value of this variable can be either a string
or a glyph (*note Glyphs::).
- - Variable: overlay-arrow-position
+ -- Variable: overlay-arrow-position
This variable holds a marker that indicates where to display the
overlay arrow. It should point at the beginning of a line. The
arrow text appears at the beginning of that line, overlaying any
\1f
File: lispref.info, Node: Temporary Displays, Next: Blinking, Prev: Overlay Arrow, Up: Display
-Temporary Displays
-==================
+52.8 Temporary Displays
+=======================
Temporary displays are used by commands to put output into a buffer and
then present it to the user for perusal rather than for editing. Many
of the help commands use this feature.
- - Special Form: with-output-to-temp-buffer buffer-name forms...
+ -- Special Form: with-output-to-temp-buffer buffer-name forms...
This function executes FORMS while arranging to insert any output
they print into the buffer named BUFFER-NAME. The buffer is then
shown in some window for viewing, displayed but not selected.
---------- Buffer: foo ----------
This is the contents of foo.
---------- Buffer: foo ----------
-
+
(with-output-to-temp-buffer "foo"
(print 20)
(print standard-output))
=> #<buffer foo>
-
+
---------- Buffer: foo ----------
20
-
+
#<buffer foo>
-
+
---------- Buffer: foo ----------
- - Variable: temp-buffer-show-function
+ -- Variable: temp-buffer-show-function
If this variable is non-`nil', `with-output-to-temp-buffer' calls
it as a function to do the job of displaying a help buffer. The
function gets one argument, which is the buffer it should display.
In Emacs versions 18 and earlier, this variable was called
`temp-buffer-show-hook'.
- - Function: momentary-string-display string position &optional char
+ -- Function: momentary-string-display string position &optional char
message
This function momentarily displays STRING in the current buffer at
POSITION. It has no effect on the undo list or on the buffer's
This is the contents of foo.
-!-Second line.
---------- Buffer: foo ----------
-
+
(momentary-string-display
"**** Important Message! ****"
(point) ?\r
"Type RET when done reading")
=> t
-
+
---------- Buffer: foo ----------
This is the contents of foo.
**** Important Message! ****Second line.
---------- Buffer: foo ----------
-
+
---------- Echo Area ----------
Type RET when done reading
---------- Echo Area ----------
\1f
File: lispref.info, Node: Blinking, Next: Usual Display, Prev: Temporary Displays, Up: Display
-Blinking Parentheses
-====================
+52.9 Blinking Parentheses
+=========================
This section describes the mechanism by which XEmacs shows a matching
open parenthesis when the user inserts a close parenthesis.
- - Variable: blink-paren-function
+ -- Variable: blink-paren-function
The value of this variable should be a function (of no arguments)
to be called whenever a character with close parenthesis syntax is
inserted. The value of `blink-paren-function' may be `nil', in
standard convention for hooks, it was renamed to
`blink-paren-function' in version 19.
- - Variable: blink-matching-paren
+ -- Variable: blink-matching-paren
If this variable is `nil', then `blink-matching-open' does nothing.
- - Variable: blink-matching-paren-distance
+ -- Variable: blink-matching-paren-distance
This variable specifies the maximum distance to scan for a matching
parenthesis before giving up.
- - Variable: blink-matching-paren-delay
+ -- Variable: blink-matching-paren-delay
This variable specifies the number of seconds for the cursor to
remain at the matching parenthesis. A fraction of a second often
gives good results, but the default is 1, which works on all
systems.
- - Command: blink-matching-open
+ -- Command: blink-matching-open
This function is the default value of `blink-paren-function'. It
assumes that point follows a character with close parenthesis
syntax and moves the cursor momentarily to the matching opening
\1f
File: lispref.info, Node: Usual Display, Next: Display Tables, Prev: Blinking, Up: Display
-Usual Display Conventions
-=========================
+52.10 Usual Display Conventions
+===============================
The usual display conventions define how to display each character
code. You can override these conventions by setting up a display table
the screen. Since they change the number of columns the characters
occupy, they also affect the indentation functions.
- - User Option: ctl-arrow
+ -- User Option: ctl-arrow
This buffer-local variable controls how control characters are
displayed. If it is non-`nil', they are displayed as a caret
followed by the character: `^A'. If it is `nil', they are
displayed as a backslash followed by three octal digits: `\001'.
- - Variable: default-ctl-arrow
+ -- Variable: default-ctl-arrow
The value of this variable is the default value for `ctl-arrow' in
buffers that do not override it. *Note Default Value::.
- - User Option: tab-width
+ -- User Option: tab-width
The value of this variable is the spacing between tab stops used
for displaying tab characters in Emacs buffers. The default is 8.
Note that this feature is completely independent from the
\1f
File: lispref.info, Node: Display Tables, Next: Beeping, Prev: Usual Display, Up: Display
-Display Tables
-==============
+52.11 Display Tables
+====================
You can use the "display table" feature to control how all 256 possible
character codes display on the screen. This is useful for displaying
\1f
File: lispref.info, Node: Display Table Format, Next: Active Display Table, Up: Display Tables
-Display Table Format
---------------------
+52.11.1 Display Table Format
+----------------------------
A display table is an array of 256 elements. (In FSF Emacs, a display
table is 262 elements. The six extra elements specify the truncation
XEmacs the variables `truncation-glyph', `continuation-glyph', etc. are
used. *Note Truncation::.)
- - Function: make-display-table
+ -- Function: make-display-table
This creates and returns a display table. The table initially has
`nil' in all elements.
\1f
File: lispref.info, Node: Active Display Table, Next: Character Descriptors, Prev: Display Table Format, Up: Display Tables
-Active Display Table
---------------------
+52.11.2 Active Display Table
+----------------------------
The active display table is controlled by the variable
`current-display-table'. This is a specifier, which means that you can
"glyph table" and such. Note that "glyph" has a different meaning in
XEmacs.)
- - Variable: current-display-table
+ -- Variable: current-display-table
The display table currently in use. This is a specifier.
Display tables are used to control how characters are displayed.
\1f
File: lispref.info, Node: Character Descriptors, Prev: Active Display Table, Up: Display Tables
-Character Descriptors
----------------------
+52.11.3 Character Descriptors
+-----------------------------
Each element of the display-table vector describes how to display a
particular character and is called a "character descriptor". A
\1f
File: lispref.info, Node: Beeping, Prev: Display Tables, Up: Display
-Beeping
-=======
+52.12 Beeping
+=============
You can make XEmacs ring a bell, play a sound, or blink the screen to
attract the user's attention. Be conservative about how often you do
this; frequent bells can become irritating. Also be careful not to use
beeping alone when signaling an error is appropriate. (*Note Errors::.)
- - Function: ding &optional dont-terminate sound device
+ -- Function: ding &optional dont-terminate sound device
This function beeps, or flashes the screen (see `visible-bell'
below). It also terminates any keyboard macro currently executing
unless DONT-TERMINATE is non-`nil'. If SOUND is specified, it
specifies what device to make the sound on, and defaults to the
selected device.
- - Function: beep &optional dont-terminate sound device
+ -- Function: beep &optional dont-terminate sound device
This is a synonym for `ding'.
- - User Option: visible-bell
+ -- User Option: visible-bell
This variable determines whether XEmacs should flash the screen to
represent a bell. Non-`nil' means yes, `nil' means no. On TTY
devices, this is effective only if the Termcap entry for the
terminal type has the visible bell flag (`vb') set.
- - Variable: sound-alist
+ -- Variable: sound-alist
This variable holds an alist associating names with sounds. When
`beep' or `ding' is called with one of the name symbols, the
associated sound will be generated instead of the standard beep.
Other lisp packages may use other beep types, but these are the
ones that the C kernel of XEmacs uses.
- - User Option: bell-volume
+ -- User Option: bell-volume
This variable specifies the default volume for sounds, from 0 to
100.
- - Command: load-default-sounds
+ -- Command: load-default-sounds
This function loads and installs some sound files as beep-types.
- - Command: load-sound-file filename sound-name &optional volume
+ -- Command: load-sound-file filename sound-name &optional volume
This function reads in an audio file and adds it to `sound-alist'.
The sound file must be in the Sun/NeXT U-LAW format. SOUND-NAME
should be a symbol, specifying the name of the sound. If VOLUME
is specified, the sound will be played at that volume; otherwise,
the value of `bell-volume' will be used.
- - Function: play-sound sound &optional volume device
+ -- Function: play-sound sound &optional volume device
This function plays sound SOUND, which should be a symbol
mentioned in `sound-alist'. If VOLUME is specified, it overrides
the value (if any) specified in `sound-alist'. DEVICE specifies
the device to play the sound on, and defaults to the selected
device.
- - Command: play-sound-file file &optional volume device
+ -- Command: play-sound-file file &optional volume device
This function plays the named sound file at volume VOLUME, which
defaults to `bell-volume'. DEVICE specifies the device to play
the sound on, and defaults to the selected device.
\1f
File: lispref.info, Node: Hash Tables, Next: Range Tables, Prev: Display, Up: Top
-Hash Tables
-***********
+53 Hash Tables
+**************
- - Function: hash-table-p object
+ -- Function: hash-table-p object
This function returns `t' if OBJECT is a hash table, else `nil'.
* Menu:
\1f
File: lispref.info, Node: Introduction to Hash Tables, Next: Working With Hash Tables, Up: Hash Tables
-Introduction to Hash Tables
-===========================
+53.1 Introduction to Hash Tables
+================================
A "hash table" is a data structure that provides mappings from
arbitrary Lisp objects called "keys" to other arbitrary Lisp objects
(without the `:' character), as well as the additional keyword `data',
which specifies the initial hash table contents.
- - Function: make-hash-table &key `test' `size' `rehash-size'
+ -- Function: make-hash-table &key `test' `size' `rehash-size'
`rehash-threshold' `weakness'
This function returns a new empty hash table object.
pointed to by something other than a weak hash table, even if the
other is not.
- - Function: copy-hash-table hash-table
+ -- Function: copy-hash-table hash-table
This function returns a new hash table which contains the same
keys and values as HASH-TABLE. The keys and values will not
themselves be copied.
- - Function: hash-table-count hash-table
+ -- Function: hash-table-count hash-table
This function returns the number of entries in HASH-TABLE.
- - Function: hash-table-test hash-table
+ -- Function: hash-table-test hash-table
This function returns the test function of HASH-TABLE. This can
be one of `eq', `eql' or `equal'.
- - Function: hash-table-size hash-table
+ -- Function: hash-table-size hash-table
This function returns the current number of slots in HASH-TABLE,
whether occupied or not.
- - Function: hash-table-rehash-size hash-table
+ -- Function: hash-table-rehash-size hash-table
This function returns the current rehash size of HASH-TABLE. This
is a float greater than 1.0; the factor by which HASH-TABLE is
enlarged when the rehash threshold is exceeded.
- - Function: hash-table-rehash-threshold hash-table
+ -- Function: hash-table-rehash-threshold hash-table
This function returns the current rehash threshold of HASH-TABLE.
This is a float between 0.0 and 1.0; the maximum "load factor" of
HASH-TABLE, beyond which the HASH-TABLE is enlarged by rehashing.
- - Function: hash-table-weakness hash-table
+ -- Function: hash-table-weakness hash-table
This function returns the weakness of HASH-TABLE. This can be one
of `nil', `t', `key' or `value'.
\1f
File: lispref.info, Node: Working With Hash Tables, Next: Weak Hash Tables, Prev: Introduction to Hash Tables, Up: Hash Tables
-Working With Hash Tables
-========================
+53.2 Working With Hash Tables
+=============================
- - Function: puthash key value hash-table
+ -- Function: puthash key value hash-table
This function hashes KEY to VALUE in HASH-TABLE.
- - Function: gethash key hash-table &optional default
+ -- Function: gethash key hash-table &optional default
This function finds the hash value for KEY in HASH-TABLE. If
there is no entry for KEY in HASH-TABLE, DEFAULT is returned
(which in turn defaults to `nil').
- - Function: remhash key hash-table
+ -- Function: remhash key hash-table
This function removes the entry for KEY from HASH-TABLE. Does
nothing if there is no entry for KEY in HASH-TABLE.
- - Function: clrhash hash-table
+ -- Function: clrhash hash-table
This function removes all entries from HASH-TABLE, leaving it
empty.
- - Function: maphash function hash-table
+ -- Function: maphash function hash-table
This function maps FUNCTION over entries in HASH-TABLE, calling it
with two args, each key and value in the hash table.
\1f
File: lispref.info, Node: Weak Hash Tables, Prev: Working With Hash Tables, Up: Hash Tables
-Weak Hash Tables
-================
+53.3 Weak Hash Tables
+=====================
A "weak hash table" is a special variety of hash table whose elements
do not count as GC referents. For any key-value pair in such a hash
\1f
File: lispref.info, Node: Range Tables, Next: Databases, Prev: Hash Tables, Up: Top
-Range Tables
-************
+54 Range Tables
+***************
A range table is a table that efficiently associated values with ranges
of integers.
This maps integers in the range (-3, 2) to `foo' and integers in the
range (5, 20) to `bar'.
- - Function: range-table-p object
+ -- Function: range-table-p object
Return non-`nil' if OBJECT is a range table.
* Menu:
\1f
File: lispref.info, Node: Introduction to Range Tables, Next: Working With Range Tables, Up: Range Tables
-Introduction to Range Tables
-============================
+54.1 Introduction to Range Tables
+=================================
- - Function: make-range-table
+ -- Function: make-range-table
Make a new, empty range table.
- - Function: copy-range-table range-table
+ -- Function: copy-range-table range-table
This function returns a new range table which contains the same
values for the same ranges as RANGE-TABLE. The values will not
themselves be copied.
\1f
File: lispref.info, Node: Working With Range Tables, Prev: Introduction to Range Tables, Up: Range Tables
-Working With Range Tables
-=========================
+54.2 Working With Range Tables
+==============================
- - Function: get-range-table pos range-table &optional default
+ -- Function: get-range-table pos range-table &optional default
This function finds value for position POS in RANGE-TABLE. If
there is no corresponding value, return DEFAULT (defaults to
`nil').
- - Function: put-range-table start end value range-table
+ -- Function: put-range-table start end value range-table
This function sets the value for range (START, END) to be VALUE in
RANGE-TABLE.
- - Function: remove-range-table start end range-table
+ -- Function: remove-range-table start end range-table
This function removes the value for range (START, END) in
RANGE-TABLE.
- - Function: clear-range-table range-table
+ -- Function: clear-range-table range-table
This function flushes RANGE-TABLE.
- - Function: map-range-table function range-table
+ -- Function: map-range-table function range-table
This function maps FUNCTION over entries in RANGE-TABLE, calling
it with three args, the beginning and end of the range and the
corresponding value.
\1f
File: lispref.info, Node: Databases, Next: Processes, Prev: Range Tables, Up: Top
-Databases
-*********
+55 Databases
+************
- - Function: databasep object
+ -- Function: databasep object
This function returns non-`nil' if OBJECT is a database.
* Menu:
\1f
File: lispref.info, Node: Connecting to a Database, Next: Working With a Database, Up: Databases
-Connecting to a Database
-========================
+55.1 Connecting to a Database
+=============================
- - Function: open-database file &optional type subtype access mode
+ -- Function: open-database file &optional type subtype access mode
This function opens database FILE, using database method TYPE and
SUBTYPE, with access rights ACCESS and permissions MODE. ACCESS
can be any combination of `r' `w' and `+', for read, write, and
available: `'hash', `'btree', and `'recno'. See the manpages for
the Berkeley DB functions for more information about these types.
- - Function: close-database database
+ -- Function: close-database database
This function closes database DATABASE.
- - Function: database-live-p object
+ -- Function: database-live-p object
This function returns `t' if OBJECT is an active database, else
`nil'.
\1f
File: lispref.info, Node: Working With a Database, Next: Other Database Functions, Prev: Connecting to a Database, Up: Databases
-Working With a Database
-=======================
+55.2 Working With a Database
+============================
- - Function: get-database key database &optional default
+ -- Function: get-database key database &optional default
This function finds the value for KEY in DATABASE. If there is no
corresponding value, DEFAULT is returned (`nil' if DEFAULT is
omitted).
- - Function: map-database function database
+ -- Function: map-database function database
This function maps FUNCTION over entries in DATABASE, calling it
with two args, each key and value in the database.
- - Function: put-database key value database &optional replace
+ -- Function: put-database key value database &optional replace
This function stores KEY and VALUE in DATABASE. If optional
fourth arg REPLACE is non-`nil', replace any existing entry in the
database.
- - Function: remove-database key database
+ -- Function: remove-database key database
This function removes KEY from DATABASE.
\1f
File: lispref.info, Node: Other Database Functions, Prev: Working With a Database, Up: Databases
-Other Database Functions
-========================
+55.3 Other Database Functions
+=============================
- - Function: database-file-name database
+ -- Function: database-file-name database
This function returns the filename associated with DATABASE.
- - Function: database-last-error &optional database
+ -- Function: database-last-error &optional database
This function returns the last error associated with DATABASE.
- - Function: database-subtype database
+ -- Function: database-subtype database
This function returns the subtype of DATABASE, if any.
- - Function: database-type database
+ -- Function: database-type database
This function returns the type of DATABASE.
\1f
File: lispref.info, Node: Processes, Next: System Interface, Prev: Databases, Up: Top
-Processes
-*********
+56 Processes
+************
In the terminology of operating systems, a "process" is a space in
which a program can execute. XEmacs runs in a process. XEmacs Lisp
signals, obtain status information, receive output from the process, or
send input to it.
- - Function: processp object
+ -- Function: processp object
This function returns `t' if OBJECT is a process, `nil' otherwise.
* Menu:
\1f
File: lispref.info, Node: Subprocess Creation, Next: Synchronous Processes, Up: Processes
-Functions that Create Subprocesses
-==================================
+56.1 Functions that Create Subprocesses
+=======================================
There are three functions that create a new subprocess in which to run
a program. One of them, `start-process', creates an asynchronous
specify overrides for it with `process-environment'. *Note System
Environment::.
- - Variable: exec-directory
+ -- Variable: exec-directory
The value of this variable is the name of a directory (a string)
that contains programs that come with XEmacs, that are intended
for XEmacs to invoke. The program `wakeup' is an example of such
a program; the `display-time' command uses it to get a reminder
once per minute.
- - User Option: exec-path
+ -- User Option: exec-path
The value of this variable is a list of directories to search for
programs to run in subprocesses. Each element is either the name
of a directory (i.e., a string), or `nil', which stands for the
- default directory (which is the value of `default-directory').
+ default directory (which is the value of `default-directory').
The value of `exec-path' is used by `call-process' and
`start-process' when the PROGRAM argument is not an absolute file
\1f
File: lispref.info, Node: Synchronous Processes, Next: MS-DOS Subprocesses, Prev: Subprocess Creation, Up: Processes
-Creating a Synchronous Process
-==============================
+56.2 Creating a Synchronous Process
+===================================
After a "synchronous process" is created, XEmacs waits for the process
to terminate before continuing. Starting Dired is an example of this:
The synchronous subprocess functions returned `nil' in version 18.
In version 19, they return an indication of how the process terminated.
- - Function: call-process program &optional infile destination display
+ -- Function: call-process program &optional infile destination display
&rest args
This function calls PROGRAM in a separate process and waits for it
to finish.
(call-process "pwd" nil t)
=> nil
-
+
---------- Buffer: foo ----------
/usr/user/lewis/manual
---------- Buffer: foo ----------
-
+
(call-process "grep" nil "bar" nil "lewis" "/etc/passwd")
=> nil
-
+
---------- Buffer: bar ----------
lewis:5LTsHm66CSWKg:398:21:Bil Lewis:/user/lewis:/bin/csh
-
+
---------- Buffer: bar ----------
The `insert-directory' function contains a good example of the use
(concat (file-name-as-directory file) ".")
file))
- - Function: call-process-region start end program &optional deletep
+ -- Function: call-process-region start end program &optional deletep
destination displayp &rest args
This function sends the text between START to END as standard
input to a process running PROGRAM. It deletes the text sent if
---------- Buffer: foo ----------
input-!-
---------- Buffer: foo ----------
-
+
(call-process-region 1 6 "cat" nil t)
=> nil
-
+
---------- Buffer: foo ----------
inputinput-!-
---------- Buffer: foo ----------
\1f
File: lispref.info, Node: MS-DOS Subprocesses, Next: Asynchronous Processes, Prev: Synchronous Processes, Up: Processes
-MS-DOS Subprocesses
-===================
+56.3 MS-DOS Subprocesses
+========================
On MS-DOS, you must indicate whether the data going to and from a
synchronous subprocess are text or binary. Text data requires
it. A non-`nil' value means the data is non-text; `nil' means the data
is text, and calls for conversion.
- - Variable: binary-process-input
+ -- Variable: binary-process-input
If this variable is `nil', convert newlines to CRLF sequences in
the input to a synchronous subprocess.
- - Variable: binary-process-output
+ -- Variable: binary-process-output
If this variable is `nil', convert CRLF sequences to newlines in
the output from a synchronous subprocess.
\1f
File: lispref.info, Node: Asynchronous Processes, Next: Deleting Processes, Prev: MS-DOS Subprocesses, Up: Processes
-Creating an Asynchronous Process
-================================
+56.4 Creating an Asynchronous Process
+=====================================
After an "asynchronous process" is created, Emacs and the Lisp program
both continue running immediately. The process may thereafter run in
the functions described in following sections. Here we describe how to
create an asynchronous process with `start-process'.
- - Function: start-process name buffer-or-name program &rest args
+ -- Function: start-process name buffer-or-name program &rest args
This function creates a new asynchronous subprocess and starts the
program PROGRAM running in it. It returns a process object that
stands for the new subprocess in Lisp. The argument NAME
(start-process "my-process" "foo" "sleep" "100")
=> #<process my-process>
-
+
(start-process "my-process" "foo" "ls" "-l" "/user/lewis/bin")
=> #<process my-process<1>>
-
+
---------- Buffer: foo ----------
total 2
lrwxrwxrwx 1 lewis 14 Jul 22 10:12 gnuemacs --> /emacs
-rwxrwxrwx 1 lewis 19 Jul 30 21:02 lemon
-
+
Process my-process<1> finished
-
+
Process my-process finished
---------- Buffer: foo ----------
- - Function: start-process-shell-command name buffer-or-name command
+ -- Function: start-process-shell-command name buffer-or-name command
&rest command-args
This function is like `start-process' except that it uses a shell
to execute the specified command. The argument COMMAND is a shell
command name, and COMMAND-ARGS are the arguments for the shell
command.
- - Variable: process-connection-type
+ -- Variable: process-connection-type
This variable controls the type of device used to communicate with
asynchronous subprocesses. If it is non-`nil', then PTYs are
used, when available. Otherwise, pipes are used.
\1f
File: lispref.info, Node: Deleting Processes, Next: Process Information, Prev: Asynchronous Processes, Up: Processes
-Deleting Processes
-==================
+56.5 Deleting Processes
+=======================
"Deleting a process" disconnects XEmacs immediately from the
subprocess, and removes it from the list of active processes. It sends
away. If you delete a terminated process explicitly before it is
deleted automatically, no harm results.
- - Variable: delete-exited-processes
+ -- Variable: delete-exited-processes
This variable controls automatic deletion of processes that have
terminated (due to calling `exit' or to a signal). If it is
`nil', then they continue to exist until the user runs
`list-processes'. Otherwise, they are deleted immediately after
they exit.
- - Function: delete-process name
+ -- Function: delete-process name
This function deletes the process associated with NAME, killing it
with a `SIGHUP' signal. The argument NAME may be a process, the
name of a process, a buffer, or the name of a buffer.
(delete-process "*shell*")
=> nil
- - Function: process-kill-without-query process &optional
+ -- Function: process-kill-without-query process &optional
require-query-p
This function declares that XEmacs need not query the user if
PROCESS is still running when XEmacs is exited. The process will
\1f
File: lispref.info, Node: Process Information, Next: Input to Processes, Prev: Deleting Processes, Up: Processes
-Process Information
-===================
+56.6 Process Information
+========================
Several functions return information about processes. `list-processes'
is provided for interactive use.
- - Command: list-processes
+ -- Command: list-processes
This command displays a listing of all living processes. In
addition, it finally deletes any process whose status was `Exited'
or `Signaled'. It returns `nil'.
- - Function: process-list
+ -- Function: process-list
This function returns a list of all processes that have not been
deleted.
(process-list)
=> (#<process display-time> #<process shell>)
- - Function: get-process process-name
+ -- Function: get-process process-name
This function returns the process named PROCESS-NAME. If
PROCESS-NAME is a string and there is no process with that name,
the value is `nil'. If PROCESS-NAME is actually a process, it is
(get-process "shell")
=> #<process shell>
- - Function: process-command process
+ -- Function: process-command process
This function returns the command that was executed to start
PROCESS. This is a list of strings, the first string being the
program executed and the rest of the strings being the arguments
(process-command (get-process "shell"))
=> ("/bin/csh" "-i")
- - Function: process-id process
+ -- Function: process-id process
This function returns the PID of PROCESS. This is an integer that
distinguishes the process PROCESS from all other processes running
on the same computer at the current time. The PID of a process is
chosen by the operating system kernel when the process is started
and remains constant as long as the process exists.
- - Function: process-name process
+ -- Function: process-name process
This function returns the name of PROCESS.
- - Function: process-status process
+ -- Function: process-status process
This function returns the status of PROCESS as a symbol. The
argument PROCESS must be a process, a buffer, a process name
(string) or a buffer name (string).
In earlier Emacs versions (prior to version 19), the status of a
network connection was `run' if open, and `exit' if closed.
- - Function: process-kill-without-query-p process
+ -- Function: process-kill-without-query-p process
This function returns whether PROCESS will be killed without
querying the user, if it is running when XEmacs is exited. The
default value is `nil'.
- - Function: process-exit-status process
+ -- Function: process-exit-status process
This function returns the exit status of PROCESS or the signal
number that killed it. (Use the result of `process-status' to
determine which of those it is.) If PROCESS has not yet
terminated, the value is 0.
- - Function: process-tty-name process
+ -- Function: process-tty-name process
This function returns the terminal name that PROCESS is using for
its communication with Emacs--or `nil' if it is using pipes
instead of a terminal (see `process-connection-type' in *Note
\1f
File: lispref.info, Node: Input to Processes, Next: Signals to Processes, Prev: Process Information, Up: Processes
-Sending Input to Processes
-==========================
+56.7 Sending Input to Processes
+===============================
Asynchronous subprocesses receive input when it is sent to them by
XEmacs, which is done with the functions in this section. You must
system to periodically drain the input buffer. For most programs,
these EOFs do no harm.
- - Function: process-send-string process string &optional start end
+ -- Function: process-send-string process string &optional start end
This function sends PROCESS the contents of STRING as standard
input.
(process-send-string "shell<1>" "ls\n")
=> nil
-
-
+
+
---------- Buffer: *shell* ----------
...
introduction.texi syntax-tables.texi~
...
---------- Buffer: *shell* ----------
- - Function: process-send-region process start end &optional buffer
+ -- Function: process-send-region process start end &optional buffer
This function sends the text in the region defined by START and
END as standard input to PROCESS.
markers that indicate positions in the current buffer. (It is
unimportant which number is larger.)
- - Function: process-send-eof &optional process
+ -- Function: process-send-eof &optional process
This function makes PROCESS see an end-of-file in its input. The
EOF comes after any text already sent to it.
\1f
File: lispref.info, Node: Signals to Processes, Next: Output from Processes, Prev: Input to Processes, Up: Processes
-Sending Signals to Processes
-============================
+56.8 Sending Signals to Processes
+=================================
"Sending a signal" to a subprocess is a way of interrupting its
activities. There are several different signals, each with its own
a signal to be sent. It must be either an integer or a symbol which
names the signal, like `SIGSEGV'.
- - Function: process-send-signal signal &optional process current-group
+ -- Function: process-send-signal signal &optional process current-group
This function sends the signal SIGNAL to the process PROCESS. The
following functions can be implemented in terms of
`process-send-signal'.
- - Function: interrupt-process &optional process current-group
+ -- Function: interrupt-process &optional process current-group
This function interrupts the process PROCESS by sending the signal
`SIGINT'. Outside of XEmacs, typing the "interrupt character"
(normally `C-c') sends this signal. When the argument
"typing `C-c'" on the terminal by which XEmacs talks to the
subprocess.
- - Function: kill-process &optional process current-group
+ -- Function: kill-process &optional process current-group
This function kills the process PROCESS by sending the signal
`SIGKILL'. This signal kills the subprocess immediately, and
cannot be handled by the subprocess.
- - Function: quit-process &optional process current-group
+ -- Function: quit-process &optional process current-group
This function sends the signal `SIGQUIT' to the process PROCESS.
This signal is the one sent by the "quit character" (usually
`C-\') when you are not inside XEmacs.
- - Function: stop-process &optional process current-group
+ -- Function: stop-process &optional process current-group
This function stops the process PROCESS by sending the signal
`SIGTSTP'. Use `continue-process' to resume its execution.
non-`nil', you can think of this function as "typing `C-z'" on the
terminal XEmacs uses to communicate with the subprocess.
- - Function: continue-process &optional process current-group
+ -- Function: continue-process &optional process current-group
This function resumes execution of the process PROCESS by sending
it the signal `SIGCONT'. This presumes that PROCESS was stopped
previously.
- - Command: signal-process pid signal
+ -- Command: signal-process pid signal
This function sends a signal to the process with process id PID,
which need not be a child of XEmacs. The argument SIGNAL
specifies which signal to send.
\1f
File: lispref.info, Node: Output from Processes, Next: Sentinels, Prev: Signals to Processes, Up: Processes
-Receiving Output from Processes
-===============================
+56.9 Receiving Output from Processes
+====================================
There are two ways to receive the output that a subprocess writes to
its standard output stream. The output can be inserted in a buffer,
\1f
File: lispref.info, Node: Process Buffers, Next: Filter Functions, Up: Output from Processes
-Process Buffers
----------------
+56.9.1 Process Buffers
+----------------------
A process can (and usually does) have an "associated buffer", which is
an ordinary Emacs buffer that is used for two purposes: storing the
to point to the end of the text just inserted. Usually, but not
always, the `process-mark' is at the end of the buffer.
- - Function: process-buffer process
+ -- Function: process-buffer process
This function returns the associated buffer of the process PROCESS.
(process-buffer (get-process "shell"))
=> #<buffer *shell*>
- - Function: process-mark process
+ -- Function: process-mark process
This function returns the process marker for PROCESS, which is the
marker that says where to insert output from the process.
transmission to the process, the process marker is useful for
distinguishing the new input from previous output.
- - Function: set-process-buffer process buffer
+ -- Function: set-process-buffer process buffer
This function sets the buffer associated with PROCESS to BUFFER.
If BUFFER is `nil', the process becomes associated with no buffer.
- - Function: get-buffer-process buffer-or-name
+ -- Function: get-buffer-process buffer-or-name
This function returns the process associated with BUFFER-OR-NAME.
If there are several processes associated with BUFFER-OR-NAME,
then one is chosen. (Presently, the one chosen is the one most
\1f
File: lispref.info, Node: Filter Functions, Next: Accepting Output, Prev: Process Buffers, Up: Output from Processes
-Process Filter Functions
-------------------------
+56.9.2 Process Filter Functions
+-------------------------------
A process "filter function" is a function that receives the standard
output from the associated process. If a process has a filter, then
that produces the same output twice in a row may send it as one batch
of 200 characters one time, and five batches of 40 characters the next.
- - Function: set-process-filter process filter
+ -- Function: set-process-filter process filter
This function gives PROCESS the filter function FILTER. If FILTER
is `nil', then the process will have no filter. If FILTER is `t',
then no output from the process will be accepted until the filter
but is queued, and will be processed as soon as the filter is
changed.)
- - Function: process-filter process
+ -- Function: process-filter process
This function returns the filter function of PROCESS, or `nil' if
it has none. `t' means that output processing has been stopped.
\1f
File: lispref.info, Node: Accepting Output, Prev: Filter Functions, Up: Output from Processes
-Accepting Output from Processes
--------------------------------
+56.9.3 Accepting Output from Processes
+--------------------------------------
Output from asynchronous subprocesses normally arrives only while
XEmacs is waiting for some sort of external event, such as elapsed time
explicitly permit output to arrive at a specific point, or even to wait
until output arrives from a process.
- - Function: accept-process-output &optional process seconds millisec
+ -- Function: accept-process-output &optional process seconds millisec
This function allows XEmacs to read pending output from processes.
The output is inserted in the associated buffers or given to
their filter functions. If PROCESS is non-`nil' then this
\1f
File: lispref.info, Node: Sentinels, Next: Process Window Size, Prev: Output from Processes, Up: Processes
-Sentinels: Detecting Process Status Changes
-===========================================
+56.10 Sentinels: Detecting Process Status Changes
+=================================================
A "process sentinel" is a function that is called whenever the
associated process changes status for any reason, including signals
Emacs does this automatically; sentinels never need to do it explicitly.
*Note Match Data::.
- - Function: set-process-sentinel process sentinel
+ -- Function: set-process-sentinel process sentinel
This function associates SENTINEL with PROCESS. If SENTINEL is
`nil', then the process will have no sentinel. The default
behavior when there is no sentinel is to insert a message in the
-| Process: #<process shell> had the event `killed'
=> #<process shell>
- - Function: process-sentinel process
+ -- Function: process-sentinel process
This function returns the sentinel of PROCESS, or `nil' if it has
none.
- - Function: waiting-for-user-input-p
+ -- Function: waiting-for-user-input-p
While a sentinel or filter function is running, this function
returns non-`nil' if XEmacs was waiting for keyboard input from
the user at the time the sentinel or filter function was called,
\1f
File: lispref.info, Node: Process Window Size, Next: Transaction Queues, Prev: Sentinels, Up: Processes
-Process Window Size
-===================
+56.11 Process Window Size
+=========================
- - Function: set-process-window-size process height width
+ -- Function: set-process-window-size process height width
This function tells PROCESS that its logical window size is HEIGHT
by WIDTH characters. This is principally useful with pty's.
\1f
File: lispref.info, Node: Transaction Queues, Next: Network, Prev: Process Window Size, Up: Processes
-Transaction Queues
-==================
+56.12 Transaction Queues
+========================
You can use a "transaction queue" for more convenient communication
with subprocesses using transactions. First use `tq-create' to create
a transaction queue communicating with a specified process. Then you
can call `tq-enqueue' to send a transaction.
- - Function: tq-create process
+ -- Function: tq-create process
This function creates and returns a transaction queue
communicating with PROCESS. The argument PROCESS should be a
subprocess capable of sending and receiving streams of bytes. It
may be a child process, or it may be a TCP connection to a server,
possibly on another machine.
- - Function: tq-enqueue queue question regexp closure fn
+ -- Function: tq-enqueue queue question regexp closure fn
This function sends a transaction to queue QUEUE. Specifying the
queue has the effect of specifying the subprocess to talk to.
The return value of `tq-enqueue' itself is not meaningful.
- - Function: tq-close queue
+ -- Function: tq-close queue
Shut down transaction queue QUEUE, waiting for all pending
transactions to complete, and then terminate the connection or
child process.
\1f
File: lispref.info, Node: Network, Prev: Transaction Queues, Up: Processes
-Network Connections
-===================
+56.13 Network Connections
+=========================
XEmacs Lisp programs can open TCP network connections to other
processes on the same machine or other machines. A network connection
connection, and it never returns either of those values for a real
subprocess. *Note Process Information::.
- - Function: open-network-stream name buffer-or-name host service
+ -- Function: open-network-stream name buffer-or-name host service
&optional protocol
This function opens a TCP connection for a service to a host. It
returns a process object to represent the connection.
\1f
File: lispref.info, Node: System Interface, Next: X-Windows, Prev: Processes, Up: Top
-Operating System Interface
-**************************
+57 Operating System Interface
+*****************************
This chapter is about starting and getting out of Emacs, access to
values in the operating system environment, and terminal input, output,
\1f
File: lispref.info, Node: Starting Up, Next: Getting Out, Up: System Interface
-Starting Up XEmacs
-==================
+57.1 Starting Up XEmacs
+=======================
This section describes what XEmacs does when it is started, and how you
can customize these actions.
\1f
File: lispref.info, Node: Start-up Summary, Next: Init File, Up: Starting Up
-Summary: Sequence of Actions at Start Up
-----------------------------------------
+57.1.1 Summary: Sequence of Actions at Start Up
+-----------------------------------------------
The order of operations performed (in `startup.el') by XEmacs when it
is started up is as follows:
5. It loads the library `site-start', unless the option
`-no-site-file' was specified. The library's file name is usually
- `site-start.el'.
+ `site-start.el'.
6. It loads the file `~/.emacs' unless `-q' was specified on the
command line. (This is not done in `-batch' mode.) The `-u'
7. It loads the library `default' unless `inhibit-default-init' is
non-`nil'. (This is not done in `-batch' mode or if `-q' was
specified on the command line.) The library's file name is
- usually `default.el'.
+ usually `default.el'.
8. It runs the normal hook `after-init-hook'.
provided there were no remaining command line arguments (a few
steps above) and the value of `inhibit-startup-message' is `nil'.
- - User Option: inhibit-startup-message
+ -- User Option: inhibit-startup-message
This variable inhibits the initial startup messages (the
nonwarranty, etc.). If it is non-`nil', then the messages are not
printed.
way that affects more than one user, because that would prevent
new users from receiving the information they are supposed to see.
- - User Option: inhibit-startup-echo-area-message
+ -- User Option: inhibit-startup-echo-area-message
This variable controls the display of the startup echo area
message. You can suppress the startup echo area message by adding
text with this form to your `.emacs' file:
\1f
File: lispref.info, Node: Init File, Next: Terminal-Specific, Prev: Start-up Summary, Up: Starting Up
-The Init File: `.emacs'
------------------------
+57.1.2 The Init File: `.emacs'
+------------------------------
When you start XEmacs, it normally attempts to load the file `.emacs'
from your home directory. This file, if it exists, must contain Lisp
this _before_ the user's init file. You can inhibit the loading of
this file with the option `-no-site-file'.
- - Variable: site-run-file
+ -- Variable: site-run-file
This variable specifies the site-customization file to load before
the user's init file. Its normal value is `"site-start"'.
of how to make various commonly desired customizations in your `.emacs'
file.
- - User Option: inhibit-default-init
+ -- User Option: inhibit-default-init
This variable prevents XEmacs from loading the default
initialization library file for your session of XEmacs. If its
value is non-`nil', then the default library is not loaded. The
default value is `nil'.
- - Variable: before-init-hook
- - Variable: after-init-hook
+ -- Variable: before-init-hook
+ -- Variable: after-init-hook
These two normal hooks are run just before, and just after,
loading of the user's init file, `default.el', and/or
`site-start.el'.
\1f
File: lispref.info, Node: Terminal-Specific, Next: Command Line Arguments, Prev: Init File, Up: Starting Up
-Terminal-Specific Initialization
---------------------------------
+57.1.3 Terminal-Specific Initialization
+---------------------------------------
Each terminal type can have its own Lisp library that XEmacs loads when
run on that type of terminal. For a terminal type named TERMTYPE, the
initializations for terminals that do not have their own libraries.
*Note Hooks::.
- - Variable: term-file-prefix
+ -- Variable: term-file-prefix
If the `term-file-prefix' variable is non-`nil', XEmacs loads a
terminal-specific initialization file as follows:
terminal-initialization file. To do this, put the following in
your `.emacs' file: `(setq term-file-prefix nil)'.
- - Variable: term-setup-hook
+ -- Variable: term-setup-hook
This variable is a normal hook that XEmacs runs after loading your
`.emacs' file, the default initialization file (if any) and the
terminal-specific Lisp file.
You can use `term-setup-hook' to override the definitions made by a
terminal-specific file.
- - Variable: window-setup-hook
+ -- Variable: window-setup-hook
This variable is a normal hook which XEmacs runs after loading your
`.emacs' file and the default initialization file (if any), after
loading terminal-specific Lisp code, and after running the hook
\1f
File: lispref.info, Node: Command Line Arguments, Prev: Terminal-Specific, Up: Starting Up
-Command Line Arguments
-----------------------
+57.1.4 Command Line Arguments
+-----------------------------
You can use command line arguments to request various actions when you
start XEmacs. Since you do not need to start XEmacs more than once per
This section describes how Emacs processes command line arguments,
and how you can customize them.
- - Function: command-line
+ -- Function: command-line
This function parses the command line that XEmacs was called with,
processes it, loads the user's `.emacs' file and displays the
startup messages.
- - Variable: command-line-processed
+ -- Variable: command-line-processed
The value of this variable is `t' once the command line has been
processed.
this variable to `nil' first in order to cause the new dumped
XEmacs to process its new command line arguments.
- - Variable: command-switch-alist
+ -- Variable: command-switch-alist
The value of this variable is an alist of user-defined command-line
options and associated handler functions. This variable exists so
you can add elements to it.
function in the `startup.el' file. See also *Note Command Line
Switches and Arguments: (xemacs)Command Switches.
- - Variable: command-line-args
+ -- Variable: command-line-args
The value of this variable is the list of command line arguments
passed to XEmacs.
- - Variable: command-line-functions
+ -- Variable: command-line-functions
This variable's value is a list of functions for handling an
unrecognized command-line argument. Each time the next argument
to be processed has no special meaning, the functions in this list
\1f
File: lispref.info, Node: Getting Out, Next: System Environment, Prev: Starting Up, Up: System Interface
-Getting out of XEmacs
-=====================
+57.2 Getting out of XEmacs
+==========================
There are two ways to get out of XEmacs: you can kill the XEmacs job,
which exits permanently, or you can suspend it, which permits you to
\1f
File: lispref.info, Node: Killing XEmacs, Next: Suspending XEmacs, Up: Getting Out
-Killing XEmacs
---------------
+57.2.1 Killing XEmacs
+---------------------
Killing XEmacs means ending the execution of the XEmacs process. The
parent process normally resumes control. The low-level primitive for
killing XEmacs is `kill-emacs'.
- - Command: kill-emacs &optional exit-data
+ -- Command: kill-emacs &optional exit-data
This function exits the XEmacs process and kills it.
If EXIT-DATA is an integer, then it is used as the exit status of
subprocesses that are running. This is done in the function
`save-buffers-kill-emacs'.
- - Variable: kill-emacs-query-functions
+ -- Variable: kill-emacs-query-functions
After asking the standard questions, `save-buffers-kill-emacs'
calls the functions in the list `kill-buffer-query-functions', in
order of appearance, with no arguments. These functions can ask
for additional confirmation from the user. If any of them returns
non-`nil', XEmacs is not killed.
- - Variable: kill-emacs-hook
+ -- Variable: kill-emacs-hook
This variable is a normal hook; once `save-buffers-kill-emacs' is
finished with all file saving and confirmation, it runs the
functions in this hook.
\1f
File: lispref.info, Node: Suspending XEmacs, Prev: Killing XEmacs, Up: Getting Out
-Suspending XEmacs
------------------
+57.2.2 Suspending XEmacs
+------------------------
"Suspending XEmacs" means stopping XEmacs temporarily and returning
control to its superior process, which is usually the shell. This
moving to a different window. Therefore, suspending is not allowed
when XEmacs is an X client.
- - Command: suspend-emacs &optional stuffstring
+ -- Command: suspend-emacs &optional stuffstring
This function stops XEmacs and returns control to the superior
process. If and when the superior process resumes XEmacs,
`suspend-emacs' returns `nil' to its caller in Lisp.
(suspend-emacs)
=> nil
-
+
(add-hook 'suspend-hook
(function (lambda ()
(or (y-or-n-p
---------- Buffer: Minibuffer ----------
Really suspend? y
---------- Buffer: Minibuffer ----------
-
+
---------- Parent Shell ----------
lewis@slug[23] % /user/lewis/manual
lewis@slug[24] % fg
-
+
---------- Echo Area ----------
Resumed!
- - Variable: suspend-hook
+ -- Variable: suspend-hook
This variable is a normal hook run before suspending.
- - Variable: suspend-resume-hook
+ -- Variable: suspend-resume-hook
This variable is a normal hook run after suspending.
\1f
File: lispref.info, Node: System Environment, Next: User Identification, Prev: Getting Out, Up: System Interface
-Operating System Environment
-============================
+57.3 Operating System Environment
+=================================
XEmacs provides access to variables in the operating system environment
through various functions. These variables include the name of the
system, the user's UID, and so on.
- - Variable: system-type
+ -- Variable: system-type
The value of this variable is a symbol indicating the type of
operating system XEmacs is operating on. Here is a table of the
possible values:
`system-configuration' to distinguish between different operating
systems.
- - Variable: system-configuration
+ -- Variable: system-configuration
This variable holds the three-part configuration name for the
hardware/software configuration of your system, as a string. The
convenient way to test parts of this string is with `string-match'.
- - Function: system-name
+ -- Function: system-name
This function returns the name of the machine you are running on.
(system-name)
=> "prep.ai.mit.edu"
Emacs is confused about the name of your system. The variable is also
useful for constructing frame titles (*note Frame Titles::).
- - Variable: mail-host-address
+ -- Variable: mail-host-address
If this variable is non-`nil', it is used instead of `system-name'
for purposes of generating email addresses. For example, it is
used when constructing the default value of `user-mail-address'.
starts up, the value actually used is the one saved when XEmacs
was dumped. *Note Building XEmacs::.)
- - Command: getenv var &optional interactivep
+ -- Command: getenv var &optional interactivep
This function returns the value of the environment variable VAR,
as a string. Within XEmacs, the environment variable values are
kept in the Lisp variable `process-environment'.
(getenv "USER")
=> "lewis"
-
+
lewis@slug[10] % printenv
PATH=.:/user/lewis/bin:/usr/bin:/usr/local/bin
USER=lewis
SHELL=/bin/csh
HOME=/user/lewis
- - Command: setenv variable &optional value unset
+ -- Command: setenv variable &optional value unset
This command sets the value of the environment variable named
VARIABLE to VALUE. Both arguments should be strings. This
function works by modifying `process-environment'; binding that
variable with `let' is also reasonable practice.
- - Variable: process-environment
+ -- Variable: process-environment
This variable is a list of strings, each describing one environment
variable. The functions `getenv' and `setenv' work by
manipulating this variable.
"SHELL=/bin/csh"
"HOME=/user/lewis")
- - Variable: path-separator
+ -- Variable: path-separator
This variable holds a string which says which character separates
directories in a search path (as found in an environment
variable). Its value is `":"' for Unix and GNU systems, and `";"'
for MS-DOS and Windows NT.
- - Variable: invocation-name
+ -- Variable: invocation-name
This variable holds the program name under which Emacs was
invoked. The value is a string, and does not include a directory
name.
- - Variable: invocation-directory
+ -- Variable: invocation-directory
This variable holds the directory from which the Emacs executable
was invoked, or perhaps `nil' if that directory cannot be
determined.
- - Variable: installation-directory
+ -- Variable: installation-directory
If non-`nil', this is a directory within which to look for the
`lib-src' and `etc' subdirectories. This is non-`nil' when Emacs
can't find those directories in their standard installed
locations, but can find them in a directory related somehow to the
one containing the Emacs executable.
- - Function: load-average &optional use-floats
+ -- Function: load-average &optional use-floats
This function returns a list of the current 1-minute, 5-minute and
15-minute load averages. The values are integers that are 100
times the system load averages. (The load averages indicate the
=> (169 158 164)
(load-average t)
=> (1.69921875 1.58984375 1.640625)
-
+
lewis@rocky[5] % uptime
8:06pm up 16 day(s), 21:57, 40 users,
load average: 1.68, 1.59, 1.64
run, or it may be unimplemented for the particular system type.
In that case, the function will signal an error.
- - Function: emacs-pid
+ -- Function: emacs-pid
This function returns the process ID of the Emacs process.
\1f
File: lispref.info, Node: User Identification, Next: Time of Day, Prev: System Environment, Up: System Interface
-User Identification
-===================
+57.4 User Identification
+========================
- - Variable: user-mail-address
+ -- Variable: user-mail-address
This holds the nominal email address of the user who is using
Emacs. When Emacs starts up, it computes a default value that is
usually right, but users often set this themselves when the
default value is not right.
- - Function: user-login-name &optional uid
+ -- Function: user-login-name &optional uid
If you don't specify UID, this function returns the name under
which the user is logged in. If the environment variable `LOGNAME'
is set, that value is used. Otherwise, if the environment variable
(user-login-name)
=> "lewis"
- - Function: user-real-login-name
+ -- Function: user-real-login-name
This function returns the user name corresponding to Emacs's real
UID. This ignores the effective UID and ignores the environment
variables `LOGNAME' and `USER'.
- - Variable: user-full-name
+ -- Variable: user-full-name
This variable holds the name of the user running this Emacs. It is
initialized at startup time from the value of `NAME' environment
variable. You can change the value of this variable to alter the
result of the `user-full-name' function.
- - Function: user-full-name &optional user
+ -- Function: user-full-name &optional user
This function returns the full name of USER. If USER is `nil', it
defaults to the user running this Emacs. In that case, the value
of `user-full-name' variable, if non-`nil', will be used.
variables are also useful for constructing frame titles (*note Frame
Titles::).
- - Function: user-real-uid
+ -- Function: user-real-uid
This function returns the real UID of the user.
(user-real-uid)
=> 19
- - Function: user-uid
+ -- Function: user-uid
This function returns the effective UID of the user.
- - Function: user-home-directory
+ -- Function: user-home-directory
This function returns the "`HOME'" directory of the user, and is
intended to replace occurrences of "`(getenv "HOME")'". Under
Unix systems, the following is done:
\1f
File: lispref.info, Node: Time of Day, Next: Time Conversion, Prev: User Identification, Up: System Interface
-Time of Day
-===========
+57.5 Time of Day
+================
This section explains how to determine the current time and the time
zone.
- - Function: current-time-string &optional time-value
+ -- Function: current-time-string &optional time-value
This function returns the current time and date as a
humanly-readable string. The format of the string is unvarying;
the number of characters used for each part is always the same, so
(current-time-string)
=> "Wed Oct 14 22:21:05 1987"
- - Function: current-time
+ -- Function: current-time
This function returns the system's time value as a list of three
integers: `(HIGH LOW MICROSEC)'. The integers HIGH and LOW
combine to give the number of seconds since 0:00 January 1, 1970,
as you get with the function `file-attributes'. *Note File
Attributes::.
- - Function: current-time-zone &optional time-value
+ -- Function: current-time-zone &optional time-value
This function returns a list describing the time zone that the
user is in.
\1f
File: lispref.info, Node: Time Conversion, Next: Timers, Prev: Time of Day, Up: System Interface
-Time Conversion
-===============
+57.6 Time Conversion
+====================
These functions convert time values (lists of two or three integers) to
strings or to calendrical information. There is also a function to
values from the functions `current-time' (*note Time of Day::) and
`file-attributes' (*note File Attributes::).
- - Function: format-time-string format-string &optional time
+ -- Function: format-time-string format-string &optional time
This function converts TIME to a string according to
FORMAT-STRING. If TIME is omitted, it defaults to the current
time. The argument FORMAT-STRING may contain `%'-sequences which
`%Z'
This stands for the time zone abbreviation.
- - Function: decode-time &optional specified-time
+ -- Function: decode-time &optional specified-time
This function converts a time value into calendrical information.
The optional SPECIFIED-TIME should be a list of (HIGH LOW .
IGNORED) or (HIGH . LOW), as from `current-time' and
Note that Common Lisp has different meanings for DOW and ZONE.
- - Function: encode-time seconds minutes hour day month year &optional
+ -- Function: encode-time seconds minutes hour day month year &optional
zone
This function is the inverse of `decode-time'. It converts seven
items of calendrical data into a time value. For the meanings of
\1f
File: lispref.info, Node: Timers, Next: Terminal Input, Prev: Time Conversion, Up: System Interface
-Timers for Delayed Execution
-============================
+57.7 Timers for Delayed Execution
+=================================
You can set up a timer to call a function at a specified future time.
- - Function: add-timeout secs function object &optional resignal
+ -- Function: add-timeout secs function object &optional resignal
This function adds a timeout, to be signaled after the timeout
period has elapsed. SECS is a number of seconds, expressed as an
integer or a float. FUNCTION will be called after that many
(NOTE: In FSF Emacs, this function is called `run-at-time' and has
different semantics.)
- - Function: disable-timeout id
+ -- Function: disable-timeout id
Cancel the requested action for ID, which should be a value
previously returned by `add-timeout'. This cancels the effect of
that call to `add-timeout'; the arrival of the specified time will
\1f
File: lispref.info, Node: Terminal Input, Next: Terminal Output, Prev: Timers, Up: System Interface
-Terminal Input
-==============
+57.8 Terminal Input
+===================
This section describes functions and variables for recording or
manipulating terminal input. See *Note Display::, for related
\1f
File: lispref.info, Node: Input Modes, Next: Translating Input, Up: Terminal Input
-Input Modes
------------
+57.8.1 Input Modes
+------------------
- - Function: set-input-mode interrupt flow meta &optional quit-char
+ -- Function: set-input-mode interrupt flow meta &optional quit-char
console
This function sets the mode for reading keyboard input. If
INTERRUPT is non-null, then XEmacs uses input interrupts. If it is
The `current-input-mode' function returns the input mode settings
XEmacs is currently using.
- - Function: current-input-mode &optional console
+ -- Function: current-input-mode &optional console
This function returns current mode for reading keyboard input. It
returns a list, corresponding to the arguments of `set-input-mode',
of the form `(INTERRUPT FLOW META QUIT)' in which:
\1f
File: lispref.info, Node: Translating Input, Next: Recording Input, Prev: Input Modes, Up: Terminal Input
-Translating Input Events
-------------------------
+57.8.2 Translating Input Events
+-------------------------------
This section describes features for translating input events into other
input events before they become part of key sequences.
- - Variable: function-key-map
+ -- Variable: function-key-map
This variable holds a keymap that describes the character sequences
sent by function keys on an ordinary character terminal. This
keymap uses the same data structure as other keymaps, but is used
Emacs versions 18 and earlier used totally different means of
detecting the character sequences that represent function keys.
- - Variable: key-translation-map
+ -- Variable: key-translation-map
This variable is another keymap used just like `function-key-map'
to translate input events into other events. It differs from
`function-key-map' in two ways:
(if (memq 'hyper (event-modifiers e))
e
(add-event-modifier "H-" e))))))
-
+
(defun add-event-modifier (string e)
(let ((symbol (if (symbolp e) e (car e))))
(setq symbol (intern (concat string
(if (symbolp e)
symbol
(cons symbol (cdr e)))))
-
+
(define-key function-key-map "\C-ch" 'hyperify)
The `iso-transl' library uses this feature to provide a way of
\1f
File: lispref.info, Node: Recording Input, Prev: Translating Input, Up: Terminal Input
-Recording Input
----------------
+57.8.3 Recording Input
+----------------------
- - Function: recent-keys &optional number
+ -- Function: recent-keys &optional number
This function returns a vector containing recent input events from
the keyboard or mouse. By default, 100 events are recorded, which
is how many `recent-keys' returns.
returned. You may change the number of stored events using
`set-recent-keys-ring-size'.
- - Function: recent-keys-ring-size
+ -- Function: recent-keys-ring-size
This function returns the number of recent events stored
internally. This is also the maximum number of events
`recent-keys' can return. By default, 100 events are stored.
- - Function: set-recent-keys-ring-size size
+ -- Function: set-recent-keys-ring-size size
This function changes the number of events stored by XEmacs and
returned by `recent-keys'.
remember last 250 events and will make `recent-keys' return last
250 events by default.
- - Command: open-dribble-file filename
+ -- Command: open-dribble-file filename
This function opens a "dribble file" named FILENAME. When a
dribble file is open, each input event from the keyboard or mouse
(but not those from keyboard macros) is written in that file. A
\1f
File: lispref.info, Node: Terminal Output, Next: Flow Control, Prev: Terminal Input, Up: System Interface
-Terminal Output
-===============
+57.9 Terminal Output
+====================
The terminal output functions send output to the terminal or keep track
of output sent to the terminal. The function `device-baud-rate' tells
you what XEmacs thinks is the output speed of the terminal.
- - Function: device-baud-rate &optional device
+ -- Function: device-baud-rate &optional device
This function's value is the output speed of the terminal
associated with DEVICE, as far as XEmacs knows. DEVICE defaults
to the selected device (usually the only device) if omitted.
makes decisions that are less than optimal. To fix the problem, use
`set-device-baud-rate'.
- - Function: set-device-baud-rate device baud-rate
+ -- Function: set-device-baud-rate device baud-rate
This function sets the output speed of DEVICE. See
`device-baud-rate'. DEVICE defaults to the selected device
(usually the only device) if `nil'.
- - Function: send-string-to-terminal char-or-string &optional stdout-p
+ -- Function: send-string-to-terminal char-or-string &optional stdout-p
device
This function sends CHAR-OR-STRING to the terminal without
alteration. Control characters in CHAR-OR-STRING have
(send-string-to-terminal "\eF4\^U\^F")
=> nil
- - Command: open-termscript filename
+ -- Command: open-termscript filename
This function is used to open a "termscript file" that will record
all the characters sent by XEmacs to the terminal. (If there are
multiple tty or stream devices, all characters sent to all such
(open-termscript "../junk/termscript")
=> nil
-\1f
-File: lispref.info, Node: Flow Control, Next: Batch Mode, Prev: Terminal Output, Up: System Interface
-
-Flow Control
-============
-
-This section attempts to answer the question "Why does XEmacs choose to
-use flow-control characters in its command character set?" For a
-second view on this issue, read the comments on flow control in the
-`emacs/INSTALL' file from the distribution; for help with Termcap
-entries and DEC terminal concentrators, see `emacs/etc/TERMS'.
-
- At one time, most terminals did not need flow control, and none used
-`C-s' and `C-q' for flow control. Therefore, the choice of `C-s' and
-`C-q' as command characters was uncontroversial. XEmacs, for economy
-of keystrokes and portability, used nearly all the ASCII control
-characters, with mnemonic meanings when possible; thus, `C-s' for
-search and `C-q' for quote.
-
- Later, some terminals were introduced which required these characters
-for flow control. They were not very good terminals for full-screen
-editing, so XEmacs maintainers did not pay attention. In later years,
-flow control with `C-s' and `C-q' became widespread among terminals,
-but by this time it was usually an option. And the majority of users,
-who can turn flow control off, were unwilling to switch to less
-mnemonic key bindings for the sake of flow control.
-
- So which usage is "right", XEmacs's or that of some terminal and
-concentrator manufacturers? This question has no simple answer.
-
- One reason why we are reluctant to cater to the problems caused by
-`C-s' and `C-q' is that they are gratuitous. There are other
-techniques (albeit less common in practice) for flow control that
-preserve transparency of the character stream. Note also that their use
-for flow control is not an official standard. Interestingly, on the
-model 33 teletype with a paper tape punch (which is very old), `C-s'
-and `C-q' were sent by the computer to turn the punch on and off!
-
- As X servers and other window systems replace character-only
-terminals, this problem is gradually being cured. For the mean time,
-XEmacs provides a convenient way of enabling flow control if you want
-it: call the function `enable-flow-control'.
-
- - Command: enable-flow-control &optional argument
- This function enables use of `C-s' and `C-q' for output flow
- control, and provides the characters `C-\' and `C-^' as aliases
- for them using `keyboard-translate-table' (*note Translating
- Input::).
-
- With optional argument ARGUMENT (interactively the prefix
- argument), enable flow control mode if ARGUMENT is positive; else
- disable it.
-
- You can use the function `enable-flow-control-on' in your `.emacs'
-file to enable flow control automatically on certain terminal types.
-
- - Function: enable-flow-control-on &rest termtypes
- This function enables flow control, and the aliases `C-\' and
- `C-^', if the terminal type is one of TERMTYPES. For example:
-
- (enable-flow-control-on "vt200" "vt300" "vt101" "vt131")
-
- Here is how `enable-flow-control' does its job:
-
- 1. It sets CBREAK mode for terminal input, and tells the operating
- system to handle flow control, with `(set-input-mode nil t)'.
-
- 2. It sets up `keyboard-translate-table' to translate `C-\' and `C-^'
- into `C-s' and `C-q'. Except at its very lowest level, XEmacs
- never knows that the characters typed were anything but `C-s' and
- `C-q', so you can in effect type them as `C-\' and `C-^' even when
- they are input for other commands. *Note Translating Input::.
-
- If the terminal is the source of the flow control characters, then
-once you enable kernel flow control handling, you probably can make do
-with less padding than normal for that terminal. You can reduce the
-amount of padding by customizing the Termcap entry. You can also
-reduce it by setting `baud-rate' to a smaller value so that XEmacs uses
-a smaller speed when calculating the padding needed. *Note Terminal
-Output::.
-
-\1f
-File: lispref.info, Node: Batch Mode, Prev: Flow Control, Up: System Interface
-
-Batch Mode
-==========
-
-The command line option `-batch' causes XEmacs to run noninteractively.
-In this mode, XEmacs does not read commands from the terminal, it does
-not alter the terminal modes, and it does not expect to be outputting
-to an erasable screen. The idea is that you specify Lisp programs to
-run; when they are finished, XEmacs should exit. The way to specify
-the programs to run is with `-l FILE', which loads the library named
-FILE, and `-f FUNCTION', which calls FUNCTION with no arguments.
-
- Any Lisp program output that would normally go to the echo area,
-either using `message' or using `prin1', etc., with `t' as the stream,
-goes instead to XEmacs's standard error descriptor when in batch mode.
-Thus, XEmacs behaves much like a noninteractive application program.
-(The echo area output that XEmacs itself normally generates, such as
-command echoing, is suppressed entirely.)
-
- - Function: noninteractive
- This function returns non-`nil' when XEmacs is running in batch
- mode.
-
- - Variable: noninteractive
- This variable is non-`nil' when XEmacs is running in batch mode.
- Setting this variable to `nil', however, will not change whether
- XEmacs is running in batch mode, and will not change the return
- value of the `noninteractive' function.
-
-\1f
-File: lispref.info, Node: X-Windows, Next: ToolTalk Support, Prev: System Interface, Up: Top
-
-Functions Specific to the X Window System
-*****************************************
-
-XEmacs provides the concept of "devices", which generalizes connections
-to an X server, a TTY device, etc. Most information about an X server
-that XEmacs is connected to can be determined through general console
-and device functions. *Note Consoles and Devices::. However, there
-are some features of the X Window System that do not generalize well,
-and they are covered specially here.
-
-* Menu:
-
-* X Selections:: Transferring text to and from other X clients.
-* X Server:: Information about the X server connected to
- a particular device.
-* X Miscellaneous:: Other X-specific functions and variables.
-
-\1f
-File: lispref.info, Node: X Selections, Next: X Server, Up: X-Windows
-
-X Selections
-============
-
-The X server records a set of "selections" which permit transfer of
-data between application programs. The various selections are
-distinguished by "selection types", represented in XEmacs by symbols.
-X clients including XEmacs can read or set the selection for any given
-type.
-
- - Function: x-own-selection data &optional type
- This function sets a "selection" in the X server. It takes two
- arguments: a value, DATA, and the selection type TYPE to assign it
- to. DATA may be a string, a cons of two markers, or an extent.
- In the latter cases, the selection is considered to be the text
- between the markers, or between the extent's endpoints.
-
- Each possible TYPE has its own selection value, which changes
- independently. The usual values of TYPE are `PRIMARY' and
- `SECONDARY'; these are symbols with upper-case names, in accord
- with X Windows conventions. The default is `PRIMARY'.
-
- (In FSF Emacs, this function is called `x-set-selection' and takes
- different arguments.)
-
- - Function: x-get-selection
- This function accesses selections set up by XEmacs or by other X
- clients. It returns the value of the current primary selection.
-
- - Function: x-disown-selection &optional secondary-p
- Assuming we own the selection, this function disowns it. If
- SECONDARY-P is non-`nil', the secondary selection instead of the
- primary selection is discarded.
-
- The X server also has a set of numbered "cut buffers" which can
-store text or other data being moved between applications. Cut buffers
-are considered obsolete, but XEmacs supports them for the sake of X
-clients that still use them.
-
- - Function: x-get-cutbuffer &optional n
- This function returns the contents of cut buffer number N. (This
- function is called `x-get-cut-buffer' in FSF Emacs.)
-
- - Function: x-store-cutbuffer string &optional push
- This function stores STRING into the first cut buffer (cut buffer
- 0).
-
- Normally, the contents of the first cut buffer are simply replaced
- by STRING. However, if optional argument PUSH is non-`nil', the
- cut buffers are rotated. This means that the previous value of
- the first cut buffer moves to the second cut buffer, and the
- second to the third, and so on, moving the other values down
- through the series of cut buffers, kill-ring-style. There are 8
- cut buffers altogether.
-
- Cut buffers are considered obsolete; you should use selections
- instead.
-
- This function has no effect if support for cut buffers was not
- compiled in.
-
- This function is called `x-set-cut-buffer' in FSF Emacs.
-
-\1f
-File: lispref.info, Node: X Server, Next: X Miscellaneous, Prev: X Selections, Up: X-Windows
-
-X Server
-========
-
-This section describes how to access and change the overall status of
-the X server XEmacs is using.
-
-* Menu:
-
-* Resources:: Getting resource values from the server.
-* Server Data:: Getting info about the X server.
-* Grabs:: Restricting access to the server by other apps.
-
-\1f
-File: lispref.info, Node: Resources, Next: Server Data, Up: X Server
-
-Resources
----------
-
- - Function: default-x-device
- This function return the default X device for resourcing. This is
- the first-created X device that still exists.
-
- - Function: x-get-resource name class type &optional locale device
- noerror
- This function retrieves a resource value from the X resource
- manager.
-
- * The first arg is the name of the resource to retrieve, such as
- `"font"'.
-
- * The second arg is the class of the resource to retrieve, like
- `"Font"'.
-
- * The third arg should be one of the symbols `string',
- `integer', `natnum', or `boolean', specifying the type of
- object that the database is searched for.
-
- * The fourth arg is the locale to search for the resources on,
- and can currently be a buffer, a frame, a device, or the
- symbol `global'. If omitted, it defaults to `global'.
-
- * The fifth arg is the device to search for the resources on.
- (The resource database for a particular device is constructed
- by combining non-device- specific resources such any
- command-line resources specified and any app-defaults files
- found [or the fallback resources supplied by XEmacs, if no
- app-defaults file is found] with device-specific resources
- such as those supplied using `xrdb'.) If omitted, it defaults
- to the device of LOCALE, if a device can be derived (i.e. if
- LOCALE is a frame or device), and otherwise defaults to the
- value of `default-x-device'.
-
- * The sixth arg NOERROR, if non-`nil', means do not signal an
- error if a bogus resource specification was retrieved (e.g.
- if a non-integer was given when an integer was requested).
- In this case, a warning is issued instead.
-
- The resource names passed to this function are looked up relative
- to the locale.
-
- If you want to search for a subresource, you just need to specify
- the resource levels in NAME and CLASS. For example, NAME could be
- `"modeline.attributeFont"', and CLASS `"Face.AttributeFont"'.
-
- Specifically,
-
- 1. If LOCALE is a buffer, a call
-
- `(x-get-resource "foreground" "Foreground" 'string SOME-BUFFER)'
-
- is an interface to a C call something like
-
- `XrmGetResource (db, "xemacs.buffer.BUFFER-NAME.foreground",
- "Emacs.EmacsLocaleType.EmacsBuffer.Foreground",
- "String");'
-
- 2. If LOCALE is a frame, a call
-
- `(x-get-resource "foreground" "Foreground" 'string SOME-FRAME)'
-
- is an interface to a C call something like
-
- `XrmGetResource (db, "xemacs.frame.FRAME-NAME.foreground",
- "Emacs.EmacsLocaleType.EmacsFrame.Foreground",
- "String");'
-
- 3. If LOCALE is a device, a call
-
- `(x-get-resource "foreground" "Foreground" 'string SOME-DEVICE)'
-
- is an interface to a C call something like
-
- `XrmGetResource (db, "xemacs.device.DEVICE-NAME.foreground",
- "Emacs.EmacsLocaleType.EmacsDevice.Foreground",
- "String");'
-
- 4. If LOCALE is the symbol `global', a call
-
- `(x-get-resource "foreground" "Foreground" 'string 'global)'
-
- is an interface to a C call something like
-
- `XrmGetResource (db, "xemacs.foreground",
- "Emacs.Foreground",
- "String");'
-
- Note that for `global', no prefix is added other than that of the
- application itself; thus, you can use this locale to retrieve
- arbitrary application resources, if you really want to.
-
- The returned value of this function is `nil' if the queried
- resource is not found. If TYPE is `string', a string is returned,
- and if it is `integer', an integer is returned. If TYPE is
- `boolean', then the returned value is the list `(t)' for true,
- `(nil)' for false, and is `nil' to mean "unspecified".
-
- - Function: x-put-resource resource-line &optional device
- This function adds a resource to the resource database for DEVICE.
- RESOURCE-LINE specifies the resource to add and should be a
- standard resource specification.
-
- - Variable: x-emacs-application-class
- This variable holds The X application class of the XEmacs process.
- This controls, among other things, the name of the "app-defaults"
- file that XEmacs will use. For changes to this variable to take
- effect, they must be made before the connection to the X server is
- initialized, that is, this variable may only be changed before
- XEmacs is dumped, or by setting it in the file
- `lisp/term/x-win.el'.
-
- By default, this variable is `nil' at startup. When the connection
- to the X server is first initialized, the X resource database will
- be consulted and the value will be set according to whether any
- resources are found for the application class "XEmacs".
-
-\1f
-File: lispref.info, Node: Server Data, Next: Grabs, Prev: Resources, Up: X Server
-
-Data about the X Server
------------------------
-
-This section describes functions and a variable that you can use to get
-information about the capabilities and origin of the X server
-corresponding to a particular device. The device argument is generally
-optional and defaults to the selected device.
-
- - Function: x-server-version &optional device
- This function returns the list of version numbers of the X server
- DEVICE is on. The returned value is a list of three integers: the
- major and minor version numbers of the X protocol in use, and the
- vendor-specific release number.
-
- - Function: x-server-vendor &optional device
- This function returns the vendor supporting the X server DEVICE is
- on.
-
- - Function: x-display-visual-class &optional device
- This function returns the visual class of the display DEVICE is
- on. The value is one of the symbols `static-gray', `gray-scale',
- `static-color', `pseudo-color', `true-color', and `direct-color'.
- (Note that this is different from previous versions of XEmacs,
- which returned `StaticGray', `GrayScale', etc.)
-
-\1f
-File: lispref.info, Node: Grabs, Prev: Server Data, Up: X Server
-
-Restricting Access to the Server by Other Apps
-----------------------------------------------
-
- - Function: x-grab-keyboard &optional device
- This function grabs the keyboard on the given device (defaulting
- to the selected one). So long as the keyboard is grabbed, all
- keyboard events will be delivered to XEmacs--it is not possible
- for other X clients to eavesdrop on them. Ungrab the keyboard
- with `x-ungrab-keyboard' (use an `unwind-protect'). Returns `t'
- if the grab was successful; `nil' otherwise.
-
- - Function: x-ungrab-keyboard &optional device
- This function releases a keyboard grab made with `x-grab-keyboard'.
-
- - Function: x-grab-pointer &optional device cursor ignore-keyboard
- This function grabs the pointer and restricts it to its current
- window. If optional DEVICE argument is `nil', the selected device
- will be used. If optional CURSOR argument is non-`nil', change
- the pointer shape to that until `x-ungrab-pointer' is called (it
- should be an object returned by the `make-cursor' function). If
- the second optional argument IGNORE-KEYBOARD is non-`nil', ignore
- all keyboard events during the grab. Returns `t' if the grab is
- successful, `nil' otherwise.
-
- - Function: x-ungrab-pointer &optional device
- This function releases a pointer grab made with `x-grab-pointer'.
- If optional first arg DEVICE is `nil' the selected device is used.
- If it is `t' the pointer will be released on all X devices.
-
-\1f
-File: lispref.info, Node: X Miscellaneous, Prev: X Server, Up: X-Windows
-
-Miscellaneous X Functions and Variables
-=======================================
-
- - Variable: x-bitmap-file-path
- This variable holds a list of the directories in which X bitmap
- files may be found. If `nil', this is initialized from the
- `"*bitmapFilePath"' resource. This is used by the
- `make-image-instance' function (however, note that if the
- environment variable `XBMLANGPATH' is set, it is consulted first).
-
- - Variable: x-library-search-path
- This variable holds the search path used by `read-color' to find
- `rgb.txt'.
-
- - Function: x-valid-keysym-name-p keysym
- This function returns true if KEYSYM names a keysym that the X
- library knows about. Valid keysyms are listed in the files
- `/usr/include/X11/keysymdef.h' and in `/usr/lib/X11/XKeysymDB', or
- whatever the equivalents are on your system.
-
- - Function: x-window-id &optional frame
- This function returns the ID of the X11 window. This gives us a
- chance to manipulate the Emacs window from within a different
- program. Since the ID is an unsigned long, we return it as a
- string.
-
- - Variable: x-allow-sendevents
- If non-`nil', synthetic events are allowed. `nil' means they are
- ignored. Beware: allowing XEmacs to process SendEvents opens a
- big security hole.
-
- - Function: x-debug-mode arg &optional device
- With a true arg, make the connection to the X server synchronous.
- With false, make it asynchronous. Synchronous connections are
- much slower, but are useful for debugging. (If you get X errors,
- make the connection synchronous, and use a debugger to set a
- breakpoint on `x_error_handler'. Your backtrace of the C stack
- will now be useful. In asynchronous mode, the stack above
- `x_error_handler' isn't helpful because of buffering.) If DEVICE
- is not specified, the selected device is assumed.
-
- Calling this function is the same as calling the C function
- `XSynchronize', or starting the program with the `-sync' command
- line argument.
-
- - Variable: x-debug-events
- If non-zero, debug information about events that XEmacs sees is
- displayed. Information is displayed on stderr. Currently defined
- values are:
-
- * 1 == non-verbose output
-
- * 2 == verbose output
-
-\1f
-File: lispref.info, Node: ToolTalk Support, Next: LDAP Support, Prev: X-Windows, Up: Top
-
-ToolTalk Support
-****************
-
-* Menu:
-
-* XEmacs ToolTalk API Summary::
-* Sending Messages::
-* Receiving Messages::
-
-\1f
-File: lispref.info, Node: XEmacs ToolTalk API Summary, Next: Sending Messages, Up: ToolTalk Support
-
-XEmacs ToolTalk API Summary
-===========================
-
-The XEmacs Lisp interface to ToolTalk is similar, at least in spirit,
-to the standard C ToolTalk API. Only the message and pattern parts of
-the API are supported at present; more of the API could be added if
-needed. The Lisp interface departs from the C API in a few ways:
-
- * ToolTalk is initialized automatically at XEmacs startup-time.
- Messages can only be sent other ToolTalk applications connected to
- the same X11 server that XEmacs is running on.
-
- * There are fewer entry points; polymorphic functions with keyword
- arguments are used instead.
-
- * The callback interface is simpler and marginally less functional.
- A single callback may be associated with a message or a pattern;
- the callback is specified with a Lisp symbol (the symbol should
- have a function binding).
-
- * The session attribute for messages and patterns is always
- initialized to the default session.
-
- * Anywhere a ToolTalk enum constant, e.g. `TT_SESSION', is valid, one
- can substitute the corresponding symbol, e.g. `'TT_SESSION'. This
- simplifies building lists that represent messages and patterns.
-
-\1f
-File: lispref.info, Node: Sending Messages, Next: Receiving Messages, Prev: XEmacs ToolTalk API Summary, Up: ToolTalk Support
-
-Sending Messages
-================
-
-* Menu:
-
-* Example of Sending Messages::
-* Elisp Interface for Sending Messages::
-
-\1f
-File: lispref.info, Node: Example of Sending Messages, Next: Elisp Interface for Sending Messages, Up: Sending Messages
-
-Example of Sending Messages
----------------------------
-
-Here's a simple example that sends a query to another application and
-then displays its reply. Both the query and the reply are stored in
-the first argument of the message.
-
- (defun tooltalk-random-query-handler (msg)
- (let ((state (get-tooltalk-message-attribute msg 'state)))
- (cond
- ((eq state 'TT_HANDLED)
- (message (get-tooltalk-message-attribute msg arg_val 0)))
- ((memq state '(TT_FAILED TT_REJECTED))
- (message "Random query turns up nothing")))))
-
- (defvar random-query-message
- '( class TT_REQUEST
- scope TT_SESSION
- address TT_PROCEDURE
- op "random-query"
- args '((TT_INOUT "?" "string"))
- callback tooltalk-random-query-handler))
-
- (let ((m (make-tooltalk-message random-query-message)))
- (send-tooltalk-message m))
-
-\1f
-File: lispref.info, Node: Elisp Interface for Sending Messages, Prev: Example of Sending Messages, Up: Sending Messages
-
-Elisp Interface for Sending Messages
-------------------------------------
-
- - Function: make-tooltalk-message attributes
- Create a ToolTalk message and initialize its attributes. The
- value of ATTRIBUTES must be a list of alternating keyword/values,
- where keywords are symbols that name valid message attributes.
- For example:
-
- (make-tooltalk-message
- '(class TT_NOTICE
- scope TT_SESSION
- address TT_PROCEDURE
- op "do-something"
- args ("arg1" 12345 (TT_INOUT "arg3" "string"))))
-
- Values must always be strings, integers, or symbols that represent
- ToolTalk constants. Attribute names are the same as those
- supported by `set-tooltalk-message-attribute', plus `args'.
-
- The value of `args' should be a list of message arguments where
- each message argument has the following form:
-
- `(mode [value [type]])' or just `value'
-
- Where MODE is one of `TT_IN', `TT_OUT', or `TT_INOUT' and TYPE is
- a string. If TYPE isn't specified then `int' is used if VALUE is
- a number; otherwise `string' is used. If TYPE is `string' then
- VALUE is converted to a string (if it isn't a string already) with
- `prin1-to-string'. If only a value is specified then MODE
- defaults to `TT_IN'. If MODE is `TT_OUT' then VALUE and TYPE
- don't need to be specified. You can find out more about the
- semantics and uses of ToolTalk message arguments in chapter 4 of
- the `ToolTalk Programmer's Guide'.
-
-
- - Function: send-tooltalk-message msg
- Send the message on its way. Once the message has been sent it's
- almost always a good idea to get rid of it with
- `destroy-tooltalk-message'.
-
-
- - Function: return-tooltalk-message msg &optional mode
- Send a reply to this message. The second argument can be `reply',
- `reject' or `fail'; the default is `reply'. Before sending a
- reply, all message arguments whose mode is `TT_INOUT' or `TT_OUT'
- should have been filled in--see `set-tooltalk-message-attribute'.
-
-
- - Function: get-tooltalk-message-attribute msg attribute &optional argn
- Returns the indicated ToolTalk message attribute. Attributes are
- identified by symbols with the same name (underscores and all) as
- the suffix of the ToolTalk `tt_message_<attribute>' function that
- extracts the value. String attribute values are copied and
- enumerated type values (except disposition) are converted to
- symbols; e.g. `TT_HANDLER' is `'TT_HANDLER', `uid' and `gid' are
- represented by fixnums (small integers), `opnum' is converted to a
- string, and `disposition' is converted to a fixnum. We convert
- `opnum' (a C int) to a string (e.g. `123' => `"123"') because
- there's no guarantee that opnums will fit within the range of
- XEmacs Lisp integers.
-
- [TBD] Use the `plist' attribute instead of C API `user' attribute
- for user-defined message data. To retrieve the value of a message
- property, specify the indicator for ARGN. For example, to get the
- value of a property called `rflag', use
-
- (get-tooltalk-message-attribute msg 'plist 'rflag)
-
- To get the value of a message argument use one of the `arg_val'
- (strings), `arg_ival' (integers), or `arg_bval' (strings with
- embedded nulls), attributes. For example, to get the integer
- value of the third argument:
-
- (get-tooltalk-message-attribute msg 'arg_ival 2)
-
- As you can see, argument numbers are zero-based. The type of each
- arguments can be retrieved with the `arg_type' attribute; however
- ToolTalk doesn't define any semantics for the string value of
- `arg_type'. Conventionally `string' is used for strings and `int'
- for 32 bit integers. Note that XEmacs Lisp stores the lengths of
- strings explicitly (unlike C) so treating the value returned by
- `arg_bval' like a string is fine.
-
-
- - Function: set-tooltalk-message-attribute value msg attribute
- &optional argn
- Initialize one ToolTalk message attribute.
-
- Attribute names and values are the same as for
- `get-tooltalk-message-attribute'. A property list is provided for
- user data (instead of the `user' message attribute); see
- `get-tooltalk-message-attribute'.
-
- Callbacks are handled slightly differently than in the C ToolTalk
- API. The value of CALLBACK should be the name of a function of one
- argument. It will be called each time the state of the message
- changes. This is usually used to notice when the message's state
- has changed to `TT_HANDLED' (or `TT_FAILED'), so that reply
- argument values can be used.
-
- If one of the argument attributes is specified as `arg_val',
- `arg_ival', or `arg_bval', then ARGN must be the number of an
- already created argument. Arguments can be added to a message
- with `add-tooltalk-message-arg'.
-
-
- - Function: add-tooltalk-message-arg msg mode type &optional value
- Append one new argument to the message. MODE must be one of
- `TT_IN', `TT_INOUT', or `TT_OUT', TYPE must be a string, and VALUE
- can be a string or an integer. ToolTalk doesn't define any
- semantics for TYPE, so only the participants in the protocol
- you're using need to agree what types mean (if anything).
- Conventionally `string' is used for strings and `int' for 32 bit
- integers. Arguments can initialized by providing a value or with
- `set-tooltalk-message-attribute'; the latter is necessary if you
- want to initialize the argument with a string that can contain
- embedded nulls (use `arg_bval').
-
-
- - Function: create-tooltalk-message &optional no-callback
- Create a new ToolTalk message. The message's session attribute is
- initialized to the default session. Other attributes can be
- initialized with `set-tooltalk-message-attribute'.
- `make-tooltalk-message' is the preferred way to create and
- initialize a message.
-
- Optional arg NO-CALLBACK says don't add a C-level callback at all.
- Normally don't do that; just don't specify the Lisp callback when
- calling `make-tooltalk-message'.
-
-
- - Function: destroy-tooltalk-message msg
- Apply `tt_message_destroy' to the message. It's not necessary to
- destroy messages after they've been processed by a message or
- pattern callback, the Lisp/ToolTalk callback machinery does this
- for you.
-
-\1f
-File: lispref.info, Node: Receiving Messages, Prev: Sending Messages, Up: ToolTalk Support
-
-Receiving Messages
-==================
-
-* Menu:
-
-* Example of Receiving Messages::
-* Elisp Interface for Receiving Messages::
-
-\1f
-File: lispref.info, Node: Example of Receiving Messages, Next: Elisp Interface for Receiving Messages, Up: Receiving Messages
-
-Example of Receiving Messages
------------------------------
-
-Here's a simple example of a handler for a message that tells XEmacs to
-display a string in the mini-buffer area. The message operation is
-called `emacs-display-string'. Its first (0th) argument is the string
-to display.
-
- (defun tooltalk-display-string-handler (msg)
- (message (get-tooltalk-message-attribute msg 'arg_val 0)))
-
- (defvar display-string-pattern
- '(category TT_HANDLE
- scope TT_SESSION
- op "emacs-display-string"
- callback tooltalk-display-string-handler))
-
- (let ((p (make-tooltalk-pattern display-string-pattern)))
- (register-tooltalk-pattern p))
-
-\1f
-File: lispref.info, Node: Elisp Interface for Receiving Messages, Prev: Example of Receiving Messages, Up: Receiving Messages
-
-Elisp Interface for Receiving Messages
---------------------------------------
-
- - Function: make-tooltalk-pattern attributes
- Create a ToolTalk pattern and initialize its attributes. The
- value of attributes must be a list of alternating keyword/values,
- where keywords are symbols that name valid pattern attributes or
- lists of valid attributes. For example:
-
- (make-tooltalk-pattern
- '(category TT_OBSERVE
- scope TT_SESSION
- op ("operation1" "operation2")
- args ("arg1" 12345 (TT_INOUT "arg3" "string"))))
-
- Attribute names are the same as those supported by
- `add-tooltalk-pattern-attribute', plus `'args'.
-
- Values must always be strings, integers, or symbols that represent
- ToolTalk constants or lists of same. When a list of values is
- provided all of the list elements are added to the attribute. In
- the example above, messages whose `op' attribute is `"operation1"'
- or `"operation2"' would match the pattern.
-
- The value of ARGS should be a list of pattern arguments where each
- pattern argument has the following form:
-
- `(mode [value [type]])' or just `value'
-
- Where MODE is one of `TT_IN', `TT_OUT', or `TT_INOUT' and TYPE is
- a string. If TYPE isn't specified then `int' is used if VALUE is
- a number; otherwise `string' is used. If TYPE is `string' then
- VALUE is converted to a string (if it isn't a string already) with
- `prin1-to-string'. If only a value is specified then MODE
- defaults to `TT_IN'. If MODE is `TT_OUT' then VALUE and TYPE
- don't need to be specified. You can find out more about the
- semantics and uses of ToolTalk pattern arguments in chapter 3 of
- the `ToolTalk Programmer's Guide'.
-
-
- - Function: register-tooltalk-pattern pattern
- XEmacs will begin receiving messages that match this pattern.
-
- - Function: unregister-tooltalk-pattern pattern
- XEmacs will stop receiving messages that match this pattern.
-
- - Function: add-tooltalk-pattern-attribute value pattern indicator
- Add one value to the indicated pattern attribute. The names of
- attributes are the same as the ToolTalk accessors used to set them
- less the `tooltalk_pattern_' prefix and the `_add' suffix. For
- example, the name of the attribute for the
- `tt_pattern_disposition_add' attribute is `disposition'. The
- `category' attribute is handled specially, since a pattern can only
- be a member of one category (`TT_OBSERVE' or `TT_HANDLE').
-
- Callbacks are handled slightly differently than in the C ToolTalk
- API. The value of CALLBACK should be the name of a function of one
- argument. It will be called each time the pattern matches an
- incoming message.
-
- - Function: add-tooltalk-pattern-arg pattern mode vtype &optional value
- Add one fully-specified argument to a ToolTalk pattern. MODE must
- be one of `TT_IN', `TT_INOUT', or `TT_OUT'. VTYPE must be a
- string. VALUE can be an integer, string or `nil'. If VALUE is an
- integer then an integer argument (`tt_pattern_iarg_add') is added;
- otherwise a string argument is added. At present there's no way
- to add a binary data argument.
-
-
- - Function: create-tooltalk-pattern
- Create a new ToolTalk pattern and initialize its session attribute
- to be the default session.
-
- - Function: destroy-tooltalk-pattern pattern
- Apply `tt_pattern_destroy' to the pattern. This effectively
- unregisters the pattern.
-
- - Function: describe-tooltalk-message msg &optional stream
- Print the message's attributes and arguments to STREAM. This is
- often useful for debugging.
-
-\1f
-File: lispref.info, Node: LDAP Support, Next: PostgreSQL Support, Prev: ToolTalk Support, Up: Top
-
-LDAP Support
-************
-
-XEmacs can be linked with a LDAP client library to provide Elisp
-primitives to access directory servers using the Lightweight Directory
-Access Protocol.
-
-* Menu:
-
-* Building XEmacs with LDAP support:: How to add LDAP support to XEmacs
-* XEmacs LDAP API:: Lisp access to LDAP functions
-* Syntax of Search Filters:: A brief summary of RFC 1558
-
-\1f
-File: lispref.info, Node: Building XEmacs with LDAP support, Next: XEmacs LDAP API, Prev: LDAP Support, Up: LDAP Support
-
-Building XEmacs with LDAP support
-=================================
-
-LDAP support must be added to XEmacs at build time since it requires
-linking to an external LDAP client library. As of 21.2, XEmacs has been
-successfully built and tested with
-
- * OpenLDAP 1.2 (<http://www.openldap.org/>)
-
- * University of Michigan's LDAP 3.3
- (<http://www.umich.edu/~dirsvcs/ldap/>)
-
- * LDAP SDK 1.0 from Netscape Corp. (<http://developer.netscape.com/>)
-
- Other libraries conforming to RFC 1823 will probably work also but
-may require some minor tweaking at C level.
-
- The standard XEmacs configure script auto-detects an installed LDAP
-library provided the library itself and the corresponding header files
-can be found in the library and include paths. A successful detection
-will be signalled in the final output of the configure script.
-
-\1f
-File: lispref.info, Node: XEmacs LDAP API, Next: Syntax of Search Filters, Prev: Building XEmacs with LDAP support, Up: LDAP Support
-
-XEmacs LDAP API
-===============
-
-XEmacs LDAP API consists of two layers: a low-level layer which tries
-to stay as close as possible to the C API (where practical) and a
-higher-level layer which provides more convenient primitives to
-effectively use LDAP.
-
- The low-level API should be used directly for very specific purposes
-(such as multiple operations on a connection) only. The higher-level
-functions provide a more convenient way to access LDAP directories
-hiding the subtleties of handling the connection, translating arguments
-and ensuring compliance with LDAP internationalization rules and formats
-(currently partly implemented only).
-
-* Menu:
-
-* LDAP Variables:: Lisp variables related to LDAP
-* The High-Level LDAP API:: High-level LDAP lisp functions
-* The Low-Level LDAP API:: Low-level LDAP lisp primitives
-* LDAP Internationalization:: I18n variables and functions
-
-\1f
-File: lispref.info, Node: LDAP Variables, Next: The High-Level LDAP API, Prev: XEmacs LDAP API, Up: XEmacs LDAP API
-
-LDAP Variables
---------------
-
- - Variable: ldap-default-host
- The default LDAP server hostname. A TCP port number can be
- appended to that name using a colon as a separator.
-
- - Variable: ldap-default-port
- Default TCP port for LDAP connections. Initialized from the LDAP
- library. Default value is 389.
-
- - Variable: ldap-default-base
- Default base for LDAP searches. This is a string using the syntax
- of RFC 1779. For instance, "o=ACME, c=US" limits the search to the
- Acme organization in the United States.
-
- - Variable: ldap-host-parameters-alist
- An alist of per host options for LDAP transactions. The list
- elements look like `(HOST PROP1 VAL1 PROP2 VAL2 ...)' HOST is the
- name of an LDAP server. A TCP port number can be appended to that
- name using a colon as a separator. PROPN and VALN are
- property/value pairs describing parameters for the server. Valid
- properties:
- `binddn'
- The distinguished name of the user to bind as. This may look
- like `cn=Babs Jensen,o=ACME,c=US', see RFC 1779 for details.
-
- `passwd'
- The password to use for authentication.
-
- `auth'
- The authentication method to use, possible values depend on
- the LDAP library XEmacs was compiled with, they may include
- `simple', `krbv41' and `krbv42'.
-
- `base'
- The base for the search. This may look like `cÿ, o¬me', see
- RFC 1779 for syntax details.
-
- `scope'
- One of the symbols `base', `onelevel' or `subtree' indicating
- the scope of the search limited to a base object, to a single
- level or to the whole subtree.
-
- `deref'
- The dereference policy is one of the symbols `never',
- `always', `search' or `find' and defines how aliases are
- dereferenced.
- `never'
- Aliases are never dereferenced
-
- `always'
- Aliases are always dereferenced
-
- `search'
- Aliases are dereferenced when searching
-
- `find'
- Aliases are dereferenced when locating the base object
- for the search
-
- `timelimit'
- The timeout limit for the connection in seconds.
-
- `sizelimit'
- The maximum number of matches to return for searches
- performed on this connection.
-
- - Variable: ldap-verbose
- If non-`nil', LDAP operations will echo progress messages.
- Defaults to `nil'.
-
-\1f
-File: lispref.info, Node: The High-Level LDAP API, Next: The Low-Level LDAP API, Prev: LDAP Variables, Up: XEmacs LDAP API
-
-The High-Level LDAP API
------------------------
-
-The following functions provide the most convenient interface to perform
-LDAP operations. All of them open a connection to a host, perform an
-operation (add/search/modify/delete) on one or several entries and
-cleanly close the connection thus insulating the user from all the
-details of the low-level interface such as LDAP Lisp objects *note The
-Low-Level LDAP API::.
-
- Note that `ldap-search' which used to be the name of the high-level
-search function in XEmacs 21.1 is now obsolete. For consistency in the
-naming as well as backward compatibility, that function now acts as a
-wrapper that calls either `ldap-search-basic' (low-level search
-function) or `ldap-search-entries' (high-level search function)
-according to the actual parameters. A direct call to one of these two
-functions is preferred since it is faster and unambiguous.
-
- - Command: ldap-search-entries filter &optional host attributes
- attrsonly withdn
- Perform an LDAP search. FILTER is the search filter *note Syntax
- of Search Filters:: HOST is the LDAP host on which to perform the
- search. ATTRIBUTES is the specific attributes to retrieve, `nil'
- means retrieve all. ATTRSONLY if non-`nil' retrieves the
- attributes only without their associated values. If WITHDN is
- non-`nil' each entry in the result will be prepended with its
- distinguished name DN. Additional search parameters can be
- specified through `ldap-host-parameters-alist'. The function
- returns a list of matching entries. Each entry is itself an alist
- of attribute/value pairs optionally preceded by the DN of the
- entry according to the value of WITHDN.
-
- - Function: ldap-add-entries entries &optional host binddn passwd
- Add entries to an LDAP directory. ENTRIES is a list of entry
- specifications of the form `(DN (ATTR . VALUE) (ATTR . VALUE) ...)'
- where DN the distinguished name of an entry to add, the following
- are cons cells containing attribute/value string pairs. HOST is
- the LDAP host, defaulting to `ldap-default-host'. BINDDN is the
- DN to bind as to the server. PASSWD is the corresponding password.
-
- - Function: ldap-modify-entries entry-mods &optional host binddn passwd
- Modify entries of an LDAP directory. ENTRY_MODS is a list of
- entry modifications of the form `(DN MOD-SPEC1 MOD-SPEC2 ...)'
- where DN is the distinguished name of the entry to modify, the
- following are modification specifications. A modification
- specification is itself a list of the form `(MOD-OP ATTR VALUE1
- VALUE2 ...)' MOD-OP and ATTR are mandatory, VALUES are optional
- depending on MOD-OP. MOD-OP is the type of modification, one of
- the symbols `add', `delete' or `replace'. ATTR is the LDAP
- attribute type to modify. HOST is the LDAP host, defaulting to
- `ldap-default-host'. BINDDN is the DN to bind as to the server.
- PASSWD is the corresponding password.
-
- - Function: ldap-delete-entries dn &optional host binddn passwd
- Delete an entry from an LDAP directory. DN is the distinguished
- name of an entry to delete or a list of those. HOST is the LDAP
- host, defaulting to `ldap-default-host'. BINDDN is the DN to bind
- as to the server. PASSWD is the corresponding password.
-
-\1f
-File: lispref.info, Node: The Low-Level LDAP API, Next: LDAP Internationalization, Prev: The High-Level LDAP API, Up: XEmacs LDAP API
-
-The Low-Level LDAP API
-----------------------
-
-The low-level API should be used directly for very specific purposes
-(such as multiple operations on a connection) only. The higher-level
-functions provide a more convenient way to access LDAP directories
-hiding the subtleties of handling the connection, translating arguments
-and ensuring compliance with LDAP internationalization rules and formats
-(currently partly implemented only). See *note The High-Level LDAP API::
-
- Note that the former functions `ldap-*-internal' functions have been
-renamed in XEmacs 21.2
-
-* Menu:
-
-* The LDAP Lisp Object::
-* Opening and Closing a LDAP Connection::
-* Low-level Operations on a LDAP Server::
-
projects / chise / xemacs-chise.git / blobdiff