-This is ../info/lispref.info, produced by makeinfo version 4.0 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: Sequence Functions, Next: Arrays, Up: Sequences Arrays Vectors
+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::.
-Sequences
-=========
+\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
+
+49.2.4 Font Instance Size
+-------------------------
+
+ -- 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
+ 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
+ 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
+ which is 1 point smaller. Otherwise, it returns the next smaller
+ version of this font that is defined.
+
+\1f
+File: lispref.info, Node: Font Instance Characteristics, Next: Font Convenience Functions, Prev: Font Instance Size, Up: Fonts
+
+49.2.5 Font Instance Characteristics
+------------------------------------
+
+ -- 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
+ 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
+ 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
+ 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
+ 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
+ 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
+
+49.2.6 Font Convenience Functions
+---------------------------------
+
+ -- 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
+ 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
+ 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
+ omitted. This is equivalent to using `specifier-instance' and
+ applying `font-instance-properties' to the result.
+
+\1f
+File: lispref.info, Node: Colors, Prev: Fonts, Up: Faces and Window-System Objects
+
+49.3 Colors
+===========
+
+* Menu:
+
+* Color Specifiers:: Specifying how a color will appear.
+* Color Instances:: What a color specifier gets instanced as.
+* Color Instance Properties:: Properties of color instances.
+* Color Convenience Functions:: Convenience functions that automatically
+ instance and retrieve the properties
+ of a color specifier.
+
+\1f
+File: lispref.info, Node: Color Specifiers, Next: Color Instances, Up: Colors
+
+49.3.1 Color Specifiers
+-----------------------
+
+ -- Function: color-specifier-p object
+ This function returns non-`nil' if OBJECT is a color specifier.
+
+ -- 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
+ instantiator, or a list of instantiators. *Note Specifiers::, for
+ a detailed description of how specifiers work.
+
+ Valid instantiators for color specifiers are:
+
+ * A string naming a color (e.g. under X this might be
+ "lightseagreen2" or "#F534B2").
+
+ * A color 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
+ color at all, thus using the "natural" color of the
+ terminal's text).
+
+ * A vector of one or two elements: a face to inherit from, and
+ optionally a symbol naming which property of that face to
+ inherit, either `foreground' or `background' (if omitted,
+ defaults to the same property that this color specifier is
+ used for; if this specifier is not part of a face, the
+ instantiator would not be valid).
+
+ -- 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
+ instantiator, or a list of instantiators. *Note Specifiers::, for
+ a detailed description of how specifiers work.
+
+ Valid instantiators for face-boolean specifiers are
+
+ * t or nil.
+
+ * A vector of two or three elements: a face to inherit from,
+ optionally a symbol naming the property of that face to
+ inherit from (if omitted, defaults to the same property that
+ this face-boolean specifier is used for; if this specifier is
+ not part of a face, the instantiator would not be valid), and
+ optionally a value which, if non-`nil', means to invert the
+ sense of the inherited property.
+
+
+\1f
+File: lispref.info, Node: Color Instances, Next: Color Instance Properties, Prev: Color Specifiers, Up: Colors
+
+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
+`face-background-instance' return a color-instance object. For example,
+
+ (face-background-instance 'default (next-window))
+ => #<color-instance moccasin 47=(FFFF,E4E4,B5B5) 0x678d>
+
+ The color-instance object returned describes the way the background
+color of the `default' face is displayed in the next window after the
+selected one.
+
+ -- 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
+
+49.3.3 Color Instance Properties
+--------------------------------
+
+ -- Function: color-instance-name color-instance
+ This function returns the name used to allocate 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.
+
+ (color-instance-rgb-components
+ (face-background-instance 'default (next-window)))
+ => (65535 58596 46517)
+
+\1f
+File: lispref.info, Node: Color Convenience Functions, Prev: Color Instance Properties, Up: Colors
+
+49.3.4 Color Convenience Functions
+----------------------------------
+
+ -- 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
+ 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
+ selected window if omitted. This is equivalent to using
+ `specifier-instance' and applying `color-instance-rgb-components'
+ to the result.
+
+ (color-rgb-components (face-background 'default (next-window)))
+ => (65535 58596 46517)
+
+\1f
+File: lispref.info, Node: Glyphs, Next: Annotations, Prev: Faces and Window-System Objects, Up: Top
+
+50 Glyphs
+*********
+
+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,
+any place there is an image or something that acts like an image, there
+will be a glyph object representing it.
+
+ -- Function: glyphp object
+ This function returns `t' if OBJECT is a glyph.
+
+* Menu:
+
+* 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 Intro, Next: Images, Up: Glyphs
+
+50.1 Glyph Introduction
+=======================
+
+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: Images, Next: Using Glyphs, Prev: Glyph Intro, Up: Glyphs
+
+50.2 Images
+===========
+
+* Menu:
+
+* Image Specifiers:: Specifying an image's appearance.
+* Image Instantiator Conversion:: Lazy realization of graphics.
+* Image Instantiator Formats:: A catalog of image descriptors.
+* Image Instances:: Classes of graphical objects.
+
+\1f
+File: lispref.info, Node: Image Specifiers, Next: Image Instantiator Conversion, Up: Images
+
+50.2.1 Image Specifiers
+-----------------------
+
+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.
+
+ -- Function: make-image-specifier spec-list
+ This function creates a new image specifier object and initializes
+ it according to SPEC-LIST. *Note Specifiers::.
+
+ 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.
+
+ 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.).
+
+ *Note Image Instances::, for a more detailed discussion of image
+instance types.
+
+ An image instantiator should be a string or a vector of the form
+
+ `[FORMAT :KEYWORD VALUE ...]'
+
+ i.e. a format symbol followed by zero or more alternating
+keyword-value pairs.
+
+ The form of an instantiator can be checked with
+`valid-instantiator-p' with a TYPE of `image', *Note Specifier
+Validation Functions::.
+
+ For a complete list of the format symbols and their usage, *Note
+Image Instantiator Formats::.
+
+ If the instantiator is a string, it will be converted into a vector
+by looking it up according to the specs in the
+`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
+
+50.2.4.1 Image Instance Types
+.............................
+
+Image instances come in a number of different types. The type of an
+image instance specifies the nature of the image: Whether it is a text
+string, a mono pixmap, a color pixmap, etc.
+
+ The valid image instance types are
+
+`nothing'
+ Nothing is displayed.
+
+`text'
+ Displayed as text. The foreground and background colors and the
+ font of the text are specified independent of the pixmap.
+ Typically these attributes will come from the face of the
+ surrounding text, unless a face is specified for the glyph in
+ which the image appears.
+
+`mono-pixmap'
+ Displayed as a mono pixmap (a pixmap with only two colors where the
+ foreground and background can be specified independent of the
+ pixmap; typically the pixmap assumes the foreground and background
+ colors of the text around it, unless a face is specified for the
+ glyph in which the image appears).
+
+`color-pixmap'
+ Displayed as a color pixmap.
+
+`pointer'
+ Used as the mouse pointer for a window.
+
+`subwindow'
+ A child window that is treated as an image. This allows (e.g.)
+ another program to be responsible for drawing into the window.
+ Not currently implemented.
+
+`widget'
+ An active GUI element implemented as a "widget" or "control" of the
+ underlying window system.
+
+ The following functions are used to check whether an image instance
+type is valid in the running XEmacs.
+
+ -- Function: valid-image-instance-type-p type
+ This function returns non-`nil' if TYPE is a valid image instance
+ type.
+
+ -- Function: image-instance-type-list
+ This function returns a list of the valid image instance types.
+
+ The following functions are used to determine the type of an image
+instance.
+
+ -- 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'.
+
+ -- Function: text-image-instance-p object
+ Return non-`nil' if OBJECT is an image instance of type `text'.
+
+ -- Function: mono-pixmap-image-instance-p object
+ Return non-`nil' if OBJECT is an image instance of type
+ `mono-pixmap'.
+
+ -- Function: color-pixmap-image-instance-p object
+ Return non-`nil' if OBJECT is an image instance of type
+ `color-pixmap'.
+
+ -- Function: pointer-image-instance-p object
+ Return non-`nil' if OBJECT is an image instance of type `pointer'.
+
+ -- 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: Image Instance Functions, Prev: Image Instance Types, Up: Image Instances
+
+50.2.4.2 Image Instance Functions
+.................................
+
+ -- Function: make-image-instance data &optional domain dest-types
+ noerror
+ This function creates a new image-instance object.
+
+ DATA is an image instantiator, which describes the image (*note
+ Image Specifiers::).
+
+ DEST-TYPES should be a list of allowed image instance types that
+ can be generated. The DEST-TYPES list is unordered. If multiple
+ destination types are possible for a given instantiator, the "most
+ natural" type for the instantiator's format is chosen. These are
+
+ `XBM'
+ `xface'
+ `mono-pixmap', then `color-pixmap', then `pointer'.
+
+ `XPM'
+ `GIF'
+ `JPEG'
+ `PNG'
+ `TIFF'
+ `color-pixmap', then `mono-pixmap', then `pointer'.
+
+ `string'
+ `formatted-string formats'
+ `text', then `mono-pixmap' (not currently implemented), then
+ `color-pixmap' (not currently implemented).
+
+ `mswindows-resource'
+ For pointer resources, `pointer'.
+
+ For the others, `color-pixmap'.
+
+ The other formats can only be instantiated as one type.
+
+ If you want to control more specifically the order of the types
+ into which an image is instantiated, call `make-image-instance'
+ repeatedly until it succeeds, passing less and less preferred
+ destination types each time.
+
+ If DEST-TYPES is omitted, all possible types are allowed.
+
+ DOMAIN specifies the domain to which the image instance will be
+ attached. This domain is termed the "governing domain". The type
+ of the governing domain depends on the image instantiator format.
+ (Although, more correctly, it should probably depend on the image
+ instance type.) For example, pixmap image instances are specific
+ to a device, but widget image instances are specific to a
+ particular 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.
+
+ Pixmaps are considered to be three-dimensional. The height and
+width of the pixel array that is displayed, and the color depth of its
+pixels, are accessed with these functions.
+
+ -- Function: image-instance-depth image-instance
+ This function returns the depth of the image instance. This is 0
+ for a mono pixmap, or a positive integer for a color pixmap.
+
+ -- Function: image-instance-height image-instance
+ This function returns the height of the image instance, in pixels.
+
+ -- Function: image-instance-width image-instance
+ This function returns the width of the image instance, in pixels.
+
+ The hotspot is a point relative to the origin of the pixmap. When
+an image is used as a mouse pointer, the hotspot is the point on the
+image that sits over the location that the pointer points to. This is,
+for example, the tip of the arrow or the center of the crosshairs.
+
+ These functions access the coordinates of the hotspot. They simply
+return `nil' for a non-pointer image instance.
+
+ -- Function: image-instance-hotspot-x image-instance
+ This function returns the X coordinate of the image instance's
+ hotspot, if known.
+
+ -- Function: image-instance-hotspot-y image-instance
+ This function returns the Y coordinate of the image instance's
+ hotspot, if known.
+
+ Mono pixmaps and pointers may have their foreground and background
+colors set when instanced. Use these functions to access color
+information.
+
+ -- Function: image-instance-foreground image-instance
+ This function returns the foreground color of IMAGE-INSTANCE, if
+ applicable. This will be a color instance or `nil'. (It will only
+ be non-`nil' for colorized mono pixmaps and for pointers.)
+
+ -- Function: image-instance-background image-instance
+ This function returns the background color of IMAGE-INSTANCE, if
+ applicable. This will be a color instance or `nil'. (It will only
+ be non-`nil' for colorized mono pixmaps and for pointers.)
+
+\1f
+File: lispref.info, Node: Using Glyphs, Next: Manipulating Glyphs, Prev: Images, Up: Glyphs
+
+50.3 Using Glyphs
+=================
+
+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:
+
+* 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: Creating Glyphs, Next: Buffer Glyphs, Up: Using Glyphs
+
+50.3.1 Creating Glyphs
+----------------------
+
+ -- Function: make-glyph &optional spec-list type
+ This function creates a new glyph object of type TYPE.
+
+ 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.
+
+ -- 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'.
+
+ `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'.
+
+ -- 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'.
+
+ `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'.
+
+\1f
+File: lispref.info, Node: Buffer Glyphs, Next: Redisplay Glyphs, Prev: Creating Glyphs, Up: Using Glyphs
+
+50.3.2 Buffer 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. 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'.)
+
+
+\1f
+File: lispref.info, Node: Redisplay Glyphs, Next: Frame Glyphs, Prev: Buffer Glyphs, Up: Using Glyphs
+
+50.3.3 Redisplay Glyphs
+-----------------------
+
+To use a glyph to control the shape of miscellaneous redisplay effects
+such as the truncation and continuation markers, set the appropriate
+existing glyph variables with `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.
+
+ -- 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: 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.
+
+
+\1f
+File: lispref.info, Node: External Glyphs, Next: Native GUI Widgets, Prev: Frame Glyphs, Up: Using Glyphs
+
+50.3.5 External Glyphs
+----------------------
+
+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.)
+
+ 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: Native GUI Widgets, Next: Subwindows, Prev: External Glyphs, Up: Using Glyphs
+
+50.3.6 Native GUI Widgets
+-------------------------
+
+A "native widget" is a primitive GUI object defined either by the host
+GUI platform or an external toolkit, and accessed from Lisp as a
+"glyph."
+
+* Menu:
+
+* Introduction to Widgets:: Native widgets provide tight integration of
+ GUI features with the platform GUI.
+* Lisp API to Native Widgets:: Native widgets are glyphs.
+* Layouts:: Specifying composite widgets from Lisp.
+* Primitive Widgets:: Catalogue of available native widgets.
+
+\1f
+File: lispref.info, Node: Introduction to Widgets, Next: Lisp API to Native Widgets, Up: Native GUI Widgets
+
+50.3.6.1 Introduction to Native Widgets and Subwindow Glyphs
+............................................................
+
+Traditionally Emacsen have hidden the GUI apparatus from the Lisp
+programmer, but in XEmacs 21.4 the ability to embed autonomous GUI
+objects, called "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.
+
+ 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.
+
+\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.
+
+\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)))])])])
+
+\1f
+File: lispref.info, Node: Primitive Widgets, Prev: Layouts, Up: Native GUI Widgets
+
+50.3.6.4 Primitive Widgets
+..........................
+
+`button'
+ A button widget; either a push button, radio button or toggle
+ button.
+
+`combo-box'
+ A drop list of selectable items in a widget, for editing text.
+
+`edit-field'
+ A text editing widget.
+
+`label'
+ A static, text-only, widget; for displaying text.
+
+`progress-gauge'
+ A sliding widget, for showing progress.
+
+`tab-control'
+ A tab widget; a series of user selectable tabs.
+
+`tree-view'
+ A folding widget.
+
+`scrollbar'
+ A scrollbar widget. (#### Probably not the same as the scrollbar
+ controlling an Emacs window.)
+
+\1f
+File: lispref.info, Node: Subwindows, Prev: Native GUI Widgets, Up: Using Glyphs
+
+50.3.7 Subwindows
+-----------------
+
+Subwindows are not currently implemented.
+
+ -- Function: subwindowp object
+ This function returns non-`nil' if OBJECT is a subwindow.
+
+\1f
+File: lispref.info, Node: Manipulating Glyphs, Next: Glyph Examples, Prev: Using Glyphs, Up: Glyphs
+
+50.4 Manipulating Glyphs
+========================
+
+Each glyphs has properties that may be accessed. Most of these can
+also be set after the glyph is initialized, with the exception of the
+glyph's type. This is not a real restriction, as it is almost never
+useful to create glyphs of types other than `buffer'.
+
+* Menu:
+
+* 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: Glyph Properties, Next: Glyph Convenience Functions, Up: Manipulating Glyphs
+
+50.4.1 Glyph Properties
+-----------------------
+
+Each glyph has a list of properties, which control all of the aspects of
+the glyph's appearance. The following symbols have predefined meanings:
+
+`image'
+ The image used to display the glyph.
+
+`baseline'
+ Percent above baseline that glyph is to be displayed. Only for
+ glyphs displayed inside of a buffer.
+
+`contrib-p'
+ Whether the glyph contributes to the height of the line it's on.
+ Only for glyphs displayed inside of a buffer.
+
+`face'
+ Face of this glyph (_not_ a specifier).
+
+ -- Function: set-glyph-property glyph property value &optional locale
+ tag-set how-to-add
+ This function changes a property of a GLYPH.
+
+ For built-in properties, the actual value of the property is a
+ specifier and you cannot change this; but you can change the
+ specifications within the specifier, and that is what this
+ function will do. 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.
+
+ 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
+ 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).
+
+ * 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
+ `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).
+
+ 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 `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.
+
+ 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: glyph-property glyph property &optional locale
+ This function returns GLYPH's value of the given PROPERTY.
+
+ 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.
+
+ 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: glyph-property-instance glyph property &optional domain
+ default no-fallback
+ This function returns the instance of GLYPH'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 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).
+
+ DOMAIN defaults to the selected window if omitted.
+
+ DOMAIN can be a frame or device, instead of a window. The value
+ returned for such a domain is used in special circumstances when a
+ more specific domain does not apply; for example, a frame value
+ might be used for coloring a toolbar, which is conceptually
+ attached to a frame rather than a particular window. The value is
+ also useful in determining what the value would be for a
+ particular window within the frame or device, if it is not
+ overridden by a more specific specification.
+
+ If 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::.
+
+ -- 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: Glyph Convenience Functions, Next: Glyph Dimensions, Prev: Glyph Properties, Up: Manipulating Glyphs
+
+50.4.2 Glyph Convenience Functions
+----------------------------------
+
+The following functions are provided for working with specific
+properties of a glyph. Note that these are exactly like calling the
+general functions described above and passing in the appropriate value
+for PROPERTY.
+
+ 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.)
+
+ -- 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.
+
+ -- 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'.
+
+ -- 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.
+
+ 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.
+
+ -- 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: 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: 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: 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: 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: 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'.
+
+ 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: glyph-face glyph
+ This function returns the face of GLYPH. (Remember, this is not a
+ specifier, but a simple property.)
+
+ -- Function: set-glyph-face glyph face
+ This function changes the face of GLYPH to FACE.
+
+\1f
+File: lispref.info, Node: Glyph Dimensions, Next: Glyph Types, Prev: Glyph Convenience Functions, Up: Manipulating Glyphs
+
+50.4.3 Glyph Dimensions
+-----------------------
+
+ -- 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: 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: 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: 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, Prev: Glyph Dimensions, Up: Manipulating Glyphs
+
+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
+image instance types that can be generated. When you call
+`glyph-image-instance' to retrieve the image instance of a glyph,
+XEmacs does the equivalent of calling `make-image-instance' and passing
+in DEST-TYPES the list of allowable image instance types for the
+glyph's type.
+
+ * `buffer' glyphs can be used as the begin-glyph or end-glyph of an
+ extent, in the modeline, and in the toolbar. Their image can be
+ instantiated as `nothing', `mono-pixmap', `color-pixmap', `text',
+ and `subwindow'.
+
+ * `pointer' glyphs can be used to specify the mouse pointer. Their
+ image can be instantiated as `pointer'.
+
+ * `icon' glyphs can be used to specify the icon used when a frame is
+ iconified. Their image can be instantiated as `mono-pixmap' and
+ `color-pixmap'.
+
+ -- Function: glyph-type glyph
+ This function returns the type of the given glyph. The return
+ value will be a symbol, one of `buffer', `pointer', or `icon'.
+
+ -- Function: valid-glyph-type-p glyph-type
+ Given a GLYPH-TYPE, this function returns non-`nil' if it is valid.
+
+ -- Function: glyph-type-list
+ This function returns a list of valid glyph types.
+
+ -- Function: buffer-glyph-p object
+ This function returns non-`nil' if OBJECT is a glyph of type
+ `buffer'.
+
+ -- Function: icon-glyph-p object
+ This function returns non-`nil' if OBJECT is a glyph of type
+ `icon'.
+
+ -- Function: pointer-glyph-p object
+ This function returns non-`nil' if OBJECT is a glyph of type
+ `pointer'.
+
+\1f
+File: lispref.info, Node: Glyph Examples, Prev: Manipulating Glyphs, Up: Glyphs
+
+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.
+
+ The easiest way to create a glyph is to use a file that contains a
+graphical image, such as a JPEG, TIFF, or PNG file:
+
+ ;; Create a glyph from a JPEG file:
+ (setq foo (make-glyph [jpeg :file "/tmp/file1.jpg"]))
+
+ ;; Create a glyph from a XPM file:
+ (setq foo (make-glyph [xpm :file "/tmp/file2.xpm"]))
+
+ ;; Create a glyph from a PNG file:
+ (setq foo (make-glyph [png :file "/tmp/file3.png"]))
+
+ ;; Create a glyph from a TIFF file:
+ (setq foo (make-glyph [tiff :file "/tmp/file4.tiff"]))
+
+ The parameters passed to `make-glyph' are called "Image Specifiers",
+and can handle more image types than those shown above. You can also
+put the raw image data into a string (e.g., if you put the contents of
+a JPEG file into a string), and use that to create a glyph. *Note
+Image Specifiers::, for more information.
+
+ *Caution*: In order for XEmacs to read a particular graphics file
+ format, support for that format must have been compiled into
+ XEmacs. It's possible, although somewhat unlikely, for XEmacs to
+ have been compiled without support for any of the various graphics
+ file formats. To see what graphics formats your particular
+ version of XEmacs supports, use `M-x describe-installation'.
+
+ To programmatically query whether or not a particular file format
+ is supported, you can use the `featurep' function, with one of:
+ `gif', `tiff', `jpeg', `xpm', `xbm', `png', or `xface'. For an
+ up-to-date list, *Note Image Specifiers::. Example:
+
+ ;; Returns `t' if TIFF is supported:
+ (featurep 'tiff)
+
+ Another example is:
+
+ ;; Returns a list of `t' or `nil', depending on whether or not the
+ ;; corresponding feature is supported:
+ (mapcar #'(lambda (format-symbol) (featurep format-symbol))
+ '(gif tiff jpeg xpm png))
+
+
+ Once you have a glyph, you can then insert it into a buffer.
+Example:
+
+ ;; Use this function to insert a glyph at the left edge of point in the
+ ;; current buffer. Any existing glyph at this location is replaced.
+ (defun insert-glyph (gl)
+ "Insert a glyph at the left edge of point."
+ (let ( (prop 'myimage) ;; myimage is an arbitrary name, chosen
+ ;; to (hopefully) not conflict with any
+ ;; other properties. Change it if
+ ;; necessary.
+ extent )
+ ;; First, check to see if one of our extents already exists at
+ ;; point. For ease-of-programming, we are creating and using our
+ ;; own extents (multiple extents are allowed to exist/overlap at the
+ ;; same point, and it's quite possible for other applications to
+ ;; embed extents in the current buffer without your knowledge).
+ ;; Basically, if an extent, with the property stored in "prop",
+ ;; exists at point, we assume that it is one of ours, and we re-use
+ ;; it (this is why it is important for the property stored in "prop"
+ ;; to be unique, and only used by us).
+ (if (not (setq extent (extent-at (point) (current-buffer) prop)))
+ (progn
+ ;; If an extent does not already exist, create a zero-length
+ ;; extent, and give it our special property.
+ (setq extent (make-extent (point) (point) (current-buffer)))
+ (set-extent-property extent prop t)
+ ))
+ ;; 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
+ (insert-glyph (make-glyph [jpeg :file "/tmp/file1.jpg"]))
+ ;; Create a new extent at point. We can't simply call "insert-glyph",
+ ;; as "insert-glyph" will simply replace the first glyph with the
+ ;; second.
+ (setq extent (make-extent (point) (point) (current-buffer)))
+ ;; Here, we're only setting the 'myimage property in case we need
+ ;; to later identify/locate/reuse this particular extent.
+ (set-extent-property extent 'myimage t)
+ (set-extent-property extent 'begin-glyph
+ (make-glyph [jpeg :file "/tmp/file2.jpg"]))
+ )
+
+ Here are the gory details:
+
+ * Glyphs are displayed by attaching them to extents (see *Note
+ Extents::), either to the beginning or the end of extents.
+
+ Note that extents can be used for many things, and not just for
+ displaying images (although, in the above example, we are creating
+ our own extent for the sole purpose of displaying an image).
+ Also, note that multiple extents are allowed to exist at the same
+ position, and they can overlap.
+
+ * Glyphs are often displayed inside the text area (alongside text).
+ This is the default.
+
+ Although glyphs can also be displayed in the margins, how to do
+ this will not be described here. For more information on this, see
+ *Note Annotation Basics:: (look for information on "layout types")
+ and *Note Extent Properties:: (look for `begin-glyph-layout' and
+ `end-glyph-layout').
+
+ * The easiest way to insert a glyph into text is to create a
+ zero-length extent at the point where you want the glyph to appear.
+
+ Note that zero-length extents are attached to the character to the
+ right of the extent; deleting this character will also delete the
+ extent.
+
+ * It's often a good idea to assign a unique property to the
+ newly-created extent, in case you later want to locate it, and
+ replace any existing glyph with a different one (or just delete
+ the existing one). In the above example, we are using "myimage"
+ as our (hopefully) unique property name.
+
+ If you need to locate all of the extents, you'll have to use
+ functions like `extent-list' or `next-extent', or provide
+ additional parameters to the `extent-at' function. Assigning a
+ unique property to the extent makes it easy to locate your
+ extents; for example, `extent-list' can return only those extents
+ with a particular property. *Note Finding Extents::, and *Note
+ Mapping Over Extents::, for more information.
+
+ * Glyphs are displayed by assigning then to the `begin-glyph' or
+ `end-glyph' property of the extent. For zero-length extents, it
+ doesn't really matter if you assign the glyph to the `begin-glyph'
+ or `end-glyph' property, as they are both at the same location;
+ however, for non-zero-length extents (extents that cover one or
+ more characters of text), it does matter which one you use.
+
+ Assigning `nil' to the `begin-glyph' or `end-glyph' property will
+ delete any existing glyph. In this case, you may also want to
+ delete the extent, assuming that the extent is used for no other
+ purpose.
+
+ * If you happen to insert two glyphs, side-by-side, note that the
+ example `insert-glyph' function will have trouble, if it's again
+ used at the same point (it can only locate one of the two extents).
+ *Note Finding Extents::, and *Note Mapping Over Extents::, for more
+ information on locating extents in a buffer.
+
+ * Among other things, glyphs provide a way of displaying graphics
+ alongside text. Note, however, that glyphs only provide a way of
+ displaying graphics; glyphs are not actually part of the text, and
+ are only displayed alongside the text. If you save the text in
+ the buffer, the graphics are not saved. The low-level glyph code
+ does not provide a way of saving graphics with the text. If you
+ need to save graphics and text, you have to write your own code to
+ do this, and this topic is outside the scope of this discussion.
+
+
+\1f
+File: lispref.info, Node: Annotations, Next: Display, Prev: Glyphs, Up: Top
+
+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.
+Annotations can be displayed intermixed with text, in any whitespace at
+the beginning or end of a line, or in a special area at the left or
+right side of the frame called a "margin", whose size is controllable.
+Annotations are implemented using extents (*note Extents::); but you
+can work with annotations without knowing how extents work.
+
+* Menu:
+
+* Annotation Basics:: Introduction to annotations.
+* Annotation Primitives:: Creating and deleting annotations.
+* Annotation Properties:: Retrieving and changing the characteristics
+ of an annotation.
+* Margin Primitives:: Controlling the size of the margins.
+* Locating Annotations:: Looking for annotations in a buffer.
+* Annotation Hooks:: Hooks called at certain times during an
+ annotation's lifetime.
+
+\1f
+File: lispref.info, Node: Annotation Basics, Next: Annotation Primitives, Up: Annotations
+
+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
+right-hand side of the frame, in any whitespace at the beginning or end
+of a line, or inside of the text itself. Every annotation may have an
+associated action to be performed when the annotation is selected. The
+term "annotation" is used to refer to an individual note. The term
+"margin" is generically used to refer to the whitespace before the
+first character on a line or after the last character on a line.
+
+ Each annotation has the following characteristics:
+GLYPH
+ This is a glyph object and is used as the displayed representation
+ of the annotation.
+
+DOWN-GLYPH
+ If given, this glyph is used as the displayed representation of
+ the annotation when the mouse is pressed down over the annotation.
+
+FACE
+ The face with which to display the glyph.
+
+SIDE
+ Which side of the text (left or right) the annotation is displayed
+ at.
+
+ACTION
+ If non-`nil', this field must contain a function capable of being
+ the first argument to `funcall'. This function is normally
+ evaluated with a single argument, the value of the DATA field,
+ each time the annotation is selected. However, if the WITH-EVENT
+ parameter to `make-annotation' is non-`nil', the function is
+ called with two arguments. The first argument is the same as
+ before, and the second argument is the event (a button-up event,
+ usually) that activated the annotation.
+
+DATA
+ Not used internally. This field can contain any E-Lisp object.
+ It is passed as the first argument to ACTION described above.
+
+MENU
+ A menu displayed when the right mouse button is pressed over the
+ annotation.
+
+ The margin is divided into "outside" and "inside". The outside
+margin is space on the left or right side of the frame which normal text
+cannot be displayed in. The inside margin is that space between the
+leftmost or rightmost point at which text can be displayed and where the
+first or last character actually is.
+
+ There are four different "layout types" which affect the exact
+location an annotation appears.
+
+`outside-margin'
+ The annotation is placed in the outside margin area. as close as
+ possible to the edge of the frame. If the outside margin is not
+ wide enough for an annotation to fit, it is not displayed.
+
+`inside-margin'
+ The annotation is placed in the inside margin area, as close as
+ possible to the edge of the frame. If the inside margin is not
+ wide enough for the annotation to fit, it will be displayed using
+ any available outside margin space if and only if the specifier
+ `use-left-overflow' or `use-right-overflow' (depending on which
+ side the annotation appears in) is non-`nil'.
+
+`whitespace'
+ The annotation is placed in the inside margin area, as close as
+ possible to the first or last non-whitespace character on a line.
+ If the inside margin is not wide enough for the annotation to fit,
+ it will be displayed if and only if the specifier
+ `use-left-overflow' or `use-right-overflow' (depending on which
+ side the annotation appears in) is non-`nil'.
+
+`text'
+ The annotation is placed at the position it is inserted. It will
+ create enough space for itself inside of the text area. It does
+ not take up a place in the logical buffer, only in the display of
+ the buffer.
+
+ The current layout policy is that all `whitespace' annotations are
+displayed first. Next, all `inside-margin' annotations are displayed
+using any remaining space. Finally as many `outside-margin'
+annotations are displayed as possible. The `text' annotations will
+always display as they create their own space to display in.
+
+\1f
+File: lispref.info, Node: Annotation Primitives, Next: Annotation Properties, Prev: Annotation Basics, Up: Annotations
+
+51.2 Annotation Primitives
+==========================
+
+ -- 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
+ a glyph object or a string, and is positioned using layout policy
+ LAYOUT. If POSITION is `nil', point is used. If LAYOUT is `nil',
+ `whitespace' is used. If BUFFER is `nil', the current buffer is
+ used.
+
+ If WITH-EVENT is non-`nil', then when an annotation is activated,
+ the triggering event is passed as the second arg to the annotation
+ function. If D-GLYPH is non-`nil' then it is used as the glyph
+ that will be displayed when button1 is down. If RIGHTP is
+ non-`nil' then the glyph will be displayed on the right side of
+ the buffer instead of the left.
+
+ The newly created annotation is returned.
+
+ -- Function: delete-annotation annotation
+ This function removes ANNOTATION from its buffer. This does not
+ modify the buffer text.
+
+ -- 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
+
+51.3 Annotation Properties
+==========================
+
+ -- Function: annotation-glyph annotation
+ This function returns the glyph object used to display ANNOTATION.
+
+ -- 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
+ 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
+ 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
+ This function returns the face associated with ANNOTATION.
+
+ -- Function: set-annotation-face annotation face
+ This function sets the face associated with ANNOTATION to FACE.
+
+ -- Function: annotation-layout annotation
+ This function returns the layout policy of ANNOTATION.
+
+ -- Function: set-annotation-layout annotation layout
+ This function sets the layout policy of ANNOTATION to LAYOUT.
+
+ -- 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
+ This function returns the data associated with ANNOTATION.
+
+ -- Function: set-annotation-data annotation data
+ This function sets the data field of ANNOTATION to DATA. DATA is
+ returned.
+
+ -- Function: annotation-action annotation
+ This function returns the action associated with ANNOTATION.
+
+ -- Function: set-annotation-action annotation action
+ This function sets the action field of ANNOTATION to ACTION.
+ ACTION is returned..
+
+ -- Function: annotation-menu annotation
+ This function returns the menu associated with ANNOTATION.
+
+ -- 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
+ This function returns `t' if there is enough available space to
+ display ANNOTATION, `nil' otherwise.
+
+ -- Function: annotation-width annotation
+ This function returns the width of ANNOTATION in pixels.
+
+ -- Function: hide-annotation annotation
+ This function removes ANNOTATION's glyph, making it invisible.
+
+ -- 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
+
+51.4 Locating Annotations
+=========================
+
+ -- 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
+ 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
+ This function returns a list of all annotations in BUFFER. If
+ BUFFER is `nil', the current buffer is used.
+
+ -- 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
+
+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
+ 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
+ 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
+ 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
+ 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
+ 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
+ This function returns the width in pixels of the right outside
+ margin of WINDOW. If WINDOW is `nil', the selected window is
+ assumed.
+
+ The margin colors are controlled by the faces `left-margin' and
+`right-margin'. These can be set using the X resources
+`Emacs.left-margin.background' and `Emacs.left-margin.foreground';
+likewise for the right margin.
+
+\1f
+File: lispref.info, Node: Annotation Hooks, Prev: Locating Annotations, Up: Annotations
+
+51.6 Annotation Hooks
+=====================
+
+The following three hooks are provided for use with the marginal
+annotations:
+
+`before-delete-annotation-hook'
+ This hook is called immediately before an annotation is destroyed.
+ It is passed a single argument, the annotation being destroyed.
+
+`after-delete-annotation-hook'
+ This normal hook is called immediately after an annotation is
+ destroyed.
+
+`make-annotation-hook'
+ This hook is called immediately after an annotation is created.
+ It is passed a single argument, the newly created annotation.
+
+\1f
+File: lispref.info, Node: Display, Next: Hash Tables, Prev: Annotations, Up: Top
+
+52 Emacs Display
+****************
+
+This chapter describes a number of other features related to the display
+that XEmacs presents to the user.
+
+* Menu:
+
+* Refresh Screen:: Clearing the screen and redrawing everything on it.
+* Truncation:: Folding or wrapping long text lines.
+* The Echo Area:: Where messages are displayed.
+* Warnings:: Display of Warnings.
+* Invisible Text:: Hiding part of the buffer text.
+* Selective Display:: Hiding part of the buffer text (the old way).
+* Overlay Arrow:: Display of an arrow to indicate position.
+* Temporary Displays:: Displays that go away automatically.
+* Blinking:: How XEmacs shows the matching open parenthesis.
+* Usual Display:: The usual conventions for displaying nonprinting chars.
+* Display Tables:: How to specify other conventions.
+* Beeping:: Audible signal to the user.
+
+\1f
+File: lispref.info, Node: Refresh Screen, Next: Truncation, Up: Display
+
+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
+ This function clears and redisplays frame FRAME.
+
+ FRAME defaults to the selected frame if omitted.
+
+ Normally, redisplay is preempted as normal if input arrives.
+ However, if optional second arg NO-PREEMPT is non-`nil', redisplay
+ will not stop for input and is guaranteed to proceed to completion.
+
+ Even more powerful is `redraw-display':
+
+ -- 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.
+
+ Processing user input takes absolute priority over redisplay. If you
+call these functions when input is available, they do nothing
+immediately, but a full redisplay does happen eventually--after all the
+input has been processed.
+
+ Normally, suspending and resuming XEmacs also refreshes the screen.
+Some terminal emulators record separate contents for display-oriented
+programs such as XEmacs and for ordinary sequential display. If you are
+using such a terminal, you might want to inhibit the redisplay on
+resumption. *Note Suspending XEmacs::.
+
+ -- 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.
+
+ The above functions do not actually cause the display to be updated;
+rather, they clear out the internal display records that XEmacs
+maintains, so that the next time the display is updated it will be
+redrawn from scratch. Normally this occurs the next time that
+`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
+ 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
+
+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
+truncated, this is normally shown with a `\' in the rightmost column of
+the window on X displays, and with a `$' on TTY devices. When a line
+is continued or "wrapped" onto the next line, this is shown with a
+curved arrow in the rightmost column of the window (or with a `\' on
+TTY devices). The additional screen lines used to display a long text
+line are called "continuation" lines.
+
+ Normally, whenever line truncation is in effect for a particular
+window, a horizontal scrollbar is displayed in that window if the
+device supports scrollbars. *Note Scrollbars::.
+
+ Note that continuation is different from filling; continuation
+happens on the screen only, not in the buffer contents, and it breaks a
+line precisely at the right margin, not at a word boundary. *Note
+Filling::.
+
+ -- 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
+ of text occupies exactly one screen line, and a backslash appears
+ at the edge of any line that extends to or beyond the edge of the
+ window. The default is `nil'.
+
+ If the variable `truncate-partial-width-windows' is non-`nil',
+ 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
+ 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
+ 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;
+ otherwise, `truncate-lines' says what to do with them.
+
+ The backslash and curved arrow used to indicate truncated or
+continued lines are only defaults, and can be changed. These images
+are actually glyphs (*note Glyphs::). XEmacs provides a great deal of
+flexibility in how glyphs can be controlled. (This differs from FSF
+Emacs, which uses display tables to control these images.)
+
+ For details, *Note Redisplay Glyphs::.
+
+\1f
+File: lispref.info, Node: The Echo Area, Next: Warnings, Prev: Truncation, Up: Display
+
+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
+minibuffer, despite the fact that the minibuffer appears (when active)
+in the same place on the screen as the echo area. The `XEmacs Lisp
+Reference Manual' specifies the rules for resolving conflicts between
+the echo area and the minibuffer for use of that screen space (*note
+The Minibuffer: (xemacs)Minibuffer.). Error messages appear in the
+echo area; see *Note Errors::.
+
+ You can write output in the echo area by using the Lisp printing
+functions with `t' as the stream (*note Output Functions::), or as
+follows:
+
+ -- 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
+ on the conversion specifications. `message' returns the
+ constructed string.
+
+ In batch mode, `message' prints the message text on the standard
+ error stream, followed by a newline.
+
+ If STRING is `nil', `message' clears the echo area. If the
+ minibuffer is active, this brings the minibuffer contents back onto
+ the screen immediately.
+
+ (message "Minibuffer depth is %d."
+ (minibuffer-depth))
+ -| Minibuffer depth is 0.
+ => "Minibuffer depth is 0."
+
+ ---------- Echo Area ----------
+ Minibuffer depth is 0.
+ ---------- Echo Area ----------
+
+ In addition to only displaying a message, XEmacs allows you to
+"label" your messages, giving you fine-grained control of their
+display. Message label is a symbol denoting the message type. Some
+standard labels are:
+
+ * `message'--default label used by the `message' function;
+
+ * `error'--default label used for reporting errors;
+
+ * `progress'--progress indicators like `Converting... 45%' (not
+ logged by default);
+
+ * `prompt'--prompt-like messages like `Isearch: foo' (not logged by
+ default);
+
+ * `command'--helper command messages like `Mark set' (not logged by
+ default);
+
+ * `no-log'--messages that should never be logged
+
+ Several messages may be stacked in the echo area at once. Lisp
+programs may access these messages, or remove them as appropriate, via
+the message stack.
+
+ -- Function: display-message label message &optional frame stdout-p
+ This function displays MESSAGE (a string) labeled as LABEL, as
+ described above.
+
+ The FRAME argument specifies the frame to whose minibuffer the
+ message should be printed. This is currently unimplemented. The
+ STDOUT-P argument is used internally.
+
+ (display-message 'command "Mark set")
+
+ -- 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
+ 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.
+
+ If a message remains at the head of the message-stack and
+ NO-RESTORE is `nil', it will be displayed. The string which
+ remains in the echo area will be returned, or `nil' if the
+ message-stack is now empty. If LABEL is `nil', the entire
+ message-stack is cleared.
+
+ ;; Show a message, wait for 2 seconds, and restore old minibuffer
+ ;; contents.
+ (message "A message")
+ -| A message
+ => "A Message"
+ (lmessage 'my-label "Newsflash! Newsflash!")
+ -| Newsflash! Newsflash!
+ => "Newsflash! Newsflash!"
+ (sit-for 2)
+ (clear-message 'my-label)
+ -| A message
+ => "A message"
+
+ Unless you need the return value or you need to specify a label,
+ you should just use `(message nil)'.
+
+ -- Function: current-message &optional frame
+ This function returns the current message in the echo area, or
+ `nil'. The FRAME argument is currently unused.
+
+ Some of the messages displayed in the echo area are also recorded in
+the ` *Message-Log*' buffer. Exactly which messages will be recorded
+can be tuned using the following variables.
+
+ -- User Option: log-message-max-size
+ This variable specifies the maximum size of the ` *Message-log*'
+ buffer.
+
+ -- 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
+ This variable specifies the regular expressions matching messages
+ that will not be logged. It should be a list of regular
+ expressions.
+
+ Normally, packages that generate messages that might need to be
+ ignored should label them with `progress', `prompt', or `no-log',
+ so they can be filtered by `log-message-ignore-labels'.
+
+ -- 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
+ prefix key (such as `C-x') and then delays this many seconds
+ before continuing, the prefix key is echoed in the echo area. Any
+ subsequent characters in the same command will be echoed as well.
+
+ If the value is zero, then command input is not echoed.
+
+ -- 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
+ at point--not in the echo area at all.
+
+ The value is normally `nil'; Lisp programs bind it to `t' for
+ brief periods of time.
+
+\1f
+File: lispref.info, Node: Warnings, Next: Invisible Text, Prev: The Echo Area, Up: Display
+
+52.4 Warnings
+=============
+
+XEmacs contains a facility for unified display of various warnings.
+Unlike errors, warnings are displayed in the situations when XEmacs
+encounters a problem that is recoverable, but which should be fixed for
+safe future operation.
+
+ For example, warnings are printed by the startup code when it
+encounters problems with X keysyms, when there is an error in `.emacs',
+and in other problematic situations. Unlike messages, warnings are
+displayed in a separate buffer, and include an explanatory message that
+may span across several lines. Here is an example of how a warning is
+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.
+
+ Each warning has a "class" and a "priority level". The class is a
+symbol describing what sort of warning this is, such as
+`initialization', `resource' or `key-mapping'.
+
+ The warning priority level specifies how important the warning is.
+The recognized warning levels, in increased order of priority, are:
+`debug', `info', `notice', `warning', `error', `critical', `alert' and
+`emergency'.
+
+ -- 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.
+ If unspecified, it default to `warning'.
+
+ (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
+ 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
+ (`warning' by default).
+
+ Unlike in `display-warning', MESSAGE may be a formatted message,
+ which will be, together with the rest of the arguments, passed to
+ `format'.
+
+ (lwarn 'message-log 'warning
+ "Error caught in `remove-message-hook': %s"
+ (error-message-string e))
+
+ -- 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
+ 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
+ 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
+ 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 not be displayed. The warning will still logged in
+ the *Warnings* buffer (unless also contained in
+ `log-warning-suppressed-classes'), but the buffer will not be
+ automatically popped up.
+
+\1f
+File: lispref.info, Node: Invisible Text, Next: Selective Display, Prev: Warnings, Up: Display
+
+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
+property or a property of an overlay.
+
+ In the simplest case, any non-`nil' `invisible' property makes a
+character invisible. This is the default case--if you don't alter the
+default value of `buffer-invisibility-spec', this is how the
+`invisibility' property works. This feature is much like selective
+display (*note Selective Display::), but more general and cleaner.
+
+ More generally, you can use the variable `buffer-invisibility-spec'
+to control which values of the `invisible' property make text
+invisible. This permits you to classify the text into different subsets
+in advance, by giving them different `invisible' values, and
+subsequently make various subsets visible or invisible by changing the
+value of `buffer-invisibility-spec'.
+
+ Controlling visibility with `buffer-invisibility-spec' is especially
+useful in a program to display the list of entries in a data base. It
+permits the implementation of convenient filtering commands to view
+just a part of the entries in the data base. Setting this variable is
+very fast, much faster than scanning all the text in the buffer looking
+for properties to change.
+
+ -- Variable: buffer-invisibility-spec
+ This variable specifies which kinds of `invisible' properties
+ actually make a character invisible.
+
+ `t'
+ A character is invisible if its `invisible' property is
+ non-`nil'. This is the default.
+
+ a list
+ Each element of the list makes certain characters invisible.
+ Ultimately, a character is invisible if any of the elements
+ of this list applies to it. The list can have two kinds of
+ elements:
+
+ `ATOM'
+ A character is invisible if its `invisible' property
+ value is ATOM or if it is a list with ATOM as a member.
+
+ `(ATOM . t)'
+ A character is invisible if its `invisible' property
+ value is ATOM or if it is a list with ATOM as a member.
+ Moreover, if this character is at the end of a line and
+ is followed by a visible newline, it displays an
+ ellipsis.
+
+ Ordinarily, commands that operate on text or move point do not care
+whether the text is invisible. However, the user-level line motion
+commands explicitly ignore invisible newlines. Since this causes a
+slow-down of these commands it is turned off by default, controlled by
+the variable `line-move-ignore-invisible'.
+
+\1f
+File: lispref.info, Node: Selective Display, Next: Overlay Arrow, Prev: Invisible Text, Up: Display
+
+52.6 Selective Display
+======================
+
+"Selective display" is a pair of features that hide certain lines on
+the screen.
+
+ The first variant, explicit selective display, is designed for use in
+a Lisp program. The program controls which lines are hidden by altering
+the text. Outline mode has traditionally used this variant. It has
+been partially replaced by the invisible text feature (*note Invisible
+Text::); there is a new version of Outline mode which uses that instead.
+
+ In the second variant, the choice of lines to hide is made
+automatically based on indentation. This variant is designed to be a
+user-level feature.
+
+ The way you control explicit selective display is by replacing a
+newline (control-j) with a carriage return (control-m). The text that
+was formerly a line following that newline is now invisible. Strictly
+speaking, it is temporarily no longer a line at all, since only newlines
+can separate lines; it is now part of the previous line.
+
+ Selective display does not directly affect editing commands. For
+example, `C-f' (`forward-char') moves point unhesitatingly into
+invisible text. However, the replacement of newline characters with
+carriage return characters affects some editing commands. For example,
+`next-line' skips invisible lines, since it searches only for newlines.
+Modes that use selective display can also define commands that take
+account of the newlines, or that make parts of the text visible or
+invisible.
+
+ When you write a selectively displayed buffer into a file, all the
+control-m's are output as newlines. This means that when you next read
+in the file, it looks OK, with nothing invisible. The selective display
+effect is seen only within XEmacs.
+
+ -- Variable: selective-display
+ This buffer-local variable enables selective display. This means
+ that lines, or portions of lines, may be made invisible.
+
+ * If the value of `selective-display' is `t', then any portion
+ of a line that follows a control-m is not displayed.
+
+ * If the value of `selective-display' is a positive integer,
+ then lines that start with more than that many columns of
+ indentation are not displayed.
+
+ When some portion of a buffer is invisible, the vertical movement
+ commands operate as if that portion did not exist, allowing a
+ single `next-line' command to skip any number of invisible lines.
+ However, character movement commands (such as `forward-char') do
+ not skip the invisible portion, and it is possible (if tricky) to
+ insert or delete text in an invisible portion.
+
+ In the examples below, we show the _display appearance_ of the
+ buffer `foo', which changes with the value of `selective-display'.
+ The _contents_ of the buffer do not change.
+
+ (setq selective-display nil)
+ => nil
+
+ ---------- Buffer: foo ----------
+ 1 on this column
+ 2on this column
+ 3n this column
+ 3n 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
+ 2on this column
+ 1 on this column
+ ---------- Buffer: foo ----------
+
+ -- 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 ...
+ 2on this column
+ 1 on this column
+ ---------- Buffer: foo ----------
+
+ You can use a display table to substitute other text for the
+ ellipsis (`...'). *Note Display Tables::.
+
+\1f
+File: lispref.info, Node: Overlay Arrow, Next: Temporary Displays, Prev: Selective Display, Up: Display
+
+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
+ 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
+ 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
+ text that would otherwise appear. Since the arrow is usually
+ short, and the line usually begins with indentation, normally
+ nothing significant is overwritten.
+
+ The overlay string is displayed only in the buffer that this marker
+ points into. Thus, only one buffer can have an overlay arrow at
+ any given time.
+
+ You can do the same job by creating an extent with a `begin-glyph'
+property. *Note Extent Properties::.
+
+\1f
+File: lispref.info, Node: Temporary Displays, Next: Blinking, Prev: Overlay Arrow, Up: Display
+
+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...
+ 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.
+
+ The string BUFFER-NAME specifies the temporary buffer, which need
+ not already exist. The argument must be a string, not a buffer.
+ The buffer is erased initially (with no questions asked), and it is
+ marked as unmodified after `with-output-to-temp-buffer' exits.
+
+ `with-output-to-temp-buffer' binds `standard-output' to the
+ temporary buffer, then it evaluates the forms in FORMS. Output
+ using the Lisp output functions within FORMS goes by default to
+ that buffer (but screen display and messages in the echo area,
+ although they are "output" in the general sense of the word, are
+ not affected). *Note Output Functions::.
+
+ The value of the last form in FORMS is returned.
+
+ ---------- 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
+ 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
+ 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
+ modification status.
+
+ The momentary display remains until the next input event. If the
+ next input event is CHAR, `momentary-string-display' ignores it
+ and returns. Otherwise, that event remains buffered for
+ subsequent use as input. Thus, typing CHAR will simply remove the
+ string from the display, while typing (say) `C-f' will remove the
+ string from the display and later (presumably) move point forward.
+ The argument CHAR is a space by default.
+
+ The return value of `momentary-string-display' is not meaningful.
+
+ You can do the same job in a more general way by creating an extent
+ with a begin-glyph property. *Note Extent Properties::.
+
+ If MESSAGE is non-`nil', it is displayed in the echo area while
+ STRING is displayed in the buffer. If it is `nil', a default
+ message says to type CHAR to continue.
+
+ In this example, point is initially located at the beginning of the
+ second line:
+
+ ---------- Buffer: foo ----------
+ 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 ----------
+
+ This function works by actually changing the text in the buffer.
+ As a result, if you later undo in this buffer, you will see the
+ message come and go.
+
+\1f
+File: lispref.info, Node: Blinking, Next: Usual Display, Prev: Temporary Displays, Up: Display
+
+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
+ 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
+ which case nothing is done.
+
+ *Please note:* This variable was named `blink-paren-hook' in
+ older Emacs versions, but since it is not called with the
+ standard convention for hooks, it was renamed to
+ `blink-paren-function' in version 19.
+
+ -- Variable: blink-matching-paren
+ If this variable is `nil', then `blink-matching-open' does nothing.
+
+ -- 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
+ 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
+ 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
+ character. If that character is not already on the screen, it
+ displays the character's context in the echo area. To avoid long
+ delays, this function does not search farther than
+ `blink-matching-paren-distance' characters.
+
+ Here is an example of calling this function explicitly.
+
+ (defun interactive-blink-matching-open ()
+ "Indicate momentarily the start of sexp before point."
+ (interactive)
+ (let ((blink-matching-paren-distance
+ (buffer-size))
+ (blink-matching-paren t))
+ (blink-matching-open)))
+
+\1f
+File: lispref.info, Node: Usual Display, Next: Display Tables, Prev: Blinking, Up: Display
+
+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
+(*note Display Tables::). Here are the usual display conventions:
+
+ * Character codes 32 through 126 map to glyph codes 32 through 126.
+ Normally this means they display as themselves.
+
+ * Character code 9 is a horizontal tab. It displays as whitespace
+ up to a position determined by `tab-width'.
+
+ * Character code 10 is a newline.
+
+ * All other codes in the range 0 through 31, and code 127, display
+ in one of two ways according to the value of `ctl-arrow'. If it is
+ non-`nil', these codes map to sequences of two glyphs, where the
+ first glyph is the ASCII code for `^'. (A display table can
+ specify a glyph to use instead of `^'.) Otherwise, these codes map
+ just like the codes in the range 128 to 255.
+
+ * Character codes 128 through 255 map to sequences of four glyphs,
+ where the first glyph is the ASCII code for `\', and the others are
+ digit characters representing the code in octal. (A display table
+ can specify a glyph to use instead of `\'.)
+
+ The usual display conventions apply even when there is a display
+table, for any character whose entry in the active display table is
+`nil'. Thus, when you set up a display table, you need only specify
+the characters for which you want unusual behavior.
+
+ These variables affect the way certain characters are displayed on
+the screen. Since they change the number of columns the characters
+occupy, they also affect the indentation functions.
+
+ -- 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
+ 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
+ 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
+ user-settable tab stops used by the command `tab-to-tab-stop'.
+ *Note Indent Tabs::.
+
+\1f
+File: lispref.info, Node: Display Tables, Next: Beeping, Prev: Usual Display, Up: Display
+
+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
+European languages that have letters not in the ASCII character set.
+
+ The display table maps each character code into a sequence of
+"runes", each rune being an image that takes up one character position
+on the screen. You can also define how to display each rune on your
+terminal, using the "rune table".
+
+* Menu:
+
+* Display Table Format:: What a display table consists of.
+* Active Display Table:: How XEmacs selects a display table to use.
+* Character Descriptors:: Format of an individual element of a
+ display table.
+
+\1f
+File: lispref.info, Node: Display Table Format, Next: Active Display Table, Up: Display Tables
+
+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
+and continuation glyphs, etc. This method is very kludgey, and in
+XEmacs the variables `truncation-glyph', `continuation-glyph', etc. are
+used. *Note Truncation::.)
+
+ -- Function: make-display-table
+ This creates and returns a display table. The table initially has
+ `nil' in all elements.
+
+ The 256 elements correspond to character codes; the Nth element says
+how to display the character code N. The value should be `nil', a
+string, a glyph, or a vector of strings and glyphs (*note Character
+Descriptors::). If an element is `nil', it says to display that
+character according to the usual display conventions (*note Usual
+Display::).
+
+ If you use the display table to change the display of newline
+characters, the whole buffer will be displayed as one long "line."
+
+ For example, here is how to construct a display table that mimics the
+effect of setting `ctl-arrow' to a non-`nil' value:
+
+ (setq disptab (make-display-table))
+ (let ((i 0))
+ (while (< i 32)
+ (or (= i ?\t) (= i ?\n)
+ (aset disptab i (concat "^" (char-to-string (+ i 64)))))
+ (setq i (1+ i)))
+ (aset disptab 127 "^?"))
+
+\1f
+File: lispref.info, Node: Active Display Table, Next: Character Descriptors, Prev: Display Table Format, Up: Display Tables
+
+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
+specify separate values for it in individual buffers, windows, frames,
+and devices, as well as a global value. It also means that you cannot
+set this variable using `setq'; use `set-specifier' instead. *Note
+Specifiers::. (FSF Emacs uses `window-display-table',
+`buffer-display-table', `standard-display-table', etc. to control the
+display table. However, specifiers are a cleaner and more powerful way
+of doing the same thing. FSF Emacs also uses a different format for
+the contents of a display table, using additional indirection to a
+"glyph table" and such. Note that "glyph" has a different meaning in
+XEmacs.)
+
+ -- Variable: current-display-table
+ The display table currently in use. This is a specifier.
+
+ Display tables are used to control how characters are displayed.
+ Each time that redisplay processes a character, it is looked up in
+ all the display tables that apply (obtained by calling
+ `specifier-instance' on `current-display-table' and any overriding
+ display tables specified in currently active faces). The first
+ entry found that matches the character determines how the
+ character is displayed. If there is no matching entry, the
+ default display method is used. (Non-control characters are
+ displayed as themselves and control characters are displayed
+ according to the buffer-local variable `ctl-arrow'. Control
+ characters are further affected by `control-arrow-glyph' and
+ `octal-escape-glyph'.)
+
+ Each instantiator in this specifier and the display-table
+ specifiers in faces is a display table or a list of such tables.
+ If a list, each table will be searched in turn for an entry
+ matching a particular character. Each display table is one of
+
+ * A vector, specifying values for characters starting at 0.
+
+ * A char table, either of type `char' or `generic'.
+
+ * A range table.
+
+ Each entry in a display table should be one of
+
+ * nil (this entry is ignored and the search continues).
+
+ * A character (use this character; if it happens to be the same
+ as the original character, default processing happens,
+ otherwise redisplay attempts to display this character
+ directly; #### At some point recursive display-table lookup
+ will be implemented).
+
+ * A string (display each character in the string directly; ####
+ At some point recursive display-table lookup will be
+ implemented).
+
+ * A glyph (display the glyph; #### At some point recursive
+ display-table lookup will be implemented when a string glyph
+ is being processed).
+
+ * A cons of the form (format "STRING") where STRING is a
+ printf-like spec used to process the character. ####
+ Unfortunately no formatting directives other than %% are
+ implemented.
+
+ * A vector (each element of the vector is processed recursively;
+ in such a case, nil elements in the vector are simply
+ ignored).
+
+ #### At some point in the near future, display tables are
+ likely to be expanded to include other features, such as
+ referencing characters in particular fonts and allowing the
+ character search to continue all the way up the chain of
+ specifier instantiators. These features are necessary to
+ properly display Unicode characters.
+
+ Individual faces can also specify an overriding display table; this
+is set using `set-face-display-table'. *Note Faces::.
+
+ If no display table can be determined for a particular window, then
+XEmacs uses the usual display conventions. *Note Usual Display::.
+
+\1f
+File: lispref.info, Node: Character Descriptors, Prev: Active Display Table, Up: Display Tables
+
+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
+character descriptor can be:
+
+a string
+ Display this particular string wherever the character is to be
+ displayed.
+
+a glyph
+ Display this particular glyph wherever the character is to be
+ displayed.
+
+a vector
+ The vector may contain strings and/or glyphs. Display the
+ elements of the vector one after another wherever the character is
+ to be displayed.
+
+`nil'
+ Display according to the standard interpretation (*note Usual
+ Display::).
+
+\1f
+File: lispref.info, Node: Beeping, Prev: Display Tables, Up: Display
+
+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
+ 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
+ should be a symbol specifying which sound to make. This sound
+ will be played if `visible-bell' is `nil'. (This only works if
+ sound support was compiled into the executable and you are running
+ on the console of a Sun SparcStation, SGI, HP9000s700, or Linux
+ PC. Otherwise you just get a beep.) The optional third argument
+ specifies what device to make the sound on, and defaults to the
+ selected device.
+
+ -- Function: beep &optional dont-terminate sound device
+ This is a synonym for `ding'.
+
+ -- 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
+ 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.
+
+ Each element of `sound-alist' is a list describing a sound. The
+ first element of the list is the name of the sound being defined.
+ Subsequent elements of the list are alternating keyword/value
+ pairs:
+
+ `sound'
+ A string of raw sound data, or the name of another sound to
+ play. The symbol `t' here means use the default X beep.
+
+ `volume'
+ An integer from 0-100, defaulting to `bell-volume'.
+
+ `pitch'
+ If using the default X beep, the pitch (Hz) to generate.
+
+ `duration'
+ If using the default X beep, the duration (milliseconds).
+
+ For compatibility, elements of `sound-alist' may also be:
+
+ * `( sound-name . <sound> )'
+
+ * `( sound-name <volume> <sound> )'
+
+ You should probably add things to this list by calling the function
+ `load-sound-file'.
+
+ Caveats:
+
+ - You can only play audio data if running on the console screen
+ of a Sun SparcStation, SGI, or HP9000s700.
+
+ - The pitch, duration, and volume options are available
+ everywhere, but many X servers ignore the `pitch' option.
+
+ The following beep-types are used by XEmacs itself:
+
+ `auto-save-error'
+ when an auto-save does not succeed
+
+ `command-error'
+ when the XEmacs command loop catches an error
+
+ `undefined-key'
+ when you type a key that is undefined
+
+ `undefined-click'
+ when you use an undefined mouse-click combination
+
+ `no-completion'
+ during completing-read
+
+ `y-or-n-p'
+ when you type something other than 'y' or 'n'
+
+ `yes-or-no-p'
+ when you type something other than 'yes' or 'no'
+
+ `default'
+ used when nothing else is appropriate.
+
+ Other lisp packages may use other beep types, but these are the
+ ones that the C kernel of XEmacs uses.
+
+ -- User Option: bell-volume
+ This variable specifies the default volume for sounds, from 0 to
+ 100.
+
+ -- Command: load-default-sounds
+ This function loads and installs some sound files as beep-types.
+
+ -- 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
+ 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
+ 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
+
+53 Hash Tables
+**************
+
+ -- Function: hash-table-p object
+ This function returns `t' if OBJECT is a hash table, else `nil'.
+
+* Menu:
+
+* Introduction to Hash Tables:: Hash tables are fast data structures for
+ implementing simple tables (i.e. finite
+ mappings from keys to values).
+* Working With Hash Tables:: Hash table functions.
+* Weak Hash Tables:: Hash tables with special garbage-collection
+ behavior.
+
+\1f
+File: lispref.info, Node: Introduction to Hash Tables, Next: Working With Hash Tables, Up: 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
+called "values". A key/value pair is sometimes called an "entry" in
+the hash table. There are many ways other than hash tables of
+implementing the same sort of mapping, e.g. association lists (*note
+Association Lists::) and property lists (*note Property Lists::), but
+hash tables provide much faster lookup when there are many entries in
+the mapping. Hash tables are an implementation of the abstract data
+type "dictionary", also known as "associative array".
+
+ Internally, hash tables are hashed using the "linear probing" hash
+table implementation method. This method hashes each key to a
+particular spot in the hash table, and then scans forward sequentially
+until a blank entry is found. To look up a key, hash to the appropriate
+spot, then search forward for the key until either a key is found or a
+blank entry stops the search. This method is used in preference to
+double hashing because of changes in recent hardware. The penalty for
+non-sequential access to memory has been increasing, and this
+compensates for the problem of clustering that linear probing entails.
+
+ When hash tables are created, the user may (but is not required to)
+specify initial properties that influence performance.
+
+ Use the `:size' parameter to specify the number of entries that are
+likely to be stored in the hash table, to avoid the overhead of resizing
+the table. But if the pre-allocated space for the entries is never
+used, it is simply wasted and makes XEmacs slower. Excess unused hash
+table entries exact a small continuous performance penalty, since they
+must be scanned at every garbage collection. If the number of entries
+in the hash table is unknown, simply avoid using the `:size' keyword.
+
+ Use the `:rehash-size' and `:rehash-threshold' keywords to adjust
+the algorithm for deciding when to rehash the hash table. For
+temporary hash tables that are going to be very heavily used, use a
+small rehash threshold, for example, 0.4 and a large rehash size, for
+example 2.0. For permanent hash tables that will be infrequently used,
+specify a large rehash threshold, for example 0.8.
+
+ Hash tables can also be created by the lisp reader using structure
+syntax, for example:
+ #s(hash-table size 20 data (foo 1 bar 2))
+
+ The structure syntax accepts the same keywords as `make-hash-table'
+(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'
+ `rehash-threshold' `weakness'
+ This function returns a new empty hash table object.
+
+ Keyword `:test' can be `eq', `eql' (default) or `equal'.
+ Comparison between keys is done using this function. If speed is
+ important, consider using `eq'. When storing strings in the hash
+ table, you will likely need to use `equal'.
+
+ Keyword `:size' specifies the number of keys likely to be inserted.
+ This number of entries can be inserted without enlarging the hash
+ table.
+
+ Keyword `:rehash-size' must be a float greater than 1.0, and
+ specifies the factor by which to increase the size of the hash
+ table when enlarging.
+
+ Keyword `:rehash-threshold' must be a float between 0.0 and 1.0,
+ and specifies the load factor of the hash table which triggers
+ enlarging.
+
+ Non-standard keyword `:weakness' can be `nil' (default), `t',
+ `key-and-value', `key', `value' or `key-or-value'. `t' is an
+ alias for `key-and-value'.
+
+ A key-and-value-weak hash table, also known as a fully-weak or
+ simply as a weak hash table, is one whose pointers do not count as
+ GC referents: for any key-value pair in the hash table, if the only
+ remaining pointer to either the key or the value is in a weak hash
+ table, then the pair will be removed from the hash table, and the
+ key and value collected. A non-weak hash table (or any other
+ pointer) would prevent the object from being collected.
+
+ A key-weak hash table is similar to a fully-weak hash table except
+ that a key-value pair will be removed only if the key remains
+ unmarked outside of weak hash tables. The pair will remain in the
+ hash table if the key is pointed to by something other than a weak
+ hash table, even if the value is not.
+
+ A value-weak hash table is similar to a fully-weak hash table
+ except that a key-value pair will be removed only if the value
+ remains unmarked outside of weak hash tables. The pair will
+ remain in the hash table if the value is pointed to by something
+ other than a weak hash table, even if the key is not.
+
+ A key-or-value-weak hash table is similar to a fully-weak hash
+ table except that a key-value pair will be removed only if the
+ value and the key remain unmarked outside of weak hash tables.
+ The pair will remain in the hash table if the value or key are
+ pointed to by something other than a weak hash table, even if the
+ other is not.
+
+ -- 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
+ This function returns the number of entries in 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
+ This function returns the current number of slots in HASH-TABLE,
+ whether occupied or not.
+
+ -- 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
+ 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
+ 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
+
+53.2 Working With Hash Tables
+=============================
+
+ -- Function: puthash key value hash-table
+ This function hashes KEY to VALUE in HASH-TABLE.
+
+ -- 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
+ 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
+ This function removes all entries from HASH-TABLE, leaving it
+ empty.
+
+ -- 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.
+
+ FUNCTION may not modify HASH-TABLE, with the one exception that
+ FUNCTION may remhash or puthash the entry currently being
+ processed by FUNCTION.
+
+\1f
+File: lispref.info, Node: Weak Hash Tables, Prev: Working With Hash Tables, Up: 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
+table, if either the key or value (or in some cases, if one particular
+one of the two) has no references to it outside of weak hash tables
+(and similar structures such as weak lists), the pair will be removed
+from the table, and the key and value collected. A non-weak hash table
+(or any other pointer) would prevent the objects from being collected.
+
+ Weak hash tables are useful for keeping track of information in a
+non-obtrusive way, for example to implement caching. If the cache
+contains objects such as buffers, markers, image instances, etc. that
+will eventually disappear and get garbage-collected, using a weak hash
+table ensures that these objects are collected normally rather than
+remaining around forever, long past their actual period of use.
+(Otherwise, you'd have to explicitly map over the hash table every so
+often and remove unnecessary elements.)
+
+ There are four types of weak hash tables:
+
+key-and-value-weak hash tables
+ In these hash tables, also known as fully weak or simply as weak
+ hash tables, a pair disappears if either the key or the value is
+ unreferenced outside of the table.
+
+key-weak hash tables
+ In these hash tables, a pair disappears if the key is unreferenced
+ outside of the table, regardless of how the value is referenced.
+
+value-weak hash tables
+ In these hash tables, a pair disappears if the value is
+ unreferenced outside of the table, regardless of how the key is
+ referenced.
+
+key-or-value-weak hash tables
+ In these hash tables, a pair disappears if both the key and the
+ value are unreferenced outside of the table.
+
+ Also see *Note Weak Lists::.
+
+ Weak hash tables are created by specifying the `:weakness' keyword to
+`make-hash-table'.
+
+\1f
+File: lispref.info, Node: Range Tables, Next: Databases, Prev: Hash Tables, Up: Top
+
+54 Range Tables
+***************
+
+A range table is a table that efficiently associated values with ranges
+of integers.
+
+ Note that range tables have a read syntax, like this:
+
+ #s(range-table data ((-3 2) foo (5 20) bar))
+
+ This maps integers in the range (-3, 2) to `foo' and integers in the
+range (5, 20) to `bar'.
+
+ -- Function: range-table-p object
+ Return non-`nil' if OBJECT is a range table.
+
+* Menu:
+
+* Introduction to Range Tables:: Range tables efficiently map ranges of
+ integers to values.
+* Working With Range Tables:: Range table functions.
+
+\1f
+File: lispref.info, Node: Introduction to Range Tables, Next: Working With Range Tables, Up: Range Tables
+
+54.1 Introduction to Range Tables
+=================================
+
+ -- Function: make-range-table
+ Make a new, empty 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
+
+54.2 Working With Range Tables
+==============================
+
+ -- 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
+ This function sets the value for range (START, END) to be VALUE in
+ 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
+ This function flushes 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
+
+55 Databases
+************
+
+ -- Function: databasep object
+ This function returns non-`nil' if OBJECT is a database.
+
+* Menu:
+
+* Connecting to a Database::
+* Working With a Database::
+* Other Database Functions::
+
+\1f
+File: lispref.info, Node: Connecting to a Database, Next: Working With a Database, Up: Databases
+
+55.1 Connecting to a Database
+=============================
+
+ -- 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
+ creation flags.
+
+ TYPE can have the value `'dbm' or `'berkeley-db' to select the
+ type of database file to use. (Note: XEmacs may not support both
+ of these types.)
+
+ For a TYPE of `'dbm', there are no subtypes, so SUBTYPE should be
+ `nil'.
+
+ For a TYPE of `'berkeley-db', the following subtypes are
+ available: `'hash', `'btree', and `'recno'. See the manpages for
+ the Berkeley DB functions for more information about these types.
+
+ -- Function: close-database database
+ This function closes database DATABASE.
+
+ -- 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
+
+55.2 Working With a Database
+============================
+
+ -- 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
+ 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
+ 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
+ This function removes KEY from DATABASE.
+
+\1f
+File: lispref.info, Node: Other Database Functions, Prev: Working With a Database, Up: Databases
+
+55.3 Other Database Functions
+=============================
+
+ -- Function: database-file-name database
+ This function returns the filename associated with DATABASE.
+
+ -- Function: database-last-error &optional database
+ This function returns the last error associated with DATABASE.
+
+ -- Function: database-subtype database
+ This function returns the subtype of DATABASE, if any.
+
+ -- Function: database-type database
+ This function returns the type of DATABASE.
+
+\1f
+File: lispref.info, Node: Processes, Next: System Interface, Prev: Databases, Up: Top
+
+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
+programs can invoke other programs in processes of their own. These are
+called "subprocesses" or "child processes" of the XEmacs process, which
+is their "parent process".
+
+ A subprocess of XEmacs may be "synchronous" or "asynchronous",
+depending on how it is created. When you create a synchronous
+subprocess, the Lisp program waits for the subprocess to terminate
+before continuing execution. When you create an asynchronous
+subprocess, it can run in parallel with the Lisp program. This kind of
+subprocess is represented within XEmacs by a Lisp object which is also
+called a "process". Lisp programs can use this object to communicate
+with the subprocess or to control it. For example, you can send
+signals, obtain status information, receive output from the process, or
+send input to it.
+
+ -- Function: processp object
+ This function returns `t' if OBJECT is a process, `nil' otherwise.
+
+* Menu:
+
+* Subprocess Creation:: Functions that start subprocesses.
+* Synchronous Processes:: Details of using synchronous subprocesses.
+* MS-DOS Subprocesses:: On MS-DOS, you must indicate text vs binary
+ for data sent to and from a subprocess.
+* Asynchronous Processes:: Starting up an asynchronous subprocess.
+* Deleting Processes:: Eliminating an asynchronous subprocess.
+* Process Information:: Accessing run-status and other attributes.
+* Input to Processes:: Sending input to an asynchronous subprocess.
+* Signals to Processes:: Stopping, continuing or interrupting
+ an asynchronous subprocess.
+* Output from Processes:: Collecting output from an asynchronous subprocess.
+* Sentinels:: Sentinels run when process run-status changes.
+* Process Window Size:: Changing the logical window size of a process.
+* Transaction Queues:: Transaction-based communication with subprocesses.
+* Network:: Opening network connections.
+
+\1f
+File: lispref.info, Node: Subprocess Creation, Next: Synchronous Processes, Up: Processes
+
+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
+process and returns a process object (*note Asynchronous Processes::).
+The other two, `call-process' and `call-process-region', create a
+synchronous process and do not return a process object (*note
+Synchronous Processes::).
+
+ Synchronous and asynchronous processes are explained in the following
+sections. Since the three functions are all called in a similar
+fashion, their common arguments are described here.
+
+ In all cases, the function's PROGRAM argument specifies the program
+to be run. An error is signaled if the file is not found or cannot be
+executed. If the file name is relative, the variable `exec-path'
+contains a list of directories to search. Emacs initializes
+`exec-path' when it starts up, based on the value of the environment
+variable `PATH'. The standard file name constructs, `~', `.', and
+`..', are interpreted as usual in `exec-path', but environment variable
+substitutions (`$HOME', etc.) are not recognized; use
+`substitute-in-file-name' to perform them (*note File Name Expansion::).
+
+ Each of the subprocess-creating functions has a BUFFER-OR-NAME
+argument which specifies where the standard output from the program will
+go. If BUFFER-OR-NAME is `nil', that says to discard the output unless
+a filter function handles it. (*Note Filter Functions::, and *Note
+Read and Print::.) Normally, you should avoid having multiple
+processes send output to the same buffer because their output would be
+intermixed randomly.
+
+ All three of the subprocess-creating functions have a `&rest'
+argument, ARGS. The ARGS must all be strings, and they are supplied to
+PROGRAM as separate command line arguments. Wildcard characters and
+other shell constructs are not allowed in these strings, since they are
+passed directly to the specified program.
+
+ *Please note:* The argument PROGRAM contains only the name of the
+program; it may not contain any command-line arguments. You must use
+ARGS to provide those.
+
+ If you want to use features of the shell, then invoke the shell
+directly using, for example, PROGRAM of `"sh"', and ARGS of `"-c"' and
+"COMMAND LINE...".
+
+ The subprocess gets its current directory from the value of
+`default-directory' (*note File Name Expansion::).
+
+ The subprocess inherits its environment from XEmacs; but you can
+specify overrides for it with `process-environment'. *Note System
+Environment::.
+
+ -- 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
+ 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').
+
+ The value of `exec-path' is used by `call-process' and
+ `start-process' when the PROGRAM argument is not an absolute file
+ name.
+
+\1f
+File: lispref.info, Node: Synchronous Processes, Next: MS-DOS Subprocesses, Prev: Subprocess Creation, Up: Processes
+
+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:
+it runs `ls' in a synchronous process, then modifies the output
+slightly. Because the process is synchronous, the entire directory
+listing arrives in the buffer before XEmacs tries to do anything with
+it.
+
+ While Emacs waits for the synchronous subprocess to terminate, the
+user can quit by typing `C-g'. The first `C-g' tries to kill the
+subprocess with a `SIGINT' signal; but it waits until the subprocess
+actually terminates before quitting. If during that time the user
+types another `C-g', that kills the subprocess instantly with `SIGKILL'
+and quits immediately. *Note Quitting::.
+
+ 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
+ &rest args
+ This function calls PROGRAM in a separate process and waits for it
+ to finish.
+
+ The standard input for the process comes from file INFILE if
+ INFILE is not `nil' and from `/dev/null' otherwise. The argument
+ DESTINATION says where to put the process output. Here are the
+ possibilities:
+
+ a buffer
+ Insert the output in that buffer, before point. This
+ includes both the standard output stream and the standard
+ error stream of the process.
+
+ a string
+ Find or create a buffer with that name, then insert the
+ output in that buffer, before point.
+
+ `t'
+ Insert the output in the current buffer, before point.
+
+ `nil'
+ Discard the output.
+
+ 0
+ Discard the output, and return immediately without waiting
+ for the subprocess to finish.
+
+ In this case, the process is not truly synchronous, since it
+ can run in parallel with Emacs; but you can think of it as
+ synchronous in that Emacs is essentially finished with the
+ subprocess as soon as this function returns.
+
+ (REAL-DESTINATION ERROR-DESTINATION)
+ Keep the standard output stream separate from the standard
+ error stream; deal with the ordinary output as specified by
+ REAL-DESTINATION, and dispose of the error output according
+ to ERROR-DESTINATION. The value `nil' means discard it, `t'
+ means mix it with the ordinary output, and a string specifies
+ a file name to redirect error output into.
+
+ You can't directly specify a buffer to put the error output
+ in; that is too difficult to implement. But you can achieve
+ this result by sending the error output to a temporary file
+ and then inserting the file into a buffer.
+
+ If DISPLAY is non-`nil', then `call-process' redisplays the buffer
+ as output is inserted. Otherwise the function does no redisplay,
+ and the results become visible on the screen only when XEmacs
+ redisplays that buffer in the normal course of events.
+
+ The remaining arguments, ARGS, are strings that specify command
+ line arguments for the program.
+
+ The value returned by `call-process' (unless you told it not to
+ wait) indicates the reason for process termination. A number
+ gives the exit status of the subprocess; 0 means success, and any
+ other value means failure. If the process terminated with a
+ signal, `call-process' returns a string describing the signal.
+
+ In the examples below, the buffer `foo' is current.
+
+ (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
+ of `call-process':
+
+ (call-process insert-directory-program nil t nil switches
+ (if full-directory-p
+ (concat (file-name-as-directory file) ".")
+ file))
+
+ -- 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
+ DELETEP is non-`nil'; this is useful when BUFFER is `t', to insert
+ the output in the current buffer.
+
+ The arguments DESTINATION and DISPLAYP control what to do with the
+ output from the subprocess, and whether to update the display as
+ it comes in. For details, see the description of `call-process',
+ above. If DESTINATION is the integer 0, `call-process-region'
+ discards the output and returns `nil' immediately, without waiting
+ for the subprocess to finish.
+
+ The remaining arguments, ARGS, are strings that specify command
+ line arguments for the program.
+
+ The return value of `call-process-region' is just like that of
+ `call-process': `nil' if you told it to return without waiting;
+ otherwise, a number or string which indicates how the subprocess
+ terminated.
+
+ In the following example, we use `call-process-region' to run the
+ `cat' utility, with standard input being the first five characters
+ in buffer `foo' (the word `input'). `cat' copies its standard
+ input into its standard output. Since the argument DESTINATION is
+ `t', this output is inserted in the current buffer.
+
+ ---------- Buffer: foo ----------
+ input-!-
+ ---------- Buffer: foo ----------
+
+ (call-process-region 1 6 "cat" nil t)
+ => nil
+
+ ---------- Buffer: foo ----------
+ inputinput-!-
+ ---------- Buffer: foo ----------
+
+ The `shell-command-on-region' command uses `call-process-region'
+ like this:
+
+ (call-process-region
+ start end
+ shell-file-name ; Name of program.
+ nil ; Do not delete region.
+ buffer ; Send output to `buffer'.
+ nil ; No redisplay during output.
+ "-c" command) ; Arguments for the shell.
+
+\1f
+File: lispref.info, Node: MS-DOS Subprocesses, Next: Asynchronous Processes, Prev: Synchronous Processes, Up: Processes
- In XEmacs Lisp, a "sequence" is either a list, a vector, a bit
-vector, or a string. The common property that all sequences have is
-that each is an ordered collection of elements. This section describes
-functions that accept any kind of sequence.
+56.3 MS-DOS Subprocesses
+========================
- - Function: sequencep object
- Returns `t' if OBJECT is a list, vector, bit vector, or string,
- `nil' otherwise.
+On MS-DOS, you must indicate whether the data going to and from a
+synchronous subprocess are text or binary. Text data requires
+translation between the end-of-line convention used within Emacs (a
+single newline character) and the convention used outside Emacs (the
+two-character sequence, CRLF).
+
+ The variable `binary-process-input' applies to input sent to the
+subprocess, and `binary-process-output' applies to output received from
+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
+ If this variable is `nil', convert newlines to CRLF sequences in
+ the input to a synchronous subprocess.
+
+ -- Variable: binary-process-output
+ If this variable is `nil', convert CRLF sequences to newlines in
+ the output from a synchronous subprocess.
+
+ *Note Files and MS-DOS::, for related information.
+
+\1f
+File: lispref.info, Node: Asynchronous Processes, Next: Deleting Processes, Prev: MS-DOS Subprocesses, Up: Processes
- - Function: copy-sequence sequence
- Returns a copy of SEQUENCE. The copy is the same type of object
- as the original sequence, and it has the same elements in the same
- order.
-
- Storing a new element into the copy does not affect the original
- SEQUENCE, and vice versa. However, the elements of the new
- sequence are not copies; they are identical (`eq') to the elements
- of the original. Therefore, changes made within these elements, as
- found via the copied sequence, are also visible in the original
- sequence.
-
- If the sequence is a string with extents or text properties, the
- extents and text properties in the copy are also copied, not
- shared with the original. (This means that modifying the extents
- or text properties of the original will not affect the copy.)
- However, the actual values of the properties are shared. *Note
- Extents::, *Note Text Properties::.
-
- See also `append' in *Note Building Lists::, `concat' in *Note
- Creating Strings::, `vconcat' in *Note Vectors::, and `bvconcat'
- in *Note Bit Vectors::, for other ways to copy sequences.
-
- (setq bar '(1 2))
- => (1 2)
- (setq x (vector 'foo bar))
- => [foo (1 2)]
- (setq y (copy-sequence x))
- => [foo (1 2)]
-
- (eq x y)
+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
+parallel with Emacs, and the two may communicate with each other using
+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
+ 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
+ specifies the name for the process object; if a process with this
+ name already exists, then NAME is modified (by adding `<1>', etc.)
+ to be unique. The buffer BUFFER-OR-NAME is the buffer to
+ associate with the process.
+
+ The remaining arguments, ARGS, are strings that specify command
+ line arguments for the program.
+
+ In the example below, the first process is started and runs
+ (rather, sleeps) for 100 seconds. Meanwhile, the second process
+ is started, and given the name `my-process<1>' for the sake of
+ uniqueness. It inserts the directory listing at the end of the
+ buffer `foo', before the first process finishes. Then it
+ finishes, and a message to that effect is inserted in the buffer.
+ Much later, the first process finishes, and another message is
+ inserted in the buffer for it.
+
+ (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
+ &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
+ 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.
+
+ PTYs are usually preferable for processes visible to the user, as
+ in Shell mode, because they allow job control (`C-c', `C-z', etc.)
+ to work between the process and its children whereas pipes do not.
+ For subprocesses used for internal purposes by programs, it is
+ often better to use a pipe, because they are more efficient. In
+ addition, the total number of PTYs is limited on many systems and
+ it is good not to waste them. A rule of thumb is to use ptys for
+ processes the user interacts with directly, and pipes for
+ processes that are hidden from the user.
+
+ The value `process-connection-type' is used when `start-process'
+ is called. So you can specify how to communicate with one
+ subprocess by binding the variable around the call to
+ `start-process'.
+
+ (let ((process-connection-type nil)) ; Use a pipe.
+ (start-process ...))
+
+ To determine whether a given subprocess actually got a pipe or a
+ PTY, use the function `process-tty-name' (*note Process
+ Information::).
+
+ Lisp functions that manipulate processes usually accept a PROCESS
+argument. Besides using an actual process object for this argument, you
+can use a process name, a buffer object, the name of a buffer, or
+`nil'. Specifying a buffer or buffer name for the PROCESS argument
+means use the process associated with the buffer (or the most recent
+one, if there is more than one). `nil' means use the process
+associated with the current buffer. *Note Process Information::.
+*Note Process Buffers::.
+
+\1f
+File: lispref.info, Node: Deleting Processes, Next: Process Information, Prev: Asynchronous Processes, Up: 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
+a signal to the subprocess to make the subprocess terminate, but this is
+not guaranteed to happen immediately. The process object itself
+continues to exist as long as other Lisp objects point to it.
+
+ You can delete a process explicitly at any time. Processes are
+deleted automatically after they terminate, but not necessarily right
+away. If you delete a terminated process explicitly before it is
+deleted automatically, no harm results.
+
+ -- 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
+ 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
- (equal x y)
- => t
- (eq (elt x 1) (elt y 1))
+
+ -- 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
+ be deleted silently. If REQUIRE-QUERY-P is non-`nil', then XEmacs
+ _will_ query the user (this is the default). The return value is
+ `t' if a query was formerly required, and `nil' otherwise.
+
+ (process-kill-without-query (get-process "shell"))
=> t
-
- ;; Replacing an element of one sequence.
- (aset x 0 'quux)
- x => [quux (1 2)]
- y => [foo (1 2)]
-
- ;; Modifying the inside of a shared element.
- (setcar (aref x 1) 69)
- x => [quux (69 2)]
- y => [foo (69 2)]
-
- ;; Creating a bit vector.
- (bit-vector 1 0 1 1 0 1 0 0)
- => #*10110100
-
- - Function: length sequence
- Returns the number of elements in SEQUENCE. If SEQUENCE is a cons
- cell that is not a list (because the final CDR is not `nil'), a
- `wrong-type-argument' error is signaled.
-
- (length '(1 2 3))
- => 3
- (length ())
- => 0
- (length "foobar")
- => 6
- (length [1 2 3])
- => 3
- (length #*01101)
- => 5
-
- - Function: elt sequence index
- This function returns the element of SEQUENCE indexed by INDEX.
- Legitimate values of INDEX are integers ranging from 0 up to one
- less than the length of SEQUENCE. If SEQUENCE is a list, then
- out-of-range values of INDEX return `nil'; otherwise, they trigger
- an `args-out-of-range' error.
-
- (elt [1 2 3 4] 2)
- => 3
- (elt '(1 2 3 4) 2)
- => 3
- (char-to-string (elt "1234" 2))
- => "3"
- (elt #*00010000 3)
- => 1
- (elt [1 2 3 4] 4)
- error-->Args out of range: [1 2 3 4], 4
- (elt [1 2 3 4] -1)
- error-->Args out of range: [1 2 3 4], -1
-
- This function generalizes `aref' (*note Array Functions::) and
- `nth' (*note List Elements::).
-
-\1f
-File: lispref.info, Node: Arrays, Next: Array Functions, Prev: Sequence Functions, Up: Sequences Arrays Vectors
-
-Arrays
-======
-
- An "array" object has slots that hold a number of other Lisp
-objects, called the elements of the array. Any element of an array may
-be accessed in constant time. In contrast, an element of a list
-requires access time that is proportional to the position of the element
-in the list.
-
- When you create an array, you must specify how many elements it has.
-The amount of space allocated depends on the number of elements.
-Therefore, it is impossible to change the size of an array once it is
-created; you cannot add or remove elements. However, you can replace an
-element with a different value.
-
- XEmacs defines three types of array, all of which are
-one-dimensional: "strings", "vectors", and "bit vectors". A vector is a
-general array; its elements can be any Lisp objects. A string is a
-specialized array; its elements must be characters. A bit vector is
-another specialized array; its elements must be bits (an integer, either
-0 or 1). Each type of array has its own read syntax. *Note String
-Type::, *Note Vector Type::, and *Note Bit Vector Type::.
-
- All kinds of array share these characteristics:
-
- * The first element of an array has index zero, the second element
- has index 1, and so on. This is called "zero-origin" indexing.
- For example, an array of four elements has indices 0, 1, 2, and 3.
-
- * The elements of an array may be referenced or changed with the
- functions `aref' and `aset', respectively (*note Array
- Functions::).
-
- In principle, if you wish to have an array of text characters, you
-could use either a string or a vector. In practice, we always choose
-strings for such applications, for four reasons:
-
- * They usually occupy one-fourth the space of a vector of the same
- elements. (This is one-eighth the space for 64-bit machines such
- as the DEC Alpha, and may also be different when MULE support is
- compiled into XEmacs.)
-
- * Strings are printed in a way that shows the contents more clearly
- as characters.
-
- * Strings can hold extent and text properties. *Note Extents::,
- *Note Text Properties::.
-
- * Many of the specialized editing and I/O facilities of XEmacs
- accept only strings. For example, you cannot insert a vector of
- characters into a buffer the way you can insert a string. *Note
- Strings and Characters::.
-
- By contrast, for an array of keyboard input characters (such as a key
-sequence), a vector may be necessary, because many keyboard input
-characters are non-printable and are represented with symbols rather
-than with characters. *Note Key Sequence Input::.
-
- Similarly, when representing an array of bits, a bit vector has the
-following advantages over a regular vector:
-
- * They occupy 1/32nd the space of a vector of the same elements.
- (1/64th on 64-bit machines such as the DEC Alpha.)
-
- * Bit vectors are printed in a way that shows the contents more
- clearly as bits.
-
-\1f
-File: lispref.info, Node: Array Functions, Next: Vectors, Prev: Arrays, Up: Sequences Arrays Vectors
-
-Functions that Operate on Arrays
-================================
- In this section, we describe the functions that accept strings,
-vectors, and bit vectors.
+\1f
+File: lispref.info, Node: Process Information, Next: Input to Processes, Prev: Deleting Processes, Up: Processes
- - Function: arrayp object
- This function returns `t' if OBJECT is an array (i.e., a string,
- vector, or bit vector).
+56.6 Process Information
+========================
- (arrayp "asdf")
- => t
- (arrayp [a])
- => t
- (arrayp #*101)
- => t
+Several functions return information about processes. `list-processes'
+is provided for interactive use.
+
+ -- 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
+ 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
+ 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
+ returned as given. (That is not very useful, so the argument is
+ usually a name.) For example:
+
+ (get-process "shell")
+ => #<process shell>
+
+ -- 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
+ that were given to the program.
+
+ (process-command (get-process "shell"))
+ => ("/bin/csh" "-i")
+
+ -- 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
+ This function returns the name of 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).
+
+ The possible values for an actual subprocess are:
+
+ `run'
+ for a process that is running.
- - Function: aref array index
- This function returns the INDEXth element of ARRAY. The first
- element is at index zero.
-
- (setq primes [2 3 5 7 11 13])
- => [2 3 5 7 11 13]
- (aref primes 4)
- => 11
- (elt primes 4)
- => 11
-
- (aref "abcdefg" 1)
- => ?b
-
- (aref #*1101 2)
- => 0
-
- See also the function `elt', in *Note Sequence Functions::.
-
- - Function: aset array index object
- This function sets the INDEXth element of ARRAY to be OBJECT. It
- returns OBJECT.
-
- (setq w [foo bar baz])
- => [foo bar baz]
- (aset w 0 'fu)
- => fu
- w
- => [fu bar baz]
-
- (setq x "asdfasfd")
- => "asdfasfd"
- (aset x 3 ?Z)
- => ?Z
+ `stop'
+ for a process that is stopped but continuable.
+
+ `exit'
+ for a process that has exited.
+
+ `signal'
+ for a process that has received a fatal signal.
+
+ `open'
+ for a network connection that is open.
+
+ `closed'
+ for a network connection that is closed. Once a connection
+ is closed, you cannot reopen it, though you might be able to
+ open a new connection to the same place.
+
+ `nil'
+ if PROCESS does not identify an existing process.
+
+ (process-status "shell")
+ => run
+ (process-status (get-buffer "*shell*"))
+ => run
x
- => "asdZasfd"
-
- (setq bv #*1111)
- => #*1111
- (aset bv 2 0)
- => 0
- bv
- => #*1101
-
- If ARRAY is a string and OBJECT is not a character, a
- `wrong-type-argument' error results.
-
- - Function: fillarray array object
- This function fills the array ARRAY with OBJECT, so that each
- element of ARRAY is OBJECT. It returns ARRAY.
-
- (setq a [a b c d e f g])
- => [a b c d e f g]
- (fillarray a 0)
- => [0 0 0 0 0 0 0]
- a
- => [0 0 0 0 0 0 0]
-
- (setq s "When in the course")
- => "When in the course"
- (fillarray s ?-)
- => "------------------"
-
- (setq bv #*1101)
- => #*1101
- (fillarray bv 0)
- => #*0000
-
- If ARRAY is a string and OBJECT is not a character, a
- `wrong-type-argument' error results.
-
- The general sequence functions `copy-sequence' and `length' are
-often useful for objects known to be arrays. *Note Sequence
-Functions::.
+ => #<process xx<1>>
+ (process-status x)
+ => exit
+
+ For a network connection, `process-status' returns one of the
+ symbols `open' or `closed'. The latter means that the other side
+ closed the connection, or XEmacs did `delete-process'.
+
+ 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
+ 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
+ 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
+ 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
+ Asynchronous Processes::).
\1f
-File: lispref.info, Node: Vectors, Next: Vector Functions, Prev: Array Functions, Up: Sequences Arrays Vectors
+File: lispref.info, Node: Input to Processes, Next: Signals to Processes, Prev: Process Information, Up: Processes
-Vectors
-=======
+56.7 Sending Input to Processes
+===============================
- Arrays in Lisp, like arrays in most languages, are blocks of memory
-whose elements can be accessed in constant time. A "vector" is a
-general-purpose array; its elements can be any Lisp objects. (The other
-kind of array in XEmacs Lisp is the "string", whose elements must be
-characters.) Vectors in XEmacs serve as obarrays (vectors of symbols),
-although this is a shortcoming that should be fixed. They are also used
-internally as part of the representation of a byte-compiled function; if
-you print such a function, you will see a vector in it.
+Asynchronous subprocesses receive input when it is sent to them by
+XEmacs, which is done with the functions in this section. You must
+specify the process to send input to, and the input data to send. The
+data appears on the "standard input" of the subprocess.
- In XEmacs Lisp, the indices of the elements of a vector start from
-zero and count up from there.
+ Some operating systems have limited space for buffered input in a
+PTY. On these systems, XEmacs sends long input in chunks, with EOF
+characters added amidst the other characters, to force the operating
+system to periodically drain the input buffer. For most programs,
+these EOFs do no harm.
- Vectors are printed with square brackets surrounding the elements.
-Thus, a vector whose elements are the symbols `a', `b' and `a' is
-printed as `[a b a]'. You can write vectors in the same way in Lisp
-input.
+ -- Function: process-send-string process string &optional start end
+ This function sends PROCESS the contents of STRING as standard
+ input.
- A vector, like a string or a number, is considered a constant for
-evaluation: the result of evaluating it is the same vector. This does
-not evaluate or even examine the elements of the vector. *Note
-Self-Evaluating Forms::.
+ The argument PROCESS may be a process or the name of a process, or
+ a buffer or the name of a buffer, in which case the buffer's
+ process is used. If it is `nil', the current buffer's process is
+ used.
- Here are examples of these principles:
+ Optional arguments START and END specify part of STRING; see
+ `substring'.
- (setq avector [1 two '(three) "four" [five]])
- => [1 two (quote (three)) "four" [five]]
- (eval avector)
- => [1 two (quote (three)) "four" [five]]
- (eq avector (eval avector))
- => t
+ The function returns `nil'.
+
+ (process-send-string "shell<1>" "ls\n")
+ => nil
+
+
+ ---------- Buffer: *shell* ----------
+ ...
+ introduction.texi syntax-tables.texi~
+ introduction.texi~ text.texi
+ introduction.txt text.texi~
+ ...
+ ---------- Buffer: *shell* ----------
+
+ -- 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.
+
+ The argument PROCESS may be a process or the name of a process, or
+ a buffer or the name of a buffer, in which case the buffer's
+ process is used. If it is `nil', the current buffer's process is
+ used.
+
+ An error is signaled unless both START and END are integers or
+ markers that indicate positions in the current buffer. (It is
+ unimportant which number is larger.)
+
+ -- 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.
+
+ PROCESS may be a process, a buffer, the name of a process or
+ buffer, or `nil', indicating the current buffer's process. An
+ error is signaled if PROCESS does not identify any process.
+
+ The function returns the process object identified by PROCESS.
+
+ (process-send-eof "shell")
+ => "shell"
\1f
-File: lispref.info, Node: Vector Functions, Next: Bit Vectors, Prev: Vectors, Up: Sequences Arrays Vectors
+File: lispref.info, Node: Signals to Processes, Next: Output from Processes, Prev: Input to Processes, Up: Processes
-Functions That Operate on Vectors
+56.8 Sending Signals to Processes
=================================
- Here are some functions that relate to vectors:
+"Sending a signal" to a subprocess is a way of interrupting its
+activities. There are several different signals, each with its own
+meaning. The set of signals and their names is defined by the operating
+system. For example, the signal `SIGINT' means that the user has typed
+`C-c', or that some analogous thing has happened.
+
+ Each signal has a standard effect on the subprocess. Most signals
+kill the subprocess, but some stop or resume execution instead. Most
+signals can optionally be handled by programs; if the program handles
+the signal, then we can say nothing in general about its effects.
+
+ The set of signals and their names is defined by the operating
+system; XEmacs has facilities for sending only a few of the signals
+that are defined. XEmacs can send signals only to its own subprocesses.
+
+ You can send signals explicitly by calling the functions in this
+section. XEmacs also sends signals automatically at certain times:
+killing a buffer sends a `SIGHUP' signal to all its associated
+processes; killing XEmacs sends a `SIGHUP' signal to all remaining
+processes. (`SIGHUP' is a signal that indicates that the connection
+between the user and the process is broken, for example if a connection
+via a telephone line is hung up.)
+
+ Each of the signal-sending functions takes two optional arguments:
+PROCESS and CURRENT-GROUP.
+
+ The argument PROCESS must be either a process or a buffer, the name
+of one, or `nil'. If it is `nil', the process defaults to the process
+associated with the current buffer. An error is signaled if PROCESS
+does not identify a process.
+
+ The argument CURRENT-GROUP is a flag that makes a difference when
+you are running a job-control shell as an XEmacs subprocess. If it is
+non-`nil', then the signal is sent to the current foreground process
+group of the terminal that XEmacs uses to communicate with the
+subprocess. If the process is a job-control shell, this means the
+shell's current subjob. If it is `nil', the signal is sent to the
+process group of the immediate subprocess of XEmacs. If the subprocess
+is a job-control shell, this is the shell itself.
+
+ The flag CURRENT-GROUP has no effect when a pipe is used to
+communicate with the subprocess, because the operating system does not
+support the distinction in the case of pipes. For the same reason,
+job-control shells won't work when a pipe is used. See
+`process-connection-type' in *Note Asynchronous Processes::.
+
+ Some of the functions below take a SIGNAL argument, which identifies
+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
+ 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
+ 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
+ CURRENT-GROUP is non-`nil', you can think of this function as
+ "typing `C-c'" on the terminal by which XEmacs talks to the
+ subprocess.
+
+ -- 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
+ 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
+ This function stops the process PROCESS by sending the signal
+ `SIGTSTP'. Use `continue-process' to resume its execution.
+
+ On systems with job control, the "stop character" (usually `C-z')
+ sends this signal (outside of XEmacs). When CURRENT-GROUP is
+ 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
+ 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
+ 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
- - Function: vectorp object
- This function returns `t' if OBJECT is a vector.
+56.9 Receiving Output from Processes
+====================================
- (vectorp [a])
- => t
- (vectorp "asdf")
- => nil
+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,
+which is called the associated buffer of the process, or a function
+called the "filter function" can be called to act on the output. If
+the process has no buffer and no filter function, its output is
+discarded.
+
+* Menu:
+
+* Process Buffers:: If no filter, output is put in a buffer.
+* Filter Functions:: Filter functions accept output from the process.
+* Accepting Output:: Explicitly permitting subprocess output.
+ Waiting for subprocess output.
- - Function: vector &rest objects
- This function creates and returns a vector whose elements are the
- arguments, OBJECTS.
+\1f
+File: lispref.info, Node: Process Buffers, Next: Filter Functions, Up: Output from Processes
- (vector 'foo 23 [bar baz] "rats")
- => [foo 23 [bar baz] "rats"]
- (vector)
- => []
+56.9.1 Process Buffers
+----------------------
- - Function: make-vector length object
- This function returns a new vector consisting of LENGTH elements,
- each initialized to OBJECT.
+A process can (and usually does) have an "associated buffer", which is
+an ordinary Emacs buffer that is used for two purposes: storing the
+output from the process, and deciding when to kill the process. You
+can also use the buffer to identify a process to operate on, since in
+normal practice only one process is associated with any given buffer.
+Many applications of processes also use the buffer for editing input to
+be sent to the process, but this is not built into XEmacs Lisp.
- (setq sleepy (make-vector 9 'Z))
- => [Z Z Z Z Z Z Z Z Z]
+ Unless the process has a filter function (*note Filter Functions::),
+its output is inserted in the associated buffer. The position to insert
+the output is determined by the `process-mark', which is then updated
+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: vconcat &rest sequences
- This function returns a new vector containing all the elements of
- the SEQUENCES. The arguments SEQUENCES may be lists, vectors, or
- strings. If no SEQUENCES are given, an empty vector is returned.
+ -- Function: process-buffer process
+ This function returns the associated buffer of the process PROCESS.
- The value is a newly constructed vector that is not `eq' to any
- existing vector.
+ (process-buffer (get-process "shell"))
+ => #<buffer *shell*>
- (setq a (vconcat '(A B C) '(D E F)))
- => [A B C D E F]
- (eq a (vconcat a))
- => nil
- (vconcat)
- => []
- (vconcat [A B C] "aa" '(foo (6 7)))
- => [A B C 97 97 foo (6 7)]
+ -- 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.
+
+ If PROCESS does not have a buffer, `process-mark' returns a marker
+ that points nowhere.
+
+ Insertion of process output in a buffer uses this marker to decide
+ where to insert, and updates it to point after the inserted text.
+ That is why successive batches of output are inserted
+ consecutively.
+
+ Filter functions normally should use this marker in the same
+ fashion as is done by direct insertion of output in the buffer. A
+ good example of a filter function that uses `process-mark' is
+ found at the end of the following section.
+
+ When the user is expected to enter input in the process buffer for
+ transmission to the process, the process marker is useful for
+ distinguishing the new input from previous output.
- The `vconcat' function also allows integers as arguments. It
- converts them to strings of digits, making up the decimal print
- representation of the integer, and then uses the strings instead
- of the original integers. *Don't use this feature; we plan to
- eliminate it. If you already use this feature, change your
- programs now!* The proper way to convert an integer to a decimal
- number in this way is with `format' (*note Formatting Strings::)
- or `number-to-string' (*note String Conversion::).
+ -- 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.
- For other concatenation functions, see `mapconcat' in *Note
- Mapping Functions::, `concat' in *Note Creating Strings::, `append'
- in *Note Building Lists::, and `bvconcat' in *Note Bit Vector
- Functions::.
+ -- 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
+ recently created.) It is usually a bad idea to have more than one
+ process associated with the same buffer.
- The `append' function provides a way to convert a vector into a list
-with the same elements (*note Building Lists::):
+ (get-buffer-process "*shell*")
+ => #<process shell>
- (setq avector [1 two (quote (three)) "four" [five]])
- => [1 two (quote (three)) "four" [five]]
- (append avector nil)
- => (1 two (quote (three)) "four" [five])
+ Killing the process's buffer deletes the process, which kills the
+ subprocess with a `SIGHUP' signal (*note Signals to Processes::).
\1f
-File: lispref.info, Node: Bit Vectors, Next: Bit Vector Functions, Prev: Vector Functions, Up: Sequences Arrays Vectors
+File: lispref.info, Node: Filter Functions, Next: Accepting Output, Prev: Process Buffers, Up: Output from Processes
+
+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
+_all_ output from that process is passed to the filter. The process
+buffer is used directly for output from the process only when there is
+no filter.
+
+ A filter function must accept two arguments: the associated process
+and a string, which is the output. The function is then free to do
+whatever it chooses with the output.
+
+ A filter function runs only while XEmacs is waiting (e.g., for
+terminal input, or for time to elapse, or for process output). This
+avoids the timing errors that could result from running filters at
+random places in the middle of other Lisp programs. You may explicitly
+cause Emacs to wait, so that filter functions will run, by calling
+`sit-for' or `sleep-for' (*note Waiting::), or `accept-process-output'
+(*note Accepting Output::). Emacs is also waiting when the command loop
+is reading input.
+
+ Quitting is normally inhibited within a filter function--otherwise,
+the effect of typing `C-g' at command level or to quit a user command
+would be unpredictable. If you want to permit quitting inside a filter
+function, bind `inhibit-quit' to `nil'. *Note Quitting::.
+
+ If an error happens during execution of a filter function, it is
+caught automatically, so that it doesn't stop the execution of whatever
+program was running when the filter function was started. However, if
+`debug-on-error' is non-`nil', the error-catching is turned off. This
+makes it possible to use the Lisp debugger to debug the filter
+function. *Note Debugger::.
+
+ Many filter functions sometimes or always insert the text in the
+process's buffer, mimicking the actions of XEmacs when there is no
+filter. Such filter functions need to use `set-buffer' in order to be
+sure to insert in that buffer. To avoid setting the current buffer
+semipermanently, these filter functions must use `unwind-protect' to
+make sure to restore the previous current buffer. They should also
+update the process marker, and in some cases update the value of point.
+Here is how to do these things:
+
+ (defun ordinary-insertion-filter (process string)
+ (let ((old-buffer (current-buffer)))
+ (unwind-protect
+ (let (moving)
+ (set-buffer (process-buffer process))
+ (setq moving (= (point) (process-mark process)))
+ (save-excursion
+ ;; Insert the text, moving the process-marker.
+ (goto-char (process-mark process))
+ (insert string)
+ (set-marker (process-mark process) (point)))
+ (if moving (goto-char (process-mark process))))
+ (set-buffer old-buffer))))
+
+The reason to use an explicit `unwind-protect' rather than letting
+`save-excursion' restore the current buffer is so as to preserve the
+change in point made by `goto-char'.
+
+ To make the filter force the process buffer to be visible whenever
+new text arrives, insert the following line just before the
+`unwind-protect':
+
+ (display-buffer (process-buffer process))
+
+ To force point to move to the end of the new output no matter where
+it was previously, eliminate the variable `moving' and call `goto-char'
+unconditionally.
+
+ In earlier Emacs versions, every filter function that did regexp
+searching or matching had to explicitly save and restore the match data.
+Now Emacs does this automatically; filter functions never need to do it
+explicitly. *Note Match Data::.
+
+ A filter function that writes the output into the buffer of the
+process should check whether the buffer is still alive. If it tries to
+insert into a dead buffer, it will get an error. If the buffer is dead,
+`(buffer-name (process-buffer PROCESS))' returns `nil'.
+
+ The output to the function may come in chunks of any size. A program
+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
+ 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
+ is changed. (Output received during this time is not discarded,
+ but is queued, and will be processed as soon as the filter is
+ changed.)
+
+ -- 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.
+
+ Here is an example of use of a filter function:
+
+ (defun keep-output (process output)
+ (setq kept (cons output kept)))
+ => keep-output
+ (setq kept nil)
+ => nil
+ (set-process-filter (get-process "shell") 'keep-output)
+ => keep-output
+ (process-send-string "shell" "ls ~/other\n")
+ => nil
+ kept
+ => ("lewis@slug[8] % "
+ "FINAL-W87-SHORT.MSS backup.otl kolstad.mss~
+ address.txt backup.psf kolstad.psf
+ backup.bib~ david.mss resume-Dec-86.mss~
+ backup.err david.psf resume-Dec.psf
+ backup.mss dland syllabus.mss
+ "
+ "#backups.mss# backup.mss~ kolstad.mss
+ ")
-Bit Vectors
-===========
+\1f
+File: lispref.info, Node: Accepting Output, Prev: Filter Functions, Up: 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
+or terminal input. Occasionally it is useful in a Lisp program to
+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
+ 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
+ function does not return until some output has been received from
+ PROCESS.
+
+ The arguments SECONDS and MILLISEC let you specify timeout
+ periods. The former specifies a period measured in seconds and the
+ latter specifies one measured in milliseconds. The two time
+ periods thus specified are added together, and
+ `accept-process-output' returns after that much time whether or
+ not there has been any subprocess output. Note that SECONDS is
+ allowed to be a floating-point number; thus, there is no need to
+ ever use MILLISEC. (It is retained for compatibility purposes.)
+
+ The function `accept-process-output' returns non-`nil' if it did
+ get some output, or `nil' if the timeout expired before output
+ arrived.
+
+\1f
+File: lispref.info, Node: Sentinels, Next: Process Window Size, Prev: Output from Processes, Up: Processes
+
+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
+(whether sent by XEmacs or caused by the process's own actions) that
+terminate, stop, or continue the process. The process sentinel is also
+called if the process exits. The sentinel receives two arguments: the
+process for which the event occurred, and a string describing the type
+of event.
+
+ The string describing the event looks like one of the following:
+
+ * `"finished\n"'.
+
+ * `"exited abnormally with code EXITCODE\n"'.
+
+ * `"NAME-OF-SIGNAL\n"'.
+
+ * `"NAME-OF-SIGNAL (core dumped)\n"'.
+
+ A sentinel runs only while XEmacs is waiting (e.g., for terminal
+input, or for time to elapse, or for process output). This avoids the
+timing errors that could result from running them at random places in
+the middle of other Lisp programs. A program can wait, so that
+sentinels will run, by calling `sit-for' or `sleep-for' (*note
+Waiting::), or `accept-process-output' (*note Accepting Output::).
+Emacs is also waiting when the command loop is reading input.
+
+ Quitting is normally inhibited within a sentinel--otherwise, the
+effect of typing `C-g' at command level or to quit a user command would
+be unpredictable. If you want to permit quitting inside a sentinel,
+bind `inhibit-quit' to `nil'. *Note Quitting::.
+
+ A sentinel that writes the output into the buffer of the process
+should check whether the buffer is still alive. If it tries to insert
+into a dead buffer, it will get an error. If the buffer is dead,
+`(buffer-name (process-buffer PROCESS))' returns `nil'.
+
+ If an error happens during execution of a sentinel, it is caught
+automatically, so that it doesn't stop the execution of whatever
+programs was running when the sentinel was started. However, if
+`debug-on-error' is non-`nil', the error-catching is turned off. This
+makes it possible to use the Lisp debugger to debug the sentinel.
+*Note Debugger::.
+
+ In earlier Emacs versions, every sentinel that did regexp searching
+or matching had to explicitly save and restore the match data. Now
+Emacs does this automatically; sentinels never need to do it explicitly.
+*Note Match Data::.
+
+ -- 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's buffer when the process status changes.
+
+ (defun msg-me (process event)
+ (princ
+ (format "Process: %s had the event `%s'" process event)))
+ (set-process-sentinel (get-process "shell") 'msg-me)
+ => msg-me
+ (kill-process (get-process "shell"))
+ -| Process: #<process shell> had the event `killed'
+ => #<process shell>
+
+ -- Function: process-sentinel process
+ This function returns the sentinel of PROCESS, or `nil' if it has
+ none.
+
+ -- 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,
+ `nil' if it was not.
+
+\1f
+File: lispref.info, Node: Process Window Size, Next: Transaction Queues, Prev: Sentinels, Up: Processes
+
+56.11 Process Window Size
+=========================
+
+ -- 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
+
+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
+ 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
+ This function sends a transaction to queue QUEUE. Specifying the
+ queue has the effect of specifying the subprocess to talk to.
- Bit vectors are specialized vectors that can only represent arrays
-of 1's and 0's. Bit vectors have a very efficient representation and
-are useful for representing sets of boolean (true or false) values.
+ The argument QUESTION is the outgoing message that starts the
+ transaction. The argument FN is the function to call when the
+ corresponding answer comes back; it is called with two arguments:
+ CLOSURE, and the answer received.
- There is no limit on the size of a bit vector. You could, for
-example, create a bit vector with 100,000 elements if you really wanted
-to.
+ The argument REGEXP is a regular expression that should match the
+ entire answer, but nothing less; that's how `tq-enqueue' determines
+ where the answer ends.
- Bit vectors have a special printed representation consisting of `#*'
-followed by the bits of the vector. For example, a bit vector whose
-elements are 0, 1, 1, 0, and 1, respectively, is printed as
+ The return value of `tq-enqueue' itself is not meaningful.
- #*01101
+ -- Function: tq-close queue
+ Shut down transaction queue QUEUE, waiting for all pending
+ transactions to complete, and then terminate the connection or
+ child process.
- Bit vectors are considered constants for evaluation, like vectors,
-strings, and numbers. *Note Self-Evaluating Forms::.
+ Transaction queues are implemented by means of a filter function.
+*Note Filter Functions::.
\1f
-File: lispref.info, Node: Bit Vector Functions, Prev: Bit Vectors, Up: Sequences Arrays Vectors
+File: lispref.info, Node: Network, Prev: Transaction Queues, Up: Processes
+
+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
+is handled by Lisp much like a subprocess, and is represented by a
+process object. However, the process you are communicating with is not
+a child of the XEmacs process, so you can't kill it or send it signals.
+All you can do is send and receive data. `delete-process' closes the
+connection, but does not kill the process at the other end; that
+process must decide what to do about closure of the connection.
+
+ You can distinguish process objects representing network connections
+from those representing subprocesses with the `process-status'
+function. It always returns either `open' or `closed' for a network
+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
+ &optional protocol
+ This function opens a TCP connection for a service to a host. It
+ returns a process object to represent the connection.
+
+ Input and output work as for other process objects.
+ `delete-process' closes the connection.
+
+ The NAME argument specifies the name for the process object. It
+ is modified as necessary to make it unique.
+
+ The BUFFER-OR-NAME argument is the buffer to associate with the
+ connection. It can be a buffer or the name of one. Output from
+ the connection is inserted in the buffer, unless you specify a
+ filter function to handle the output. If BUFFER-OR-NAME is `nil',
+ it means that the connection is not associated with any buffer.
+
+ The arguments HOST and SERVICE specify where to connect to; HOST
+ is the host name or IP address (a string), and SERVICE is the name
+ of a defined network service (a string) or a port number (an
+ integer).
+
+ Optional fifth arg PROTOCOL is the network protocol to use.
+ Currently only `tcp' (Transmission Control Protocol) and `udp'
+ (User Datagram Protocol) are supported. When omitted, `tcp' is
+ assumed.
+
+ Output via `process-send-string' and input via buffer or filter
+ (see `set-process-filter') are stream-oriented. That means UDP
+ datagrams are not guaranteed to be sent and received in discrete
+ packets. (But small datagrams around 500 bytes that are not
+ truncated by `process-send-string' are usually fine.) Note further
+ that the UDP protocol does not guard against lost packets.
-Functions That Operate on Bit Vectors
-=====================================
+\1f
+File: lispref.info, Node: System Interface, Next: X-Windows, Prev: Processes, Up: Top
- Here are some functions that relate to bit vectors:
+57 Operating System Interface
+*****************************
- - Function: bit-vector-p object
- This function returns `t' if OBJECT is a bit vector.
+This chapter is about starting and getting out of Emacs, access to
+values in the operating system environment, and terminal input, output,
+and flow control.
- (bit-vector-p #*01)
- => t
- (bit-vector-p [0 1])
- => nil
- (bit-vector-p "01")
- => nil
+ *Note Building XEmacs::, for related information. See also *Note
+Display::, for additional operating system status information
+pertaining to the terminal and the screen.
+
+* Menu:
+
+* Starting Up:: Customizing XEmacs start-up processing.
+* Getting Out:: How exiting works (permanent or temporary).
+* System Environment:: Distinguish the name and kind of system.
+* User Identification:: Finding the name and user id of the user.
+* Time of Day:: Getting the current time.
+* Time Conversion:: Converting a time from numeric form to a string, or
+ to calendrical data (or vice versa).
+* Timers:: Setting a timer to call a function at a certain time.
+* Terminal Input:: Recording terminal input for debugging.
+* Terminal Output:: Recording terminal output for debugging.
+* Flow Control:: How to turn output flow control on or off.
+* Batch Mode:: Running XEmacs without terminal interaction.
- - Function: bitp object
- This function returns `t' if OBJECT is either 0 or 1.
+\1f
+File: lispref.info, Node: Starting Up, Next: Getting Out, Up: System Interface
- - Function: bit-vector &rest bits
- This function creates and returns a bit vector whose elements are
- the arguments BITS. Each argument must be a bit, i.e. one of the
- two integers 0 or 1.
+57.1 Starting Up XEmacs
+=======================
- (bit-vector 0 0 0 1 0 0 0 0 1 0)
- => #*0001000010
- (bit-vector)
- => #*
+This section describes what XEmacs does when it is started, and how you
+can customize these actions.
- - Function: make-bit-vector length bit
- This function creates and returns a bit vector consisting of
- LENGTH elements, each initialized to BIT, which must be one of the
- two integers 0 or 1.
+* Menu:
- (setq picket-fence (make-bit-vector 9 1))
- => #*111111111
+* Start-up Summary:: Sequence of actions XEmacs performs at start-up.
+* Init File:: Details on reading the init file (`.emacs').
+* Terminal-Specific:: How the terminal-specific Lisp file is read.
+* Command Line Arguments:: How command line arguments are processed,
+ and how you can customize them.
- - Function: bvconcat &rest sequences
- This function returns a new bit vector containing all the elements
- of the SEQUENCES. The arguments SEQUENCES may be lists, vectors,
- or bit vectors, all of whose elements are the integers 0 or 1. If
- no SEQUENCES are given, an empty bit vector is returned.
+\1f
+File: lispref.info, Node: Start-up Summary, Next: Init File, Up: Starting Up
- The value is a newly constructed bit vector that is not `eq' to any
- existing bit vector.
+57.1.1 Summary: Sequence of Actions at Start Up
+-----------------------------------------------
- (setq a (bvconcat '(1 1 0) '(0 0 1)))
- => #*110001
- (eq a (bvconcat a))
- => nil
- (bvconcat)
- => #*
- (bvconcat [1 0 0 0 0] #*111 '(0 0 0 0 1))
- => #*1000011100001
+The order of operations performed (in `startup.el') by XEmacs when it
+is started up is as follows:
+
+ 1. It loads the initialization library for the window system, if you
+ are using a window system. This library's name is
+ `term/WINDOWSYSTEM-win.el'.
+
+ 2. It processes the initial options. (Some of them are handled even
+ earlier than this.)
+
+ 3. It initializes the X window frame and faces, if appropriate.
+
+ 4. It runs the normal hook `before-init-hook'.
- For other concatenation functions, see `mapconcat' in *Note
- Mapping Functions::, `concat' in *Note Creating Strings::,
- `vconcat' in *Note Vector Functions::, and `append' in *Note
- Building Lists::.
+ 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'.
- The `append' function provides a way to convert a bit vector into a
-list with the same elements (*note Building Lists::):
+ 6. It loads the file `~/.emacs' unless `-q' was specified on the
+ command line. (This is not done in `-batch' mode.) The `-u'
+ option can specify the user name whose home directory should be
+ used instead of `~'.
- (setq bv #*00001110)
- => #*00001110
- (append bv nil)
- => (0 0 0 0 1 1 1 0)
+ 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'.
+
+ 8. It runs the normal hook `after-init-hook'.
+
+ 9. It sets the major mode according to `initial-major-mode', provided
+ the buffer `*scratch*' is still current and still in Fundamental
+ mode.
+
+ 10. It loads the terminal-specific Lisp file, if any, except when in
+ batch mode or using a window system.
+
+ 11. It displays the initial echo area message, unless you have
+ suppressed that with `inhibit-startup-echo-area-message'.
+
+ 12. It processes the action arguments from the command line.
+
+ 13. It runs `term-setup-hook'.
+
+ 14. It calls `frame-notice-user-settings', which modifies the
+ parameters of the selected frame according to whatever the init
+ files specify.
+
+ 15. It runs `window-setup-hook'. *Note Terminal-Specific::.
+
+ 16. It displays copyleft, nonwarranty, and basic use information,
+ 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
+ This variable inhibits the initial startup messages (the
+ nonwarranty, etc.). If it is non-`nil', then the messages are not
+ printed.
+
+ This variable exists so you can set it in your personal init file,
+ once you are familiar with the contents of the startup message.
+ Do not set this variable in the init file of a new user, or in a
+ 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
+ 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:
+
+ (setq inhibit-startup-echo-area-message
+ "YOUR-LOGIN-NAME")
+
+ Simply setting `inhibit-startup-echo-area-message' to your login
+ name is not sufficient to inhibit the message; Emacs explicitly
+ checks whether `.emacs' contains an expression as shown above.
+ Your login name must appear in the expression as a Lisp string
+ constant.
+
+ This way, you can easily inhibit the message for yourself if you
+ wish, but thoughtless copying of your `.emacs' file will not
+ inhibit the message for someone else.
+
+\1f
+File: lispref.info, Node: Init File, Next: Terminal-Specific, Prev: Start-up Summary, Up: Starting Up
+
+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
+code. It is called your "init file". The command line switches `-q'
+and `-u' affect the use of the init file; `-q' says not to load an init
+file, and `-u' says to load a specified user's init file instead of
+yours. *Note Entering XEmacs: (xemacs)Entering XEmacs.
+
+ A site may have a "default init file", which is the library named
+`default.el'. XEmacs finds the `default.el' file through the standard
+search path for libraries (*note How Programs Do Loading::). The
+XEmacs distribution does not come with this file; sites may provide one
+for local customizations. If the default init file exists, it is
+loaded whenever you start Emacs, except in batch mode or if `-q' is
+specified. But your own personal init file, if any, is loaded first; if
+it sets `inhibit-default-init' to a non-`nil' value, then XEmacs does
+not subsequently load the `default.el' file.
+
+ Another file for site-customization is `site-start.el'. Emacs loads
+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
+ This variable specifies the site-customization file to load before
+ the user's init file. Its normal value is `"site-start"'.
+
+ If there is a great deal of code in your `.emacs' file, you should
+move it into another file named `SOMETHING.el', byte-compile it (*note
+Byte Compilation::), and make your `.emacs' file load the other file
+using `load' (*note Loading::).
+
+ *Note Init File Examples: (xemacs)Init File Examples, for examples
+of how to make various commonly desired customizations in your `.emacs'
+file.
+
+ -- 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
+ 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
+
+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
+library is called `term/TERMTYPE'. XEmacs finds the file by searching
+the `load-path' directories as it does for other files, and trying the
+`.elc' and `.el' suffixes. Normally, terminal-specific Lisp library is
+located in `emacs/lisp/term', a subdirectory of the `emacs/lisp'
+directory in which most XEmacs Lisp libraries are kept.
+
+ The library's name is constructed by concatenating the value of the
+variable `term-file-prefix' and the terminal type. Normally,
+`term-file-prefix' has the value `"term/"'; changing this is not
+recommended.
+
+ The usual function of a terminal-specific library is to enable
+special keys to send sequences that XEmacs can recognize. It may also
+need to set or add to `function-key-map' if the Termcap entry does not
+specify all the terminal's function keys. *Note Terminal Input::.
+
+ When the name of the terminal type contains a hyphen, only the part
+of the name before the first hyphen is significant in choosing the
+library name. Thus, terminal types `aaa-48' and `aaa-30-rv' both use
+the `term/aaa' library. If necessary, the library can evaluate
+`(getenv "TERM")' to find the full name of the terminal type.
+
+ Your `.emacs' file can prevent the loading of the terminal-specific
+library by setting the variable `term-file-prefix' to `nil'. This
+feature is useful when experimenting with your own peculiar
+customizations.
+
+ You can also arrange to override some of the actions of the
+terminal-specific library by setting the variable `term-setup-hook'.
+This is a normal hook which XEmacs runs using `run-hooks' at the end of
+XEmacs initialization, after loading both your `.emacs' file and any
+terminal-specific libraries. You can use this variable to define
+initializations for terminals that do not have their own libraries.
+*Note Hooks::.
+
+ -- Variable: term-file-prefix
+ If the `term-file-prefix' variable is non-`nil', XEmacs loads a
+ terminal-specific initialization file as follows:
+
+ (load (concat term-file-prefix (getenv "TERM")))
+
+ You may set the `term-file-prefix' variable to `nil' in your
+ `.emacs' file if you do not wish to load the
+ terminal-initialization file. To do this, put the following in
+ your `.emacs' file: `(setq term-file-prefix nil)'.
+
+ -- 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
+ 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
+ `term-setup-hook'.
\1f
-File: lispref.info, Node: Symbols, Next: Evaluation, Prev: Sequences Arrays Vectors, Up: Top
+File: lispref.info, Node: Command Line Arguments, Prev: Terminal-Specific, Up: Starting Up
+
+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
+day, and will often leave your XEmacs session running longer than that,
+command line arguments are hardly ever used. As a practical matter, it
+is best to avoid making the habit of using them, since this habit would
+encourage you to kill and restart XEmacs unnecessarily often. These
+options exist for two reasons: to be compatible with other editors (for
+invocation by other programs) and to enable shell scripts to run
+specific Lisp programs.
+
+ This section describes how Emacs processes command line arguments,
+and how you can customize them.
+
+ -- 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
+ The value of this variable is `t' once the command line has been
+ processed.
+
+ If you redump XEmacs by calling `dump-emacs', you may wish to set
+ this variable to `nil' first in order to cause the new dumped
+ XEmacs to process its new command line arguments.
+
+ -- 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.
+
+ A "command line option" is an argument on the command line of the
+ form:
+
+ -OPTION
+
+ The elements of the `command-switch-alist' look like this:
+
+ (OPTION . HANDLER-FUNCTION)
+
+ The HANDLER-FUNCTION is called to handle OPTION and receives the
+ option name as its sole argument.
+
+ In some cases, the option is followed in the command line by an
+ argument. In these cases, the HANDLER-FUNCTION can find all the
+ remaining command-line arguments in the variable
+ `command-line-args-left'. (The entire list of command-line
+ arguments is in `command-line-args'.)
-Symbols
-*******
+ The command line arguments are parsed by the `command-line-1'
+ function in the `startup.el' file. See also *Note Command Line
+ Switches and Arguments: (xemacs)Command Switches.
- A "symbol" is an object with a unique name. This chapter describes
-symbols, their components, their property lists, and how they are
-created and interned. Separate chapters describe the use of symbols as
-variables and as function names; see *Note Variables::, and *Note
-Functions::. For the precise read syntax for symbols, see *Note Symbol
-Type::.
+ -- Variable: command-line-args
+ The value of this variable is the list of command line arguments
+ passed to XEmacs.
- You can test whether an arbitrary Lisp object is a symbol with
-`symbolp':
+ -- 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
+ are called, in order of appearance, until one of them returns a
+ non-`nil' value.
- - Function: symbolp object
- This function returns `t' if OBJECT is a symbol, `nil' otherwise.
+ These functions are called with no arguments. They can access the
+ command-line argument under consideration through the variable
+ `argi'. The remaining arguments (not including the current one)
+ are in the variable `command-line-args-left'.
+
+ When a function recognizes and processes the argument in `argi', it
+ should return a non-`nil' value to say it has dealt with that
+ argument. If it has also dealt with some of the following
+ arguments, it can indicate that by deleting them from
+ `command-line-args-left'.
+
+ If all of these functions return `nil', then the argument is used
+ as a file name to visit.
+
+\1f
+File: lispref.info, Node: Getting Out, Next: System Environment, Prev: Starting Up, Up: System Interface
+
+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
+reenter the XEmacs process later. As a practical matter, you seldom
+kill XEmacs--only when you are about to log out. Suspending is much
+more common.
* Menu:
-* Symbol Components:: Symbols have names, values, function definitions
- and property lists.
-* Definitions:: A definition says how a symbol will be used.
-* Creating Symbols:: How symbols are kept unique.
-* Symbol Properties:: Each symbol has a property list
- for recording miscellaneous information.
+* Killing XEmacs:: Exiting XEmacs irreversibly.
+* Suspending XEmacs:: Exiting XEmacs reversibly.
\1f
-File: lispref.info, Node: Symbol Components, Next: Definitions, Up: Symbols
+File: lispref.info, Node: Killing XEmacs, Next: Suspending XEmacs, Up: Getting Out
-Symbol Components
-=================
+57.2.1 Killing XEmacs
+---------------------
- Each symbol has four components (or "cells"), each of which
-references another object:
-
-Print name
- The "print name cell" holds a string that names the symbol for
- reading and printing. See `symbol-name' in *Note Creating
- Symbols::.
-
-Value
- The "value cell" holds the current value of the symbol as a
- variable. When a symbol is used as a form, the value of the form
- is the contents of the symbol's value cell. See `symbol-value' in
- *Note Accessing Variables::.
-
-Function
- The "function cell" holds the function definition of the symbol.
- When a symbol is used as a function, its function definition is
- used in its place. This cell is also used to make a symbol stand
- for a keymap or a keyboard macro, for editor command execution.
- Because each symbol has separate value and function cells,
- variables and function names do not conflict. See
- `symbol-function' in *Note Function Cells::.
-
-Property list
- The "property list cell" holds the property list of the symbol.
- See `symbol-plist' in *Note Symbol Properties::.
-
- The print name cell always holds a string, and cannot be changed.
-The other three cells can be set individually to any specified Lisp
-object.
-
- The print name cell holds the string that is the name of the symbol.
-Since symbols are represented textually by their names, it is important
-not to have two symbols with the same name. The Lisp reader ensures
-this: every time it reads a symbol, it looks for an existing symbol with
-the specified name before it creates a new one. (In XEmacs Lisp, this
-lookup uses a hashing algorithm and an obarray; see *Note Creating
-Symbols::.)
-
- In normal usage, the function cell usually contains a function or
-macro, as that is what the Lisp interpreter expects to see there (*note
-Evaluation::). Keyboard macros (*note Keyboard Macros::), keymaps
-(*note Keymaps::) and autoload objects (*note Autoloading::) are also
-sometimes stored in the function cell of symbols. We often refer to
-"the function `foo'" when we really mean the function stored in the
-function cell of the symbol `foo'. We make the distinction only when
-necessary.
-
- The property list cell normally should hold a correctly formatted
-property list (*note Property Lists::), as a number of functions expect
-to see a property list there.
-
- The function cell or the value cell may be "void", which means that
-the cell does not reference any object. (This is not the same thing as
-holding the symbol `void', nor the same as holding the symbol `nil'.)
-Examining a cell that is void results in an error, such as `Symbol's
-value as variable is void'.
-
- The four functions `symbol-name', `symbol-value', `symbol-plist',
-and `symbol-function' return the contents of the four cells of a
-symbol. Here as an example we show the contents of the four cells of
-the symbol `buffer-file-name':
-
- (symbol-name 'buffer-file-name)
- => "buffer-file-name"
- (symbol-value 'buffer-file-name)
- => "/gnu/elisp/symbols.texi"
- (symbol-plist 'buffer-file-name)
- => (variable-documentation 29529)
- (symbol-function 'buffer-file-name)
- => #<subr buffer-file-name>
-
-Because this symbol is the variable which holds the name of the file
-being visited in the current buffer, the value cell contents we see are
-the name of the source file of this chapter of the XEmacs Lisp Manual.
-The property list cell contains the list `(variable-documentation
-29529)' which tells the documentation functions where to find the
-documentation string for the variable `buffer-file-name' in the `DOC'
-file. (29529 is the offset from the beginning of the `DOC' file to
-where that documentation string begins.) The function cell contains
-the function for returning the name of the file. `buffer-file-name'
-names a primitive function, which has no read syntax and prints in hash
-notation (*note Primitive Function Type::). A symbol naming a function
-written in Lisp would have a lambda expression (or a byte-code object)
-in this cell.
-
-\1f
-File: lispref.info, Node: Definitions, Next: Creating Symbols, Prev: Symbol Components, Up: Symbols
-
-Defining Symbols
-================
+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'.
- A "definition" in Lisp is a special form that announces your
-intention to use a certain symbol in a particular way. In XEmacs Lisp,
-you can define a symbol as a variable, or define it as a function (or
-macro), or both independently.
-
- A definition construct typically specifies a value or meaning for the
-symbol for one kind of use, plus documentation for its meaning when used
-in this way. Thus, when you define a symbol as a variable, you can
-supply an initial value for the variable, plus documentation for the
-variable.
-
- `defvar' and `defconst' are special forms that define a symbol as a
-global variable. They are documented in detail in *Note Defining
-Variables::.
-
- `defun' defines a symbol as a function, creating a lambda expression
-and storing it in the function cell of the symbol. This lambda
-expression thus becomes the function definition of the symbol. (The
-term "function definition", meaning the contents of the function cell,
-is derived from the idea that `defun' gives the symbol its definition
-as a function.) `defsubst', `define-function' and `defalias' are other
-ways of defining a function. *Note Functions::.
-
- `defmacro' defines a symbol as a macro. It creates a macro object
-and stores it in the function cell of the symbol. Note that a given
-symbol can be a macro or a function, but not both at once, because both
-macro and function definitions are kept in the function cell, and that
-cell can hold only one Lisp object at any given time. *Note Macros::.
-
- In XEmacs Lisp, a definition is not required in order to use a symbol
-as a variable or function. Thus, you can make a symbol a global
-variable with `setq', whether you define it first or not. The real
-purpose of definitions is to guide programmers and programming tools.
-They inform programmers who read the code that certain symbols are
-_intended_ to be used as variables, or as functions. In addition,
-utilities such as `etags' and `make-docfile' recognize definitions, and
-add appropriate information to tag tables and the `DOC' file. *Note
-Accessing Documentation::.
-
-\1f
-File: lispref.info, Node: Creating Symbols, Next: Symbol Properties, Prev: Definitions, Up: Symbols
-
-Creating and Interning Symbols
-==============================
+ -- Command: kill-emacs &optional exit-data
+ This function exits the XEmacs process and kills it.
- To understand how symbols are created in XEmacs Lisp, you must know
-how Lisp reads them. Lisp must ensure that it finds the same symbol
-every time it reads the same set of characters. Failure to do so would
-cause complete confusion.
-
- When the Lisp reader encounters a symbol, it reads all the characters
-of the name. Then it "hashes" those characters to find an index in a
-table called an "obarray". Hashing is an efficient method of looking
-something up. For example, instead of searching a telephone book cover
-to cover when looking up Jan Jones, you start with the J's and go from
-there. That is a simple version of hashing. Each element of the
-obarray is a "bucket" which holds all the symbols with a given hash
-code; to look for a given name, it is sufficient to look through all
-the symbols in the bucket for that name's hash code.
-
- If a symbol with the desired name is found, the reader uses that
-symbol. If the obarray does not contain a symbol with that name, the
-reader makes a new symbol and adds it to the obarray. Finding or adding
-a symbol with a certain name is called "interning" it, and the symbol
-is then called an "interned symbol".
-
- Interning ensures that each obarray has just one symbol with any
-particular name. Other like-named symbols may exist, but not in the
-same obarray. Thus, the reader gets the same symbols for the same
-names, as long as you keep reading with the same obarray.
-
- No obarray contains all symbols; in fact, some symbols are not in any
-obarray. They are called "uninterned symbols". An uninterned symbol
-has the same four cells as other symbols; however, the only way to gain
-access to it is by finding it in some other object or as the value of a
-variable.
-
- In XEmacs Lisp, an obarray is actually a vector. Each element of the
-vector is a bucket; its value is either an interned symbol whose name
-hashes to that bucket, or 0 if the bucket is empty. Each interned
-symbol has an internal link (invisible to the user) to the next symbol
-in the bucket. Because these links are invisible, there is no way to
-find all the symbols in an obarray except using `mapatoms' (below).
-The order of symbols in a bucket is not significant.
-
- In an empty obarray, every element is 0, and you can create an
-obarray with `(make-vector LENGTH 0)'. *This is the only valid way to
-create an obarray.* Prime numbers as lengths tend to result in good
-hashing; lengths one less than a power of two are also good.
-
- *Do not try to put symbols in an obarray yourself.* This does not
-work--only `intern' can enter a symbol in an obarray properly. *Do not
-try to intern one symbol in two obarrays.* This would garble both
-obarrays, because a symbol has just one slot to hold the following
-symbol in the obarray bucket. The results would be unpredictable.
-
- It is possible for two different symbols to have the same name in
-different obarrays; these symbols are not `eq' or `equal'. However,
-this normally happens only as part of the abbrev mechanism (*note
-Abbrevs::).
-
- Common Lisp note: In Common Lisp, a single symbol may be interned
- in several obarrays.
-
- Most of the functions below take a name and sometimes an obarray as
-arguments. A `wrong-type-argument' error is signaled if the name is
-not a string, or if the obarray is not a vector.
-
- - Function: symbol-name symbol
- This function returns the string that is SYMBOL's name. For
- example:
-
- (symbol-name 'foo)
- => "foo"
-
- Changing the string by substituting characters, etc, does change
- the name of the symbol, but fails to update the obarray, so don't
- do it!
-
- - Function: make-symbol name
- This function returns a newly-allocated, uninterned symbol whose
- name is NAME (which must be a string). Its value and function
- definition are void, and its property list is `nil'. In the
- example below, the value of `sym' is not `eq' to `foo' because it
- is a distinct uninterned symbol whose name is also `foo'.
-
- (setq sym (make-symbol "foo"))
- => foo
- (eq sym 'foo)
- => nil
+ If EXIT-DATA is an integer, then it is used as the exit status of
+ the XEmacs process. (This is useful primarily in batch operation;
+ see *Note Batch Mode::.)
- - Function: intern name &optional obarray
- This function returns the interned symbol whose name is NAME. If
- there is no such symbol in the obarray OBARRAY, `intern' creates a
- new one, adds it to the obarray, and returns it. If OBARRAY is
- omitted, the value of the global variable `obarray' is used.
+ If EXIT-DATA is a string, its contents are stuffed into the
+ terminal input buffer so that the shell (or whatever program next
+ reads input) can read them.
- (setq sym (intern "foo"))
- => foo
- (eq sym 'foo)
- => t
-
- (setq sym1 (intern "foo" other-obarray))
- => foo
- (eq sym 'foo)
- => nil
+ All the information in the XEmacs process, aside from files that have
+been saved, is lost when the XEmacs is killed. Because killing XEmacs
+inadvertently can lose a lot of work, XEmacs queries for confirmation
+before actually terminating if you have buffers that need saving or
+subprocesses that are running. This is done in the function
+`save-buffers-kill-emacs'.
- - Function: intern-soft name &optional obarray
- This function returns the symbol in OBARRAY whose name is NAME, or
- `nil' if OBARRAY has no symbol with that name. Therefore, you can
- use `intern-soft' to test whether a symbol with a given name is
- already interned. If OBARRAY is omitted, the value of the global
- variable `obarray' is used.
+ -- 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.
- (intern-soft "frazzle") ; No such symbol exists.
- => nil
- (make-symbol "frazzle") ; Create an uninterned one.
- => frazzle
- (intern-soft "frazzle") ; That one cannot be found.
+ -- 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
+
+57.2.2 Suspending XEmacs
+------------------------
+
+"Suspending XEmacs" means stopping XEmacs temporarily and returning
+control to its superior process, which is usually the shell. This
+allows you to resume editing later in the same XEmacs process, with the
+same buffers, the same kill ring, the same undo history, and so on. To
+resume XEmacs, use the appropriate command in the parent shell--most
+likely `fg'.
+
+ Some operating systems do not support suspension of jobs; on these
+systems, "suspension" actually creates a new shell temporarily as a
+subprocess of XEmacs. Then you would exit the shell to return to
+XEmacs.
+
+ Suspension is not useful with window systems such as X, because the
+XEmacs job may not have a parent that can resume it again, and in any
+case you can give input to some other job such as a shell merely by
+moving to a different window. Therefore, suspending is not allowed
+when XEmacs is an X client.
+
+ -- 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.
+
+ If optional arg STUFFSTRING is non-`nil', its characters are sent
+ to be read as terminal input by XEmacs's superior shell. The
+ characters in STUFFSTRING are not echoed by the superior shell;
+ only the results appear.
+
+ Before suspending, `suspend-emacs' runs the normal hook
+ `suspend-hook'. In Emacs version 18, `suspend-hook' was not a
+ normal hook; its value was a single function, and if its value was
+ non-`nil', then `suspend-emacs' returned immediately without
+ actually suspending anything.
+
+ After the user resumes XEmacs, `suspend-emacs' runs the normal hook
+ `suspend-resume-hook'. *Note Hooks::.
+
+ The next redisplay after resumption will redraw the entire screen,
+ unless the variable `no-redraw-on-reenter' is non-`nil' (*note
+ Refresh Screen::).
+
+ In the following example, note that `pwd' is not echoed after
+ XEmacs is suspended. But it is read and executed by the shell.
+
+ (suspend-emacs)
=> nil
- (setq sym (intern "frazzle")) ; Create an interned one.
- => frazzle
- (intern-soft "frazzle") ; That one can be found!
- => frazzle
- (eq sym 'frazzle) ; And it is the same one.
- => t
- - Variable: obarray
- This variable is the standard obarray for use by `intern' and
- `read'.
-
- - Function: mapatoms function &optional obarray
- This function calls FUNCTION for each symbol in the obarray
- OBARRAY. It returns `nil'. If OBARRAY is omitted, it defaults to
- the value of `obarray', the standard obarray for ordinary symbols.
-
- (setq count 0)
- => 0
- (defun count-syms (s)
- (setq count (1+ count)))
- => count-syms
- (mapatoms 'count-syms)
+ (add-hook 'suspend-hook
+ (function (lambda ()
+ (or (y-or-n-p
+ "Really suspend? ")
+ (error "Suspend cancelled")))))
+ => (lambda nil
+ (or (y-or-n-p "Really suspend? ")
+ (error "Suspend cancelled")))
+ (add-hook 'suspend-resume-hook
+ (function (lambda () (message "Resumed!"))))
+ => (lambda nil (message "Resumed!"))
+ (suspend-emacs "pwd")
=> nil
- count
- => 1871
+ ---------- Buffer: Minibuffer ----------
+ Really suspend? y
+ ---------- Buffer: Minibuffer ----------
- See `documentation' in *Note Accessing Documentation::, for another
- example using `mapatoms'.
+ ---------- Parent Shell ----------
+ lewis@slug[23] % /user/lewis/manual
+ lewis@slug[24] % fg
- - Function: unintern symbol &optional obarray
- This function deletes SYMBOL from the obarray OBARRAY. If
- `symbol' is not actually in the obarray, `unintern' does nothing.
- If OBARRAY is `nil', the current obarray is used.
+ ---------- Echo Area ----------
+ Resumed!
- If you provide a string instead of a symbol as SYMBOL, it stands
- for a symbol name. Then `unintern' deletes the symbol (if any) in
- the obarray which has that name. If there is no such symbol,
- `unintern' does nothing.
+ -- Variable: suspend-hook
+ This variable is a normal hook run before suspending.
- If `unintern' does delete a symbol, it returns `t'. Otherwise it
- returns `nil'.
+ -- Variable: suspend-resume-hook
+ This variable is a normal hook run after suspending.
\1f
-File: lispref.info, Node: Symbol Properties, Prev: Creating Symbols, Up: Symbols
+File: lispref.info, Node: System Environment, Next: User Identification, Prev: Getting Out, Up: System Interface
-Symbol Properties
-=================
+57.3 Operating System Environment
+=================================
- A "property list" ("plist" for short) is a list of paired elements,
-often stored in the property list cell of a symbol. Each of the pairs
-associates a property name (usually a symbol) with a property or value.
-Property lists are generally used to record information about a
-symbol, such as its documentation as a variable, the name of the file
-where it was defined, or perhaps even the grammatical class of the
-symbol (representing a word) in a language-understanding system.
+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.
- Some objects which are not symbols also have property lists
-associated with them, and XEmacs provides a full complement of
-functions for working with property lists. *Note Property Lists::.
+ -- 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:
- The property names and values in a property list can be any Lisp
-objects, but the names are usually symbols. They are compared using
-`eq'. Here is an example of a property list, found on the symbol
-`progn' when the compiler is loaded:
+ `aix-v3'
+ AIX.
- (lisp-indent-function 0 byte-compile byte-compile-progn)
+ `berkeley-unix'
+ Berkeley BSD.
+
+ `dgux'
+ Data General DGUX operating system.
-Here `lisp-indent-function' and `byte-compile' are property names, and
-the other two elements are the corresponding values.
+ `gnu'
+ A GNU system using the GNU HURD and Mach.
+
+ `hpux'
+ Hewlett-Packard HPUX operating system.
+
+ `irix'
+ Silicon Graphics Irix system.
+
+ `linux'
+ A GNU system using the Linux kernel.
+
+ `ms-dos'
+ Microsoft MS-DOS "operating system."
+
+ `next-mach'
+ NeXT Mach-based system.
+
+ `rtu'
+ Masscomp RTU, UCB universe.
+
+ `unisoft-unix'
+ UniSoft UniPlus.
+
+ `usg-unix-v'
+ AT&T System V.
+
+ `windows-nt'
+ Microsoft windows NT.
+
+ `xenix'
+ SCO Xenix 386.
+
+ We do not wish to add new symbols to make finer distinctions
+ unless it is absolutely necessary! In fact, we hope to eliminate
+ some of these alternatives in the future. We recommend using
+ `system-configuration' to distinguish between different operating
+ systems.
+
+ -- 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
+ This function returns the name of the machine you are running on.
+ (system-name)
+ => "prep.ai.mit.edu"
+
+ The symbol `system-name' is a variable as well as a function. In
+fact, the function returns whatever value the variable `system-name'
+currently holds. Thus, you can set the variable `system-name' in case
+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
+ 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'.
+ *Note User Identification::. (Since this is done when XEmacs
+ starts up, the value actually used is the one saved when XEmacs
+ was dumped. *Note Building XEmacs::.)
+
+ -- 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'.
+
+ When invoked interactively, `getenv' prints the value in the echo
+ area.
+
+ (getenv "USER")
+ => "lewis"
+
+ lewis@slug[10] % printenv
+ PATH=.:/user/lewis/bin:/usr/bin:/usr/local/bin
+ USER=lewis
+ TERM=ibmapa16
+ SHELL=/bin/csh
+ HOME=/user/lewis
+
+ -- 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
+ This variable is a list of strings, each describing one environment
+ variable. The functions `getenv' and `setenv' work by
+ manipulating this variable.
+
+ process-environment
+ => ("l=/usr/stanford/lib/gnuemacs/lisp"
+ "PATH=.:/user/lewis/bin:/usr/class:/nfsusr/local/bin"
+ "USER=lewis"
+ "TERM=ibmapa16"
+ "SHELL=/bin/csh"
+ "HOME=/user/lewis")
+
+ -- 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
+ 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
+ This variable holds the directory from which the Emacs executable
+ was invoked, or perhaps `nil' if that directory cannot be
+ determined.
+
+ -- 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
+ 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
+ number of processes trying to run.)
+
+ When USE-FLOATS is non-`nil', floats will be returned instead of
+ integers. These floats are not multiplied by 100.
+
+ (load-average)
+ => (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
+
+ If the 5-minute or 15-minute load averages are not available,
+ return a shortened list, containing only those averages which are
+ available.
+
+ On some systems, this function may require special privileges to
+ run, or it may be unimplemented for the particular system type.
+ In that case, the function will signal an error.
+
+ -- Function: emacs-pid
+ This function returns the process ID of the Emacs process.
-* Menu:
+\1f
+File: lispref.info, Node: User Identification, Next: Time of Day, Prev: System Environment, Up: System Interface
+
+57.4 User Identification
+========================
+
+ -- 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
+ 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' is set, that value is used. Otherwise, the value is based
+ on the effective UID, not the real UID.
+
+ If you specify UID, the value is the user name that corresponds to
+ UID (which should be an integer).
+
+ (user-login-name)
+ => "lewis"
+
+ -- 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
+ 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
+ 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.
+
+ If USER is specified explicitly, `user-full-name' variable is
+ ignored.
+
+ (user-full-name)
+ => "Hrvoje Niksic"
+ (setq user-full-name "Hrvoje \"Niksa\" Niksic")
+ (user-full-name)
+ => "Hrvoje \"Niksa\" Niksic"
+ (user-full-name "hniksic")
+ => "Hrvoje Niksic"
+
+ The symbols `user-login-name', `user-real-login-name' and
+`user-full-name' are variables as well as functions. The functions
+return the same values that the variables hold. These variables allow
+you to "fake out" Emacs by telling the functions what to return. The
+variables are also useful for constructing frame titles (*note Frame
+Titles::).
-* Plists and Alists:: Comparison of the advantages of property
- lists and association lists.
-* Object Plists:: Functions to access objects' property lists.
-* Other Plists:: Accessing property lists stored elsewhere.
+ -- Function: user-real-uid
+ This function returns the real UID of the user.
+
+ (user-real-uid)
+ => 19
+
+ -- Function: user-uid
+ This function returns the effective UID of the user.
+
+ -- 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:
+
+ 1. Return the value of "`(getenv "HOME")'", if set.
+
+ 2. Return "/", as a fallback, but issue a warning. (Future
+ versions of XEmacs will also attempt to lookup the `HOME'
+ directory via `getpwent()', but this has not yet been
+ implemented.)
+
+ Under MS Windows, this is done:
+
+ 1. Return the value of "`(getenv "HOME")'", if set.
+
+ 2. If the environment variables `HOMEDRIVE' and `HOMEDIR' are
+ both set, return the concatenation (the following description
+ uses MS Windows environment variable substitution syntax):
+ `%HOMEDRIVE%%HOMEDIR%'.
+
+ 3. Return "C:\", as a fallback, but issue a warning.
\1f
-File: lispref.info, Node: Plists and Alists, Next: Object Plists, Up: Symbol Properties
+File: lispref.info, Node: Time of Day, Next: Time Conversion, Prev: User Identification, Up: System Interface
-Property Lists and Association Lists
-------------------------------------
+57.5 Time of Day
+================
- Association lists (*note Association Lists::) are very similar to
-property lists. In contrast to association lists, the order of the
-pairs in the property list is not significant since the property names
-must be distinct.
-
- Property lists are better than association lists for attaching
-information to various Lisp function names or variables. If all the
-associations are recorded in one association list, the program will need
-to search that entire list each time a function or variable is to be
-operated on. By contrast, if the information is recorded in the
-property lists of the function names or variables themselves, each
-search will scan only the length of one property list, which is usually
-short. This is why the documentation for a variable is recorded in a
-property named `variable-documentation'. The byte compiler likewise
-uses properties to record those functions needing special treatment.
-
- However, association lists have their own advantages. Depending on
-your application, it may be faster to add an association to the front of
-an association list than to update a property. All properties for a
-symbol are stored in the same property list, so there is a possibility
-of a conflict between different uses of a property name. (For this
-reason, it is a good idea to choose property names that are probably
-unique, such as by including the name of the library in the property
-name.) An association list may be used like a stack where associations
-are pushed on the front of the list and later discarded; this is not
-possible with a property list.
-
-\1f
-File: lispref.info, Node: Object Plists, Next: Other Plists, Prev: Plists and Alists, Up: Symbol Properties
-
-Property List Functions for Objects
------------------------------------
+This section explains how to determine the current time and the time
+zone.
+
+ -- 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
+ you can reliably use `substring' to extract pieces of it. It is
+ wise to count the characters from the beginning of the string
+ rather than from the end, as additional information may be added
+ at the end.
+
+ The argument TIME-VALUE, if given, specifies a time to format
+ instead of the current time. The argument should be a list whose
+ first two elements are integers. Thus, you can use times obtained
+ from `current-time' (see below) and from `file-attributes' (*note
+ File Attributes::).
+
+ (current-time-string)
+ => "Wed Oct 14 22:21:05 1987"
+
+ -- 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,
+ which is HIGH * 2**16 + LOW.
+
+ The third element, MICROSEC, gives the microseconds since the
+ start of the current second (or 0 for systems that return time
+ only on the resolution of a second).
+
+ The first two elements can be compared with file time values such
+ as you get with the function `file-attributes'. *Note File
+ Attributes::.
+
+ -- Function: current-time-zone &optional time-value
+ This function returns a list describing the time zone that the
+ user is in.
+
+ The value has the form `(OFFSET NAME)'. Here OFFSET is an integer
+ giving the number of seconds ahead of UTC (east of Greenwich). A
+ negative value means west of Greenwich. The second element, NAME
+ is a string giving the name of the time zone. Both elements
+ change when daylight savings time begins or ends; if the user has
+ specified a time zone that does not use a seasonal time
+ adjustment, then the value is constant through time.
+
+ If the operating system doesn't supply all the information
+ necessary to compute the value, both elements of the list are
+ `nil'.
+
+ The argument TIME-VALUE, if given, specifies a time to analyze
+ instead of the current time. The argument should be a cons cell
+ containing two integers, or a list whose first two elements are
+ integers. Thus, you can use times obtained from `current-time'
+ (see above) and from `file-attributes' (*note File Attributes::).
- Once upon a time, only symbols had property lists. Now, several
-other object types, including strings, extents, faces and glyphs also
-have property lists.
-
- - Function: symbol-plist symbol
- This function returns the property list of SYMBOL.
-
- - Function: object-plist object
- This function returns the property list of OBJECT. If OBJECT is a
- symbol, this is identical to `symbol-plist'.
-
- - Function: setplist symbol plist
- This function sets SYMBOL's property list to PLIST. Normally,
- PLIST should be a well-formed property list, but this is not
- enforced.
-
- (setplist 'foo '(a 1 b (2 3) c nil))
- => (a 1 b (2 3) c nil)
- (symbol-plist 'foo)
- => (a 1 b (2 3) c nil)
-
- For symbols in special obarrays, which are not used for ordinary
- purposes, it may make sense to use the property list cell in a
- nonstandard fashion; in fact, the abbrev mechanism does so (*note
- Abbrevs::). But generally, its use is discouraged. Use `put'
- instead. `setplist' can only be used with symbols, not other
- object types.
-
- - Function: get object property &optional default
- This function finds the value of the property named PROPERTY in
- OBJECT's property list. If there is no such property, `default'
- (which itself defaults to `nil') is returned.
-
- PROPERTY is compared with the existing properties using `eq', so
- any object is a legitimate property.
-
- See `put' for an example.
-
- - Function: put object property value
- This function puts VALUE onto OBJECT's property list under the
- property name PROPERTY, replacing any previous property value.
- The `put' function returns VALUE.
-
- (put 'fly 'verb 'transitive)
- =>'transitive
- (put 'fly 'noun '(a buzzing little bug))
- => (a buzzing little bug)
- (get 'fly 'verb)
- => transitive
- (object-plist 'fly)
- => (verb transitive noun (a buzzing little bug))
-
- - Function: remprop object property
- This function removes the entry for PROPERTY from the property
- list of OBJECT. It returns `t' if the property was indeed found
- and removed, or `nil' if there was no such property. (This
- function was probably omitted from Emacs originally because, since
- `get' did not allow a DEFAULT, it was very difficult to
- distinguish between a missing property and a property whose value
- was `nil'; thus, setting a property to `nil' was close enough to
- `remprop' for most purposes.)
-
-\1f
-File: lispref.info, Node: Other Plists, Prev: Object Plists, Up: Symbol Properties
-
-Property Lists Not Associated with Objects
-------------------------------------------
-
- These functions are useful for manipulating property lists that are
-stored in places other than symbols:
-
- - Function: getf plist property &optional default
- This returns the value of the PROPERTY property stored in the
- property list PLIST. For example,
-
- (getf '(foo 4) 'foo)
- => 4
-
- - Macro: putf plist property value
- This stores VALUE as the value of the PROPERTY property in the
- property list PLIST. It may modify PLIST destructively, or it may
- construct a new list structure without altering the old. The
- function returns the modified property list, so you can store that
- back in the place where you got PLIST. For example,
-
- (setq my-plist '(bar t foo 4))
- => (bar t foo 4)
- (setq my-plist (putf my-plist 'foo 69))
- => (bar t foo 69)
- (setq my-plist (putf my-plist 'quux '(a)))
- => (quux (a) bar t foo 5)
-
- - Function: plists-eq a b
- This function returns non-`nil' if property lists A and B are
- `eq'. This means that the property lists have the same values for
- all the same properties, where comparison between values is done
- using `eq'.
-
- - Function: plists-equal a b
- This function returns non-`nil' if property lists A and B are
- `equal'.
-
- Both of the above functions do order-insensitive comparisons.
-
- (plists-eq '(a 1 b 2 c nil) '(b 2 a 1))
- => t
- (plists-eq '(foo "hello" bar "goodbye") '(bar "goodbye" foo "hello"))
- => nil
- (plists-equal '(foo "hello" bar "goodbye") '(bar "goodbye" foo "hello"))
- => t
+\1f
+File: lispref.info, Node: Time Conversion, Next: Timers, Prev: Time of Day, Up: System Interface
+
+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
+convert calendrical information to a time value. You can get time
+values from the functions `current-time' (*note Time of Day::) and
+`file-attributes' (*note File Attributes::).
+
+ -- 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
+ say to substitute parts of the time. Here is a table of what the
+ `%'-sequences mean:
+
+ `%a'
+ This stands for the abbreviated name of the day of week.
+
+ `%A'
+ This stands for the full name of the day of week.
+
+ `%b'
+ This stands for the abbreviated name of the month.
+
+ `%B'
+ This stands for the full name of the month.
+
+ `%c'
+ This is a synonym for `%x %X'.
+
+ `%C'
+ This has a locale-specific meaning. In the default locale
+ (named C), it is equivalent to `%A, %B %e, %Y'.
+
+ `%d'
+ This stands for the day of month, zero-padded.
+
+ `%D'
+ This is a synonym for `%m/%d/%y'.
+
+ `%e'
+ This stands for the day of month, blank-padded.
+
+ `%h'
+ This is a synonym for `%b'.
+
+ `%H'
+ This stands for the hour (00-23).
+
+ `%I'
+ This stands for the hour (00-12).
+
+ `%j'
+ This stands for the day of the year (001-366).
+
+ `%k'
+ This stands for the hour (0-23), blank padded.
+
+ `%l'
+ This stands for the hour (1-12), blank padded.
+
+ `%m'
+ This stands for the month (01-12).
+
+ `%M'
+ This stands for the minute (00-59).
+
+ `%n'
+ This stands for a newline.
+
+ `%p'
+ This stands for `AM' or `PM', as appropriate.
+
+ `%r'
+ This is a synonym for `%I:%M:%S %p'.
+
+ `%R'
+ This is a synonym for `%H:%M'.
+
+ `%S'
+ This stands for the seconds (00-60).
+
+ `%t'
+ This stands for a tab character.
+
+ `%T'
+ This is a synonym for `%H:%M:%S'.
+
+ `%U'
+ This stands for the week of the year (01-52), assuming that
+ weeks start on Sunday.
+
+ `%w'
+ This stands for the numeric day of week (0-6). Sunday is day
+ 0.
+
+ `%W'
+ This stands for the week of the year (01-52), assuming that
+ weeks start on Monday.
+
+ `%x'
+ This has a locale-specific meaning. In the default locale
+ (named C), it is equivalent to `%D'.
+
+ `%X'
+ This has a locale-specific meaning. In the default locale
+ (named C), it is equivalent to `%T'.
+
+ `%y'
+ This stands for the year without century (00-99).
+
+ `%Y'
+ This stands for the year with century.
+
+ `%Z'
+ This stands for the time zone abbreviation.
+
+ -- 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
+ `file-attributes', or `nil' to use the current time.
+
+ The return value is a list of nine elements, as follows:
+
+ (SECONDS MINUTES HOUR DAY MONTH YEAR DOW DST ZONE)
+
+ Here is what the elements mean:
+
+ SEC
+ The number of seconds past the minute, as an integer between
+ 0 and 59.
+
+ MINUTE
+ The number of minutes past the hour, as an integer between 0
+ and 59.
+
+ HOUR
+ The hour of the day, as an integer between 0 and 23.
+
+ DAY
+ The day of the month, as an integer between 1 and 31.
+
+ MONTH
+ The month of the year, as an integer between 1 and 12.
+
+ YEAR
+ The year, an integer typically greater than 1900.
+
+ DOW
+ The day of week, as an integer between 0 and 6, where 0
+ stands for Sunday.
+
+ DST
+ `t' if daylight savings time is effect, otherwise `nil'.
+
+ ZONE
+ An integer indicating the time zone, as the number of seconds
+ east of Greenwich.
+
+ Note that Common Lisp has different meanings for DOW and ZONE.
+
+ -- 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
+ the arguments, see the table above under `decode-time'.
+
+ Year numbers less than 100 are treated just like other year
+ numbers. If you want them to stand for years above 1900, you must
+ alter them yourself before you call `encode-time'.
+
+ The optional argument ZONE defaults to the current time zone and
+ its daylight savings time rules. If specified, it can be either a
+ list (as you would get from `current-time-zone') or an integer (as
+ you would get from `decode-time'). The specified zone is used
+ without any further alteration for daylight savings time.
+
+\1f
+File: lispref.info, Node: Timers, Next: Terminal Input, Prev: Time Conversion, Up: System Interface
+
+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
+ 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
+ seconds have elapsed, with one argument, the given OBJECT. If the
+ optional RESIGNAL argument is provided, then after this timeout
+ expires, `add-timeout' will automatically be called again with
+ RESIGNAL as the first argument.
+
+ This function returns an object which is the "id" of this
+ particular timeout. You can pass that object to `disable-timeout'
+ to turn off the timeout before it has been signalled.
+
+ The number of seconds may be expressed as a floating-point number,
+ in which case some fractional part of a second will be used.
+ Caveat: the usable timeout granularity will vary from system to
+ system.
+
+ Adding a timeout causes a timeout event to be returned by
+ `next-event', and the function will be invoked by
+ `dispatch-event', so if XEmacs is in a tight loop, the function
+ will not be invoked until the next call to sit-for or until the
+ return to top-level (the same is true of process filters).
+
+ WARNING: if you are thinking of calling add-timeout from inside of
+ a callback function as a way of resignalling a timeout, think
+ again. There is a race condition. That's why the RESIGNAL
+ argument exists.
+
+ (NOTE: In FSF Emacs, this function is called `run-at-time' and has
+ different semantics.)
+
+ -- 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
+ not cause anything special to happen. (NOTE: In FSF Emacs, this
+ function is called `cancel-timer'.)
\1f
-File: lispref.info, Node: Evaluation, Next: Control Structures, Prev: Symbols, Up: Top
+File: lispref.info, Node: Terminal Input, Next: Terminal Output, Prev: Timers, Up: System Interface
-Evaluation
-**********
+57.8 Terminal Input
+===================
- The "evaluation" of expressions in XEmacs Lisp is performed by the
-"Lisp interpreter"--a program that receives a Lisp object as input and
-computes its "value as an expression". How it does this depends on the
-data type of the object, according to rules described in this chapter.
-The interpreter runs automatically to evaluate portions of your
-program, but can also be called explicitly via the Lisp primitive
-function `eval'.
+This section describes functions and variables for recording or
+manipulating terminal input. See *Note Display::, for related
+functions.
* Menu:
-* Intro Eval:: Evaluation in the scheme of things.
-* Eval:: How to invoke the Lisp interpreter explicitly.
-* Forms:: How various sorts of objects are evaluated.
-* Quoting:: Avoiding evaluation (to put constants in the program).
+* Input Modes:: Options for how input is processed.
+* Translating Input:: Low level conversion of some characters or events
+ into others.
+* Recording Input:: Saving histories of recent or all input events.
\1f
-File: lispref.info, Node: Intro Eval, Next: Eval, Up: Evaluation
+File: lispref.info, Node: Input Modes, Next: Translating Input, Up: Terminal Input
+
+57.8.1 Input Modes
+------------------
+
+ -- 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
+ `nil', then it uses CBREAK mode. When XEmacs communicates
+ directly with X, it ignores this argument and uses interrupts if
+ that is the way it knows how to communicate.
+
+ If FLOW is non-`nil', then XEmacs uses XON/XOFF (`C-q', `C-s')
+ flow control for output to the terminal. This has no effect except
+ in CBREAK mode. *Note Flow Control::.
+
+ The default setting is system dependent. Some systems always use
+ CBREAK mode regardless of what is specified.
+
+ The argument META controls support for input character codes above
+ 127. If META is `t', XEmacs converts characters with the 8th bit
+ set into Meta characters. If META is `nil', XEmacs disregards the
+ 8th bit; this is necessary when the terminal uses it as a parity
+ bit. If META is neither `t' nor `nil', XEmacs uses all 8 bits of
+ input unchanged. This is good for terminals using European 8-bit
+ character sets.
+
+ If QUIT-CHAR is non-`nil', it specifies the character to use for
+ quitting. Normally this character is `C-g'. *Note Quitting::.
+
+ The `current-input-mode' function returns the input mode settings
+XEmacs is currently using.
+
+ -- 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:
+ INTERRUPT
+ is non-`nil' when XEmacs is using interrupt-driven input. If
+ `nil', Emacs is using CBREAK mode.
+
+ FLOW
+ is non-`nil' if XEmacs uses XON/XOFF (`C-q', `C-s') flow
+ control for output to the terminal. This value has no effect
+ unless INTERRUPT is non-`nil'.
+
+ META
+ is `t' if XEmacs treats the eighth bit of input characters as
+ the meta bit; `nil' means XEmacs clears the eighth bit of
+ every input character; any other value means XEmacs uses all
+ eight bits as the basic character code.
+
+ QUIT
+ is the character XEmacs currently uses for quitting, usually
+ `C-g'.
-Introduction to Evaluation
-==========================
+\1f
+File: lispref.info, Node: Translating Input, Next: Recording Input, Prev: Input Modes, Up: Terminal Input
+
+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
+ 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
+ differently: it specifies translations to make while reading
+ events.
+
+ If `function-key-map' "binds" a key sequence K to a vector V, then
+ when K appears as a subsequence _anywhere_ in a key sequence, it
+ is replaced with the events in V.
+
+ For example, VT100 terminals send `<ESC> O P' when the keypad PF1
+ key is pressed. Therefore, we want XEmacs to translate that
+ sequence of events into the single event `pf1'. We accomplish
+ this by "binding" `<ESC> O P' to `[pf1]' in `function-key-map',
+ when using a VT100.
+
+ Thus, typing `C-c <PF1>' sends the character sequence `C-c <ESC> O
+ P'; later the function `read-key-sequence' translates this back
+ into `C-c <PF1>', which it returns as the vector `[?\C-c pf1]'.
+
+ Entries in `function-key-map' are ignored if they conflict with
+ bindings made in the minor mode, local, or global keymaps. The
+ intent is that the character sequences that function keys send
+ should not have command bindings in their own right.
+
+ The value of `function-key-map' is usually set up automatically
+ according to the terminal's Terminfo or Termcap entry, but
+ sometimes those need help from terminal-specific Lisp files.
+ XEmacs comes with terminal-specific files for many common
+ terminals; their main purpose is to make entries in
+ `function-key-map' beyond those that can be deduced from Termcap
+ and Terminfo. *Note Terminal-Specific::.
+
+ Emacs versions 18 and earlier used totally different means of
+ detecting the character sequences that represent function keys.
+
+ -- 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:
+
+ * `key-translation-map' goes to work after `function-key-map' is
+ finished; it receives the results of translation by
+ `function-key-map'.
+
+ * `key-translation-map' overrides actual key bindings.
+
+ The intent of `key-translation-map' is for users to map one
+ character set to another, including ordinary characters normally
+ bound to `self-insert-command'.
+
+ You can use `function-key-map' or `key-translation-map' for more
+than simple aliases, by using a function, instead of a key sequence, as
+the "translation" of a key. Then this function is called to compute
+the translation of that key.
+
+ The key translation function receives one argument, which is the
+prompt that was specified in `read-key-sequence'--or `nil' if the key
+sequence is being read by the editor command loop. In most cases you
+can ignore the prompt value.
+
+ If the function reads input itself, it can have the effect of
+altering the event that follows. For example, here's how to define
+`C-c h' to turn the character that follows into a Hyper character:
+
+ (defun hyperify (prompt)
+ (let ((e (read-event)))
+ (vector (if (numberp e)
+ (logior (lsh 1 20) e)
+ (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
+ (symbol-name symbol))))
+ (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
+inputting non-ASCII Latin-1 characters.
+
+\1f
+File: lispref.info, Node: Recording Input, Prev: Translating Input, Up: Terminal Input
- The Lisp interpreter, or evaluator, is the program that computes the
-value of an expression that is given to it. When a function written in
-Lisp is called, the evaluator computes the value of the function by
-evaluating the expressions in the function body. Thus, running any
-Lisp program really means running the Lisp interpreter.
-
- How the evaluator handles an object depends primarily on the data
-type of the object.
-
- A Lisp object that is intended for evaluation is called an
-"expression" or a "form". The fact that expressions are data objects
-and not merely text is one of the fundamental differences between
-Lisp-like languages and typical programming languages. Any object can
-be evaluated, but in practice only numbers, symbols, lists and strings
-are evaluated very often.
-
- It is very common to read a Lisp expression and then evaluate the
-expression, but reading and evaluation are separate activities, and
-either can be performed alone. Reading per se does not evaluate
-anything; it converts the printed representation of a Lisp object to the
-object itself. It is up to the caller of `read' whether this object is
-a form to be evaluated, or serves some entirely different purpose.
-*Note Input Functions::.
-
- Do not confuse evaluation with command key interpretation. The
-editor command loop translates keyboard input into a command (an
-interactively callable function) using the active keymaps, and then
-uses `call-interactively' to invoke the command. The execution of the
-command itself involves evaluation if the command is written in Lisp,
-but that is not a part of command key interpretation itself. *Note
-Command Loop::.
-
- Evaluation is a recursive process. That is, evaluation of a form may
-call `eval' to evaluate parts of the form. For example, evaluation of
-a function call first evaluates each argument of the function call, and
-then evaluates each form in the function body. Consider evaluation of
-the form `(car x)': the subform `x' must first be evaluated
-recursively, so that its value can be passed as an argument to the
-function `car'.
-
- Evaluation of a function call ultimately calls the function specified
-in it. *Note Functions::. The execution of the function may itself
-work by evaluating the function definition; or the function may be a
-Lisp primitive implemented in C, or it may be a byte-compiled function
-(*note Byte Compilation::).
-
- The evaluation of forms takes place in a context called the
-"environment", which consists of the current values and bindings of all
-Lisp variables.(1) Whenever the form refers to a variable without
-creating a new binding for it, the value of the binding in the current
-environment is used. *Note Variables::.
-
- Evaluation of a form may create new environments for recursive
-evaluation by binding variables (*note Local Variables::). These
-environments are temporary and vanish by the time evaluation of the form
-is complete. The form may also make changes that persist; these changes
-are called "side effects". An example of a form that produces side
-effects is `(setq foo 1)'.
-
- The details of what evaluation means for each kind of form are
-described below (*note Forms::).
-
- ---------- Footnotes ----------
-
- (1) This definition of "environment" is specifically not intended to
-include all the data that can affect the result of a program.
-
-\1f
-File: lispref.info, Node: Eval, Next: Forms, Prev: Intro Eval, Up: Evaluation
-
-Eval
-====
-
- Most often, forms are evaluated automatically, by virtue of their
-occurrence in a program being run. On rare occasions, you may need to
-write code that evaluates a form that is computed at run time, such as
-after reading a form from text being edited or getting one from a
-property list. On these occasions, use the `eval' function.
-
- *Please note:* it is generally cleaner and more flexible to call
-functions that are stored in data structures, rather than to evaluate
-expressions stored in data structures. Using functions provides the
-ability to pass information to them as arguments.
-
- The functions and variables described in this section evaluate forms,
-specify limits to the evaluation process, or record recently returned
-values. Loading a file also does evaluation (*note Loading::).
-
- - Function: eval form
- This is the basic function for performing evaluation. It evaluates
- FORM in the current environment and returns the result. How the
- evaluation proceeds depends on the type of the object (*note
- Forms::).
-
- Since `eval' is a function, the argument expression that appears
- in a call to `eval' is evaluated twice: once as preparation before
- `eval' is called, and again by the `eval' function itself. Here
- is an example:
-
- (setq foo 'bar)
- => bar
- (setq bar 'baz)
- => baz
- ;; `eval' receives argument `bar', which is the value of `foo'
- (eval foo)
- => baz
- (eval 'foo)
- => bar
-
- The number of currently active calls to `eval' is limited to
- `max-lisp-eval-depth' (see below).
-
- - Command: eval-region start end &optional stream
- This function evaluates the forms in the current buffer in the
- region defined by the positions START and END. It reads forms from
- the region and calls `eval' on them until the end of the region is
- reached, or until an error is signaled and not handled.
-
- If STREAM is supplied, `standard-output' is bound to it during the
- evaluation.
-
- You can use the variable `load-read-function' to specify a function
- for `eval-region' to use instead of `read' for reading
- expressions. *Note How Programs Do Loading::.
-
- `eval-region' always returns `nil'.
-
- - Command: eval-buffer buffer &optional stream
- This is like `eval-region' except that it operates on the whole
- contents of BUFFER.
-
- - Variable: max-lisp-eval-depth
- This variable defines the maximum depth allowed in calls to `eval',
- `apply', and `funcall' before an error is signaled (with error
- message `"Lisp nesting exceeds max-lisp-eval-depth"'). This counts
- internal uses of those functions, such as for calling the functions
- mentioned in Lisp expressions, and recursive evaluation of
- function call arguments and function body forms.
-
- This limit, with the associated error when it is exceeded, is one
- way that Lisp avoids infinite recursion on an ill-defined function.
-
- The default value of this variable is 500. If you set it to a
- value less than 100, Lisp will reset it to 100 if the given value
- is reached.
-
- `max-specpdl-size' provides another limit on nesting. *Note Local
- Variables::.
-
- - Variable: values
- The value of this variable is a list of the values returned by all
- the expressions that were read from buffers (including the
- minibuffer), evaluated, and printed. The elements are ordered
- most recent first.
-
- (setq x 1)
- => 1
- (list 'A (1+ 2) auto-save-default)
- => (A 3 t)
- values
- => ((A 3 t) 1 ...)
-
- This variable is useful for referring back to values of forms
- recently evaluated. It is generally a bad idea to print the value
- of `values' itself, since this may be very long. Instead, examine
- particular elements, like this:
-
- ;; Refer to the most recent evaluation result.
- (nth 0 values)
- => (A 3 t)
- ;; That put a new element on,
- ;; so all elements move back one.
- (nth 1 values)
- => (A 3 t)
- ;; This gets the element that was next-to-most-recent
- ;; before this example.
- (nth 3 values)
- => 1
-
-\1f
-File: lispref.info, Node: Forms, Next: Quoting, Prev: Eval, Up: Evaluation
-
-Kinds of Forms
-==============
-
- A Lisp object that is intended to be evaluated is called a "form".
-How XEmacs evaluates a form depends on its data type. XEmacs has three
-different kinds of form that are evaluated differently: symbols, lists,
-and "all other types". This section describes all three kinds,
-starting with "all other types" which are self-evaluating forms.
+57.8.3 Recording Input
+----------------------
-* Menu:
+ -- 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.
+
+ All input events are included, whether or not they were used as
+ parts of key sequences. Thus, you always get the last 100 inputs,
+ not counting keyboard macros. (Events from keyboard macros are
+ excluded because they are less interesting for debugging; it
+ should be enough to see the events that invoked the macros.)
+
+ If NUMBER is specified, not more than NUMBER events will be
+ returned. You may change the number of stored events using
+ `set-recent-keys-ring-size'.
-* Self-Evaluating Forms:: Forms that evaluate to themselves.
-* Symbol Forms:: Symbols evaluate as variables.
-* Classifying Lists:: How to distinguish various sorts of list forms.
-* Function Indirection:: When a symbol appears as the car of a list,
- we find the real function via the symbol.
-* Function Forms:: Forms that call functions.
-* Macro Forms:: Forms that call macros.
-* Special Forms:: ``Special forms'' are idiosyncratic primitives,
- most of them extremely important.
-* Autoloading:: Functions set up to load files
- containing their real definitions.
+ -- 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
+ This function changes the number of events stored by XEmacs and
+ returned by `recent-keys'.
+
+ For example, `(set-recent-keys-ring-size 250)' will make XEmacs
+ remember last 250 events and will make `recent-keys' return last
+ 250 events by default.
+
+ -- 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
+ non-character event is expressed using its printed representation
+ surrounded by `<...>'.
+
+ You close the dribble file by calling this function with an
+ argument of `nil'.
+
+ This function is normally used to record the input necessary to
+ trigger an XEmacs bug, for the sake of a bug report.
+
+ (open-dribble-file "~/dribble")
+ => nil
+
+ See also the `open-termscript' function (*note Terminal Output::).
+
+\1f
+File: lispref.info, Node: Terminal Output, Next: Flow Control, Prev: Terminal Input, Up: System Interface
+
+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
+ 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.
+ Changing this value does not change the speed of actual data
+ transmission, but the value is used for calculations such as
+ padding. This value has no effect for window-system devices.
+ (This is different in FSF Emacs, where the baud rate also affects
+ decisions about whether to scroll part of the screen or repaint,
+ even when using a window system.)
+
+ The value is measured in bits per second.
+
+ XEmacs attempts to automatically initialize the baud rate by querying
+the terminal. If you are running across a network, however, and
+different parts of the network work are at different baud rates, the
+value returned by XEmacs may be different from the value used by your
+local terminal. Some network protocols communicate the local terminal
+speed to the remote machine, so that XEmacs and other programs can get
+the proper value, but others do not. If XEmacs has the wrong value, it
+makes decisions that are less than optimal. To fix the problem, use
+`set-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
+ device
+ This function sends CHAR-OR-STRING to the terminal without
+ alteration. Control characters in CHAR-OR-STRING have
+ terminal-dependent effects.
+
+ If DEVICE is `nil', this function writes to XEmacs's stderr, or to
+ stdout if STDOUT-P is non-`nil'. Otherwise, DEVICE should be a
+ tty or stream device, and the function writes to the device's
+ normal or error output, according to STDOUT-P.
+
+ One use of this function is to define function keys on terminals
+ that have downloadable function key definitions. For example,
+ this is how on certain terminals to define function key 4 to move
+ forward four characters (by transmitting the characters `C-u C-f'
+ to the computer):
+
+ (send-string-to-terminal "\eF4\^U\^F")
+ => nil
+
+ -- 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
+ devices are recorded.) The function returns `nil'. Termscript
+ files are useful for investigating problems where XEmacs garbles
+ the screen, problems that are due to incorrect Termcap entries or
+ to undesirable settings of terminal options more often than to
+ actual XEmacs bugs. Once you are certain which characters were
+ actually output, you can determine reliably whether they
+ correspond to the Termcap specifications in use.
+
+ A `nil' value for FILENAME stops recording terminal output.
+
+ See also `open-dribble-file' in *Note Terminal Input::.
+
+ (open-termscript "../junk/termscript")
+ => nil
projects / chise / xemacs-chise.git.1 / blobdiff