This is ../info/lispref.info, produced by makeinfo version 4.6 from lispref/lispref.texi. INFO-DIR-SECTION XEmacs Editor START-INFO-DIR-ENTRY * Lispref: (lispref). XEmacs Lisp Reference Manual. END-INFO-DIR-ENTRY Edition History: GNU Emacs Lisp Reference Manual Second Edition (v2.01), May 1993 GNU Emacs Lisp Reference Manual Further Revised (v2.02), August 1993 Lucid Emacs Lisp Reference Manual (for 19.10) First Edition, March 1994 XEmacs Lisp Programmer's Manual (for 19.12) Second Edition, April 1995 GNU Emacs Lisp Reference Manual v2.4, June 1995 XEmacs Lisp Programmer's Manual (for 19.13) Third Edition, July 1995 XEmacs Lisp Reference Manual (for 19.14 and 20.0) v3.1, March 1996 XEmacs Lisp Reference Manual (for 19.15 and 20.1, 20.2, 20.3) v3.2, April, May, November 1997 XEmacs Lisp Reference Manual (for 21.0) v3.3, April 1998 Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995 Free Software Foundation, Inc. Copyright (C) 1994, 1995 Sun Microsystems, Inc. Copyright (C) 1995, 1996 Ben Wing. Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice are preserved on all copies. Permission is granted to copy and distribute modified versions of this manual under the conditions for verbatim copying, provided that the entire resulting derived work is distributed under the terms of a permission notice identical to this one. Permission is granted to copy and distribute translations of this manual into another language, under the above conditions for modified versions, except that this permission notice may be stated in a translation approved by the Foundation. Permission is granted to copy and distribute modified versions of this manual under the conditions for verbatim copying, provided also that the section entitled "GNU General Public License" is included exactly as in the original, and provided that the entire resulting derived work is distributed under the terms of a permission notice identical to this one. Permission is granted to copy and distribute translations of this manual into another language, under the above conditions for modified versions, except that the section entitled "GNU General Public License" may be included in a translation approved by the Free Software Foundation instead of in the original English.  File: lispref.info, Node: Font Instance Size, Next: Font Instance Characteristics, Prev: Font Instance Names, Up: Fonts 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.  File: lispref.info, Node: Font Instance Characteristics, Next: Font Convenience Functions, Prev: Font Instance Size, Up: Fonts 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'.  File: lispref.info, Node: Font Convenience Functions, Prev: Font Instance Characteristics, Up: Fonts 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.  File: lispref.info, Node: Colors, Prev: Fonts, Up: Faces and Window-System Objects 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.  File: lispref.info, Node: Color Specifiers, Next: Color Instances, Up: Colors 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.  File: lispref.info, Node: Color Instances, Next: Color Instance Properties, Prev: Color Specifiers, Up: Colors 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)) => # 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.  File: lispref.info, Node: Color Instance Properties, Next: Color Convenience Functions, Prev: Color Instances, Up: Colors 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)  File: lispref.info, Node: Color Convenience Functions, Prev: Color Instance Properties, Up: Colors 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)  File: lispref.info, Node: Glyphs, Next: Annotations, Prev: Faces and Window-System Objects, Up: Top 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.) The actual image that is displayed (as opposed to its position or clipping) is defined by an "image specifier" object contained within the glyph. The separation between an image specifier object and a glyph object is made because the glyph includes other properties than just the actual image: e.g. the face it is displayed in (for text images), the alignment of the image (when it is in a buffer), etc. - Function: glyphp object This function returns `t' if OBJECT is a glyph. * Menu: * Glyph Functions:: Functions for working with glyphs. * Images:: Graphical images displayed in a frame. * Glyph Types:: Each glyph has a particular type. * Mouse Pointer:: Controlling the mouse pointer. * Redisplay Glyphs:: Glyphs controlling various redisplay functions. * Subwindows:: Inserting an externally-controlled subwindow into a buffer. * Glyph Examples:: Examples of how to work with glyphs.  File: lispref.info, Node: Glyph Functions, Next: Images, Up: Glyphs Glyph Functions =============== * Menu: * Creating Glyphs:: Creating new glyphs. * Glyph Properties:: Accessing and modifying a glyph's properties. * Glyph Convenience Functions:: Convenience functions for accessing particular properties of a glyph. * Glyph Dimensions:: Determining the height, width, etc. of a glyph.  File: lispref.info, Node: Creating Glyphs, Next: Glyph Properties, Up: Glyph Functions Creating Glyphs --------------- - Function: make-glyph &optional spec-list type This function creates a new glyph object of type TYPE. SPEC-LIST is used to initialize the glyph's image. It is typically an image instantiator (a string or a vector; *Note Image Specifiers::), but can also be a list of such instantiators (each one in turn is tried until an image is successfully produced), a cons of a locale (frame, buffer, etc.) and an instantiator, a list of such conses, or any other form accepted by `canonicalize-spec-list'. *Note Specifiers::, for more information about specifiers. TYPE specifies the type of the glyph, which specifies in which contexts the glyph can be used, and controls the allowable image types into which the glyph's image can be instantiated. TYPE should be one of `buffer' (used for glyphs in an extent, the modeline, the toolbar, or elsewhere in a buffer), `pointer' (used for the mouse-pointer), or `icon' (used for a frame's icon), and defaults to `buffer'. *Note Glyph Types::. A glyph in XEmacs does *NOT* refer to a single unit of textual display (the XEmacs term for this is "rune"), but rather is an object encapsulating a graphical element, such as an image or widget (an element such as a button or text field; "widget" is the term for this under X Windows, and it's called a "control" under MS Windows). This graphical element could appear in a buffer, a margin, a gutter, or a toolbar, or as a mouse pointer or an icon, for example. Creating a glyph using `make-glyph' does not specify _where_ the glyph will be used, but it does specify _what_ the glyph will look like. In particular, SPEC-LIST is used to specify this, and it's used to initialize the glyph's `image' property, which is an image specifier. (Note that "image" as used in the context of a glyph's `image' property or in the terms "image specifier", "image instantiator", or "image instance" does not refer to what people normally think of as an image (which in XEmacs is called a "pixmap"), but to any graphical element--a pixmap, a widget, or even a block of text, when used in the places that call for a glyph.) The format of the SPEC-LIST is typically an image instantiator (a string or a vector; *Note Image Specifiers::), but can also be a list of such instantiators (each one in turn is tried until an image is successfully produced), a cons of a locale (frame, buffer, etc.) and an instantiator, a list of such conses, or any other form accepted by `canonicalize-spec-list'. *Note Specifiers::, for more information about specifiers. If you're not familiar with specifiers, you should be in order to understand how glyphs work. The clearest introduction to specifiers is in the Lispref manual, available under Info. (Choose Help->Info->Info Contents on the menubar or type C-h i.) You can also see `make-specifier' for a capsule summary. What's important to keep in mind is that a specifier lets you set a different value for any particular buffer, window, frame, device, or console. This allows for a great deal of flexibility; in particular, only one global glyph needs to exist for a particular purpose (e.g. the icon used to represent an iconified frame, the mouse pointer used over particular areas of a frame, etc.), and in these cases you do not create your own glyph, but rather modify the existing one. As well as using SPEC-LIST to initialize the glyph, you can set specifications using `set-glyph-image'. Note that, due to a possibly questionable historical design decision, a glyph itself is not actually a specifier, but rather is an object containing an image specifier (as well as other, seldom-used properties). Therefore, you cannot set or access specifications for the glyph's image by directly using `set-specifier', `specifier-instance' or the like on the glyph; instead use them on `(glyph-image GLYPH)' or use the convenience functions `set-glyph-image', `glyph-image-instance', and `glyph-image'. Once you have created a glyph, you specify where it will be used as follows: * To insert a glyph into a buffer, create an extent in the buffer and then use `set-extent-begin-glyph' or `set-extent-end-glyph' to set a glyph to be displayed at the corresponding edge of the extent. (It is common to create zero-width extents for this purpose.) * To insert a glyph into the left or right margin of a buffer, first make sure the margin is visible by setting a value for the specifiers `left-margin-width' or `right-margin-width'. (Not strictly necessary when using margin glyphs with layout policy `whitespace'.) Then follow the same procedure above for inserting a glyph in a buffer, and then set a non-default layout policy for the glyph using `set-extent-begin-glyph-layout' or `set-extent-end-glyph-layout'. Alternatively, use the high-level annotations API (see `make-annotation'). (In point of fact, you can also use the annotations API for glyphs in a buffer, by setting a layout policy of `text'.) * To insert a glyph into the modeline, just put the glyph directly as one of the modeline elements. (Unfortunately you can't currently put a begin glyph or end glyph on one of the modeline extents--they're ignored.) * To insert a glyph into a toolbar, specify it as part of a toolbar instantiator (typically set on the specifier `default-toolbar'). See `default-toolbar' for more information. (Note that it is standard practice to use a symbol in place of the glyph list in the toolbar instantiator; the symbol is evalled to get the glyph list. This facilitates both creating the toolbar instantiator and modifying individual glyphs in a toolbar later on. For example, you can change the way that the Mail toolbar button looks by modifying the value of the variable `toolbar-mail-icon' (in general, `toolbar-*-icon') and then calling `(set-specifier-dirty-flag default-toolbar)'. (#### Unfortunately this doesn't quite work the way it should; the change will appear in new frames, but not existing ones. * To insert a glyph into a gutter, create or modify a gutter instantiator (typically set on the specifier `default-gutter'). Gutter instantiators consist of strings or lists of strings, so to insert a glyph, create an extent over the string, and use `set-extent-begin-glyph' or `set-extent-end-glyph' to set a glyph to be displayed at the corresponding edge of the extent, just like for glyphs in a buffer. * To use a glyph as the icon for a frame, you do not actually create a new glyph; rather, you change the specifications for the existing glyph `frame-icon-glyph'. (Remember that, because of the specifier nature of glyphs, you can set different values for any particular buffer or frame.) * To use a glyph as the mouse pointer, in general you do not create a new glyph, but rather you change the specifications of various existing glyphs, such as `text-pointer-glyph' for the pointer used over text, `modeline-pointer-glyph' for the pointer used over the modeline, etc. Do an apropos over `*-pointer-glyph' to find all of them. (Note also that you can temporarily set the mouse pointer to some specific shape by using `set-frame-pointer', which takes an image instance, as obtained from calling `glyph-image-instance' on a glyph of type `pointer' - either one of the above-mentioned variables or one you created yourself. (See below for what it means to create a glyph of type `pointer'.) This pointer will last only until the next mouse motion event is processed or certain other things happen, such as creating or deleting a window. (In fact, the above-mentioned pointer glyph variables are implemented as part of the default handler for mouse motion events. If you want to customize this behavior, take a look at `mode-motion-hook', or `mouse-motion-handler' if you really want to get low-level.) * To use a glyph to control the shape of miscellaneous redisplay effects such as the truncation and continuation markers, set the appropriate existing glyph variables, as for icons and pointers above. See `continuation-glyph', `control-arrow-glyph', `hscroll-glyph', `invisible-text-glyph', `octal-escape-glyph', and `truncation-glyph'. See also `overlay-arrow-string', an odd redisplay leftover which can be set to a glyph you created, and will cause the glyph to be displayed on top of the text position specified in the marker stored in `overlay-arrow-position'. * To use a glyph in a display table (i.e. to control the appearance of any individual character), create the appropriate character glyphs and then set a specification for the specifier `current-display-table', which controls the appearance of characters. You can also set an overriding display table for use with text displayed in a particular face; see `set-face-display-table' and `make-display-table'. #### Note: Display tables do not currently support general Mule characters. They will be overhauled at some point to support this and to provide other features required under Mule. * To use a glyph as the background pixmap of a face: Note that the background pixmap of a face is actually an image specifier - probably the only place in XEmacs where an image specifier occurs outside of a glyph. Similarly to how the glyph's image specifier works, you don't create your own image specifier, but rather add specifications to the existing one (using `set-face-background-pixmap'). Note that the image instance that is generated in order to actually display the background pixmap is of type `mono-pixmap', meaning that it's a two-color image and the foreground and background of the image get filled in with the corresponding colors from the face. It is extremely rare that you will ever have to specify a value for TYPE, which should be one of `buffer' (used for glyphs in an extent, the modeline, the toolbar, or elsewhere in a buffer), `pointer' (used for the mouse-pointer), or `icon' (used for a frame's icon), and defaults to `buffer'. The only cases where it needs to be specified is when creating icon or pointer glyphs, and in both cases the necessary glyphs have already been created at startup and are accessed through the appropriate variables, e.g. `text-pointer-glyph' (or in general, `*-pointer-glyph') and `frame-icon-glyph'. *Note Glyph Types::. - Function: make-glyph-internal &optional type This function creates a new, uninitialized glyph of type TYPE. - 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'. 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 `pointer-glyph' object with the specification list SPEC-LIST. This function is equivalent to calling `make-glyph' with a TYPE of `icon'. 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'.  File: lispref.info, Node: Glyph Properties, Next: Glyph Convenience Functions, Prev: Creating Glyphs, Up: Glyph Functions 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. 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). 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: 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.  File: lispref.info, Node: Glyph Convenience Functions, Next: Glyph Dimensions, Prev: Glyph Properties, Up: Glyph Functions 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.  File: lispref.info, Node: Glyph Dimensions, Prev: Glyph Convenience Functions, Up: Glyph Functions 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.  File: lispref.info, Node: Images, Next: Glyph Types, Prev: Glyph Functions, Up: Glyphs Images ====== * Menu: * Image Specifiers:: Specifying how an image will appear. * Image Instantiator Conversion:: Conversion is applied to image instantiators at the time they are added to an image specifier or at the time they are passed to `make-image-instance'. * Image Instances:: What an image specifier gets instanced as.  File: lispref.info, Node: Image Specifiers, Next: Image Instantiator Conversion, Up: Images Image Specifiers ---------------- An image specifier is used to describe the actual image of a glyph. It works like other specifiers (*note Specifiers::), in that it contains a number of specifications describing how the image should appear in a variety of circumstances. These specifications are called "image instantiators". When XEmacs wants to display the image, it instantiates the image into an "image instance". Image instances are their own primitive object type (similar to font instances and color instances), describing how the image appears in a particular domain. (On the other hand, image instantiators, which are just descriptions of how the image should appear, are represented using strings or vectors.) - Function: image-specifier-p object This function returns non-`nil' if OBJECT is an image specifier. Usually, an image specifier results from calling `glyph-image' on a glyph. - Function: make-image-specifier spec-list This function creates a new image specifier object and initializes it according to SPEC-LIST. *Note Specifiers::. Note that, in practice, you rarely, if ever, need to actually create an image specifier! (This function exists mainly for completeness.) Pretty much the only use for image specifiers is to control how glyphs are displayed, and the image specifier associated with a glyph (the `image' property of a glyph) is created automatically when a glyph is created and need not (and cannot, for that matter) ever be changed (*note Glyphs::). In fact, the design decision to create a separate image specifier type, rather than make glyphs themselves be specifiers, is debatable--the other properties of glyphs are rarely used and could conceivably have been incorporated into the glyph's instantiator. The rarely used glyph types (buffer, pointer, icon) could also have been incorporated into the instantiator. Image instantiators come in many formats: `xbm', `xpm', `gif', `jpeg', etc. This describes the format of the data describing the image. The resulting image instances also come in many types--`mono-pixmap', `color-pixmap', `text', `pointer', etc. This refers to the behavior of the image and the sorts of places it can appear. (For example, a color-pixmap image has fixed colors specified for it, while a mono-pixmap image comes in two unspecified shades "foreground" and "background" that are determined from the face of the glyph or surrounding text; a text image appears as a string of text and has an unspecified foreground, background, and font; a pointer image behaves like a mono-pixmap image but can only be used as a mouse pointer [mono-pixmap images cannot be used as mouse pointers]; etc.) It is important to keep the distinction between image instantiator format and image instance type in mind. Typically, a given image instantiator format can result in many different image instance types (for example, `xpm' can be instanced as `color-pixmap', `mono-pixmap', or `pointer'; whereas `cursor-font' can be instanced only as `pointer'), and a particular image instance type can be generated by many different image instantiator formats (e.g. `color-pixmap' can be generated by `xpm', `gif', `jpeg', etc.). *Note Image Instances::, for a more detailed discussion of image instance types. An image instantiator should be a string or a vector of the form `[FORMAT :KEYWORD VALUE ...]' i.e. a format symbol followed by zero or more alternating keyword-value pairs. The "format" field should be a symbol, one of `nothing' Don't display anything; no keywords are valid for this. Can only be instanced as `nothing'. `string' Display this image as a text string. Can only be instanced as `text', although support for instancing as `mono-pixmap' should be added. `formatted-string' Display this image as a text string with replaceable fields, similar to a modeline format string; not currently implemented. `xbm' An X bitmap; only if X support was compiled into this XEmacs. Can be instanced as `mono-pixmap', `color-pixmap', or `pointer'. `xpm' An XPM pixmap; only if XPM support was compiled into this XEmacs. Can be instanced as `color-pixmap', `mono-pixmap', or `pointer'. XPM is an add-on library for X that was designed to rectify the shortcomings of the XBM format. Most implementations of X include the XPM library as a standard part. If your vendor does not, it is highly recommended that you download it and install it. You can get it from the standard XEmacs FTP site, among other places. `xface' An X-Face bitmap, used to encode people's faces in e-mail messages; only if X-Face support was compiled into this XEmacs. Can be instanced as `mono-pixmap', `color-pixmap', or `pointer'. `gif' A GIF87 or GIF89 image; only if GIF support was compiled into this XEmacs. Can be instanced as `color-pixmap'. Note that XEmacs includes GIF decoding functions as a standard part of it, so if you have X support, you will normally have GIF support, unless you explicitly disable it at configure time. `jpeg' A JPEG-format image; only if JPEG support was compiled into this XEmacs. Can be instanced as `color-pixmap'. If you have the JPEG libraries present on your system when XEmacs is built, XEmacs will automatically detect this and use them, unless you explicitly disable it at configure time. `png' A PNG/GIF24 image; only if PNG support was compiled into this XEmacs. Can be instanced as `color-pixmap'. `tiff' A TIFF-format image; only if TIFF support was compiled into this XEmacs. `cursor-font' One of the standard cursor-font names, such as `watch' or `right_ptr' under X. Under X, this is, more specifically, any of the standard cursor names from appendix B of the Xlib manual [also known as the file `'] minus the `XC_' prefix. On other window systems, the valid names will be specific to the type of window system. Can only be instanced as `pointer'. `font' A glyph from a font; i.e. the name of a font, and glyph index into it of the form `FONT fontname index [[mask-font] mask-index]'. Only if X support was compiled into this XEmacs. Currently can only be instanced as `pointer', although this should probably be fixed. `mswindows-resource' An MS Windows pointer resource. Specifies a resource to retrieve directly from the system (an OEM resource) or from a file, particularly an executable file. If the resource is to be retrieved from a file, use :file and optionally :resource-id. Otherwise use :resource-id. Always specify :resource-type to specify the type (cursor, bitmap or icon) of the resource. Possible values for :resource-id are listed below. Can be instanced as `pointer' or `color-pixmap'. `subwindow' An embedded windowing system window. Can only be instanced as `subwindow'. `button' A button widget; either a push button, radio button or toggle button. Can only be instanced as `widget'. `combo-box' A drop list of selectable items in a widget, for editing text. Can only be instanced as `widget'. `edit-field' A text editing widget. Can only be instanced as `widget'. `label' A static, text-only, widget; for displaying text. Can only be instanced as `widget'. `layout' A widget for controlling the positioning of children underneath it. Through the use of nested layouts, a widget hierarchy can be created which can have the appearance of any standard dialog box or similar arrangement; all of this is counted as one "glyph" and could appear in many of the places that expect a single glyph. Can only be instanced as `widget'. `native-layout' The native version of a layout widget. Can only be instanced as `widget'. `progress-gauge' A sliding widget, for showing progress. Can only be instanced as `widget'. `tab-control' A tab widget; a series of user selectable tabs. Can only be instanced as `widget'. `tree-view' A folding widget. Can only be instanced as `widget'. `scrollbar' A scrollbar widget. Can only be instanced as `widget'. `autodetect' XEmacs tries to guess what format the data is in. If X support exists, the data string will be checked to see if it names a filename. If so, and this filename contains XBM or XPM data, the appropriate sort of pixmap or pointer will be created. [This includes picking up any specified hotspot or associated mask file.] Otherwise, if `pointer' is one of the allowable image-instance types and the string names a valid cursor-font name, the image will be created as a pointer. Otherwise, the image will be displayed as text. If no X support exists, the image will always be displayed as text. `inherit' Inherit from the background-pixmap property of a face. Can only be instanced as `mono-pixmap'. The valid keywords are: `:data' Inline data. For most formats above, this should be a string. For XBM images, this should be a list of three elements: width, height, and a string of bit data. This keyword is not valid for instantiator format `nothing'. `:file' Data is contained in a file. The value is the name of this file. If both `:data' and `:file' are specified, the image is created from what is specified in `:data' and the string in `:file' becomes the value of the `image-instance-file-name' function when applied to the resulting image-instance. This keyword is not valid for instantiator formats `nothing', `string', `formatted-string', `cursor-font', `font', and `autodetect'. `:foreground' `:background' For `xbm', `xface', `cursor-font', and `font'. These keywords allow you to explicitly specify foreground and background colors. The argument should be anything acceptable to `make-color-instance'. This will cause what would be a `mono-pixmap' to instead be colorized as a two-color color-pixmap, and specifies the foreground and/or background colors for a pointer instead of black and white. `:mask-data' For `xbm' and `xface'. This specifies a mask to be used with the bitmap. The format is a list of width, height, and bits, like for `:data'. `:mask-file' For `xbm' and `xface'. This specifies a file containing the mask data. If neither a mask file nor inline mask data is given for an XBM image, and the XBM image comes from a file, XEmacs will look for a mask file with the same name as the image file but with `Mask' or `msk' appended. For example, if you specify the XBM file `left_ptr' [usually located in `/usr/include/X11/bitmaps'], the associated mask file `left_ptrmsk' will automatically be picked up. `:hotspot-x' `:hotspot-y' For `xbm' and `xface'. These keywords specify a hotspot if the image is instantiated as a `pointer'. Note that if the XBM image file specifies a hotspot, it will automatically be picked up if no explicit hotspot is given. `:color-symbols' Only for `xpm'. This specifies an alist that maps strings that specify symbolic color names to the actual color to be used for that symbolic color (in the form of a string or a color-specifier object). If this is not specified, the contents of `xpm-color-symbols' are used to generate the alist. `:resource-id' Only for `mswindows-resource'. This must be either an integer (which directly specifies a resource number) or a string. Valid strings are For bitmaps: "close", "uparrow", "dnarrow", "rgarrow", "lfarrow", "reduce", "zoom", "restore", "reduced", "zoomd", "restored", "uparrowd", "dnarrowd", "rgarrowd", "lfarrowd", "mnarrow", "combo", "uparrowi", "dnarrowi", "rgarrowi", "lfarrowi", "size", "btsize", "check", "checkboxes", and "btncorners". For cursors: "normal", "ibeam", "wait", "cross", "up", "sizenwse", "sizenesw", "sizewe", "sizens", "sizeall", and "no". For icons: "sample", "hand", "ques", "bang", "note", and "winlogo". `:resource-type' Only for `mswindows-resource'. This must be a symbol, either `cursor', `icon', or `bitmap', specifying the type of resource to be retrieved. `:face' Only for `inherit'. This specifies the face to inherit from. For widgets this also specifies the face to use for display. It defaults to gui-element-face. Keywords accepted as menu item specs are also accepted by widgets. These are `:selected', `:active', `:suffix', `:keys', `:style', `:filter', `:config', `:included', `:key-sequence', `:accelerator', `:label' and `:callback'. If instead of a vector, the instantiator is a string, it will be converted into a vector by looking it up according to the specs in the `console-type-image-conversion-list' for the console type of the domain (usually a window; sometimes a frame or device) over which the image is being instantiated. If the instantiator specifies data from a file, the data will be read in at the time that the instantiator is added to the image specifier (which may be well before the image is actually displayed), and the instantiator will be converted into one of the inline-data forms, with the filename retained using a `:file' keyword. This implies that the file must exist when the instantiator is added to the image, but does not need to exist at any other time (e.g. it may safely be a temporary file). - Function: valid-image-instantiator-format-p format &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 return a list of valid image-instantiator formats. - Variable: xpm-color-symbols This variable holds definitions of logical color-names used when reading XPM files. Elements of this list should be of the form `(COLOR-NAME FORM-TO-EVALUATE)'. The COLOR-NAME should be a string, which is the name of the color to define; the FORM-TO-EVALUATE should evaluate to a color specifier object, or a string to be passed to `make-color-instance' (*note Colors::). If a loaded XPM file references a symbolic color called COLOR-NAME, it will display as the computed color instead. The default value of this variable defines the logical color names `"foreground"' and `"background"' to be the colors of the `default' face. - Variable: x-bitmap-file-path A list of the directories in which X bitmap files may be found. If `nil', this is initialized from the `"*bitmapFilePath"' resource. This is used by the `make-image-instance' function (however, note that if the environment variable `XBMLANGPATH' is set, it is consulted first).  File: lispref.info, Node: Image Instantiator Conversion, Next: Image Instances, Prev: Image Specifiers, Up: Images Image Instantiator Conversion ----------------------------- - Function: set-console-type-image-conversion-list console-type list This function sets the image-conversion-list for consoles of the given CONSOLE-TYPE. The image-conversion-list specifies how image instantiators that are strings should be interpreted. Each element of the list should be a list of two elements (a regular expression string and a vector) or a list of three elements (the preceding two plus an integer index into the vector). The string is converted to the vector associated with the first matching regular expression. If a vector index is specified, the string itself is substituted into that position in the vector. Note: The conversion above is applied when the image instantiator is added to an image specifier, not when the specifier is actually instantiated. Therefore, changing the image-conversion-list only affects newly-added instantiators. Existing instantiators in glyphs and image specifiers will not be affected. - Function: console-type-image-conversion-list console-type This function returns the image-conversion-list for consoles of the given CONSOLE-TYPE.  File: lispref.info, Node: Image Instances, Prev: Image Instantiator Conversion, Up: Images Image Instances --------------- Image-instance objects encapsulate the way a particular image (pixmap, etc.) is displayed on a particular device. In most circumstances, you do not need to directly create image instances; use a glyph instead. However, it may occasionally be useful to explicitly create image instances, if you want more control over the instantiation process. - Function: image-instance-p object This function returns non-`nil' if OBJECT is an image instance. * Menu: * Image Instance Types:: Each image instances has a particular type. * Image Instance Functions:: Functions for working with image instances.  File: lispref.info, Node: Image Instance Types, Next: Image Instance Functions, Up: Image Instances Image Instance Types .................... Image instances come in a number of different types. The type of an image instance specifies the nature of the image: Whether it is a text string, a mono pixmap, a color pixmap, etc. The valid image instance types are `nothing' Nothing is displayed. `text' Displayed as text. The foreground and background colors and the font of the text are specified independent of the pixmap. Typically these attributes will come from the face of the surrounding text, unless a face is specified for the glyph in which the image appears. `mono-pixmap' Displayed as a mono pixmap (a pixmap with only two colors where the foreground and background can be specified independent of the pixmap; typically the pixmap assumes the foreground and background colors of the text around it, unless a face is specified for the glyph in which the image appears). `color-pixmap' Displayed as a color pixmap. `pointer' Used as the mouse pointer for a window. `subwindow' A child window that is treated as an image. This allows (e.g.) another program to be responsible for drawing into the window. Not currently implemented. - Function: valid-image-instance-type-p type This function returns non-`nil' if TYPE is a valid image instance type. - Function: image-instance-type-list This function returns a list of the valid image instance types. - Function: image-instance-type image-instance This function returns the type of the given image instance. The return value will be one of `nothing', `text', `mono-pixmap', `color-pixmap', `pointer', or `subwindow'. - Function: text-image-instance-p object This function returns non-`nil' if OBJECT is an image instance of type `text'. - Function: mono-pixmap-image-instance-p object This function returns non-`nil' if OBJECT is an image instance of type `mono-pixmap'. - Function: color-pixmap-image-instance-p object This function returns non-`nil' if OBJECT is an image instance of type `color-pixmap'. - Function: pointer-image-instance-p object This function returns non-`nil' if OBJECT is an image instance of type `pointer'. - Function: subwindow-image-instance-p object This function returns non-`nil' if OBJECT is an image instance of type `subwindow'. - Function: nothing-image-instance-p object This function returns non-`nil' if OBJECT is an image instance of type `nothing'. - Function: widget-image-instance-p object Return `t' if OBJECT is an image instance of type `widget'.  File: lispref.info, Node: Image Instance Functions, Prev: Image Instance Types, Up: Image Instances Image Instance Functions ........................ - Function: make-image-instance data &optional domain dest-types 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. (For XBM, the most natural types are `mono-pixmap', followed by `color-pixmap', followed by `pointer'. For the other normal image formats, the most natural types are `color-pixmap', followed by `mono-pixmap', followed by `pointer'. For the string and formatted-string formats, the most natural types are `text', followed by `mono-pixmap' (not currently implemented), followed by `color-pixmap' (not currently implemented). For MS Windows resources, the most natural type for pointer resources is `pointer', and for the others it's `color-pixmap'. The other formats can only be instantiated as one type. (If you want to control more specifically the order of the types into which an image is instantiated, just call `make-image-instance' repeatedly until it succeeds, passing less and less preferred destination types each time. If DEST-TYPES is omitted, all possible types are allowed. DOMAIN specifies the domain to which the image instance will be attached. This domain is termed the "governing domain". The type of the governing domain depends on the image instantiator format. (Although, more correctly, it should probably depend on the image instance type.) For example, pixmap image instances are specific to a device, but widget image instances are specific to a particular XEmacs window because in order to display such a widget when two windows onto the same buffer want to display the widget, two separate underlying widgets must be created. (That's because a widget is actually a child window-system window, and all window-system windows have a unique existence on the screen.) This means that the governing domain for a pixmap image instance will be some device (most likely, the only existing device), whereas the governing domain for a widget image instance will be some XEmacs window. If you specify an overly general DOMAIN (e.g. a frame when a window was wanted), an error is signaled. If you specify an overly specific DOMAIN (e.g. a window when a device was wanted), the corresponding general domain is fetched and used instead. For `make-image-instance', it makes no difference whether you specify an overly specific domain or the properly general domain derived from it. However, it does matter when creating an image instance by instantiating a specifier or glyph (e.g. with `glyph-image-instance'), because the more specific domain causes spec lookup to start there and proceed to more general domains. (It would also matter when creating an image instance with an instantiator format of `inherit', but we currently disallow this. #### We should fix this.) n If omitted, DOMAIN defaults to the selected window. 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. - Function: image-instance-name image-instance This function returns the name of the given image instance. - Function: image-instance-domain image-instance Return the governing domain of the given IMAGE-INSTANCE. The governing domain of an image instance is the domain that the image instance is specific to. It is _NOT_ necessarily the domain that was given to the call to `specifier-instance' that resulted in the creation of this image instance. See `make-image-instance' for more information on governing domains. - Function: image-instance-string image-instance This function returns the string of the given image instance. This will only be non-`nil' for text image instances. - Function: image-instance-file-name image-instance This function returns the file name from which IMAGE-INSTANCE was read, if known. - Function: image-instance-mask-file-name image-instance This function returns the file name from which IMAGE-INSTANCE's mask was read, if known. - Function: image-instance-depth image-instance This function returns the depth of the image instance. This is 0 for a mono pixmap, or a positive integer for a color pixmap. - Function: image-instance-height image-instance This function returns the height of the image instance, in pixels. - Function: image-instance-width image-instance This function returns the width of the image instance, in pixels. - Function: image-instance-hotspot-x image-instance This function returns the X coordinate of the image instance's hotspot, if known. This is a point relative to the origin of the pixmap. When an image is used as a mouse pointer, the hotspot is the point on the image that sits over the location that the pointer points to. This is, for example, the tip of the arrow or the center of the crosshairs. This will always be `nil' for a non-pointer image instance. - Function: image-instance-hotspot-y image-instance This function returns the Y coordinate of the image instance's hotspot, if known. - Function: image-instance-foreground image-instance This function returns the foreground color of IMAGE-INSTANCE, if applicable. This will be a color instance or `nil'. (It will only be non-`nil' for colorized mono pixmaps and for pointers.) - Function: image-instance-background image-instance This function returns the background color of IMAGE-INSTANCE, if applicable. This will be a color instance or `nil'. (It will only be non-`nil' for colorized mono pixmaps and for pointers.)  File: lispref.info, Node: Glyph Types, Next: Mouse Pointer, Prev: Images, Up: Glyphs Glyph Types =========== Each glyph has a particular type, which controls how the glyph's image is generated. Each glyph type has a corresponding list of allowable image instance types that can be generated. When you call `glyph-image-instance' to retrieve the image instance of a glyph, XEmacs does the equivalent of calling `make-image-instance' and passing in DEST-TYPES the list of allowable image instance types for the glyph's type. * `buffer' glyphs can be used as the begin-glyph or end-glyph of an extent, in the modeline, and in the toolbar. Their image can be instantiated as `nothing', `mono-pixmap', `color-pixmap', `text', and `subwindow'. * `pointer' glyphs can be used to specify the mouse pointer. Their image can be instantiated as `pointer'. * `icon' glyphs can be used to specify the icon used when a frame is iconified. Their image can be instantiated as `mono-pixmap' and `color-pixmap'. - Function: glyph-type glyph This function returns the type of the given glyph. The return value will be a symbol, one of `buffer', `pointer', or `icon'. - Function: valid-glyph-type-p glyph-type Given a GLYPH-TYPE, this function returns non-`nil' if it is valid. - Function: glyph-type-list This function returns a list of valid glyph types. - Function: buffer-glyph-p object This function returns non-`nil' if OBJECT is a glyph of type `buffer'. - Function: icon-glyph-p object This function returns non-`nil' if OBJECT is a glyph of type `icon'. - Function: pointer-glyph-p object This function returns non-`nil' if OBJECT is a glyph of type `pointer'.  File: lispref.info, Node: Mouse Pointer, Next: Redisplay Glyphs, Prev: Glyph Types, Up: Glyphs Mouse Pointer ============= The shape of the mouse pointer when over a particular section of a frame is controlled using various glyph variables. Since the image of a glyph is a specifier, it can be controlled on a per-buffer, per-frame, per-window, or per-device basis. You should use `set-glyph-image' to set the following variables, _not_ `setq'. - Glyph: text-pointer-glyph This variable specifies the shape of the mouse pointer when over text. - Glyph: nontext-pointer-glyph This variable specifies the shape of the mouse pointer when over a buffer, but not over text. If unspecified in a particular domain, `text-pointer-glyph' is used. - Glyph: modeline-pointer-glyph This variable specifies the shape of the mouse pointer when over the modeline. If unspecified in a particular domain, `nontext-pointer-glyph' is used. - Glyph: selection-pointer-glyph This variable specifies the shape of the mouse pointer when over a selectable text region. If unspecified in a particular domain, `text-pointer-glyph' is used. - Glyph: gc-pointer-glyph This variable specifies the shape of the mouse pointer when a garbage collection is in progress. If the selected window is on a window system and this glyph specifies a value (i.e. a pointer image instance) in the domain of the selected window, the pointer will be changed as specified during garbage collection. Otherwise, a message will be printed in the echo area, as controlled by `gc-message'. - Glyph: busy-pointer-glyph This variable specifies the shape of the mouse pointer when XEmacs is busy. If unspecified in a particular domain, the pointer is not changed when XEmacs is busy. - Glyph: menubar-pointer-glyph This variable specifies the shape of the mouse pointer when over the menubar. If unspecified in a particular domain, the window-system-provided default pointer is used. - Glyph: scrollbar-pointer-glyph This variable specifies the shape of the mouse pointer when over a scrollbar. If unspecified in a particular domain, the window-system-provided default pointer is used. - Glyph: toolbar-pointer-glyph This variable specifies the shape of the mouse pointer when over a toolbar. If unspecified in a particular domain, `nontext-pointer-glyph' is used. Internally, these variables are implemented in `default-mouse-motion-handler', and thus only take effect when the mouse moves. That function calls `set-frame-pointer', which sets the current mouse pointer for a frame. - Function: set-frame-pointer frame image-instance This function sets the mouse pointer of FRAME to the given pointer image instance. You should not call this function directly. (If you do, the pointer will change again the next time the mouse moves.)  File: lispref.info, Node: Redisplay Glyphs, Next: Subwindows, Prev: Mouse Pointer, Up: Glyphs Redisplay Glyphs ================ - Glyph: truncation-glyph This variable specifies what is displayed at the end of truncated lines. - Glyph: continuation-glyph This variable specifies what is displayed at the end of wrapped lines. - Glyph: octal-escape-glyph This variable specifies what to prefix character codes displayed in octal with. - Glyph: hscroll-glyph This variable specifies what to display at the beginning of horizontally scrolled lines. - Glyph: invisible-text-glyph This variable specifies what to use to indicate the presence of invisible text. This is the glyph that is displayed when an ellipsis is called for, according to `selective-display-ellipses' or `buffer-invisibility-spec'). Normally this is three dots ("..."). - Glyph: control-arrow-glyph This variable specifies what to use as an arrow for control characters.  File: lispref.info, Node: Subwindows, Next: Glyph Examples, Prev: Redisplay Glyphs, Up: Glyphs Subwindows ========== Subwindows are not currently implemented. - Function: subwindowp object This function returns non-`nil' if OBJECT is a subwindow.  File: lispref.info, Node: Glyph Examples, Prev: Subwindows, Up: Glyphs 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.  File: lispref.info, Node: Annotations, Next: Display, Prev: Glyphs, Up: Top Annotations *********** An "annotation" is a pixmap or string that is not part of a buffer's text but is displayed next to a particular location in a buffer. Annotations can be displayed intermixed with text, in any whitespace at the beginning or end of a line, or in a special area at the left or right side of the frame called a "margin", whose size is controllable. Annotations are implemented using extents (*note Extents::); but you can work with annotations without knowing how extents work. * Menu: * Annotation Basics:: Introduction to annotations. * Annotation Primitives:: Creating and deleting annotations. * Annotation Properties:: Retrieving and changing the characteristics of an annotation. * Margin Primitives:: Controlling the size of the margins. * Locating Annotations:: Looking for annotations in a buffer. * Annotation Hooks:: Hooks called at certain times during an annotation's lifetime.  File: lispref.info, Node: Annotation Basics, Next: Annotation Primitives, Up: Annotations 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.  File: lispref.info, Node: Annotation Primitives, Next: Annotation Properties, Prev: Annotation Basics, Up: Annotations 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.  File: lispref.info, Node: Annotation Properties, Next: Margin Primitives, Prev: Annotation Primitives, Up: Annotations 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.  File: lispref.info, Node: Locating Annotations, Next: Annotation Hooks, Prev: Margin Primitives, Up: Annotations 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.  File: lispref.info, Node: Margin Primitives, Next: Locating Annotations, Prev: Annotation Properties, Up: Annotations 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.  File: lispref.info, Node: Annotation Hooks, Prev: Locating Annotations, Up: Annotations 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.  File: lispref.info, Node: Display, Next: Hash Tables, Prev: Annotations, Up: Top 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.  File: lispref.info, Node: Refresh Screen, Next: Truncation, Up: Display 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.  File: lispref.info, Node: Truncation, Next: The Echo Area, Prev: Refresh Screen, Up: Display 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::.  File: lispref.info, Node: The Echo Area, Next: Warnings, Prev: Truncation, Up: Display 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.  File: lispref.info, Node: Warnings, Next: Invisible Text, Prev: The Echo Area, Up: Display 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.  File: lispref.info, Node: Invisible Text, Next: Selective Display, Prev: Warnings, Up: Display 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'.  File: lispref.info, Node: Selective Display, Next: Overlay Arrow, Prev: Invisible Text, Up: Display 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::.  File: lispref.info, Node: Overlay Arrow, Next: Temporary Displays, Prev: Selective Display, Up: Display 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::.  File: lispref.info, Node: Temporary Displays, Next: Blinking, Prev: Overlay Arrow, Up: Display 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 ---------- 20 # ---------- 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.  File: lispref.info, Node: Blinking, Next: Usual Display, Prev: Temporary Displays, Up: Display 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)))  File: lispref.info, Node: Usual Display, Next: Display Tables, Prev: Blinking, Up: Display 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::.  File: lispref.info, Node: Display Tables, Next: Beeping, Prev: Usual Display, Up: Display 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.  File: lispref.info, Node: Display Table Format, Next: Active Display Table, Up: Display Tables 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 "^?"))  File: lispref.info, Node: Active Display Table, Next: Character Descriptors, Prev: Display Table Format, Up: Display Tables 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::.  File: lispref.info, Node: Character Descriptors, Prev: Active Display Table, Up: Display Tables 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::).  File: lispref.info, Node: Beeping, Prev: Display Tables, Up: Display 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-name )' 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.  File: lispref.info, Node: Hash Tables, Next: Range Tables, Prev: Display, Up: Top 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.  File: lispref.info, Node: Introduction to Hash Tables, Next: Working With Hash Tables, Up: Hash Tables 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'.  File: lispref.info, Node: Working With Hash Tables, Next: Weak Hash Tables, Prev: Introduction to Hash Tables, Up: Hash Tables 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.  File: lispref.info, Node: Weak Hash Tables, Prev: Working With Hash Tables, Up: Hash Tables 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'.  File: lispref.info, Node: Range Tables, Next: Databases, Prev: Hash Tables, Up: Top 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.  File: lispref.info, Node: Introduction to Range Tables, Next: Working With Range Tables, Up: Range Tables 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.  File: lispref.info, Node: Working With Range Tables, Prev: Introduction to Range Tables, Up: Range Tables 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.  File: lispref.info, Node: Databases, Next: Processes, Prev: Range Tables, Up: Top 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::  File: lispref.info, Node: Connecting to a Database, Next: Working With a Database, Up: Databases 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'.  File: lispref.info, Node: Working With a Database, Next: Other Database Functions, Prev: Connecting to a Database, Up: Databases 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.  File: lispref.info, Node: Other Database Functions, Prev: Working With a Database, Up: Databases 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.  File: lispref.info, Node: Processes, Next: System Interface, Prev: Databases, Up: Top 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.  File: lispref.info, Node: Subprocess Creation, Next: Synchronous Processes, Up: Processes 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.  File: lispref.info, Node: Synchronous Processes, Next: MS-DOS Subprocesses, Prev: Subprocess Creation, Up: Processes 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.  File: lispref.info, Node: MS-DOS Subprocesses, Next: Asynchronous Processes, Prev: Synchronous Processes, Up: Processes MS-DOS Subprocesses =================== On MS-DOS, you must indicate whether the data going to and from a synchronous subprocess are text or binary. Text data requires 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.  File: lispref.info, Node: Asynchronous Processes, Next: Deleting Processes, Prev: MS-DOS Subprocesses, Up: Processes 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") => # (start-process "my-process" "foo" "ls" "-l" "/user/lewis/bin") => #> ---------- 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::.  File: lispref.info, Node: Deleting Processes, Next: Process Information, Prev: Asynchronous Processes, Up: Processes 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 - 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  File: lispref.info, Node: Process Information, Next: Input to Processes, Prev: Deleting Processes, Up: Processes Process Information =================== 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) => (# #) - 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") => # - 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. `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 => #> (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::).  File: lispref.info, Node: Input to Processes, Next: Signals to Processes, Prev: Process Information, Up: Processes Sending Input to Processes ========================== Asynchronous subprocesses receive input when it is sent to them by XEmacs, which is done with the functions in this section. You must specify the process to send input to, and the input data to send. The data appears on the "standard input" of the subprocess. 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. - Function: process-send-string process string &optional start end This function sends PROCESS the contents of STRING as standard input. 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. Optional arguments START and END specify part of STRING; see `substring'. 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"  File: lispref.info, Node: Signals to Processes, Next: Output from Processes, Prev: Input to Processes, Up: Processes Sending Signals to Processes ============================ "Sending a signal" to a subprocess is a way of interrupting its activities. There are several different signals, each with its own 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.  File: lispref.info, Node: Output from Processes, Next: Sentinels, Prev: Signals to Processes, Up: Processes Receiving Output from Processes =============================== There are two ways to receive the output that a subprocess writes to its standard output stream. The output can be inserted in a buffer, 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.  File: lispref.info, Node: Process Buffers, Next: Filter Functions, Up: Output from Processes Process Buffers --------------- A process can (and usually does) have an "associated buffer", which is an ordinary Emacs buffer that is used for two purposes: storing the 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. 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: process-buffer process This function returns the associated buffer of the process PROCESS. (process-buffer (get-process "shell")) => # - 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. - Function: set-process-buffer process buffer This function sets the buffer associated with PROCESS to BUFFER. If BUFFER is `nil', the process becomes associated with no buffer. - Function: get-buffer-process buffer-or-name 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. (get-buffer-process "*shell*") => # Killing the process's buffer deletes the process, which kills the subprocess with a `SIGHUP' signal (*note Signals to Processes::).  File: lispref.info, Node: Filter Functions, Next: Accepting Output, Prev: Process Buffers, Up: Output from Processes 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 ")  File: lispref.info, Node: Accepting Output, Prev: Filter Functions, Up: Output from Processes 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.  File: lispref.info, Node: Sentinels, Next: Process Window Size, Prev: Output from Processes, Up: Processes 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: # had the event `killed' => # - 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.  File: lispref.info, Node: Process Window Size, Next: Transaction Queues, Prev: Sentinels, Up: Processes 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.  File: lispref.info, Node: Transaction Queues, Next: Network, Prev: Process Window Size, Up: Processes 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. 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. 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. The return value of `tq-enqueue' itself is not meaningful. - Function: tq-close queue Shut down transaction queue QUEUE, waiting for all pending transactions to complete, and then terminate the connection or child process. Transaction queues are implemented by means of a filter function. *Note Filter Functions::.  File: lispref.info, Node: Network, Prev: Transaction Queues, Up: Processes 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.  File: lispref.info, Node: System Interface, Next: X-Windows, Prev: Processes, Up: Top Operating System Interface ************************** This chapter is about starting and getting out of Emacs, access to values in the operating system environment, and terminal input, output, and flow control. *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.  File: lispref.info, Node: Starting Up, Next: Getting Out, Up: System Interface Starting Up XEmacs ================== This section describes what XEmacs does when it is started, and how you can customize these actions. * Menu: * 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.  File: lispref.info, Node: Start-up Summary, Next: Init File, Up: Starting Up Summary: Sequence of Actions at Start Up ---------------------------------------- The order of operations performed (in `startup.el') by XEmacs when it is started up is as follows: 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'. 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'. 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 `~'. 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.  File: lispref.info, Node: Init File, Next: Terminal-Specific, Prev: Start-up Summary, Up: Starting Up 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'.  File: lispref.info, Node: Terminal-Specific, Next: Command Line Arguments, Prev: Init File, Up: Starting Up 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'.  File: lispref.info, Node: Command Line Arguments, Prev: Terminal-Specific, Up: Starting Up 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'.) 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. - Variable: command-line-args The value of this variable is the list of command line arguments passed to XEmacs. - 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. 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.  File: lispref.info, Node: Getting Out, Next: System Environment, Prev: Starting Up, Up: System Interface 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: * Killing XEmacs:: Exiting XEmacs irreversibly. * Suspending XEmacs:: Exiting XEmacs reversibly.  File: lispref.info, Node: Killing XEmacs, Next: Suspending XEmacs, Up: Getting Out Killing XEmacs -------------- Killing XEmacs means ending the execution of the XEmacs process. The parent process normally resumes control. The low-level primitive for killing XEmacs is `kill-emacs'. - Command: kill-emacs &optional exit-data This function exits the XEmacs process and kills it. 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::.) 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. 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'. - Variable: kill-emacs-query-functions After asking the standard questions, `save-buffers-kill-emacs' calls the functions in the list `kill-buffer-query-functions', in order of appearance, with no arguments. These functions can ask for additional confirmation from the user. If any of them returns non-`nil', XEmacs is not killed. - Variable: kill-emacs-hook 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.  File: lispref.info, Node: Suspending XEmacs, Prev: Killing XEmacs, Up: Getting Out 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 (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 ---------- Buffer: Minibuffer ---------- Really suspend? y ---------- Buffer: Minibuffer ---------- ---------- Parent Shell ---------- lewis@slug[23] % /user/lewis/manual lewis@slug[24] % fg ---------- Echo Area ---------- Resumed! - Variable: suspend-hook This variable is a normal hook run before suspending. - Variable: suspend-resume-hook This variable is a normal hook run after suspending.  File: lispref.info, Node: System Environment, Next: User Identification, Prev: Getting Out, Up: System Interface Operating System Environment ============================ XEmacs provides access to variables in the operating system environment through various functions. These variables include the name of the system, the user's UID, and so on. - Variable: system-type 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: `aix-v3' AIX. `berkeley-unix' Berkeley BSD. `dgux' Data General DGUX operating system. `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.  File: lispref.info, Node: User Identification, Next: Time of Day, Prev: System Environment, Up: System Interface 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::). - 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.  File: lispref.info, Node: Time of Day, Next: Time Conversion, Prev: User Identification, Up: System Interface Time of Day =========== 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::).  File: lispref.info, Node: Time Conversion, Next: Timers, Prev: Time of Day, Up: System Interface 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.  File: lispref.info, Node: Timers, Next: Terminal Input, Prev: Time Conversion, Up: System Interface 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'.)  File: lispref.info, Node: Terminal Input, Next: Terminal Output, Prev: Timers, Up: System Interface Terminal Input ============== This section describes functions and variables for recording or manipulating terminal input. See *Note Display::, for related functions. * Menu: * 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.  File: lispref.info, Node: Input Modes, Next: Translating Input, Up: Terminal Input 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'.  File: lispref.info, Node: Translating Input, Next: Recording Input, Prev: Input Modes, Up: Terminal Input 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 ` 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" ` O P' to `[pf1]' in `function-key-map', when using a VT100. Thus, typing `C-c ' sends the character sequence `C-c O P'; later the function `read-key-sequence' translates this back into `C-c ', 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.  File: lispref.info, Node: Recording Input, Prev: Translating Input, Up: Terminal Input Recording Input --------------- - 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'. - 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::).  File: lispref.info, Node: Terminal Output, Next: Flow Control, Prev: Terminal Input, Up: System Interface 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  File: lispref.info, Node: Flow Control, Next: Batch Mode, Prev: Terminal Output, Up: System Interface Flow Control ============ This section attempts to answer the question "Why does XEmacs choose to use flow-control characters in its command character set?" For a second view on this issue, read the comments on flow control in the `emacs/INSTALL' file from the distribution; for help with Termcap entries and DEC terminal concentrators, see `emacs/etc/TERMS'. At one time, most terminals did not need flow control, and none used `C-s' and `C-q' for flow control. Therefore, the choice of `C-s' and `C-q' as command characters was uncontroversial. XEmacs, for economy of keystrokes and portability, used nearly all the ASCII control characters, with mnemonic meanings when possible; thus, `C-s' for search and `C-q' for quote. Later, some terminals were introduced which required these characters for flow control. They were not very good terminals for full-screen editing, so XEmacs maintainers did not pay attention. In later years, flow control with `C-s' and `C-q' became widespread among terminals, but by this time it was usually an option. And the majority of users, who can turn flow control off, were unwilling to switch to less mnemonic key bindings for the sake of flow control. So which usage is "right", XEmacs's or that of some terminal and concentrator manufacturers? This question has no simple answer. One reason why we are reluctant to cater to the problems caused by `C-s' and `C-q' is that they are gratuitous. There are other techniques (albeit less common in practice) for flow control that preserve transparency of the character stream. Note also that their use for flow control is not an official standard. Interestingly, on the model 33 teletype with a paper tape punch (which is very old), `C-s' and `C-q' were sent by the computer to turn the punch on and off! As X servers and other window systems replace character-only terminals, this problem is gradually being cured. For the mean time, XEmacs provides a convenient way of enabling flow control if you want it: call the function `enable-flow-control'. - Command: enable-flow-control &optional argument This function enables use of `C-s' and `C-q' for output flow control, and provides the characters `C-\' and `C-^' as aliases for them using `keyboard-translate-table' (*note Translating Input::). With optional argument ARGUMENT (interactively the prefix argument), enable flow control mode if ARGUMENT is positive; else disable it. You can use the function `enable-flow-control-on' in your `.emacs' file to enable flow control automatically on certain terminal types. - Function: enable-flow-control-on &rest termtypes This function enables flow control, and the aliases `C-\' and `C-^', if the terminal type is one of TERMTYPES. For example: (enable-flow-control-on "vt200" "vt300" "vt101" "vt131") Here is how `enable-flow-control' does its job: 1. It sets CBREAK mode for terminal input, and tells the operating system to handle flow control, with `(set-input-mode nil t)'. 2. It sets up `keyboard-translate-table' to translate `C-\' and `C-^' into `C-s' and `C-q'. Except at its very lowest level, XEmacs never knows that the characters typed were anything but `C-s' and `C-q', so you can in effect type them as `C-\' and `C-^' even when they are input for other commands. *Note Translating Input::. If the terminal is the source of the flow control characters, then once you enable kernel flow control handling, you probably can make do with less padding than normal for that terminal. You can reduce the amount of padding by customizing the Termcap entry. You can also reduce it by setting `baud-rate' to a smaller value so that XEmacs uses a smaller speed when calculating the padding needed. *Note Terminal Output::.  File: lispref.info, Node: Batch Mode, Prev: Flow Control, Up: System Interface Batch Mode ========== The command line option `-batch' causes XEmacs to run noninteractively. In this mode, XEmacs does not read commands from the terminal, it does not alter the terminal modes, and it does not expect to be outputting to an erasable screen. The idea is that you specify Lisp programs to run; when they are finished, XEmacs should exit. The way to specify the programs to run is with `-l FILE', which loads the library named FILE, and `-f FUNCTION', which calls FUNCTION with no arguments. Any Lisp program output that would normally go to the echo area, either using `message' or using `prin1', etc., with `t' as the stream, goes instead to XEmacs's standard error descriptor when in batch mode. Thus, XEmacs behaves much like a noninteractive application program. (The echo area output that XEmacs itself normally generates, such as command echoing, is suppressed entirely.) - Function: noninteractive This function returns non-`nil' when XEmacs is running in batch mode. - Variable: noninteractive This variable is non-`nil' when XEmacs is running in batch mode. Setting this variable to `nil', however, will not change whether XEmacs is running in batch mode, and will not change the return value of the `noninteractive' function.  File: lispref.info, Node: X-Windows, Next: ToolTalk Support, Prev: System Interface, Up: Top Functions Specific to the X Window System ***************************************** XEmacs provides the concept of "devices", which generalizes connections to an X server, a TTY device, etc. Most information about an X server that XEmacs is connected to can be determined through general console and device functions. *Note Consoles and Devices::. However, there are some features of the X Window System that do not generalize well, and they are covered specially here. * Menu: * X Selections:: Transferring text to and from other X clients. * X Server:: Information about the X server connected to a particular device. * X Miscellaneous:: Other X-specific functions and variables.  File: lispref.info, Node: X Selections, Next: X Server, Up: X-Windows X Selections ============ The X server records a set of "selections" which permit transfer of data between application programs. The various selections are distinguished by "selection types", represented in XEmacs by symbols. X clients including XEmacs can read or set the selection for any given type. - Function: x-own-selection data &optional type This function sets a "selection" in the X server. It takes two arguments: a value, DATA, and the selection type TYPE to assign it to. DATA may be a string, a cons of two markers, or an extent. In the latter cases, the selection is considered to be the text between the markers, or between the extent's endpoints. Each possible TYPE has its own selection value, which changes independently. The usual values of TYPE are `PRIMARY' and `SECONDARY'; these are symbols with upper-case names, in accord with X Windows conventions. The default is `PRIMARY'. (In FSF Emacs, this function is called `x-set-selection' and takes different arguments.) - Function: x-get-selection This function accesses selections set up by XEmacs or by other X clients. It returns the value of the current primary selection. - Function: x-disown-selection &optional secondary-p Assuming we own the selection, this function disowns it. If SECONDARY-P is non-`nil', the secondary selection instead of the primary selection is discarded. The X server also has a set of numbered "cut buffers" which can store text or other data being moved between applications. Cut buffers are considered obsolete, but XEmacs supports them for the sake of X clients that still use them. - Function: x-get-cutbuffer &optional n This function returns the contents of cut buffer number N. (This function is called `x-get-cut-buffer' in FSF Emacs.) - Function: x-store-cutbuffer string &optional push This function stores STRING into the first cut buffer (cut buffer 0). Normally, the contents of the first cut buffer are simply replaced by STRING. However, if optional argument PUSH is non-`nil', the cut buffers are rotated. This means that the previous value of the first cut buffer moves to the second cut buffer, and the second to the third, and so on, moving the other values down through the series of cut buffers, kill-ring-style. There are 8 cut buffers altogether. Cut buffers are considered obsolete; you should use selections instead. This function has no effect if support for cut buffers was not compiled in. This function is called `x-set-cut-buffer' in FSF Emacs.  File: lispref.info, Node: X Server, Next: X Miscellaneous, Prev: X Selections, Up: X-Windows X Server ======== This section describes how to access and change the overall status of the X server XEmacs is using. * Menu: * Resources:: Getting resource values from the server. * Server Data:: Getting info about the X server. * Grabs:: Restricting access to the server by other apps.  File: lispref.info, Node: Resources, Next: Server Data, Up: X Server Resources --------- - Function: default-x-device This function return the default X device for resourcing. This is the first-created X device that still exists. - Function: x-get-resource name class type &optional locale device noerror This function retrieves a resource value from the X resource manager. * The first arg is the name of the resource to retrieve, such as `"font"'. * The second arg is the class of the resource to retrieve, like `"Font"'. * The third arg should be one of the symbols `string', `integer', `natnum', or `boolean', specifying the type of object that the database is searched for. * The fourth arg is the locale to search for the resources on, and can currently be a buffer, a frame, a device, or the symbol `global'. If omitted, it defaults to `global'. * The fifth arg is the device to search for the resources on. (The resource database for a particular device is constructed by combining non-device- specific resources such any command-line resources specified and any app-defaults files found [or the fallback resources supplied by XEmacs, if no app-defaults file is found] with device-specific resources such as those supplied using `xrdb'.) If omitted, it defaults to the device of LOCALE, if a device can be derived (i.e. if LOCALE is a frame or device), and otherwise defaults to the value of `default-x-device'. * The sixth arg NOERROR, if non-`nil', means do not signal an error if a bogus resource specification was retrieved (e.g. if a non-integer was given when an integer was requested). In this case, a warning is issued instead. The resource names passed to this function are looked up relative to the locale. If you want to search for a subresource, you just need to specify the resource levels in NAME and CLASS. For example, NAME could be `"modeline.attributeFont"', and CLASS `"Face.AttributeFont"'. Specifically, 1. If LOCALE is a buffer, a call `(x-get-resource "foreground" "Foreground" 'string SOME-BUFFER)' is an interface to a C call something like `XrmGetResource (db, "xemacs.buffer.BUFFER-NAME.foreground", "Emacs.EmacsLocaleType.EmacsBuffer.Foreground", "String");' 2. If LOCALE is a frame, a call `(x-get-resource "foreground" "Foreground" 'string SOME-FRAME)' is an interface to a C call something like `XrmGetResource (db, "xemacs.frame.FRAME-NAME.foreground", "Emacs.EmacsLocaleType.EmacsFrame.Foreground", "String");' 3. If LOCALE is a device, a call `(x-get-resource "foreground" "Foreground" 'string SOME-DEVICE)' is an interface to a C call something like `XrmGetResource (db, "xemacs.device.DEVICE-NAME.foreground", "Emacs.EmacsLocaleType.EmacsDevice.Foreground", "String");' 4. If LOCALE is the symbol `global', a call `(x-get-resource "foreground" "Foreground" 'string 'global)' is an interface to a C call something like `XrmGetResource (db, "xemacs.foreground", "Emacs.Foreground", "String");' Note that for `global', no prefix is added other than that of the application itself; thus, you can use this locale to retrieve arbitrary application resources, if you really want to. The returned value of this function is `nil' if the queried resource is not found. If TYPE is `string', a string is returned, and if it is `integer', an integer is returned. If TYPE is `boolean', then the returned value is the list `(t)' for true, `(nil)' for false, and is `nil' to mean "unspecified". - Function: x-put-resource resource-line &optional device This function adds a resource to the resource database for DEVICE. RESOURCE-LINE specifies the resource to add and should be a standard resource specification. - Variable: x-emacs-application-class This variable holds The X application class of the XEmacs process. This controls, among other things, the name of the "app-defaults" file that XEmacs will use. For changes to this variable to take effect, they must be made before the connection to the X server is initialized, that is, this variable may only be changed before XEmacs is dumped, or by setting it in the file `lisp/term/x-win.el'. By default, this variable is `nil' at startup. When the connection to the X server is first initialized, the X resource database will be consulted and the value will be set according to whether any resources are found for the application class "XEmacs".  File: lispref.info, Node: Server Data, Next: Grabs, Prev: Resources, Up: X Server Data about the X Server ----------------------- This section describes functions and a variable that you can use to get information about the capabilities and origin of the X server corresponding to a particular device. The device argument is generally optional and defaults to the selected device. - Function: x-server-version &optional device This function returns the list of version numbers of the X server DEVICE is on. The returned value is a list of three integers: the major and minor version numbers of the X protocol in use, and the vendor-specific release number. - Function: x-server-vendor &optional device This function returns the vendor supporting the X server DEVICE is on. - Function: x-display-visual-class &optional device This function returns the visual class of the display DEVICE is on. The value is one of the symbols `static-gray', `gray-scale', `static-color', `pseudo-color', `true-color', and `direct-color'. (Note that this is different from previous versions of XEmacs, which returned `StaticGray', `GrayScale', etc.)  File: lispref.info, Node: Grabs, Prev: Server Data, Up: X Server Restricting Access to the Server by Other Apps ---------------------------------------------- - Function: x-grab-keyboard &optional device This function grabs the keyboard on the given device (defaulting to the selected one). So long as the keyboard is grabbed, all keyboard events will be delivered to XEmacs--it is not possible for other X clients to eavesdrop on them. Ungrab the keyboard with `x-ungrab-keyboard' (use an `unwind-protect'). Returns `t' if the grab was successful; `nil' otherwise. - Function: x-ungrab-keyboard &optional device This function releases a keyboard grab made with `x-grab-keyboard'. - Function: x-grab-pointer &optional device cursor ignore-keyboard This function grabs the pointer and restricts it to its current window. If optional DEVICE argument is `nil', the selected device will be used. If optional CURSOR argument is non-`nil', change the pointer shape to that until `x-ungrab-pointer' is called (it should be an object returned by the `make-cursor' function). If the second optional argument IGNORE-KEYBOARD is non-`nil', ignore all keyboard events during the grab. Returns `t' if the grab is successful, `nil' otherwise. - Function: x-ungrab-pointer &optional device This function releases a pointer grab made with `x-grab-pointer'. If optional first arg DEVICE is `nil' the selected device is used. If it is `t' the pointer will be released on all X devices.  File: lispref.info, Node: X Miscellaneous, Prev: X Server, Up: X-Windows Miscellaneous X Functions and Variables ======================================= - Variable: x-bitmap-file-path This variable holds a list of the directories in which X bitmap files may be found. If `nil', this is initialized from the `"*bitmapFilePath"' resource. This is used by the `make-image-instance' function (however, note that if the environment variable `XBMLANGPATH' is set, it is consulted first). - Variable: x-library-search-path This variable holds the search path used by `read-color' to find `rgb.txt'. - Function: x-valid-keysym-name-p keysym This function returns true if KEYSYM names a keysym that the X library knows about. Valid keysyms are listed in the files `/usr/include/X11/keysymdef.h' and in `/usr/lib/X11/XKeysymDB', or whatever the equivalents are on your system. - Function: x-window-id &optional frame This function returns the ID of the X11 window. This gives us a chance to manipulate the Emacs window from within a different program. Since the ID is an unsigned long, we return it as a string. - Variable: x-allow-sendevents If non-`nil', synthetic events are allowed. `nil' means they are ignored. Beware: allowing XEmacs to process SendEvents opens a big security hole. - Function: x-debug-mode arg &optional device With a true arg, make the connection to the X server synchronous. With false, make it asynchronous. Synchronous connections are much slower, but are useful for debugging. (If you get X errors, make the connection synchronous, and use a debugger to set a breakpoint on `x_error_handler'. Your backtrace of the C stack will now be useful. In asynchronous mode, the stack above `x_error_handler' isn't helpful because of buffering.) If DEVICE is not specified, the selected device is assumed. Calling this function is the same as calling the C function `XSynchronize', or starting the program with the `-sync' command line argument. - Variable: x-debug-events If non-zero, debug information about events that XEmacs sees is displayed. Information is displayed on stderr. Currently defined values are: * 1 == non-verbose output * 2 == verbose output  File: lispref.info, Node: ToolTalk Support, Next: LDAP Support, Prev: X-Windows, Up: Top ToolTalk Support **************** * Menu: * XEmacs ToolTalk API Summary:: * Sending Messages:: * Receiving Messages::  File: lispref.info, Node: XEmacs ToolTalk API Summary, Next: Sending Messages, Up: ToolTalk Support XEmacs ToolTalk API Summary =========================== The XEmacs Lisp interface to ToolTalk is similar, at least in spirit, to the standard C ToolTalk API. Only the message and pattern parts of the API are supported at present; more of the API could be added if needed. The Lisp interface departs from the C API in a few ways: * ToolTalk is initialized automatically at XEmacs startup-time. Messages can only be sent other ToolTalk applications connected to the same X11 server that XEmacs is running on. * There are fewer entry points; polymorphic functions with keyword arguments are used instead. * The callback interface is simpler and marginally less functional. A single callback may be associated with a message or a pattern; the callback is specified with a Lisp symbol (the symbol should have a function binding). * The session attribute for messages and patterns is always initialized to the default session. * Anywhere a ToolTalk enum constant, e.g. `TT_SESSION', is valid, one can substitute the corresponding symbol, e.g. `'TT_SESSION'. This simplifies building lists that represent messages and patterns.  File: lispref.info, Node: Sending Messages, Next: Receiving Messages, Prev: XEmacs ToolTalk API Summary, Up: ToolTalk Support Sending Messages ================ * Menu: * Example of Sending Messages:: * Elisp Interface for Sending Messages::  File: lispref.info, Node: Example of Sending Messages, Next: Elisp Interface for Sending Messages, Up: Sending Messages Example of Sending Messages --------------------------- Here's a simple example that sends a query to another application and then displays its reply. Both the query and the reply are stored in the first argument of the message. (defun tooltalk-random-query-handler (msg) (let ((state (get-tooltalk-message-attribute msg 'state))) (cond ((eq state 'TT_HANDLED) (message (get-tooltalk-message-attribute msg arg_val 0))) ((memq state '(TT_FAILED TT_REJECTED)) (message "Random query turns up nothing"))))) (defvar random-query-message '( class TT_REQUEST scope TT_SESSION address TT_PROCEDURE op "random-query" args '((TT_INOUT "?" "string")) callback tooltalk-random-query-handler)) (let ((m (make-tooltalk-message random-query-message))) (send-tooltalk-message m))  File: lispref.info, Node: Elisp Interface for Sending Messages, Prev: Example of Sending Messages, Up: Sending Messages Elisp Interface for Sending Messages ------------------------------------ - Function: make-tooltalk-message attributes Create a ToolTalk message and initialize its attributes. The value of ATTRIBUTES must be a list of alternating keyword/values, where keywords are symbols that name valid message attributes. For example: (make-tooltalk-message '(class TT_NOTICE scope TT_SESSION address TT_PROCEDURE op "do-something" args ("arg1" 12345 (TT_INOUT "arg3" "string")))) Values must always be strings, integers, or symbols that represent ToolTalk constants. Attribute names are the same as those supported by `set-tooltalk-message-attribute', plus `args'. The value of `args' should be a list of message arguments where each message argument has the following form: `(mode [value [type]])' or just `value' Where MODE is one of `TT_IN', `TT_OUT', or `TT_INOUT' and TYPE is a string. If TYPE isn't specified then `int' is used if VALUE is a number; otherwise `string' is used. If TYPE is `string' then VALUE is converted to a string (if it isn't a string already) with `prin1-to-string'. If only a value is specified then MODE defaults to `TT_IN'. If MODE is `TT_OUT' then VALUE and TYPE don't need to be specified. You can find out more about the semantics and uses of ToolTalk message arguments in chapter 4 of the `ToolTalk Programmer's Guide'. - Function: send-tooltalk-message msg Send the message on its way. Once the message has been sent it's almost always a good idea to get rid of it with `destroy-tooltalk-message'. - Function: return-tooltalk-message msg &optional mode Send a reply to this message. The second argument can be `reply', `reject' or `fail'; the default is `reply'. Before sending a reply, all message arguments whose mode is `TT_INOUT' or `TT_OUT' should have been filled in--see `set-tooltalk-message-attribute'. - Function: get-tooltalk-message-attribute msg attribute &optional argn Returns the indicated ToolTalk message attribute. Attributes are identified by symbols with the same name (underscores and all) as the suffix of the ToolTalk `tt_message_' function that extracts the value. String attribute values are copied and enumerated type values (except disposition) are converted to symbols; e.g. `TT_HANDLER' is `'TT_HANDLER', `uid' and `gid' are represented by fixnums (small integers), `opnum' is converted to a string, and `disposition' is converted to a fixnum. We convert `opnum' (a C int) to a string (e.g. `123' => `"123"') because there's no guarantee that opnums will fit within the range of XEmacs Lisp integers. [TBD] Use the `plist' attribute instead of C API `user' attribute for user-defined message data. To retrieve the value of a message property, specify the indicator for ARGN. For example, to get the value of a property called `rflag', use (get-tooltalk-message-attribute msg 'plist 'rflag) To get the value of a message argument use one of the `arg_val' (strings), `arg_ival' (integers), or `arg_bval' (strings with embedded nulls), attributes. For example, to get the integer value of the third argument: (get-tooltalk-message-attribute msg 'arg_ival 2) As you can see, argument numbers are zero-based. The type of each arguments can be retrieved with the `arg_type' attribute; however ToolTalk doesn't define any semantics for the string value of `arg_type'. Conventionally `string' is used for strings and `int' for 32 bit integers. Note that XEmacs Lisp stores the lengths of strings explicitly (unlike C) so treating the value returned by `arg_bval' like a string is fine. - Function: set-tooltalk-message-attribute value msg attribute &optional argn Initialize one ToolTalk message attribute. Attribute names and values are the same as for `get-tooltalk-message-attribute'. A property list is provided for user data (instead of the `user' message attribute); see `get-tooltalk-message-attribute'. Callbacks are handled slightly differently than in the C ToolTalk API. The value of CALLBACK should be the name of a function of one argument. It will be called each time the state of the message changes. This is usually used to notice when the message's state has changed to `TT_HANDLED' (or `TT_FAILED'), so that reply argument values can be used. If one of the argument attributes is specified as `arg_val', `arg_ival', or `arg_bval', then ARGN must be the number of an already created argument. Arguments can be added to a message with `add-tooltalk-message-arg'. - Function: add-tooltalk-message-arg msg mode type &optional value Append one new argument to the message. MODE must be one of `TT_IN', `TT_INOUT', or `TT_OUT', TYPE must be a string, and VALUE can be a string or an integer. ToolTalk doesn't define any semantics for TYPE, so only the participants in the protocol you're using need to agree what types mean (if anything). Conventionally `string' is used for strings and `int' for 32 bit integers. Arguments can initialized by providing a value or with `set-tooltalk-message-attribute'; the latter is necessary if you want to initialize the argument with a string that can contain embedded nulls (use `arg_bval'). - Function: create-tooltalk-message &optional no-callback Create a new ToolTalk message. The message's session attribute is initialized to the default session. Other attributes can be initialized with `set-tooltalk-message-attribute'. `make-tooltalk-message' is the preferred way to create and initialize a message. Optional arg NO-CALLBACK says don't add a C-level callback at all. Normally don't do that; just don't specify the Lisp callback when calling `make-tooltalk-message'. - Function: destroy-tooltalk-message msg Apply `tt_message_destroy' to the message. It's not necessary to destroy messages after they've been processed by a message or pattern callback, the Lisp/ToolTalk callback machinery does this for you.  File: lispref.info, Node: Receiving Messages, Prev: Sending Messages, Up: ToolTalk Support Receiving Messages ================== * Menu: * Example of Receiving Messages:: * Elisp Interface for Receiving Messages::  File: lispref.info, Node: Example of Receiving Messages, Next: Elisp Interface for Receiving Messages, Up: Receiving Messages Example of Receiving Messages ----------------------------- Here's a simple example of a handler for a message that tells XEmacs to display a string in the mini-buffer area. The message operation is called `emacs-display-string'. Its first (0th) argument is the string to display. (defun tooltalk-display-string-handler (msg) (message (get-tooltalk-message-attribute msg 'arg_val 0))) (defvar display-string-pattern '(category TT_HANDLE scope TT_SESSION op "emacs-display-string" callback tooltalk-display-string-handler)) (let ((p (make-tooltalk-pattern display-string-pattern))) (register-tooltalk-pattern p))  File: lispref.info, Node: Elisp Interface for Receiving Messages, Prev: Example of Receiving Messages, Up: Receiving Messages Elisp Interface for Receiving Messages -------------------------------------- - Function: make-tooltalk-pattern attributes Create a ToolTalk pattern and initialize its attributes. The value of attributes must be a list of alternating keyword/values, where keywords are symbols that name valid pattern attributes or lists of valid attributes. For example: (make-tooltalk-pattern '(category TT_OBSERVE scope TT_SESSION op ("operation1" "operation2") args ("arg1" 12345 (TT_INOUT "arg3" "string")))) Attribute names are the same as those supported by `add-tooltalk-pattern-attribute', plus `'args'. Values must always be strings, integers, or symbols that represent ToolTalk constants or lists of same. When a list of values is provided all of the list elements are added to the attribute. In the example above, messages whose `op' attribute is `"operation1"' or `"operation2"' would match the pattern. The value of ARGS should be a list of pattern arguments where each pattern argument has the following form: `(mode [value [type]])' or just `value' Where MODE is one of `TT_IN', `TT_OUT', or `TT_INOUT' and TYPE is a string. If TYPE isn't specified then `int' is used if VALUE is a number; otherwise `string' is used. If TYPE is `string' then VALUE is converted to a string (if it isn't a string already) with `prin1-to-string'. If only a value is specified then MODE defaults to `TT_IN'. If MODE is `TT_OUT' then VALUE and TYPE don't need to be specified. You can find out more about the semantics and uses of ToolTalk pattern arguments in chapter 3 of the `ToolTalk Programmer's Guide'. - Function: register-tooltalk-pattern pattern XEmacs will begin receiving messages that match this pattern. - Function: unregister-tooltalk-pattern pattern XEmacs will stop receiving messages that match this pattern. - Function: add-tooltalk-pattern-attribute value pattern indicator Add one value to the indicated pattern attribute. The names of attributes are the same as the ToolTalk accessors used to set them less the `tooltalk_pattern_' prefix and the `_add' suffix. For example, the name of the attribute for the `tt_pattern_disposition_add' attribute is `disposition'. The `category' attribute is handled specially, since a pattern can only be a member of one category (`TT_OBSERVE' or `TT_HANDLE'). Callbacks are handled slightly differently than in the C ToolTalk API. The value of CALLBACK should be the name of a function of one argument. It will be called each time the pattern matches an incoming message. - Function: add-tooltalk-pattern-arg pattern mode vtype &optional value Add one fully-specified argument to a ToolTalk pattern. MODE must be one of `TT_IN', `TT_INOUT', or `TT_OUT'. VTYPE must be a string. VALUE can be an integer, string or `nil'. If VALUE is an integer then an integer argument (`tt_pattern_iarg_add') is added; otherwise a string argument is added. At present there's no way to add a binary data argument. - Function: create-tooltalk-pattern Create a new ToolTalk pattern and initialize its session attribute to be the default session. - Function: destroy-tooltalk-pattern pattern Apply `tt_pattern_destroy' to the pattern. This effectively unregisters the pattern. - Function: describe-tooltalk-message msg &optional stream Print the message's attributes and arguments to STREAM. This is often useful for debugging.  File: lispref.info, Node: LDAP Support, Next: PostgreSQL Support, Prev: ToolTalk Support, Up: Top LDAP Support ************ XEmacs can be linked with a LDAP client library to provide Elisp primitives to access directory servers using the Lightweight Directory Access Protocol. * Menu: * Building XEmacs with LDAP support:: How to add LDAP support to XEmacs * XEmacs LDAP API:: Lisp access to LDAP functions * Syntax of Search Filters:: A brief summary of RFC 1558  File: lispref.info, Node: Building XEmacs with LDAP support, Next: XEmacs LDAP API, Prev: LDAP Support, Up: LDAP Support Building XEmacs with LDAP support ================================= LDAP support must be added to XEmacs at build time since it requires linking to an external LDAP client library. As of 21.2, XEmacs has been successfully built and tested with * OpenLDAP 1.2 () * University of Michigan's LDAP 3.3 () * LDAP SDK 1.0 from Netscape Corp. () Other libraries conforming to RFC 1823 will probably work also but may require some minor tweaking at C level. The standard XEmacs configure script auto-detects an installed LDAP library provided the library itself and the corresponding header files can be found in the library and include paths. A successful detection will be signalled in the final output of the configure script.  File: lispref.info, Node: XEmacs LDAP API, Next: Syntax of Search Filters, Prev: Building XEmacs with LDAP support, Up: LDAP Support XEmacs LDAP API =============== XEmacs LDAP API consists of two layers: a low-level layer which tries to stay as close as possible to the C API (where practical) and a higher-level layer which provides more convenient primitives to effectively use LDAP. The low-level API should be used directly for very specific purposes (such as multiple operations on a connection) only. The higher-level functions provide a more convenient way to access LDAP directories hiding the subtleties of handling the connection, translating arguments and ensuring compliance with LDAP internationalization rules and formats (currently partly implemented only). * Menu: * LDAP Variables:: Lisp variables related to LDAP * The High-Level LDAP API:: High-level LDAP lisp functions * The Low-Level LDAP API:: Low-level LDAP lisp primitives * LDAP Internationalization:: I18n variables and functions  File: lispref.info, Node: LDAP Variables, Next: The High-Level LDAP API, Prev: XEmacs LDAP API, Up: XEmacs LDAP API LDAP Variables -------------- - Variable: ldap-default-host The default LDAP server hostname. A TCP port number can be appended to that name using a colon as a separator. - Variable: ldap-default-port Default TCP port for LDAP connections. Initialized from the LDAP library. Default value is 389. - Variable: ldap-default-base Default base for LDAP searches. This is a string using the syntax of RFC 1779. For instance, "o=ACME, c=US" limits the search to the Acme organization in the United States. - Variable: ldap-host-parameters-alist An alist of per host options for LDAP transactions. The list elements look like `(HOST PROP1 VAL1 PROP2 VAL2 ...)' HOST is the name of an LDAP server. A TCP port number can be appended to that name using a colon as a separator. PROPN and VALN are property/value pairs describing parameters for the server. Valid properties: `binddn' The distinguished name of the user to bind as. This may look like `cn=Babs Jensen,o=ACME,c=US', see RFC 1779 for details. `passwd' The password to use for authentication. `auth' The authentication method to use, possible values depend on the LDAP library XEmacs was compiled with, they may include `simple', `krbv41' and `krbv42'. `base' The base for the search. This may look like `cÿ, o¬me', see RFC 1779 for syntax details. `scope' One of the symbols `base', `onelevel' or `subtree' indicating the scope of the search limited to a base object, to a single level or to the whole subtree. `deref' The dereference policy is one of the symbols `never', `always', `search' or `find' and defines how aliases are dereferenced. `never' Aliases are never dereferenced `always' Aliases are always dereferenced `search' Aliases are dereferenced when searching `find' Aliases are dereferenced when locating the base object for the search `timelimit' The timeout limit for the connection in seconds. `sizelimit' The maximum number of matches to return for searches performed on this connection. - Variable: ldap-verbose If non-`nil', LDAP operations will echo progress messages. Defaults to `nil'.  File: lispref.info, Node: The High-Level LDAP API, Next: The Low-Level LDAP API, Prev: LDAP Variables, Up: XEmacs LDAP API The High-Level LDAP API ----------------------- The following functions provide the most convenient interface to perform LDAP operations. All of them open a connection to a host, perform an operation (add/search/modify/delete) on one or several entries and cleanly close the connection thus insulating the user from all the details of the low-level interface such as LDAP Lisp objects *note The Low-Level LDAP API::. Note that `ldap-search' which used to be the name of the high-level search function in XEmacs 21.1 is now obsolete. For consistency in the naming as well as backward compatibility, that function now acts as a wrapper that calls either `ldap-search-basic' (low-level search function) or `ldap-search-entries' (high-level search function) according to the actual parameters. A direct call to one of these two functions is preferred since it is faster and unambiguous. - Command: ldap-search-entries filter &optional host attributes attrsonly withdn Perform an LDAP search. FILTER is the search filter *note Syntax of Search Filters:: HOST is the LDAP host on which to perform the search. ATTRIBUTES is the specific attributes to retrieve, `nil' means retrieve all. ATTRSONLY if non-`nil' retrieves the attributes only without their associated values. If WITHDN is non-`nil' each entry in the result will be prepended with its distinguished name DN. Additional search parameters can be specified through `ldap-host-parameters-alist'. The function returns a list of matching entries. Each entry is itself an alist of attribute/value pairs optionally preceded by the DN of the entry according to the value of WITHDN. - Function: ldap-add-entries entries &optional host binddn passwd Add entries to an LDAP directory. ENTRIES is a list of entry specifications of the form `(DN (ATTR . VALUE) (ATTR . VALUE) ...)' where DN the distinguished name of an entry to add, the following are cons cells containing attribute/value string pairs. HOST is the LDAP host, defaulting to `ldap-default-host'. BINDDN is the DN to bind as to the server. PASSWD is the corresponding password. - Function: ldap-modify-entries entry-mods &optional host binddn passwd Modify entries of an LDAP directory. ENTRY_MODS is a list of entry modifications of the form `(DN MOD-SPEC1 MOD-SPEC2 ...)' where DN is the distinguished name of the entry to modify, the following are modification specifications. A modification specification is itself a list of the form `(MOD-OP ATTR VALUE1 VALUE2 ...)' MOD-OP and ATTR are mandatory, VALUES are optional depending on MOD-OP. MOD-OP is the type of modification, one of the symbols `add', `delete' or `replace'. ATTR is the LDAP attribute type to modify. HOST is the LDAP host, defaulting to `ldap-default-host'. BINDDN is the DN to bind as to the server. PASSWD is the corresponding password. - Function: ldap-delete-entries dn &optional host binddn passwd Delete an entry from an LDAP directory. DN is the distinguished name of an entry to delete or a list of those. HOST is the LDAP host, defaulting to `ldap-default-host'. BINDDN is the DN to bind as to the server. PASSWD is the corresponding password.  File: lispref.info, Node: The Low-Level LDAP API, Next: LDAP Internationalization, Prev: The High-Level LDAP API, Up: XEmacs LDAP API The Low-Level LDAP API ---------------------- The low-level API should be used directly for very specific purposes (such as multiple operations on a connection) only. The higher-level functions provide a more convenient way to access LDAP directories hiding the subtleties of handling the connection, translating arguments and ensuring compliance with LDAP internationalization rules and formats (currently partly implemented only). See *note The High-Level LDAP API:: Note that the former functions `ldap-*-internal' functions have been renamed in XEmacs 21.2 * Menu: * The LDAP Lisp Object:: * Opening and Closing a LDAP Connection:: * Low-level Operations on a LDAP Server::