Foundation instead of in the original English.
\1f
-File: lispref.info, Node: Beeping, Prev: Display Tables, Up: Display
+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.
-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.
+\1f
+File: lispref.info, Node: Annotation Primitives, Next: Annotation Properties, Prev: Annotation Basics, Up: Annotations
- 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:
+Annotation Primitives
+=====================
- `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.
+ - 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.
- `volume'
- An integer from 0-100, defaulting to `bell-volume'.
+ 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.
- `pitch'
- If using the default X beep, the pitch (Hz) to generate.
+ The newly created annotation is returned.
- `duration'
- If using the default X beep, the duration (milliseconds).
+ - Function: delete-annotation annotation
+ This function removes ANNOTATION from its buffer. This does not
+ modify the buffer text.
- For compatibility, elements of `sound-alist' may also be:
+ - Function: annotationp annotation
+ This function returns `t' if ANNOTATION is an annotation, `nil'
+ otherwise.
- * `( sound-name . <sound> )'
+\1f
+File: lispref.info, Node: Annotation Properties, Next: Margin Primitives, Prev: Annotation Primitives, Up: Annotations
- * `( sound-name <volume> <sound> )'
+Annotation Properties
+=====================
- You should probably add things to this list by calling the function
- `load-sound-file'.
+ - Function: annotation-glyph annotation
+ This function returns the glyph object used to display ANNOTATION.
- Caveats:
+ - 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.
- - You can only play audio data if running on the console screen
- of a Sun SparcStation, SGI, or HP9000s700.
+ - Function: annotation-down-glyph annotation
+ This function returns the glyph used to display ANNOTATION when
+ the left mouse button is depressed on the annotation.
- - The pitch, duration, and volume options are available
- everywhere, but many X servers ignore the `pitch' option.
+ - 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.
- The following beep-types are used by XEmacs itself:
+ - Function: annotation-face annotation
+ This function returns the face associated with ANNOTATION.
- `auto-save-error'
- when an auto-save does not succeed
+ - Function: set-annotation-face annotation face
+ This function sets the face associated with ANNOTATION to FACE.
- `command-error'
- when the XEmacs command loop catches an error
+ - Function: annotation-layout annotation
+ This function returns the layout policy of ANNOTATION.
- `undefined-key'
- when you type a key that is undefined
+ - Function: set-annotation-layout annotation layout
+ This function sets the layout policy of ANNOTATION to LAYOUT.
- `undefined-click'
- when you use an undefined mouse-click combination
+ - 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'.
- `no-completion'
- during completing-read
+ - Function: annotation-data annotation
+ This function returns the data associated with ANNOTATION.
- `y-or-n-p'
- when you type something other than 'y' or 'n'
+ - Function: set-annotation-data annotation data
+ This function sets the data field of ANNOTATION to DATA. DATA is
+ returned.
- `yes-or-no-p'
- when you type something other than 'yes' or 'no'
+ - Function: annotation-action annotation
+ This function returns the action associated with ANNOTATION.
- `default'
- used when nothing else is appropriate.
+ - Function: set-annotation-action annotation action
+ This function sets the action field of ANNOTATION to ACTION.
+ ACTION is returned..
- Other lisp packages may use other beep types, but these are the
- ones that the C kernel of XEmacs uses.
+ - Function: annotation-menu annotation
+ This function returns the menu associated with ANNOTATION.
- - User Option: bell-volume
- This variable specifies the default volume for sounds, from 0 to
- 100.
+ - 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.
- - Command: load-default-sounds
- This function loads and installs some sound files as beep-types.
+ - Function: annotation-visible annotation
+ This function returns `t' if there is enough available space to
+ display ANNOTATION, `nil' otherwise.
- - 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: annotation-width annotation
+ This function returns the width of ANNOTATION in pixels.
- - 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.
+ - Function: hide-annotation annotation
+ This function removes ANNOTATION's glyph, making it invisible.
- - 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.
+ - Function: reveal-annotation annotation
+ This function restores ANNOTATION's glyph, making it visible.
\1f
-File: lispref.info, Node: Hash Tables, Next: Range Tables, Prev: Display, Up: Top
+File: lispref.info, Node: Locating Annotations, Next: Annotation Hooks, Prev: Margin Primitives, Up: Annotations
-Hash Tables
-***********
+Locating Annotations
+====================
- - Function: hash-table-p object
- This function returns `t' if OBJECT is a hash table, else `nil'.
+ - Function: annotations-in-region start end buffer
+ This function returns a list of all annotations in BUFFER which
+ are between START and END inclusively.
-* Menu:
+ - 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.
-* 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.
+ - Function: annotation-list &optional buffer
+ This function returns a list of all annotations in BUFFER. If
+ BUFFER is `nil', the current buffer is used.
-\1f
-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.
-
- Keyword `:weakness' can be `nil' (default), `t', `key' or `value'.
-
- 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.
-
- - 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'.
+ - Function: all-annotations
+ This function returns a list of all annotations in all buffers in
+ existence.
\1f
-File: lispref.info, Node: Working With Hash Tables, Next: Weak Hash Tables, Prev: Introduction to Hash Tables, Up: Hash Tables
-
-Working With Hash Tables
-========================
-
- - 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: 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.
\1f
-File: lispref.info, Node: Weak Hash Tables, Prev: Working With Hash Tables, Up: Hash Tables
+File: lispref.info, Node: Annotation Hooks, Prev: Locating Annotations, Up: Annotations
-Weak Hash Tables
+Annotation Hooks
================
- 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 three types of weak hash tables:
+ The following three hooks are provided for use with the marginal
+annotations:
-fully weak hash tables
- In these hash tables, a pair disappears if either the key or the
- value is unreferenced outside of the table.
+`before-delete-annotation-hook'
+ This hook is called immediately before an annotation is destroyed.
+ It is passed a single argument, the annotation being destroyed.
-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.
+`after-delete-annotation-hook'
+ This normal hook is called immediately after an annotation is
+ destroyed.
-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.
-
- Also see *Note Weak Lists::.
-
- Weak hash tables are created by specifying the `:weakness' keyword to
-`make-hash-table'.
+`make-annotation-hook'
+ This hook is called immediately after an annotation is created.
+ It is passed a single argument, the newly created annotation.
\1f
-File: lispref.info, Node: Range Tables, Next: Databases, Prev: Hash Tables, Up: Top
-
-Range Tables
-************
+File: lispref.info, Node: Display, Next: Hash Tables, Prev: Annotations, Up: Top
- A range table is a table that efficiently associated values with
-ranges of integers.
+Emacs Display
+*************
- 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.
+ This chapter describes a number of other features related to the
+display that XEmacs presents to the user.
* Menu:
-* Introduction to Range Tables:: Range tables efficiently map ranges of
- integers to values.
-* Working With Range Tables:: Range table functions.
+* Refresh Screen:: Clearing the screen and redrawing everything on it.
+* Truncation:: Folding or wrapping long text lines.
+* The Echo Area:: Where messages are displayed.
+* Warnings:: Display of Warnings.
+* Invisible Text:: Hiding part of the buffer text.
+* Selective Display:: Hiding part of the buffer text (the old way).
+* Overlay Arrow:: Display of an arrow to indicate position.
+* Temporary Displays:: Displays that go away automatically.
+* Blinking:: How XEmacs shows the matching open parenthesis.
+* Usual Display:: The usual conventions for displaying nonprinting chars.
+* Display Tables:: How to specify other conventions.
+* Beeping:: Audible signal to the user.
\1f
-File: lispref.info, Node: 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 old-table
- Make a new range table which contains the same values for the same
- ranges as the given table. The values will not themselves be
- copied.
+File: lispref.info, Node: Refresh Screen, Next: Truncation, Up: Display
-\1f
-File: lispref.info, Node: Working With Range Tables, Prev: Introduction to Range Tables, Up: Range Tables
+Refreshing the Screen
+=====================
-Working With Range Tables
-=========================
+ The function `redraw-frame' redisplays the entire contents of a
+given frame. *Note Frames::.
- - Function: get-range-table pos table &optional default
- This function finds value for position POS in TABLE. If there is
- no corresponding value, return DEFAULT (defaults to `nil').
+ - Function: redraw-frame &optional frame no-preempt
+ This function clears and redisplays frame FRAME.
- - Function: put-range-table start end val table
- This function sets the value for range (START, END) to be VAL in
- TABLE.
+ FRAME defaults to the selected frame if omitted.
- - Function: remove-range-table start end table
- This function removes the value for range (START, END) in TABLE.
+ 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.
- - Function: clear-range-table table
- This function flushes TABLE.
+ Even more powerful is `redraw-display':
- - Function: map-range-table function table
- This function maps FUNCTION over entries in TABLE, calling it with
- three args, the beginning and end of the range and the
- corresponding value.
+ - 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.
-\1f
-File: lispref.info, Node: Databases, Next: Processes, Prev: Range Tables, Up: Top
+ 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.
-Databases
-*********
+ 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::.
- - Function: databasep object
- This function returns non-`nil' if OBJECT is a database.
+ - 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.
-* Menu:
+ 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::.
-* Connecting to a Database::
-* Working With a Database::
-* Other Database Functions::
+ - Function: force-cursor-redisplay &optional frame
+ This function causes an immediate update of the cursor on FRAME,
+ which defaults to the selected frame.
\1f
-File: lispref.info, Node: 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 by
- `nil'.
-
- For a TYPE of `'berkeley_db', the following subtypes are
- available: `'hash', `'btree', and `'recno'. See the manpages for
- the Berkeley DB functions to more information about these types.
-
- - Function: close-database obj
- This function closes database OBJ.
-
- - Function: database-live-p obj
- This function returns `t' iff OBJ is an active database, else
- `nil'.
+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::.
\1f
-File: lispref.info, Node: Working With a Database, Next: Other Database Functions, Prev: Connecting to a Database, Up: Databases
+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
+Reference Manual' specifies the rules for resolving conflicts between
+the echo area and the minibuffer for use of that screen space (*note
+The Minibuffer: (emacs)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 ----------
-Working With a Database
-=======================
+ 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:
- - Function: get-database key dbase &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).
+ * `message'--default label used by the `message' function;
- - Function: map-database function dbase
- This function maps FUNCTION over entries in DATABASE, calling it
- with two args, each key and value in the database.
+ * `error'--default label used for reporting errors;
- - Function: put-database key val dbase &optional replace
- This function stores KEY and VAL in DATABASE. If optional fourth
- arg REPLACE is non-`nil', replace any existing entry in the
- database.
+ * `progress'--progress indicators like `Converting... 45%' (not
+ logged by default);
- - Function: remove-database key dbase
- This function removes KEY from DATABASE.
+ * `prompt'--prompt-like messages like `Isearch: foo' (not logged by
+ default);
-\1f
-File: lispref.info, Node: Other Database Functions, Prev: Working With a Database, Up: Databases
+ * `command'--helper command messages like `Mark set' (not logged by
+ default);
-Other Database Functions
-========================
+ * `no-log'--messages that should never be logged
- - Function: database-file-name obj
- This function returns the filename associated with the database
- OBJ.
+ 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: database-last-error &optional obj
- This function returns the last error associated with database OBJ.
+ - Function: display-message label message &optional frame stdout-p
+ This function displays MESSAGE (a string) labeled as LABEL, as
+ described above.
- - Function: database-subtype obj
- This function returns the subtype of database OBJ, if any.
+ 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.
- - Function: database-type obj
- This function returns the type of database OBJ.
+ (display-message 'command "Mark set")
-\1f
-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.
+ - 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.
-* Menu:
-
-* Subprocess Creation:: Functions that start subprocesses.
-* Synchronous Processes:: Details of using synchronous subprocesses.
-* MS-DOS Subprocesses:: On MS-DOS, you must indicate text vs binary
- for data sent to and from a subprocess.
-* Asynchronous Processes:: Starting up an asynchronous subprocess.
-* Deleting Processes:: Eliminating an asynchronous subprocess.
-* Process Information:: Accessing run-status and other attributes.
-* Input to Processes:: Sending input to an asynchronous subprocess.
-* Signals to Processes:: Stopping, continuing or interrupting
- an asynchronous subprocess.
-* Output from Processes:: Collecting output from an asynchronous subprocess.
-* Sentinels:: Sentinels run when process run-status changes.
-* Process Window Size:: Changing the logical window size of a process.
-* Transaction Queues:: Transaction-based communication with subprocesses.
-* Network:: Opening network connections.
-
-\1f
-File: lispref.info, Node: Subprocess Creation, Next: Synchronous Processes, Up: Processes
-
-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 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.
-
- 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.
+ ;; Display a command message.
+ (lmessage 'command "Comment column set to %d" comment-column)
+
+ ;; Display a progress message.
+ (lmessage 'progress "Fontifying %s... (%d)" buffer percentage)
+
+ ;; Display a message that should not be logged.
+ (lmessage 'no-log "Done")
+
+ - Function: clear-message &optional label frame stdout-p no-restore
+ This function remove any message with the given LABEL from the
+ message-stack, erasing it from the echo area if it's currently
+ displayed there.
+
+ If a message remains at the head of the message-stack and
+ NO-RESTORE is `nil', it will be displayed. The string which
+ remains in the echo area will be returned, or `nil' if the
+ message-stack is now empty. If LABEL is `nil', the entire
+ message-stack is cleared.
+
+ ;; Show a message, wait for 2 seconds, and restore old minibuffer
+ ;; contents.
+ (message "A message")
+ -| A message
+ => "A Message"
+ (lmessage 'my-label "Newsflash! Newsflash!")
+ -| Newsflash! Newsflash!
+ => "Newsflash! Newsflash!"
+ (sit-for 2)
+ (clear-message 'my-label)
+ -| A message
+ => "A message"
+
+ Unless you need the return value or you need to specify a label,
+ you should just use `(message nil)'.
+
+ - Function: current-message &optional frame
+ This function returns the current message in the echo area, or
+ `nil'. The FRAME argument is currently unused.
+
+ Some of the messages displayed in the echo area are also recorded in
+the ` *Message-Log*' buffer. Exactly which messages will be recorded
+can be tuned using the following variables.
+
+ - User Option: log-message-max-size
+ This variable specifies the maximum size of the ` *Message-log*'
+ buffer.
+
+ - Variable: log-message-ignore-labels
+ This variable specifies the labels whose messages will not be
+ logged. It should be a list of symbols.
+
+ - Variable: log-message-ignore-regexps
+ This variable specifies the regular expressions matching messages
+ that will not be logged. It should be a list of regular
+ expressions.
+
+ Normally, packages that generate messages that might need to be
+ ignored should label them with `progress', `prompt', or `no-log',
+ so they can be filtered by `log-message-ignore-labels'.
+
+ - Variable: echo-keystrokes
+ This variable determines how much time should elapse before command
+ characters echo. Its value must be a number, which specifies the
+ number of seconds to wait before echoing. If the user types a
+ prefix key (such as `C-x') and then delays this many seconds
+ before continuing, the prefix key is echoed in the echo area. Any
+ subsequent characters in the same command will be echoed as well.
+
+ If the value is zero, then command input is not echoed.
+
+ - Variable: cursor-in-echo-area
+ This variable controls where the cursor appears when a message is
+ displayed in the echo area. If it is non-`nil', then the cursor
+ appears at the end of the message. Otherwise, the cursor appears
+ at point--not in the echo area at all.
+
+ The value is normally `nil'; Lisp programs bind it to `t' for
+ brief periods of time.
\1f
-File: lispref.info, Node: 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 ----------
+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
- (call-process "grep" nil "bar" nil "lewis" "/etc/passwd")
- => nil
+ Emacs*foo: bar
- ---------- Buffer: bar ----------
- lewis:5LTsHm66CSWKg:398:21:Bil Lewis:/user/lewis:/bin/csh
+ You should replace the * with a . in order to get proper behavior when
+ you use the specifier and/or `set-face-*' functions.")
- ---------- 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 delete
- destination display &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
- DELETE is non-`nil'; this is useful when BUFFER is `t', to insert
- the output in the current buffer.
-
- The arguments DESTINATION and DISPLAY 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 ----------
+ ---------- Warning buffer ----------
+ (1) (resource/warning) Bad resource specification encountered:
+ something like
- (call-process-region 1 6 "cat" nil t)
- => nil
+ Emacs*foo: bar
- ---------- 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.
+ You should replace the * with a . in order to get proper behavior when
+ you use the specifier and/or `set-face-*' functions.
+ ---------- Warning buffer ----------
+
+ - Function: lwarn class level message &rest args
+ This function displays a formatted labeled warning message. As
+ above, CLASS should be the warning class symbol, or a list of such
+ symbols, and LEVEL should specify the warning priority level
+ (`warning' by default).
+
+ Unlike in `display-warning', MESSAGE may be a formatted message,
+ which will be, together with the rest of the arguments, passed to
+ `format'.
+
+ (lwarn 'message-log 'warning
+ "Error caught in `remove-message-hook': %s"
+ (error-message-string e))
+
+ - Variable: log-warning-minimum-level
+ This variable specifies the minimum level of warnings that should
+ be generated. Warnings with level lower than defined by this
+ variable are completely ignored, as if they never happened.
+
+ - Variable: display-warning-minimum-level
+ This variable specifies the minimum level of warnings that should
+ be displayed. Unlike `log-warning-minimum-level', setting this
+ function does not suppress warnings entirely--they are still
+ generated in the `*Warnings*' buffer, only they are not displayed
+ by default.
+
+ - Variable: log-warning-suppressed-classes
+ This variable specifies a list of classes that should not be
+ logged or displayed. If any of the class symbols associated with
+ a warning is the same as any of the symbols listed here, the
+ warning will be completely ignored, as it they never happened.
+
+ - Variable: display-warning-suppressed-classes
+ This variable specifies a list of classes that should not be
+ logged or displayed. If any of the class symbols associated with
+ a warning is the same as any of the symbols listed here, the
+ warning will not be displayed. The warning will still logged in
+ the *Warnings* buffer (unless also contained in
+ `log-warning-suppressed-classes'), but the buffer will not be
+ automatically popped up.
\1f
-File: lispref.info, Node: 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.
+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.
- - 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.
+ `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.
\1f
-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")
- => #<process my-process>
-
- (start-process "my-process" "foo" "ls" "-l" "/user/lewis/bin")
- => #<process my-process<1>>
+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 ----------
- total 2
- lrwxrwxrwx 1 lewis 14 Jul 22 10:12 gnuemacs --> /emacs
- -rwxrwxrwx 1 lewis 19 Jul 30 21:02 lemon
+ 1 on this column
+ 2on this column
+ 3n this column
+ 3n this column
+ 2on this column
+ 1 on this column
+ ---------- Buffer: foo ----------
- Process my-process<1> finished
+ (setq selective-display 2)
+ => 2
- Process my-process finished
+ ---------- Buffer: foo ----------
+ 1 on this column
+ 2on this column
+ 2on this column
+ 1 on this column
---------- 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.
-
- 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::).
-
-\1f
-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.
+ - 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.
- (process-kill-without-query (get-process "shell"))
+ (setq selective-display-ellipses t)
=> t
+
+ ---------- Buffer: foo ----------
+ 1 on this column
+ 2on this column ...
+ 2on this column
+ 1 on this column
+ ---------- Buffer: foo ----------
+
+ You can use a display table to substitute other text for the
+ ellipsis (`...'). *Note Display Tables::.
\1f
-File: lispref.info, Node: Process Information, Next: Input to Processes, Prev: Deleting Processes, Up: Processes
+File: lispref.info, Node: Overlay Arrow, Next: Temporary Displays, Prev: Selective Display, Up: Display
-Process Information
-===================
+The Overlay Arrow
+=================
- 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'.
+ 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.
- - Function: process-list
- This function returns a list of all processes that have not been
- deleted.
+ - 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::).
- (process-list)
- => (#<process display-time> #<process shell>)
+ - 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.
- - Function: get-process name
- This function returns the process named NAME, or `nil' if there is
- none. An error is signaled if NAME is not a string.
+ 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.
- (get-process "shell")
- => #<process shell>
+ You can do the same job by creating an extent with a `begin-glyph'
+property. *Note Extent Properties::.
- - 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.
+\1f
+File: lispref.info, Node: Temporary Displays, Next: Blinking, Prev: Overlay Arrow, Up: Display
- (process-command (get-process "shell"))
- => ("/bin/csh" "-i")
+Temporary Displays
+==================
- - 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.
+ 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.
- - Function: process-name process
- This function returns the name of PROCESS.
+ - 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.
- - Function: process-status process-name
- This function returns the status of PROCESS-NAME as a symbol. The
- argument PROCESS-NAME must be a process, a buffer, a process name
- (string) or a buffer name (string).
+ 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.
- The possible values for an actual subprocess are:
+ `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::.
- `run'
- for a process that is running.
+ The value of the last form in FORMS is returned.
- `stop'
- for a process that is stopped but continuable.
+ ---------- Buffer: foo ----------
+ This is the contents of foo.
+ ---------- Buffer: foo ----------
+
+ (with-output-to-temp-buffer "foo"
+ (print 20)
+ (print standard-output))
+ => #<buffer foo>
+
+ ---------- Buffer: foo ----------
+ 20
+
+ #<buffer foo>
+
+ ---------- Buffer: foo ----------
- `exit'
- for a process that has exited.
+ - 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.
- `signal'
- for a process that has received a fatal signal.
+ In Emacs versions 18 and earlier, this variable was called
+ `temp-buffer-show-hook'.
- `open'
- for a network connection that is open.
+ - 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.
- `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.
+ 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.
- `nil'
- if PROCESS-NAME is not the name of an existing process.
+ The return value of `momentary-string-display' is not meaningful.
- (process-status "shell")
- => run
- (process-status (get-buffer "*shell*"))
- => run
- x
- => #<process xx<1>>
- (process-status x)
- => exit
+ You can do the same job in a more general way by creating an extent
+ with a begin-glyph property. *Note Extent Properties::.
- 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'.
+ 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 earlier Emacs versions (prior to version 19), the status of a
- network connection was `run' if open, and `exit' if closed.
+ In this example, point is initially located at the beginning of the
+ second line:
- - 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'.
+ ---------- 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 ----------
- - 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.
+ 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.
- - Function: process-tty-name process
- This function returns the terminal name that PROCESS is using for
- its communication with Emacs--or `nil' if it is using pipes
- instead of a terminal (see `process-connection-type' in *Note
- Asynchronous Processes::).
+\1f
+File: lispref.info, Node: 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)))
\1f
-File: lispref.info, Node: Input to Processes, Next: Signals to Processes, Prev: Process Information, Up: Processes
+File: lispref.info, Node: Usual Display, Next: Display Tables, Prev: Blinking, Up: Display
-Sending Input to Processes
-==========================
+Usual Display Conventions
+=========================
- 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.
+ 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:
- Some operating systems have limited space for buffered input in a
-PTY. On these systems, Emacs sends an EOF periodically amidst the
-other characters, to force them through. For most programs, these EOFs
-do no harm.
+ * Character codes 32 through 126 map to glyph codes 32 through 126.
+ Normally this means they display as themselves.
- - Function: process-send-string process-name string
- This function sends PROCESS-NAME the contents of STRING as
- standard input. The argument PROCESS-NAME must be a process or
- the name of a process. If it is `nil', the current buffer's
- process is used.
+ * Character code 9 is a horizontal tab. It displays as whitespace
+ up to a position determined by `tab-width'.
- The function returns `nil'.
+ * Character code 10 is a newline.
- (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* ----------
+ * 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.
- - Command: process-send-region process-name start end
- This function sends the text in the region defined by START and
- END as standard input to PROCESS-NAME, which is a process or a
- process name. (If it is `nil', the current buffer's process is
- used.)
+ * 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 `\'.)
- 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.)
+ 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.
- - Function: process-send-eof &optional process-name
- This function makes PROCESS-NAME see an end-of-file in its input.
- The EOF comes after any text already sent to it.
+ 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.
- If PROCESS-NAME is not supplied, or if it is `nil', then this
- function sends the EOF to the current buffer's process. An error
- is signaled if the current buffer has no process.
+ - 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'.
- The function returns PROCESS-NAME.
+ - 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::.
- (process-send-eof "shell")
- => "shell"
+ - User Option: tab-width
+ The value of this variable is the spacing between tab stops used
+ for displaying tab characters in Emacs buffers. The default is 8.
+ Note that this feature is completely independent from the
+ user-settable tab stops used by the command `tab-to-tab-stop'.
+ *Note Indent Tabs::.
\1f
-File: lispref.info, Node: 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 usually indicates that the user
-hung up the phone.)
-
- Each of the signal-sending functions takes two optional arguments:
-PROCESS-NAME and CURRENT-GROUP.
-
- The argument PROCESS-NAME must be either a process, 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-NAME 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 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::.
-
- - Function: interrupt-process &optional process-name current-group
- This function interrupts the process PROCESS-NAME by sending the
- signal `SIGINT'. Outside of XEmacs, typing the "interrupt
- character" (normally `C-c' on some systems, and `DEL' on others)
- 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-name current-group
- This function kills the process PROCESS-NAME by sending the signal
- `SIGKILL'. This signal kills the subprocess immediately, and
- cannot be handled by the subprocess.
-
- - Function: quit-process &optional process-name current-group
- This function sends the signal `SIGQUIT' to the process
- PROCESS-NAME. This signal is the one sent by the "quit character"
- (usually `C-b' or `C-\') when you are not inside XEmacs.
-
- - Function: stop-process &optional process-name current-group
- This function stops the process PROCESS-NAME 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-name current-group
- This function resumes execution of the process PROCESS by sending
- it the signal `SIGCONT'. This presumes that PROCESS-NAME was
- stopped previously.
-
- - Function: signal-process pid signal
- This function sends a signal to process PID, which need not be a
- child of XEmacs. The argument SIGNAL specifies which signal to
- send; it should be an integer.
+File: lispref.info, Node: Display Tables, Next: Beeping, Prev: Usual Display, Up: Display
-\1f
-File: lispref.info, Node: Output from Processes, Next: Sentinels, Prev: Signals to Processes, Up: Processes
+Display Tables
+==============
-Receiving Output from Processes
-===============================
+ 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.
- 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.
+ 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:
-* 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.
+* Display Table Format:: What a display table consists of.
+* Active Display Table:: How XEmacs selects a display table to use.
+* Character Descriptors:: Format of an individual element of a
+ display table.
+
+\1f
+File: lispref.info, Node: Display Table Format, Next: Active Display Table, Up: Display Tables
+
+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 "^?"))
projects / chise / xemacs-chise.git- / blobdiff