This is ../info/elisp, produced by makeinfo version 4.11 from
elisp.texi.

INFO-DIR-SECTION Emacs
START-INFO-DIR-ENTRY
* Elisp: (elisp).       The Emacs Lisp Reference Manual.
END-INFO-DIR-ENTRY

   This is edition 2.9 of the GNU Emacs Lisp Reference Manual,
corresponding to Emacs version 22.3.

   Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1996, 1998, 1999,
2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008  Free Software
Foundation, Inc.

     Permission is granted to copy, distribute and/or modify this
     document under the terms of the GNU Free Documentation License,
     Version 1.2 or any later version published by the Free Software
     Foundation; with the Invariant Sections being "GNU General Public
     License," with the Front-Cover texts being "A GNU Manual," and
     with the Back-Cover Texts as in (a) below.  A copy of the license
     is included in the section entitled "GNU Free Documentation
     License."

     (a) The FSF's Back-Cover Text is: "You are free to copy and modify
     this GNU Manual. Buying copies from GNU Press supports the FSF in
     developing GNU and promoting software freedom."


File: elisp,  Node: Synchronous Processes,  Next: Asynchronous Processes,  Prev: Shell Arguments,  Up: Processes

37.3 Creating a Synchronous Process
===================================

After a "synchronous process" is created, Emacs waits for the process
to terminate before continuing.  Starting Dired on GNU or Unix(1) 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 Emacs 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 (except on MS-DOS, where killing other processes
doesn't work).  *Note Quitting::.

   The synchronous subprocess functions return an indication of how the
process terminated.

   The output from a synchronous subprocess is generally decoded using a
coding system, much like text read from a file.  The input sent to a
subprocess by `call-process-region' is encoded using a coding system,
much like text written into a file.  *Note Coding Systems::.

 -- 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 the null device 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
          Insert the output in a buffer with that name, before point.

    `t'
          Insert the output in the current buffer, before point.

    `nil'
          Discard the output.

    0
          Discard the output, and return `nil' 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.

          MS-DOS doesn't support asynchronous subprocesses, so this
          option doesn't work there.

    `(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.  If ERROR-DESTINATION is `nil', that
          means to discard the error output, `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.  (However, if the coding system chosen for
     decoding output is `undecided', meaning deduce the encoding from
     the actual data, then redisplay sometimes cannot continue once
     non-ASCII characters are encountered.  There are fundamental
     reasons why it is hard to fix this; see *note Output from
     Processes::.)

     Otherwise the function `call-process' does no redisplay, and the
     results become visible on the screen only when Emacs 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)
               => 0

          ---------- Buffer: foo ----------
          /usr/user/lewis/manual
          ---------- Buffer: foo ----------

          (call-process "grep" nil "bar" nil "lewis" "/etc/passwd")
               => 0

          ---------- Buffer: bar ----------
          lewis:5LTsHm66CSWKg:398:21:Bil Lewis:/user/lewis:/bin/csh

          ---------- Buffer: bar ----------

     Here is a good example of the use of `call-process', which used to
     be found in the definition of `insert-directory':

          (call-process insert-directory-program nil t nil SWITCHES
                        (if full-directory-p
                            (concat (file-name-as-directory file) ".")
                          file))

 -- Function: process-file program &optional infile buffer display
          &rest args
     This function processes files synchronously in a separate process.
     It is similar to `call-process' but may invoke a file handler based
     on the value of the variable `default-directory'.  The current
     working directory of the subprocess is `default-directory'.

     The arguments are handled in almost the same way as for
     `call-process', with the following differences:

     Some file handlers may not support all combinations and forms of
     the arguments INFILE, BUFFER, and DISPLAY.  For example, some file
     handlers might behave as if DISPLAY were `nil', regardless of the
     value actually passed.  As another example, some file handlers
     might not support separating standard output and error output by
     way of the BUFFER argument.

     If a file handler is invoked, it determines the program to run
     based on the first argument PROGRAM.  For instance, consider that a
     handler for remote files is invoked.  Then the path that is used
     for searching the program might be different than `exec-path'.

     The second argument INFILE may invoke a file handler.  The file
     handler could be different from the handler chosen for the
     `process-file' function itself.  (For example, `default-directory'
     could be on a remote host, whereas INFILE is on another remote
     host.  Or `default-directory' could be non-special, whereas INFILE
     is on a remote host.)

     If BUFFER is a list of the form `(REAL-DESTINATION
     ERROR-DESTINATION)', and ERROR-DESTINATION names a file, then the
     same remarks as for INFILE apply.

     The remaining arguments (ARGS) will be passed to the process
     verbatim.  Emacs is not involved in processing file names that are
     present in ARGS.  To avoid confusion, it may be best to avoid
     absolute file names in ARGS, but rather to specify all file names
     as relative to `default-directory'.  The function
     `file-relative-name' is useful for constructing such relative file
     names.

 -- Function: call-process-region start end program &optional delete
          destination display &rest args
     This function sends the text from 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 DESTINATION is `t', to insert
     the output in the current buffer in place of the input.

     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 (this only works if asynchronous
     subprocesses are supported).

     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)
               => 0

          ---------- 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.

 -- Function: call-process-shell-command command &optional infile
          destination display &rest args
     This function executes the shell command COMMAND synchronously in
     a separate process.  The final arguments ARGS are additional
     arguments to add at the end of COMMAND.  The other arguments are
     handled as in `call-process'.

 -- Function: shell-command-to-string command
     This function executes COMMAND (a string) as a shell command, then
     returns the command's output as a string.

   ---------- Footnotes ----------

   (1) On other systems, Emacs uses a Lisp emulation of `ls'; see *note
Contents of Directories::.


File: elisp,  Node: Asynchronous Processes,  Next: Deleting Processes,  Prev: Synchronous Processes,  Up: Processes

37.4 Creating an Asynchronous Process
=====================================

After an "asynchronous process" is created, Emacs and the subprocess
both continue running immediately.  The process thereafter runs in
parallel with Emacs, and the two can communicate with each other using
the functions described in the following sections.  However,
communication is only partially asynchronous: Emacs sends data to the
process only when certain functions are called, and Emacs accepts data
from the process only when Emacs is waiting for input or for a time
delay.

   Here we describe how to create an asynchronous 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 appending `<1>',
     etc.) to be unique.  The buffer BUFFER-OR-NAME is the buffer to
     associate with the process.

     The remaining arguments, ARGS, are strings that specify command
     line arguments for the program.

     In the example below, the first process is started and runs
     (rather, sleeps) for 100 seconds.  Meanwhile, the second process
     is started, and given the name `my-process<1>' for the sake of
     uniqueness.  It inserts the directory listing at the end of the
     buffer `foo', before the first process finishes.  Then it
     finishes, and a message to that effect is inserted in the buffer.
     Much later, the first process finishes, and another message is
     inserted in the buffer for it.

          (start-process "my-process" "foo" "sleep" "100")
               => #<process my-process>

          (start-process "my-process" "foo" "ls" "-l" "/user/lewis/bin")
               => #<process my-process<1>>

          ---------- Buffer: foo ----------
          total 2
          lrwxrwxrwx  1 lewis     14 Jul 22 10:12 gnuemacs --> /emacs
          -rwxrwxrwx  1 lewis     19 Jul 30 21:02 lemon

          Process my-process<1> finished

          Process my-process finished
          ---------- Buffer: foo ----------

 -- Function: start-process-shell-command name buffer-or-name command
          &rest command-args
     This function is like `start-process' except that it uses a shell
     to execute the specified command.  The argument COMMAND is a shell
     command name, and COMMAND-ARGS are the arguments for the shell
     command.  The variable `shell-file-name' specifies which shell to
     use.

     The point of running a program through the shell, rather than
     directly with `start-process', is so that you can employ shell
     features such as wildcards in the arguments.  It follows that if
     you include an arbitrary user-specified arguments in the command,
     you should quote it with `shell-quote-argument' first, so that any
     special shell characters do _not_ have their special shell
     meanings.  *Note Shell Arguments::.

 -- 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 of `process-connection-type' takes effect 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::).


File: elisp,  Node: Deleting Processes,  Next: Process Information,  Prev: Asynchronous Processes,  Up: Processes

37.5 Deleting Processes
=======================

"Deleting a process" disconnects Emacs immediately from the subprocess.
Processes are deleted automatically after they terminate, but not
necessarily right away.  You can delete a process explicitly at any
time.  If you delete a terminated process explicitly before it is
deleted automatically, no harm results.  Deleting a running process
sends a signal to terminate it (and its child processes if any), and
calls the process sentinel if it has one.  *Note Sentinels::.

   When a process is deleted, the process object itself continues to
exist as long as other Lisp objects point to it.  All the Lisp
primitives that work on process objects accept deleted processes, but
those that do I/O or send signals will report an error.  The process
mark continues to point to the same place as before, usually into a
buffer where output from the process was being inserted.

 -- User Option: 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 process
     This function deletes a process, killing it with a `SIGKILL'
     signal.  The argument may be a process, the name of a process, a
     buffer, or the name of a buffer.  (A buffer or buffer-name stands
     for the process that `get-buffer-process' returns.)  Calling
     `delete-process' on a running process terminates it, updates the
     process status, and runs the sentinel (if any) immediately.  If the
     process has already terminated, calling `delete-process' has no
     effect on its status, or on the running of its sentinel (which will
     happen sooner or later).

          (delete-process "*shell*")
               => nil


File: elisp,  Node: Process Information,  Next: Input to Processes,  Prev: Deleting Processes,  Up: Processes

37.6 Process Information
========================

Several functions return information about processes.  `list-processes'
is provided for interactive use.

 -- Command: list-processes &optional query-only
     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'.

     If QUERY-ONLY is non-`nil' then it lists only processes whose
     query flag is non-`nil'.  *Note Query Before Exit::.

 -- Function: process-list
     This function returns a list of all processes that have not been
     deleted.

          (process-list)
               => (#<process display-time> #<process shell>)

 -- Function: get-process name
     This function returns the process named NAME, or `nil' if there is
     none.  An error is signaled if NAME is not a string.

          (get-process "shell")
               => #<process shell>

 -- Function: process-command process
     This function returns the command that was executed to start
     PROCESS.  This is a list of strings, the first string being the
     program executed and the rest of the strings being the arguments
     that were given to the program.

          (process-command (get-process "shell"))
               => ("/bin/csh" "-i")

 -- Function: process-id process
     This function returns the PID of PROCESS.  This is an integer that
     distinguishes the process PROCESS from all other processes running
     on the same computer at the current time.  The PID of a process is
     chosen by the operating system kernel when the process is started
     and remains constant as long as the process exists.

 -- Function: process-name process
     This function returns the name of PROCESS.

 -- Function: process-status process-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 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.

    `connect'
          for a non-blocking connection that is waiting to complete.

    `failed'
          for a non-blocking connection that has failed to complete.

    `listen'
          for a network server that is listening.

    `nil'
          if PROCESS-NAME is not the name of an existing process.

          (process-status "shell")
               => run
          (process-status (get-buffer "*shell*"))
               => run
          x
               => #<process xx<1>>
          (process-status x)
               => exit

     For a network connection, `process-status' returns one of the
     symbols `open' or `closed'.  The latter means that the other side
     closed the connection, or Emacs did `delete-process'.

 -- Function: process-exit-status process
     This function returns the exit status of PROCESS or the signal
     number that killed it.  (Use the result of `process-status' to
     determine which of those it is.)  If PROCESS has not yet
     terminated, the value is 0.

 -- Function: process-tty-name process
     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::).

 -- Function: process-coding-system process
     This function returns a cons cell describing the coding systems in
     use for decoding output from PROCESS and for encoding input to
     PROCESS (*note Coding Systems::).  The value has this form:

          (CODING-SYSTEM-FOR-DECODING . CODING-SYSTEM-FOR-ENCODING)

 -- Function: set-process-coding-system process &optional
          decoding-system encoding-system
     This function specifies the coding systems to use for subsequent
     output from and input to PROCESS.  It will use DECODING-SYSTEM to
     decode subprocess output, and ENCODING-SYSTEM to encode subprocess
     input.

   Every process also has a property list that you can use to store
miscellaneous values associated with the process.

 -- Function: process-get process propname
     This function returns the value of the PROPNAME property of
     PROCESS.

 -- Function: process-put process propname value
     This function sets the value of the PROPNAME property of PROCESS
     to VALUE.

 -- Function: process-plist process
     This function returns the process plist of PROCESS.

 -- Function: set-process-plist process plist
     This function sets the process plist of PROCESS to PLIST.


File: elisp,  Node: Input to Processes,  Next: Signals to Processes,  Prev: Process Information,  Up: Processes

37.7 Sending Input to Processes
===============================

Asynchronous subprocesses receive input when it is sent to them by
Emacs, 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, Emacs sends an EOF periodically amidst the
other characters, to force them through.  For most programs, these EOFs
do no harm.

   Subprocess input is normally encoded using a coding system before the
subprocess receives it, much like text written into a file.  You can use
`set-process-coding-system' to specify which coding system to use
(*note Process Information::).  Otherwise, the coding system comes from
`coding-system-for-write', if that is non-`nil'; or else from the
defaulting mechanism (*note Default Coding Systems::).

   Sometimes the system is unable to accept input for that process,
because the input buffer is full.  When this happens, the send functions
wait a short while, accepting output from subprocesses, and then try
again.  This gives the subprocess a chance to read more of its pending
input and make space in the buffer.  It also allows filters, sentinels
and timers to run--so take account of that in writing your code.

   In these functions, the PROCESS argument can be a process or the
name of a process, or a buffer or buffer name (which stands for a
process via `get-buffer-process').  `nil' means the current buffer's
process.

 -- Function: process-send-string process string
     This function sends PROCESS the contents of STRING as standard
     input.  If it is `nil', the current buffer's process is used.

     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
     This function sends the text in the region defined by START and
     END as standard input to PROCESS.

     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.

     The function returns PROCESS.

          (process-send-eof "shell")
               => "shell"

 -- Function: process-running-child-p process
     This function will tell you whether a subprocess has given control
     of its terminal to its own child process.  The value is `t' if
     this is true, or if Emacs cannot tell; it is `nil' if Emacs can be
     certain that this is not so.


File: elisp,  Node: Signals to Processes,  Next: Output from Processes,  Prev: Input to Processes,  Up: Processes

37.8 Sending Signals to Processes
=================================

"Sending a signal" to a subprocess is a way of interrupting its
activities.  There are several different signals, each with its own
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.

   You can send signals explicitly by calling the functions in this
section.  Emacs also sends signals automatically at certain times:
killing a buffer sends a `SIGHUP' signal to all its associated
processes; killing Emacs 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 and CURRENT-GROUP.

   The argument PROCESS must be either a process, a process name, a
buffer, a buffer name, or `nil'.  A buffer or buffer name stands for a
process through `get-buffer-process'.  `nil' stands for 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 Emacs subprocess.  If it is
non-`nil', then the signal is sent to the current process-group of the
terminal that Emacs 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 Emacs.  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 current-group
     This function interrupts the process PROCESS by sending the signal
     `SIGINT'.  Outside of Emacs, 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
     Emacs 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-b'
     or `C-\') when you are not inside Emacs.

 -- 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.

     Outside of Emacs, on systems with job control, the "stop character"
     (usually `C-z') normally sends this signal.  When CURRENT-GROUP is
     non-`nil', you can think of this function as "typing `C-z'" on the
     terminal Emacs 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.

 -- Function: signal-process process signal
     This function sends a signal to process PROCESS.  The argument
     SIGNAL specifies which signal to send; it should be an integer.

     The PROCESS argument can be a system process ID; that allows you
     to send signals to processes that are not children of Emacs.


File: elisp,  Node: Output from Processes,  Next: Sentinels,  Prev: Signals to Processes,  Up: Processes

37.9 Receiving Output from Processes
====================================

There are two ways to receive the output that a subprocess writes to
its standard output stream.  The output can be inserted in a buffer,
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.

   When a subprocess terminates, Emacs reads any pending output, then
stops reading output from that subprocess.  Therefore, if the
subprocess has children that are still live and still producing output,
Emacs won't receive that output.

   Output from a subprocess can arrive only while Emacs is waiting: when
reading terminal input, in `sit-for' and `sleep-for' (*note Waiting::),
and in `accept-process-output' (*note Accepting Output::).  This
minimizes the problem of timing errors that usually plague parallel
programming.  For example, you can safely create a process and only
then specify its buffer or filter function; no output can arrive before
you finish, if the code in between does not call any primitive that
waits.

 -- Variable: process-adaptive-read-buffering
     On some systems, when Emacs reads the output from a subprocess, the
     output data is read in very small blocks, potentially resulting in
     very poor performance.  This behavior can be remedied to some
     extent by setting the variable PROCESS-ADAPTIVE-READ-BUFFERING to a
     non-`nil' value (the default), as it will automatically delay
     reading from such processes, thus allowing them to produce more
     output before Emacs tries to read it.

   It is impossible to separate the standard output and standard error
streams of the subprocess, because Emacs normally spawns the subprocess
inside a pseudo-TTY, and a pseudo-TTY has only one output channel.  If
you want to keep the output to those streams separate, you should
redirect one of them to a file--for example, by using an appropriate
shell command.

* Menu:

* Process Buffers::         If no filter, output is put in a buffer.
* Filter Functions::        Filter functions accept output from the process.
* Decoding Output::         Filters can get unibyte or multibyte strings.
* Accepting Output::        How to wait until process output arrives.


File: elisp,  Node: Process Buffers,  Next: Filter Functions,  Up: Output from Processes

37.9.1 Process Buffers
----------------------

A process can (and usually does) have an "associated buffer", which is
an ordinary Emacs buffer that is used for two purposes: storing the
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 Emacs 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"))
               => #<buffer *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 separates 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 a nondeleted process associated with the
     buffer specified by BUFFER-OR-NAME.  If there are several processes
     associated with it, this function chooses one (currently, the one
     most recently created, but don't count on that).  Deletion of a
     process (see `delete-process') makes it ineligible for this
     function to return.

     It is usually a bad idea to have more than one process associated
     with the same buffer.

          (get-buffer-process "*shell*")
               => #<process shell>

     Killing the process's buffer deletes the process, which kills the
     subprocess with a `SIGHUP' signal (*note Signals to Processes::).


File: elisp,  Node: Filter Functions,  Next: Decoding Output,  Prev: Process Buffers,  Up: Output from Processes

37.9.2 Process Filter Functions
-------------------------------

A process "filter function" is a function that receives the standard
output from the associated process.  If a process has a filter, then
_all_ output from that process is passed to the filter.  The process
buffer is used directly for output from the process only when there is
no filter.

   The filter function can only be called when Emacs is waiting for
something, because process output arrives only at such times.  Emacs
waits when reading terminal input, in `sit-for' and `sleep-for' (*note
Waiting::), and in `accept-process-output' (*note Accepting Output::).

   A filter function must accept two arguments: the associated process
and a string, which is output just received from it.  The function is
then free to do whatever it chooses with the output.

   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'.  In most cases, the right way
to do this is with the macro `with-local-quit'.  *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 Emacs 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 save and restore the
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 (proc string)
       (with-current-buffer (process-buffer proc)
         (let ((moving (= (point) (process-mark proc))))
           (save-excursion
             ;; Insert the text, advancing the process marker.
             (goto-char (process-mark proc))
             (insert string)
             (set-marker (process-mark proc) (point)))
           (if moving (goto-char (process-mark proc))))))

The reason to use `with-current-buffer', rather than using
`save-excursion' to save and restore the current buffer, is so as to
preserve the change in point made by the second call to `goto-char'.

   To make the filter force the process buffer to be visible whenever
new text arrives, insert the following line just before the
`with-current-buffer' construct:

     (display-buffer (process-buffer proc))

   To force point 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 regular
expression searching or matching had to explicitly save and restore the
match data.  Now Emacs does this automatically for filter functions;
they 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.  The expression
`(buffer-name (process-buffer PROCESS))' returns `nil' if the buffer is
dead.

   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.  If
the filter looks for certain text strings in the subprocess output, make
sure to handle the case where one of these strings is split across two
or more batches of output.

 -- Function: set-process-filter process filter
     This function gives PROCESS the filter function FILTER.  If FILTER
     is `nil', it gives the process no filter.

 -- Function: process-filter process
     This function returns the filter function of PROCESS, or `nil' if
     it has none.

   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: elisp,  Node: Decoding Output,  Next: Accepting Output,  Prev: Filter Functions,  Up: Output from Processes

37.9.3 Decoding Process Output
------------------------------

When Emacs writes process output directly into a multibyte buffer, it
decodes the output according to the process output coding system.  If
the coding system is `raw-text' or `no-conversion', Emacs converts the
unibyte output to multibyte using `string-to-multibyte', and inserts
the resulting multibyte text.

   You can use `set-process-coding-system' to specify which coding
system to use (*note Process Information::).  Otherwise, the coding
system comes from `coding-system-for-read', if that is non-`nil'; or
else from the defaulting mechanism (*note Default Coding Systems::).

   *Warning:* Coding systems such as `undecided' which determine the
coding system from the data do not work entirely reliably with
asynchronous subprocess output.  This is because Emacs has to process
asynchronous subprocess output in batches, as it arrives.  Emacs must
try to detect the proper coding system from one batch at a time, and
this does not always work.  Therefore, if at all possible, specify a
coding system that determines both the character code conversion and
the end of line conversion--that is, one like `latin-1-unix', rather
than `undecided' or `latin-1'.

   When Emacs calls a process filter function, it provides the process
output as a multibyte string or as a unibyte string according to the
process's filter multibyte flag.  If the flag is non-`nil', Emacs
decodes the output according to the process output coding system to
produce a multibyte string, and passes that to the process.  If the
flag is `nil', Emacs puts the output into a unibyte string, with no
decoding, and passes that.

   When you create a process, the filter multibyte flag takes its
initial value from `default-enable-multibyte-characters'.  If you want
to change the flag later on, use `set-process-filter-multibyte'.

 -- Function: set-process-filter-multibyte process multibyte
     This function sets the filter multibyte flag of PROCESS to
     MULTIBYTE.

 -- Function: process-filter-multibyte-p process
     This function returns the filter multibyte flag of PROCESS.


File: elisp,  Node: Accepting Output,  Prev: Decoding Output,  Up: Output from Processes

37.9.4 Accepting Output from Processes
--------------------------------------

Output from asynchronous subprocesses normally arrives only while Emacs
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
          just-this-one
     This function allows Emacs 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.

     The argument MILLISEC is semi-obsolete nowadays because SECONDS
     can be a floating point number to specify waiting a fractional
     number of seconds.  If SECONDS is 0, the function accepts whatever
     output is pending but does not wait.

     If PROCESS is a process, and the argument JUST-THIS-ONE is
     non-`nil', only output from that process is handled, suspending
     output from other processes until some output has been received
     from that process or the timeout expires.  If JUST-THIS-ONE is an
     integer, also inhibit running timers.  This feature is generally
     not recommended, but may be necessary for specific applications,
     such as speech synthesis.

     The function `accept-process-output' returns non-`nil' if it did
     get some output, or `nil' if the timeout expired before output
     arrived.


File: elisp,  Node: Sentinels,  Next: Query Before Exit,  Prev: Output from Processes,  Up: Processes

37.10 Sentinels: Detecting Process Status Changes
=================================================

A "process sentinel" is a function that is called whenever the
associated process changes status for any reason, including signals
(whether sent by Emacs 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 Emacs 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 also allows sentinels to run when the command loop is reading
input.  `delete-process' calls the sentinel when it terminates a
running process.

   Emacs does not keep a queue of multiple reasons to call the sentinel
of one process; it records just the current status and the fact that
there has been a change.  Therefore two changes in status, coming in
quick succession, can call the sentinel just once.  However, process
termination will always run the sentinel exactly once.  This is because
the process status can't change again after termination.

   Emacs explicitly checks for output from the process before running
the process sentinel.  Once the sentinel runs due to process
termination, no further output can arrive from the process.

   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'.

   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'.  In most cases, the right way to do this
is with the macro `with-local-quit'.  *Note Quitting::.

   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::.

   While a sentinel is running, the process sentinel is temporarily set
to `nil' so that the sentinel won't run recursively.  For this reason
it is not possible for a sentinel to specify a new sentinel.

   In earlier Emacs versions, every sentinel that did regular expression
searching or matching had to explicitly save and restore the match data.
Now Emacs does this automatically for sentinels; they 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.

     Changes in process sentinel take effect immediately--if the
     sentinel is slated to be run but has not been called yet, and you
     specify a new sentinel, the eventual call to the sentinel will use
     the new one.

          (defun msg-me (process event)
             (princ
               (format "Process: %s had the event `%s'" process event)))
          (set-process-sentinel (get-process "shell") 'msg-me)
               => msg-me
          (kill-process (get-process "shell"))
               -| Process: #<process shell> had the event `killed'
               => #<process shell>

 -- Function: process-sentinel process
     This function returns the sentinel of PROCESS, or `nil' if it has
     none.

 -- Function: waiting-for-user-input-p
     While a sentinel or filter function is running, this function
     returns non-`nil' if Emacs was waiting for keyboard input from the
     user at the time the sentinel or filter function was called, `nil'
     if it was not.


File: elisp,  Node: Query Before Exit,  Next: Transaction Queues,  Prev: Sentinels,  Up: Processes

37.11 Querying Before Exit
==========================

When Emacs exits, it terminates all its subprocesses by sending them
the `SIGHUP' signal.  Because subprocesses may be doing valuable work,
Emacs normally asks the user to confirm that it is ok to terminate
them.  Each process has a query flag which, if non-`nil', says that
Emacs should ask for confirmation before exiting and thus killing that
process.  The default for the query flag is `t', meaning _do_ query.

 -- Function: process-query-on-exit-flag process
     This returns the query flag of PROCESS.

 -- Function: set-process-query-on-exit-flag process flag
     This function sets the query flag of PROCESS to FLAG.  It returns
     FLAG.

          ;; Don't query about the shell process
          (set-process-query-on-exit-flag (get-process "shell") nil)
               => t

 -- Function: process-kill-without-query process &optional do-query
     This function clears the query flag of PROCESS, so that Emacs will
     not query the user on account of that process.

     Actually, the function does more than that: it returns the old
     value of the process's query flag, and sets the query flag to
     DO-QUERY.  Please don't use this function to do those things any
     more--please use the newer, cleaner functions
     `process-query-on-exit-flag' and `set-process-query-on-exit-flag'
     in all but the simplest cases.  The only way you should use
     `process-kill-without-query' nowadays is like this:

          ;; Don't query about the shell process
          (process-kill-without-query (get-process "shell"))


File: elisp,  Node: Transaction Queues,  Next: Network,  Prev: Query Before Exit,  Up: Processes

37.12 Transaction Queues
========================

You can use a "transaction queue" to communicate with a subprocess
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 &optional
          delay-question
     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 text
     at the end of the entire answer, but nothing before; that's how
     `tq-enqueue' determines where the answer ends.

     If the argument DELAY-QUESTION is non-nil, delay sending this
     question until the process has finished replying to any previous
     questions.  This produces more reliable results with some
     processes.

     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: elisp,  Node: Network,  Next: Network Servers,  Prev: Transaction Queues,  Up: Processes

37.13 Network Connections
=========================

Emacs Lisp programs can open stream (TCP) and datagram (UDP) 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 Emacs process, so it has no
process ID, and 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 program at the other end; that program must decide
what to do about closure of the connection.

   Lisp programs can listen for connections by creating network
servers.  A network server is also represented by a kind of process
object, but unlike a network connection, the network server never
transfers data itself.  When it receives a connection request, it
creates a new network connection to represent the connection just made.
(The network connection inherits certain information, including the
process plist, from the server.)  The network server then goes back to
listening for more connection requests.

   Network connections and servers are created by calling
`make-network-process' with an argument list consisting of
keyword/argument pairs, for example `:server t' to create a server
process, or `:type 'datagram' to create a datagram connection.  *Note
Low-Level Network::, for details.  You can also use the
`open-network-stream' function described below.

   You can distinguish process objects representing network connections
and servers from those representing subprocesses with the
`process-status' function.  The possible status values for network
connections are `open', `closed', `connect', and `failed'.  For a
network server, the status is always `listen'.  None of those values is
possible for a real subprocess.  *Note Process Information::.

   You can stop and resume operation of a network process by calling
`stop-process' and `continue-process'.  For a server process, being
stopped means not accepting new connections.  (Up to 5 connection
requests will be queued for when you resume the server; you can
increase this limit, unless it is imposed by the operating system.)
For a network stream connection, being stopped means not processing
input (any arriving input waits until you resume the connection).  For
a datagram connection, some number of packets may be queued but input
may be lost.  You can use the function `process-command' to determine
whether a network connection or server is stopped; a non-`nil' value
means yes.

 -- Function: open-network-stream name buffer-or-name host service
     This function opens a TCP connection, and returns a process object
     that represents 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.  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 (a string), and SERVICE is the name of a defined
     network service (a string) or a port number (an integer).

 -- Function: process-contact process &optional key
     This function returns information about how a network process was
     set up.  For a connection, when KEY is `nil', it returns
     `(HOSTNAME SERVICE)' which specifies what you connected to.

     If KEY is `t', the value is the complete status information for
     the connection or server; that is, the list of keywords and values
     specified in `make-network-process', except that some of the
     values represent the current status instead of what you specified:

    `:buffer'
          The associated value is the process buffer.

    `:filter'
          The associated value is the process filter function.

    `:sentinel'
          The associated value is the process sentinel function.

    `:remote'
          In a connection, the address in internal format of the remote
          peer.

    `:local'
          The local address, in internal format.

    `:service'
          In a server, if you specified `t' for SERVICE, this value is
          the actual port number.

     `:local' and `:remote' are included even if they were not
     specified explicitly in `make-network-process'.

     If KEY is a keyword, the function returns the value corresponding
     to that keyword.

     For an ordinary child process, this function always returns `t'.


File: elisp,  Node: Network Servers,  Next: Datagrams,  Prev: Network,  Up: Processes

37.14 Network Servers
=====================

You create a server by calling `make-network-process' with `:server t'.
The server will listen for connection requests from clients.  When it
accepts a client connection request, that creates a new network
connection, itself a process object, with the following parameters:

   * The connection's process name is constructed by concatenating the
     server process' NAME with a client identification string.  The
     client identification string for an IPv4 connection looks like
     `<A.B.C.D:P>'.  Otherwise, it is a unique number in brackets, as
     in `<NNN>'.  The number is unique for each connection in the Emacs
     session.

   * If the server's filter is non-`nil', the connection process does
     not get a separate process buffer; otherwise, Emacs creates a new
     buffer for the purpose.  The buffer name is the server's buffer
     name or process name, concatenated with the client identification
     string.

     The server's process buffer value is never used directly by Emacs,
     but it is passed to the log function, which can log connections by
     inserting text there.

   * The communication type and the process filter and sentinel are
     inherited from those of the server.  The server never directly
     uses its filter and sentinel; their sole purpose is to initialize
     connections made to the server.

   * The connection's process contact info is set according to the
     client's addressing information (typically an IP address and a
     port number).  This information is associated with the
     `process-contact' keywords `:host', `:service', `:remote'.

   * The connection's local address is set up according to the port
     number used for the connection.

   * The client process' plist is initialized from the server's plist.


File: elisp,  Node: Datagrams,  Next: Low-Level Network,  Prev: Network Servers,  Up: Processes

37.15 Datagrams
===============

A datagram connection communicates with individual packets rather than
streams of data.  Each call to `process-send' sends one datagram packet
(*note Input to Processes::), and each datagram received results in one
call to the filter function.

   The datagram connection doesn't have to talk with the same remote
peer all the time.  It has a "remote peer address" which specifies
where to send datagrams to.  Each time an incoming datagram is passed
to the filter function, the peer address is set to the address that
datagram came from; that way, if the filter function sends a datagram,
it will go back to that place.  You can specify the remote peer address
when you create the datagram connection using the `:remote' keyword.
You can change it later on by calling `set-process-datagram-address'.

 -- Function: process-datagram-address process
     If PROCESS is a datagram connection or server, this function
     returns its remote peer address.

 -- Function: set-process-datagram-address process address
     If PROCESS is a datagram connection or server, this function sets
     its remote peer address to ADDRESS.


File: elisp,  Node: Low-Level Network,  Next: Misc Network,  Prev: Datagrams,  Up: Processes

37.16 Low-Level Network Access
==============================

You can also create network connections by operating at a lower level
than that of `open-network-stream', using `make-network-process'.

* Menu:

* Proc: Network Processes.   Using `make-network-process'.
* Options: Network Options.  Further control over network connections.
* Features: Network Feature Testing.
                             Determining which network features work on
                               the machine you are using.


File: elisp,  Node: Network Processes,  Next: Network Options,  Up: Low-Level Network

37.16.1 `make-network-process'
------------------------------

The basic function for creating network connections and network servers
is `make-network-process'.  It can do either of those jobs, depending
on the arguments you give it.

 -- Function: make-network-process &rest args
     This function creates a network connection or server and returns
     the process object that represents it.  The arguments ARGS are a
     list of keyword/argument pairs.  Omitting a keyword is always
     equivalent to specifying it with value `nil', except for
     `:coding', `:filter-multibyte', and `:reuseaddr'.  Here are the
     meaningful keywords:

    :name NAME
          Use the string NAME as the process name.  It is modified if
          necessary to make it unique.

    :type TYPE
          Specify the communication type.  A value of `nil' specifies a
          stream connection (the default); `datagram' specifies a
          datagram connection.  Both connections and servers can be of
          either type.

    :server SERVER-FLAG
          If SERVER-FLAG is non-`nil', create a server.  Otherwise,
          create a connection.  For a stream type server, SERVER-FLAG
          may be an integer which then specifies the length of the
          queue of pending connections to the server.  The default
          queue length is 5.

    :host HOST
          Specify the host to connect to.  HOST should be a host name or
          Internet address, as a string, or the symbol `local' to
          specify the local host.  If you specify HOST for a server, it
          must specify a valid address for the local host, and only
          clients connecting to that address will be accepted.

    :service SERVICE
          SERVICE specifies a port number to connect to, or, for a
          server, the port number to listen on.  It should be a service
          name that translates to a port number, or an integer
          specifying the port number directly.  For a server, it can
          also be `t', which means to let the system select an unused
          port number.

    :family FAMILY
          FAMILY specifies the address (and protocol) family for
          communication.  `nil' means determine the proper address
          family automatically for the given HOST and SERVICE.  `local'
          specifies a Unix socket, in which case HOST is ignored.
          `ipv4' and `ipv6' specify to use IPv4 and IPv6 respectively.

    :local LOCAL-ADDRESS
          For a server process, LOCAL-ADDRESS is the address to listen
          on.  It overrides FAMILY, HOST and SERVICE, and you may as
          well not specify them.

    :remote REMOTE-ADDRESS
          For a connection, REMOTE-ADDRESS is the address to connect to.
          It overrides FAMILY, HOST and SERVICE, and you may as well
          not specify them.

          For a datagram server, REMOTE-ADDRESS specifies the initial
          setting of the remote datagram address.

          The format of LOCAL-ADDRESS or REMOTE-ADDRESS depends on the
          address family:

             - An IPv4 address is represented as a five-element vector
               of four 8-bit integers and one 16-bit integer `[A B C D
               P]' corresponding to numeric IPv4 address A.B.C.D and
               port number P.

             - An IPv6 address is represented as a nine-element vector
               of 16-bit integers `[A B C D E F G H P]' corresponding
               to numeric IPv6 address A:B:C:D:E:F:G:H and port number
               P.

             - A local address is represented as a string which
               specifies the address in the local address space.

             - An "unsupported family" address is represented by a cons
               `(F . AV)', where F is the family number and AV is a
               vector specifying the socket address using one element
               per address data byte.  Do not rely on this format in
               portable code, as it may depend on implementation
               defined constants, data sizes, and data structure
               alignment.

    :nowait BOOL
          If BOOL is non-`nil' for a stream connection, return without
          waiting for the connection to complete.  When the connection
          succeeds or fails, Emacs will call the sentinel function,
          with a second argument matching `"open"' (if successful) or
          `"failed"'.  The default is to block, so that
          `make-network-process' does not return until the connection
          has succeeded or failed.

    :stop STOPPED
          Start the network connection or server in the `stopped' state
          if STOPPED is non-`nil'.

    :buffer BUFFER
          Use BUFFER as the process buffer.

    :coding CODING
          Use CODING as the coding system for this process.  To specify
          different coding systems for decoding data from the
          connection and for encoding data sent to it, specify
          `(DECODING .  ENCODING)' for CODING.

          If you don't specify this keyword at all, the default is to
          determine the coding systems from the data.

    :noquery QUERY-FLAG
          Initialize the process query flag to QUERY-FLAG.  *Note Query
          Before Exit::.

    :filter FILTER
          Initialize the process filter to FILTER.

    :filter-multibyte BOOL
          If BOOL is non-`nil', strings given to the process filter are
          multibyte, otherwise they are unibyte.  If you don't specify
          this keyword at all, the default is that the strings are
          multibyte if `default-enable-multibyte-characters' is
          non-`nil'.

    :sentinel SENTINEL
          Initialize the process sentinel to SENTINEL.

    :log LOG
          Initialize the log function of a server process to LOG.  The
          log function is called each time the server accepts a network
          connection from a client.  The arguments passed to the log
          function are SERVER, CONNECTION, and MESSAGE, where SERVER is
          the server process, CONNECTION is the new process for the
          connection, and MESSAGE is a string describing what has
          happened.

    :plist PLIST
          Initialize the process plist to PLIST.

     The original argument list, modified with the actual connection
     information, is available via the `process-contact' function.


File: elisp,  Node: Network Options,  Next: Network Feature Testing,  Prev: Network Processes,  Up: Low-Level Network

37.16.2 Network Options
-----------------------

The following network options can be specified when you create a
network process.  Except for `:reuseaddr', you can also set or modify
these options later, using `set-network-process-option'.

   For a server process, the options specified with
`make-network-process' are not inherited by the client connections, so
you will need to set the necessary options for each child connection as
it is created.

:bindtodevice DEVICE-NAME
     If DEVICE-NAME is a non-empty string identifying a network
     interface name (see `network-interface-list'), only handle packets
     received on that interface.  If DEVICE-NAME is `nil' (the
     default), handle packets received on any interface.

     Using this option may require special privileges on some systems.

:broadcast BROADCAST-FLAG
     If BROADCAST-FLAG is non-`nil' for a datagram process, the process
     will receive datagram packet sent to a broadcast address, and be
     able to send packets to a broadcast address.  Ignored for a stream
     connection.

:dontroute DONTROUTE-FLAG
     If DONTROUTE-FLAG is non-`nil', the process can only send to hosts
     on the same network as the local host.

:keepalive KEEPALIVE-FLAG
     If KEEPALIVE-FLAG is non-`nil' for a stream connection, enable
     exchange of low-level keep-alive messages.

:linger LINGER-ARG
     If LINGER-ARG is non-`nil', wait for successful transmission of
     all queued packets on the connection before it is deleted (see
     `delete-process').  If LINGER-ARG is an integer, it specifies the
     maximum time in seconds to wait for queued packets to be sent
     before closing the connection.  Default is `nil' which means to
     discard unsent queued packets when the process is deleted.

:oobinline OOBINLINE-FLAG
     If OOBINLINE-FLAG is non-`nil' for a stream connection, receive
     out-of-band data in the normal data stream.  Otherwise, ignore
     out-of-band data.

:priority PRIORITY
     Set the priority for packets sent on this connection to the integer
     PRIORITY.  The interpretation of this number is protocol specific,
     such as setting the TOS (type of service) field on IP packets sent
     on this connection.  It may also have system dependent effects,
     such as selecting a specific output queue on the network interface.

:reuseaddr REUSEADDR-FLAG
     If REUSEADDR-FLAG is non-`nil' (the default) for a stream server
     process, allow this server to reuse a specific port number (see
     `:service') unless another process on this host is already
     listening on that port.  If REUSEADDR-FLAG is `nil', there may be
     a period of time after the last use of that port (by any process
     on the host), where it is not possible to make a new server on
     that port.

 -- Function: set-network-process-option process option value
     This function sets or modifies a network option for network process
     PROCESS.  See `make-network-process' for details of options OPTION
     and their corresponding values VALUE.

     The current setting of an option is available via the
     `process-contact' function.


File: elisp,  Node: Network Feature Testing,  Prev: Network Options,  Up: Low-Level Network

37.16.3 Testing Availability of Network Features
------------------------------------------------

To test for the availability of a given network feature, use `featurep'
like this:

     (featurep 'make-network-process '(KEYWORD VALUE))

The result of the first form is `t' if it works to specify KEYWORD with
value VALUE in `make-network-process'.  The result of the second form
is `t' if KEYWORD is supported by `make-network-process'.  Here are
some of the KEYWORD--VALUE pairs you can test in this way.

`(:nowait t)'
     Non-`nil' if non-blocking connect is supported.

`(:type datagram)'
     Non-`nil' if datagrams are supported.

`(:family local)'
     Non-`nil' if local (a.k.a. "UNIX domain") sockets are supported.

`(:family ipv6)'
     Non-`nil' if IPv6 is supported.

`(:service t)'
     Non-`nil' if the system can select the port for a server.

   To test for the availability of a given network option, use
`featurep' like this:

     (featurep 'make-network-process 'KEYWORD)

Here are some of the options you can test in this way.

`:bindtodevice'
`:broadcast'
`:dontroute'
`:keepalive'
`:linger'
`:oobinline'
`:priority'
`:reuseaddr'
     That particular network option is supported by
     `make-network-process' and `set-network-process-option'.


File: elisp,  Node: Misc Network,  Next: Byte Packing,  Prev: Low-Level Network,  Up: Processes

37.17 Misc Network Facilities
=============================

These additional functions are useful for creating and operating on
network connections.  Note that they are supported only on some systems.

 -- Function: network-interface-list
     This function returns a list describing the network interfaces of
     the machine you are using.  The value is an alist whose elements
     have the form `(NAME . ADDRESS)'.  ADDRESS has the same form as
     the LOCAL-ADDRESS and REMOTE-ADDRESS arguments to
     `make-network-process'.

 -- Function: network-interface-info ifname
     This function returns information about the network interface named
     IFNAME.  The value is a list of the form `(ADDR BCAST NETMASK
     HWADDR FLAGS)'.

    ADDR
          The Internet protocol address.

    BCAST
          The broadcast address.

    NETMASK
          The network mask.

    HWADDR
          The layer 2 address (Ethernet MAC address, for instance).

    FLAGS
          The current flags of the interface.

 -- Function: format-network-address address &optional omit-port
     This function converts the Lisp representation of a network
     address to a string.

     A five-element vector `[A B C D P]' represents an IPv4 address
     A.B.C.D and port number P.  `format-network-address' converts that
     to the string `"A.B.C.D:P"'.

     A nine-element vector `[A B C D E F G H P]' represents an IPv6
     address along with a port number.  `format-network-address'
     converts that to the string `"[A:B:C:D:E:F:G:H]:P"'.

     If the vector does not include the port number, P, or if OMIT-PORT
     is non-`nil', the result does not include the `:P' suffix.


File: elisp,  Node: Byte Packing,  Prev: Misc Network,  Up: Processes

37.18 Packing and Unpacking Byte Arrays
=======================================

This section describes how to pack and unpack arrays of bytes, usually
for binary network protocols.  These functions convert byte arrays to
alists, and vice versa.  The byte array can be represented as a unibyte
string or as a vector of integers, while the alist associates symbols
either with fixed-size objects or with recursive sub-alists.

   Conversion from byte arrays to nested alists is also known as
"deserializing" or "unpacking", while going in the opposite direction
is also known as "serializing" or "packing".

* Menu:

* Bindat Spec::         Describing data layout.
* Bindat Functions::    Doing the unpacking and packing.
* Bindat Examples::     Samples of what bindat.el can do for you!


File: elisp,  Node: Bindat Spec,  Next: Bindat Functions,  Up: Byte Packing

37.18.1 Describing Data Layout
------------------------------

To control unpacking and packing, you write a "data layout
specification", a special nested list describing named and typed
"fields".  This specification controls length of each field to be
processed, and how to pack or unpack it.  We normally keep bindat specs
in variables whose names end in `-bindat-spec'; that kind of name is
automatically recognized as "risky."

   A field's "type" describes the size (in bytes) of the object that
the field represents and, in the case of multibyte fields, how the
bytes are ordered within the field.  The two possible orderings are
"big endian" (also known as "network byte ordering") and "little
endian."  For instance, the number `#x23cd' (decimal 9165) in big
endian would be the two bytes `#x23' `#xcd'; and in little endian,
`#xcd' `#x23'.  Here are the possible type values:

`u8'
`byte'
     Unsigned byte, with length 1.

`u16'
`word'
`short'
     Unsigned integer in network byte order, with length 2.

`u24'
     Unsigned integer in network byte order, with length 3.

`u32'
`dword'
`long'
     Unsigned integer in network byte order, with length 4.  Note:
     These values may be limited by Emacs' integer implementation
     limits.

`u16r'
`u24r'
`u32r'
     Unsigned integer in little endian order, with length 2, 3 and 4,
     respectively.

`str LEN'
     String of length LEN.

`strz LEN'
     Zero-terminated string, in a fixed-size field with length LEN.

`vec LEN [TYPE]'
     Vector of LEN elements of type TYPE, or bytes if not TYPE is
     specified.  The TYPE is any of the simple types above, or another
     vector specified as a list `(vec LEN [TYPE])'.

`ip'
     Four-byte vector representing an Internet address.  For example:
     `[127 0 0 1]' for localhost.

`bits LEN'
     List of set bits in LEN bytes.  The bytes are taken in big endian
     order and the bits are numbered starting with `8 * LEN - 1' and
     ending with zero.  For example: `bits 2' unpacks `#x28' `#x1c' to
     `(2 3 4 11 13)' and `#x1c' `#x28' to `(3 5 10 11 12)'.

`(eval FORM)'
     FORM is a Lisp expression evaluated at the moment the field is
     unpacked or packed.  The result of the evaluation should be one of
     the above-listed type specifications.

   For a fixed-size field, the length LEN is given as an integer
specifying the number of bytes in the field.

   When the length of a field is not fixed, it typically depends on the
value of a preceding field.  In this case, the length LEN can be given
either as a list `(NAME ...)' identifying a "field name" in the format
specified for `bindat-get-field' below, or by an expression `(eval
FORM)' where FORM should evaluate to an integer, specifying the field
length.

   A field specification generally has the form `([NAME] HANDLER)'.
The square braces indicate that NAME is optional.  (Don't use names
that are symbols meaningful as type specifications (above) or handler
specifications (below), since that would be ambiguous.)  NAME can be a
symbol or the expression `(eval FORM)', in which case FORM should
evaluate to a symbol.

   HANDLER describes how to unpack or pack the field and can be one of
the following:

`TYPE'
     Unpack/pack this field according to the type specification TYPE.

`eval FORM'
     Evaluate FORM, a Lisp expression, for side-effect only.  If the
     field name is specified, the value is bound to that field name.

`fill LEN'
     Skip LEN bytes.  In packing, this leaves them unchanged, which
     normally means they remain zero.  In unpacking, this means they
     are ignored.

`align LEN'
     Skip to the next multiple of LEN bytes.

`struct SPEC-NAME'
     Process SPEC-NAME as a sub-specification.  This describes a
     structure nested within another structure.

`union FORM (TAG SPEC)...'
     Evaluate FORM, a Lisp expression, find the first TAG that matches
     it, and process its associated data layout specification SPEC.
     Matching can occur in one of three ways:

        * If a TAG has the form `(eval EXPR)', evaluate EXPR with the
          variable `tag' dynamically bound to the value of FORM.  A
          non-`nil' result indicates a match.

        * TAG matches if it is `equal' to the value of FORM.

        * TAG matches unconditionally if it is `t'.

`repeat COUNT FIELD-SPECS...'
     Process the FIELD-SPECS recursively, in order, then repeat
     starting from the first one, processing all the specs COUNT times
     overall.  The COUNT is given using the same formats as a field
     length--if an `eval' form is used, it is evaluated just once.  For
     correct operation, each spec in FIELD-SPECS must include a name.

   For the `(eval FORM)' forms used in a bindat specification, the FORM
can access and update these dynamically bound variables during
evaluation:

`last'
     Value of the last field processed.

`bindat-raw'
     The data as a byte array.

`bindat-idx'
     Current index (within `bindat-raw') for unpacking or packing.

`struct'
     The alist containing the structured data that have been unpacked so
     far, or the entire structure being packed.  You can use
     `bindat-get-field' to access specific fields of this structure.

`count'
`index'
     Inside a `repeat' block, these contain the maximum number of
     repetitions (as specified by the COUNT parameter), and the current
     repetition number (counting from 0).  Setting `count' to zero will
     terminate the inner-most repeat block after the current repetition
     has completed.


File: elisp,  Node: Bindat Functions,  Next: Bindat Examples,  Prev: Bindat Spec,  Up: Byte Packing

37.18.2 Functions to Unpack and Pack Bytes
------------------------------------------

In the following documentation, SPEC refers to a data layout
specification, `bindat-raw' to a byte array, and STRUCT to an alist
representing unpacked field data.

 -- Function: bindat-unpack spec bindat-raw &optional bindat-idx
     This function unpacks data from the unibyte string or byte array
     `bindat-raw' according to SPEC.  Normally this starts unpacking at
     the beginning of the byte array, but if BINDAT-IDX is non-`nil', it
     specifies a zero-based starting position to use instead.

     The value is an alist or nested alist in which each element
     describes one unpacked field.

 -- Function: bindat-get-field struct &rest name
     This function selects a field's data from the nested alist STRUCT.
     Usually STRUCT was returned by `bindat-unpack'.  If NAME
     corresponds to just one argument, that means to extract a
     top-level field value.  Multiple NAME arguments specify repeated
     lookup of sub-structures.  An integer name acts as an array index.

     For example, if NAME is `(a b 2 c)', that means to find field `c'
     in the third element of subfield `b' of field `a'.  (This
     corresponds to `struct.a.b[2].c' in C.)

   Although packing and unpacking operations change the organization of
data (in memory), they preserve the data's "total length", which is the
sum of all the fields' lengths, in bytes.  This value is not generally
inherent in either the specification or alist alone; instead, both
pieces of information contribute to its calculation.  Likewise, the
length of a string or array being unpacked may be longer than the data's
total length as described by the specification.

 -- Function: bindat-length spec struct
     This function returns the total length of the data in STRUCT,
     according to SPEC.

 -- Function: bindat-pack spec struct &optional bindat-raw bindat-idx
     This function returns a byte array packed according to SPEC from
     the data in the alist STRUCT.  Normally it creates and fills a new
     byte array starting at the beginning.  However, if BINDAT-RAW is
     non-`nil', it specifies a pre-allocated unibyte string or vector to
     pack into.  If BINDAT-IDX is non-`nil', it specifies the starting
     offset for packing into `bindat-raw'.

     When pre-allocating, you should make sure `(length BINDAT-RAW)'
     meets or exceeds the total length to avoid an out-of-range error.

 -- Function: bindat-ip-to-string ip
     Convert the Internet address vector IP to a string in the usual
     dotted notation.

          (bindat-ip-to-string [127 0 0 1])
               => "127.0.0.1"


File: elisp,  Node: Bindat Examples,  Prev: Bindat Functions,  Up: Byte Packing

37.18.3 Examples of Byte Unpacking and Packing
----------------------------------------------

Here is a complete example of byte unpacking and packing:

     (defvar fcookie-index-spec
       '((:version  u32)
         (:count    u32)
         (:longest  u32)
         (:shortest u32)
         (:flags    u32)
         (:delim    u8)
         (:ignored  fill 3)
         (:offset   repeat (:count)
                    (:foo u32)))
       "Description of a fortune cookie index file's contents.")

     (defun fcookie (cookies &optional index)
       "Display a random fortune cookie from file COOKIES.
     Optional second arg INDEX specifies the associated index
     filename, which is by default constructed by appending
     \".dat\" to COOKIES.  Display cookie text in possibly
     new buffer \"*Fortune Cookie: BASENAME*\" where BASENAME
     is COOKIES without the directory part."
       (interactive "fCookies file: ")
       (let* ((info (with-temp-buffer
                      (insert-file-contents-literally
                       (or index (concat cookies ".dat")))
                      (bindat-unpack fcookie-index-spec
                                     (buffer-string))))
              (sel (random (bindat-get-field info :count)))
              (beg (cdar (bindat-get-field info :offset sel)))
              (end (or (cdar (bindat-get-field info
                                               :offset (1+ sel)))
                       (nth 7 (file-attributes cookies)))))
         (switch-to-buffer
          (get-buffer-create
           (format "*Fortune Cookie: %s*"
                   (file-name-nondirectory cookies))))
         (erase-buffer)
         (insert-file-contents-literally
          cookies nil beg (- end 3))))

     (defun fcookie-create-index (cookies &optional index delim)
       "Scan file COOKIES, and write out its index file.
     Optional second arg INDEX specifies the index filename,
     which is by default constructed by appending \".dat\" to
     COOKIES.  Optional third arg DELIM specifies the unibyte
     character which, when found on a line of its own in
     COOKIES, indicates the border between entries."
       (interactive "fCookies file: ")
       (setq delim (or delim ?%))
       (let ((delim-line (format "\n%c\n" delim))
             (count 0)
             (max 0)
             min p q len offsets)
         (unless (= 3 (string-bytes delim-line))
           (error "Delimiter cannot be represented in one byte"))
         (with-temp-buffer
           (insert-file-contents-literally cookies)
           (while (and (setq p (point))
                       (search-forward delim-line (point-max) t)
                       (setq len (- (point) 3 p)))
             (setq count (1+ count)
                   max (max max len)
                   min (min (or min max) len)
                   offsets (cons (1- p) offsets))))
         (with-temp-buffer
           (set-buffer-multibyte nil)
           (insert
            (bindat-pack
             fcookie-index-spec
             `((:version . 2)
               (:count . ,count)
               (:longest . ,max)
               (:shortest . ,min)
               (:flags . 0)
               (:delim . ,delim)
               (:offset . ,(mapcar (lambda (o)
                                     (list (cons :foo o)))
                                   (nreverse offsets))))))
           (let ((coding-system-for-write 'raw-text-unix))
             (write-file (or index (concat cookies ".dat")))))))

   Following is an example of defining and unpacking a complex
structure.  Consider the following C structures:

     struct header {
         unsigned long    dest_ip;
         unsigned long    src_ip;
         unsigned short   dest_port;
         unsigned short   src_port;
     };

     struct data {
         unsigned char    type;
         unsigned char    opcode;
         unsigned short   length;  /* In network byte order */
         unsigned char    id[8];   /* null-terminated string  */
         unsigned char    data[/* (length + 3) & ~3 */];
     };

     struct packet {
         struct header    header;
         unsigned long    counters[2];  /* In little endian order */
         unsigned char    items;
         unsigned char    filler[3];
         struct data      item[/* items */];

     };

   The corresponding data layout specification:

     (setq header-spec
           '((dest-ip   ip)
             (src-ip    ip)
             (dest-port u16)
             (src-port  u16)))

     (setq data-spec
           '((type      u8)
             (opcode    u8)
             (length    u16)  ;; network byte order
             (id        strz 8)
             (data      vec (length))
             (align     4)))

     (setq packet-spec
           '((header    struct header-spec)
             (counters  vec 2 u32r)   ;; little endian order
             (items     u8)
             (fill      3)
             (item      repeat (items)
                        (struct data-spec))))

   A binary data representation:

     (setq binary-data
           [ 192 168 1 100 192 168 1 101 01 28 21 32
             160 134 1 0 5 1 0 0 2 0 0 0
             2 3 0 5 ?A ?B ?C ?D ?E ?F 0 0 1 2 3 4 5 0 0 0
             1 4 0 7 ?B ?C ?D ?E ?F ?G 0 0 6 7 8 9 10 11 12 0 ])

   The corresponding decoded structure:

     (setq decoded (bindat-unpack packet-spec binary-data))
          =>
     ((header
       (dest-ip   . [192 168 1 100])
       (src-ip    . [192 168 1 101])
       (dest-port . 284)
       (src-port  . 5408))
      (counters . [100000 261])
      (items . 2)
      (item ((data . [1 2 3 4 5])
             (id . "ABCDEF")
             (length . 5)
             (opcode . 3)
             (type . 2))
            ((data . [6 7 8 9 10 11 12])
             (id . "BCDEFG")
             (length . 7)
             (opcode . 4)
             (type . 1))))

   Fetching data from this structure:

     (bindat-get-field decoded 'item 1 'id)
          => "BCDEFG"


File: elisp,  Node: Display,  Next: System Interface,  Prev: Processes,  Up: Top

38 Emacs Display
****************

This chapter describes a number of features related to the display that
Emacs presents to the user.

* Menu:

* Refresh Screen::      Clearing the screen and redrawing everything on it.
* Forcing Redisplay::   Forcing redisplay.
* Truncation::          Folding or wrapping long text lines.
* The Echo Area::       Displaying messages at the bottom of the screen.
* Warnings::            Displaying warning messages for the user.
* Invisible Text::      Hiding part of the buffer text.
* Selective Display::   Hiding part of the buffer text (the old way).
* Temporary Displays::  Displays that go away automatically.
* Overlays::            Use overlays to highlight parts of the buffer.
* Width::               How wide a character or string is on the screen.
* Line Height::         Controlling the height of lines.
* Faces::               A face defines a graphics style for text characters:
                          font, colors, etc.
* Fringes::             Controlling window fringes.
* Scroll Bars::         Controlling vertical scroll bars.
* Display Property::    Enabling special display features.
* Images::              Displaying images in Emacs buffers.
* Buttons::             Adding clickable buttons to Emacs buffers.
* Abstract Display::    Emacs' Widget for Object Collections.
* Blinking::            How Emacs 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.
* Window Systems::      Which window system is being used.


File: elisp,  Node: Refresh Screen,  Next: Forcing Redisplay,  Up: Display

38.1 Refreshing the Screen
==========================

The function `redraw-frame' clears and redisplays the entire contents
of a given frame (*note Frames::).  This is useful if the screen is
corrupted.

 -- Function: redraw-frame frame
     This function clears and redisplays frame FRAME.

   Even more powerful is `redraw-display':

 -- Command: redraw-display
     This function clears and redisplays all visible frames.

   In Emacs, processing user input takes priority over redisplay.  If
you call these functions when input is available, they don't redisplay
immediately, but the requested redisplay does happen eventually--after
all the input has been processed.

   Normally, suspending and resuming Emacs also refreshes the screen.
Some terminal emulators record separate contents for display-oriented
programs such as Emacs and for ordinary sequential display.  If you are
using such a terminal, you might want to inhibit the redisplay on
resumption.

 -- Variable: no-redraw-on-reenter
     This variable controls whether Emacs redraws the entire screen
     after it has been suspended and resumed.  Non-`nil' means there is
     no need to redraw, `nil' means redrawing is needed.  The default
     is `nil'.


File: elisp,  Node: Forcing Redisplay,  Next: Truncation,  Prev: Refresh Screen,  Up: Display

38.2 Forcing Redisplay
======================

Emacs normally tries to redisplay the screen whenever it waits for
input.  With this function you can request an immediate attempt to
redisplay, in the middle of Lisp code, without actually waiting for
input.

 -- Function: redisplay &optional force
     This function tries immediately to redisplay, provided there are no
     pending input events.  It is equivalent to `(sit-for 0)'.

     If the optional argument FORCE is non-`nil', it does all pending
     redisplay work even if input is available, with no pre-emption.

     The function returns `t' if it actually tried to redisplay, and
     `nil' otherwise.  A value of `t' does not mean that redisplay
     proceeded to completion; it could have been pre-empted by newly
     arriving terminal input.

   `redisplay' with no argument tries immediately to redisplay, but has
no effect on the usual rules for what parts of the screen to redisplay.
By contrast, the following function adds certain windows to the pending
redisplay work (as if their contents had completely changed), but
doesn't immediately try to do any redisplay work.

 -- Function: force-window-update &optional object
     This function forces some or all windows to be updated on next
     redisplay.  If OBJECT is a window, it requires eventual redisplay
     of that window.  If OBJECT is a buffer or buffer name, it requires
     eventual redisplay of all windows displaying that buffer.  If
     OBJECT is `nil' (or omitted), it requires eventual redisplay of
     all windows.

   `force-window-update' does not do a redisplay immediately.  (Emacs
will do that when it waits for input.)  Rather, its effect is to put
more work on the queue to be done by redisplay whenever there is a
chance.

   Emacs redisplay normally stops if input arrives, and does not happen
at all if input is available before it starts.  Most of the time, this
is exactly what you want.  However, you can prevent preemption by
binding `redisplay-dont-pause' to a non-`nil' value.

 -- Variable: redisplay-dont-pause
     If this variable is non-`nil', pending input does not prevent or
     halt redisplay; redisplay occurs, and finishes, regardless of
     whether input is available.

 -- Variable: redisplay-preemption-period
     This variable specifies how many seconds Emacs waits between checks
     for new input during redisplay.  (The default is 0.1 seconds.)  If
     input has arrived when Emacs checks, it pre-empts redisplay and
     processes the available input before trying again to redisplay.

     If this variable is `nil', Emacs does not check for input during
     redisplay, and redisplay cannot be preempted by input.

     This variable is only obeyed on graphical terminals.  For text
     terminals, see *note Terminal Output::.


File: elisp,  Node: Truncation,  Next: The Echo Area,  Prev: Forcing Redisplay,  Up: Display

38.3 Truncation
===============

When a line of text extends beyond the right edge of a window, Emacs
can "continue" the line (make it "wrap" to the next screen line), or
"truncate" the line (limit it to one screen line).  The additional
screen lines used to display a long text line are called "continuation"
lines.  Continuation is not the same as 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::.

   On a graphical display, tiny arrow images in the window fringes
indicate truncated and continued lines (*note Fringes::).  On a text
terminal, a `$' in the rightmost column of the window indicates
truncation; a `\' on the rightmost column indicates a line that
"wraps."  (The display table can specify alternate characters to use
for this; *note Display Tables::).

 -- User Option: truncate-lines
     This buffer-local variable controls how Emacs displays lines that
     extend beyond the right edge of the window.  The default is `nil',
     which specifies continuation.  If the value is non-`nil', then
     these lines are truncated.

     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 buffer-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.

   When horizontal scrolling (*note Horizontal Scrolling::) is in use in
a window, that forces truncation.

   If your buffer contains _very_ long lines, and you use continuation
to display them, just thinking about them can make Emacs redisplay
slow.  The column computation and indentation functions also become
slow.  Then you might find it advisable to set `cache-long-line-scans'
to `t'.

 -- Variable: cache-long-line-scans
     If this variable is non-`nil', various indentation and motion
     functions, and Emacs redisplay, cache the results of scanning the
     buffer, and consult the cache to avoid rescanning regions of the
     buffer unless they are modified.

     Turning on the cache slows down processing of short lines somewhat.

     This variable is automatically buffer-local in every buffer.


File: elisp,  Node: The Echo Area,  Next: Warnings,  Prev: Truncation,  Up: Display

38.4 The Echo Area
==================

The "echo area" is used for displaying error messages (*note Errors::),
for 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 `GNU Emacs 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.).

   You can write output in the echo area by using the Lisp printing
functions with `t' as the stream (*note Output Functions::), or
explicitly.

* Menu:

* Displaying Messages:: Explicitly displaying text in the echo area.
* Progress::            Informing user about progress of a long operation.
* Logging Messages::    Echo area messages are logged for the user.
* Echo Area Customization:: Controlling the echo area.


File: elisp,  Node: Displaying Messages,  Next: Progress,  Up: The Echo Area

38.4.1 Displaying Messages in the Echo Area
-------------------------------------------

This section describes the functions for explicitly producing echo area
messages.  Many other Emacs features display messages there, too.

 -- Function: message format-string &rest arguments
     This function displays a message in the echo area.  The argument
     FORMAT-STRING is similar to a C language `printf' format string.
     See `format' in *note Formatting Strings::, 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 FORMAT-STRING, or strings among the ARGUMENTS, have `face' text
     properties, these affect the way the message is displayed.

     If FORMAT-STRING is `nil' or the empty string, `message' clears
     the echo area; if the echo area has been expanded automatically,
     this brings it back to its normal size.  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 ----------

     To automatically display a message in the echo area or in a
     pop-buffer, depending on its size, use `display-message-or-buffer'
     (see below).

 -- Macro: with-temp-message message &rest body
     This construct displays a message in the echo area temporarily,
     during the execution of BODY.  It displays MESSAGE, executes BODY,
     then returns the value of the last body form while restoring the
     previous echo area contents.

 -- Function: message-or-box format-string &rest arguments
     This function displays a message like `message', but may display it
     in a dialog box instead of the echo area.  If this function is
     called in a command that was invoked using the mouse--more
     precisely, if `last-nonmenu-event' (*note Command Loop Info::) is
     either `nil' or a list--then it uses a dialog box or pop-up menu to
     display the message.  Otherwise, it uses the echo area.  (This is
     the same criterion that `y-or-n-p' uses to make a similar
     decision; see *note Yes-or-No Queries::.)

     You can force use of the mouse or of the echo area by binding
     `last-nonmenu-event' to a suitable value around the call.

 -- Function: message-box format-string &rest arguments
     This function displays a message like `message', but uses a dialog
     box (or a pop-up menu) whenever that is possible.  If it is
     impossible to use a dialog box or pop-up menu, because the
     terminal does not support them, then `message-box' uses the echo
     area, like `message'.

 -- Function: display-message-or-buffer message &optional buffer-name
          not-this-window frame
     This function displays the message MESSAGE, which may be either a
     string or a buffer.  If it is shorter than the maximum height of
     the echo area, as defined by `max-mini-window-height', it is
     displayed in the echo area, using `message'.  Otherwise,
     `display-buffer' is used to show it in a pop-up buffer.

     Returns either the string shown in the echo area, or when a pop-up
     buffer is used, the window used to display it.

     If MESSAGE is a string, then the optional argument BUFFER-NAME is
     the name of the buffer used to display it when a pop-up buffer is
     used, defaulting to `*Message*'.  In the case where MESSAGE is a
     string and displayed in the echo area, it is not specified whether
     the contents are inserted into the buffer anyway.

     The optional arguments NOT-THIS-WINDOW and FRAME are as for
     `display-buffer', and only used if a buffer is displayed.

 -- Function: current-message
     This function returns the message currently being displayed in the
     echo area, or `nil' if there is none.


File: elisp,  Node: Progress,  Next: Logging Messages,  Prev: Displaying Messages,  Up: The Echo Area

38.4.2 Reporting Operation Progress
-----------------------------------

When an operation can take a while to finish, you should inform the
user about the progress it makes.  This way the user can estimate
remaining time and clearly see that Emacs is busy working, not hung.

   Functions listed in this section provide simple and efficient way of
reporting operation progress.  Here is a working example that does
nothing useful:

     (let ((progress-reporter
            (make-progress-reporter "Collecting mana for Emacs..."
                                    0  500)))
       (dotimes (k 500)
         (sit-for 0.01)
         (progress-reporter-update progress-reporter k))
       (progress-reporter-done progress-reporter))

 -- Function: make-progress-reporter message min-value max-value
          &optional current-value min-change min-time
     This function creates and returns a "progress reporter"--an object
     you will use as an argument for all other functions listed here.
     The idea is to precompute as much data as possible to make
     progress reporting very fast.

     When this progress reporter is subsequently used, it will display
     MESSAGE in the echo area, followed by progress percentage.
     MESSAGE is treated as a simple string.  If you need it to depend
     on a filename, for instance, use `format' before calling this
     function.

     MIN-VALUE and MAX-VALUE arguments stand for starting and final
     states of your operation.  For instance, if you scan a buffer,
     they should be the results of `point-min' and `point-max'
     correspondingly.  It is required that MAX-VALUE is greater than
     MIN-VALUE.  If you create progress reporter when some part of the
     operation has already been completed, then specify CURRENT-VALUE
     argument.  But normally you should omit it or set it to `nil'--it
     will default to MIN-VALUE then.

     Remaining arguments control the rate of echo area updates.
     Progress reporter will wait for at least MIN-CHANGE more percents
     of the operation to be completed before printing next message.
     MIN-TIME specifies the minimum time in seconds to pass between
     successive prints.  It can be fractional.  Depending on Emacs and
     system capabilities, progress reporter may or may not respect this
     last argument or do it with varying precision.  Default value for
     MIN-CHANGE is 1 (one percent), for MIN-TIME--0.2 (seconds.)

     This function calls `progress-reporter-update', so the first
     message is printed immediately.

 -- Function: progress-reporter-update reporter value
     This function does the main work of reporting progress of your
     operation.  It displays the message of REPORTER, followed by
     progress percentage determined by VALUE.  If percentage is zero,
     or close enough according to the MIN-CHANGE and MIN-TIME
     arguments, then it is omitted from the output.

     REPORTER must be the result of a call to `make-progress-reporter'.
     VALUE specifies the current state of your operation and must be
     between MIN-VALUE and MAX-VALUE (inclusive) as passed to
     `make-progress-reporter'.  For instance, if you scan a buffer,
     then VALUE should be the result of a call to `point'.

     This function respects MIN-CHANGE and MIN-TIME as passed to
     `make-progress-reporter' and so does not output new messages on
     every invocation.  It is thus very fast and normally you should not
     try to reduce the number of calls to it: resulting overhead will
     most likely negate your effort.

 -- Function: progress-reporter-force-update reporter value &optional
          new-message
     This function is similar to `progress-reporter-update' except that
     it prints a message in the echo area unconditionally.

     The first two arguments have the same meaning as for
     `progress-reporter-update'.  Optional NEW-MESSAGE allows you to
     change the message of the REPORTER.  Since this functions always
     updates the echo area, such a change will be immediately presented
     to the user.

 -- Function: progress-reporter-done reporter
     This function should be called when the operation is finished.  It
     prints the message of REPORTER followed by word "done" in the echo
     area.

     You should always call this function and not hope for
     `progress-reporter-update' to print "100%."  Firstly, it may never
     print it, there are many good reasons for this not to happen.
     Secondly, "done" is more explicit.

 -- Macro: dotimes-with-progress-reporter (var count [result]) message
          body...
     This is a convenience macro that works the same way as `dotimes'
     does, but also reports loop progress using the functions described
     above.  It allows you to save some typing.

     You can rewrite the example in the beginning of this node using
     this macro this way:

          (dotimes-with-progress-reporter
              (k 500)
              "Collecting some mana for Emacs..."
            (sit-for 0.01))


File: elisp,  Node: Logging Messages,  Next: Echo Area Customization,  Prev: Progress,  Up: The Echo Area

38.4.3 Logging Messages in `*Messages*'
---------------------------------------

Almost all the messages displayed in the echo area are also recorded in
the `*Messages*' buffer so that the user can refer back to them.  This
includes all the messages that are output with `message'.

 -- User Option: message-log-max
     This variable specifies how many lines to keep in the `*Messages*'
     buffer.  The value `t' means there is no limit on how many lines to
     keep.  The value `nil' disables message logging entirely.  Here's
     how to display a message and prevent it from being logged:

          (let (message-log-max)
            (message ...))

   To make `*Messages*' more convenient for the user, the logging
facility combines successive identical messages.  It also combines
successive related messages for the sake of two cases: question
followed by answer, and a series of progress messages.

   A "question followed by an answer" means two messages like the ones
produced by `y-or-n-p': the first is `QUESTION', and the second is
`QUESTION...ANSWER'.  The first message conveys no additional
information beyond what's in the second, so logging the second message
discards the first from the log.

   A "series of progress messages" means successive messages like those
produced by `make-progress-reporter'.  They have the form
`BASE...HOW-FAR', where BASE is the same each time, while HOW-FAR
varies.  Logging each message in the series discards the previous one,
provided they are consecutive.

   The functions `make-progress-reporter' and `y-or-n-p' don't have to
do anything special to activate the message log combination feature.
It operates whenever two consecutive messages are logged that share a
common prefix ending in `...'.


File: elisp,  Node: Echo Area Customization,  Prev: Logging Messages,  Up: The Echo Area

38.4.4 Echo Area Customization
------------------------------

These variables control details of how the echo area works.

 -- 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.

 -- Variable: echo-area-clear-hook
     This normal hook is run whenever the echo area is cleared--either
     by `(message nil)' or for any other reason.

 -- Variable: echo-keystrokes
     This variable determines how much time should elapse before command
     characters echo.  Its value must be an integer or floating point
     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.  (Once echoing begins in a key sequence,
     all subsequent characters in the same key sequence are echoed
     immediately.)

     If the value is zero, then command input is not echoed.

 -- Variable: message-truncate-lines
     Normally, displaying a long message resizes the echo area to
     display the entire message.  But if the variable
     `message-truncate-lines' is non-`nil', the echo area does not
     resize, and the message is truncated to fit it, as in Emacs 20 and
     before.

   The variable `max-mini-window-height', which specifies the maximum
height for resizing minibuffer windows, also applies to the echo area
(which is really a special use of the minibuffer window.  *Note
Minibuffer Misc::.


File: elisp,  Node: Warnings,  Next: Invisible Text,  Prev: The Echo Area,  Up: Display

38.5 Reporting Warnings
=======================

"Warnings" are a facility for a program to inform the user of a
possible problem, but continue running.

* Menu:

* Warning Basics::      Warnings concepts and functions to report them.
* Warning Variables::   Variables programs bind to customize their warnings.
* Warning Options::     Variables users set to control display of warnings.


File: elisp,  Node: Warning Basics,  Next: Warning Variables,  Up: Warnings

38.5.1 Warning Basics
---------------------

Every warning has a textual message, which explains the problem for the
user, and a "severity level" which is a symbol.  Here are the possible
severity levels, in order of decreasing severity, and their meanings:

`:emergency'
     A problem that will seriously impair Emacs operation soon if you
     do not attend to it promptly.

`:error'
     A report of data or circumstances that are inherently wrong.

`:warning'
     A report of data or circumstances that are not inherently wrong,
     but raise suspicion of a possible problem.

`:debug'
     A report of information that may be useful if you are debugging.

   When your program encounters invalid input data, it can either
signal a Lisp error by calling `error' or `signal' or report a warning
with severity `:error'.  Signaling a Lisp error is the easiest thing to
do, but it means the program cannot continue processing.  If you want
to take the trouble to implement a way to continue processing despite
the bad data, then reporting a warning of severity `:error' is the
right way to inform the user of the problem.  For instance, the Emacs
Lisp byte compiler can report an error that way and continue compiling
other functions.  (If the program signals a Lisp error and then handles
it with `condition-case', the user won't see the error message; it could
show the message to the user by reporting it as a warning.)

   Each warning has a "warning type" to classify it.  The type is a
list of symbols.  The first symbol should be the custom group that you
use for the program's user options.  For example, byte compiler
warnings use the warning type `(bytecomp)'.  You can also subcategorize
the warnings, if you wish, by using more symbols in the list.

 -- Function: display-warning type message &optional level buffer-name
     This function reports a warning, using MESSAGE as the message and
     TYPE as the warning type.  LEVEL should be the severity level,
     with `:warning' being the default.

     BUFFER-NAME, if non-`nil', specifies the name of the buffer for
     logging the warning.  By default, it is `*Warnings*'.

 -- Function: lwarn type level message &rest args
     This function reports a warning using the value of `(format
     MESSAGE ARGS...)' as the message.  In other respects it is
     equivalent to `display-warning'.

 -- Function: warn message &rest args
     This function reports a warning using the value of `(format
     MESSAGE ARGS...)' as the message, `(emacs)' as the type, and
     `:warning' as the severity level.  It exists for compatibility
     only; we recommend not using it, because you should specify a
     specific warning type.


File: elisp,  Node: Warning Variables,  Next: Warning Options,  Prev: Warning Basics,  Up: Warnings

38.5.2 Warning Variables
------------------------

Programs can customize how their warnings appear by binding the
variables described in this section.

 -- Variable: warning-levels
     This list defines the meaning and severity order of the warning
     severity levels.  Each element defines one severity level, and
     they are arranged in order of decreasing severity.

     Each element has the form `(LEVEL STRING FUNCTION)', where LEVEL
     is the severity level it defines.  STRING specifies the textual
     description of this level.  STRING should use `%s' to specify
     where to put the warning type information, or it can omit the `%s'
     so as not to include that information.

     The optional FUNCTION, if non-`nil', is a function to call with no
     arguments, to get the user's attention.

     Normally you should not change the value of this variable.

 -- Variable: warning-prefix-function
     If non-`nil', the value is a function to generate prefix text for
     warnings.  Programs can bind the variable to a suitable function.
     `display-warning' calls this function with the warnings buffer
     current, and the function can insert text in it.  That text becomes
     the beginning of the warning message.

     The function is called with two arguments, the severity level and
     its entry in `warning-levels'.  It should return a list to use as
     the entry (this value need not be an actual member of
     `warning-levels').  By constructing this value, the function can
     change the severity of the warning, or specify different handling
     for a given severity level.

     If the variable's value is `nil' then there is no function to call.

 -- Variable: warning-series
     Programs can bind this variable to `t' to say that the next
     warning should begin a series.  When several warnings form a
     series, that means to leave point on the first warning of the
     series, rather than keep moving it for each warning so that it
     appears on the last one.  The series ends when the local binding
     is unbound and `warning-series' becomes `nil' again.

     The value can also be a symbol with a function definition.  That is
     equivalent to `t', except that the next warning will also call the
     function with no arguments with the warnings buffer current.  The
     function can insert text which will serve as a header for the
     series of warnings.

     Once a series has begun, the value is a marker which points to the
     buffer position in the warnings buffer of the start of the series.

     The variable's normal value is `nil', which means to handle each
     warning separately.

 -- Variable: warning-fill-prefix
     When this variable is non-`nil', it specifies a fill prefix to use
     for filling each warning's text.

 -- Variable: warning-type-format
     This variable specifies the format for displaying the warning type
     in the warning message.  The result of formatting the type this way
     gets included in the message under the control of the string in the
     entry in `warning-levels'.  The default value is `" (%s)"'.  If
     you bind it to `""' then the warning type won't appear at all.


File: elisp,  Node: Warning Options,  Prev: Warning Variables,  Up: Warnings

38.5.3 Warning Options
----------------------

These variables are used by users to control what happens when a Lisp
program reports a warning.

 -- User Option: warning-minimum-level
     This user option specifies the minimum severity level that should
     be shown immediately to the user.  The default is `:warning', which
     means to immediately display all warnings except `:debug' warnings.

 -- User Option: warning-minimum-log-level
     This user option specifies the minimum severity level that should
     be logged in the warnings buffer.  The default is `:warning', which
     means to log all warnings except `:debug' warnings.

 -- User Option: warning-suppress-types
     This list specifies which warning types should not be displayed
     immediately for the user.  Each element of the list should be a
     list of symbols.  If its elements match the first elements in a
     warning type, then that warning is not displayed immediately.

 -- User Option: warning-suppress-log-types
     This list specifies which warning types should not be logged in the
     warnings buffer.  Each element of the list should be a list of
     symbols.  If it matches the first few elements in a warning type,
     then that warning is not logged.


File: elisp,  Node: Invisible Text,  Next: Selective Display,  Prev: Warnings,  Up: Display

38.6 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 (*note Text Properties::) or a property of an overlay (*note
Overlays::).  Cursor motion also partly ignores these characters; if
the command loop finds point within them, it moves point to the other
side of them.

   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
`invisible' property works.  You should normally use `t' as the value
of the `invisible' property if you don't plan to set
`buffer-invisibility-spec' yourself.

   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 database.  It
permits the implementation of convenient filtering commands to view
just a part of the entries in the database.  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.  Setting this variable makes
     it buffer-local.

    `t'
          A character is invisible if its `invisible' property is
          non-`nil'.  This is the default.

    a list
          Each element of the list specifies a criterion for
          invisibility; if a character's `invisible' property fits any
          one of these criteria, the character is invisible.  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, a sequence of such characters displays as an
               ellipsis.

   Two functions are specifically provided for adding elements to
`buffer-invisibility-spec' and removing elements from it.

 -- Function: add-to-invisibility-spec element
     This function adds the element ELEMENT to
     `buffer-invisibility-spec'.  If `buffer-invisibility-spec' was
     `t', it changes to a list, `(t)', so that text whose `invisible'
     property is `t' remains invisible.

 -- Function: remove-from-invisibility-spec element
     This removes the element ELEMENT from `buffer-invisibility-spec'.
     This does nothing if ELEMENT is not in the list.

   A convention for use of `buffer-invisibility-spec' is that a major
mode should use the mode's own name as an element of
`buffer-invisibility-spec' and as the value of the `invisible' property:

     ;; If you want to display an ellipsis:
     (add-to-invisibility-spec '(my-symbol . t))
     ;; If you don't want ellipsis:
     (add-to-invisibility-spec 'my-symbol)

     (overlay-put (make-overlay beginning end)
                  'invisible 'my-symbol)

     ;; When done with the overlays:
     (remove-from-invisibility-spec '(my-symbol . t))
     ;; Or respectively:
     (remove-from-invisibility-spec 'my-symbol)

   Ordinarily, functions that operate on text or move point do not care
whether the text is invisible.  The user-level line motion commands
explicitly ignore invisible newlines if `line-move-ignore-invisible' is
non-`nil' (the default), but only because they are explicitly
programmed to do so.

   However, if a command ends with point inside or immediately before
invisible text, the main editing loop moves point further forward or
further backward (in the same direction that the command already moved
it) until that condition is no longer true.  Thus, if the command moved
point back into an invisible range, Emacs moves point back to the
beginning of that range, and then back one more character.  If the
command moved point forward into an invisible range, Emacs moves point
forward up to the first visible character that follows the invisible
text.

   Incremental search can make invisible overlays visible temporarily
and/or permanently when a match includes invisible text.  To enable
this, the overlay should have a non-`nil' `isearch-open-invisible'
property.  The property value should be a function to be called with
the overlay as an argument.  This function should make the overlay
visible permanently; it is used when the match overlaps the overlay on
exit from the search.

   During the search, such overlays are made temporarily visible by
temporarily modifying their invisible and intangible properties.  If you
want this to be done differently for a certain overlay, give it an
`isearch-open-invisible-temporary' property which is a function.  The
function is called with two arguments: the first is the overlay, and
the second is `nil' to make the overlay visible, or `t' to make it
invisible again.


File: elisp,  Node: Selective Display,  Next: Temporary Displays,  Prev: Invisible Text,  Up: Display

38.7 Selective Display
======================

"Selective display" refers to a pair of related features for hiding
certain lines on the screen.

   The first variant, explicit selective display, is designed for use
in a Lisp program: it controls which lines are hidden by altering the
text.  This kind of hiding in some ways resembles the effect of the
`invisible' property (*note Invisible Text::), but the two features are
different and do not work the same way.

   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 hidden.  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 hidden
text.  However, the replacement of newline characters with carriage
return characters affects some editing commands.  For example,
`next-line' skips hidden lines, since it searches only for newlines.
Modes that use selective display can also define commands that take
account of the newlines, or that control which parts of the text are
hidden.

   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 hidden.  The selective display
effect is seen only within Emacs.

 -- Variable: selective-display
     This buffer-local variable enables selective display.  This means
     that lines, or portions of lines, may be made hidden.

        * If the value of `selective-display' is `t', then the character
          control-m marks the start of hidden text; the control-m, and
          the rest of the line following it, are not displayed.  This
          is explicit selective display.

        * 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 hidden, the vertical movement
     commands operate as if that portion did not exist, allowing a
     single `next-line' command to skip any number of hidden lines.
     However, character movement commands (such as `forward-char') do
     not skip the hidden portion, and it is possible (if tricky) to
     insert or delete text in an hidden 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 Emacs displays
     `...' at the end of a line that is followed by hidden 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: elisp,  Node: Temporary Displays,  Next: Overlays,  Prev: Selective Display,  Up: Display

38.8 Temporary Displays
=======================

Temporary displays are used by Lisp programs to put output into a
buffer and then present it to the user for perusal rather than for
editing.  Many 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, which is first
     created if necessary, and put into Help mode.  Finally, the buffer
     is displayed in some window, but not selected.

     If the FORMS do not change the major mode in the output buffer, so
     that it is still Help mode at the end of their execution, then
     `with-output-to-temp-buffer' makes this buffer read-only at the
     end, and also scans it for function and variable names to make them
     into clickable cross-references.  *Note Tips for Documentation
     Strings: Docstring hyperlinks, in particular the item on
     hyperlinks in documentation strings, for more details.

     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::.

     Several hooks are available for customizing the behavior of this
     construct; they are listed below.

     The value of the last form in FORMS is returned.

          ---------- Buffer: foo ----------
           This is the contents of foo.
          ---------- Buffer: foo ----------

          (with-output-to-temp-buffer "foo"
              (print 20)
              (print standard-output))
          => #<buffer foo>

          ---------- Buffer: foo ----------
          20

          #<buffer foo>

          ---------- Buffer: foo ----------

 -- Variable: temp-buffer-show-function
     If this variable is non-`nil', `with-output-to-temp-buffer' calls
     it as a function to do the job of displaying a help buffer.  The
     function gets one argument, which is the buffer it should display.

     It is a good idea for this function to run `temp-buffer-show-hook'
     just as `with-output-to-temp-buffer' normally would, inside of
     `save-selected-window' and with the chosen window and buffer
     selected.

 -- Variable: temp-buffer-setup-hook
     This normal hook is run by `with-output-to-temp-buffer' before
     evaluating BODY.  When the hook runs, the temporary buffer is
     current.  This hook is normally set up with a function to put the
     buffer in Help mode.

 -- Variable: temp-buffer-show-hook
     This normal hook is run by `with-output-to-temp-buffer' after
     displaying the temporary buffer.  When the hook runs, the
     temporary buffer is current, and the window it was displayed in is
     selected.  This hook is normally set up with a function to make
     the buffer read only, and find function names and variable names
     in it, provided the major mode is Help mode.

 -- 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.

     If the string STRING does not contain control characters, you can
     do the same job in a more general way by creating (and then
     subsequently deleting) an overlay with a `before-string' property.
     *Note Overlay 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 ----------


File: elisp,  Node: Overlays,  Next: Width,  Prev: Temporary Displays,  Up: Display

38.9 Overlays
=============

You can use "overlays" to alter the appearance of a buffer's text on
the screen, for the sake of presentation features.  An overlay is an
object that belongs to a particular buffer, and has a specified
beginning and end.  It also has properties that you can examine and set;
these affect the display of the text within the overlay.

   An overlay uses markers to record its beginning and end; thus,
editing the text of the buffer adjusts the beginning and end of each
overlay so that it stays with the text.  When you create the overlay,
you can specify whether text inserted at the beginning should be inside
the overlay or outside, and likewise for the end of the overlay.

* Menu:

* Managing Overlays::   Creating and moving overlays.
* Overlay Properties::  How to read and set properties.
			What properties do to the screen display.
* Finding Overlays::    Searching for overlays.


File: elisp,  Node: Managing Overlays,  Next: Overlay Properties,  Up: Overlays

38.9.1 Managing Overlays
------------------------

This section describes the functions to create, delete and move
overlays, and to examine their contents.  Overlay changes are not
recorded in the buffer's undo list, since the overlays are not part of
the buffer's contents.

 -- Function: overlayp object
     This function returns `t' if OBJECT is an overlay.

 -- Function: make-overlay start end &optional buffer front-advance
          rear-advance
     This function creates and returns an overlay that belongs to
     BUFFER and ranges from START to END.  Both START and END must
     specify buffer positions; they may be integers or markers.  If
     BUFFER is omitted, the overlay is created in the current buffer.

     The arguments FRONT-ADVANCE and REAR-ADVANCE specify the marker
     insertion type for the start of the overlay and for the end of the
     overlay, respectively.  *Note Marker Insertion Types::.  If they
     are both `nil', the default, then the overlay extends to include
     any text inserted at the beginning, but not text inserted at the
     end.  If FRONT-ADVANCE is non-`nil', text inserted at the
     beginning of the overlay is excluded from the overlay.  If
     REAR-ADVANCE is non-`nil', text inserted at the end of the overlay
     is included in the overlay.

 -- Function: overlay-start overlay
     This function returns the position at which OVERLAY starts, as an
     integer.

 -- Function: overlay-end overlay
     This function returns the position at which OVERLAY ends, as an
     integer.

 -- Function: overlay-buffer overlay
     This function returns the buffer that OVERLAY belongs to.  It
     returns `nil' if OVERLAY has been deleted.

 -- Function: delete-overlay overlay
     This function deletes OVERLAY.  The overlay continues to exist as
     a Lisp object, and its property list is unchanged, but it ceases
     to be attached to the buffer it belonged to, and ceases to have
     any effect on display.

     A deleted overlay is not permanently disconnected.  You can give
     it a position in a buffer again by calling `move-overlay'.

 -- Function: move-overlay overlay start end &optional buffer
     This function moves OVERLAY to BUFFER, and places its bounds at
     START and END.  Both arguments START and END must specify buffer
     positions; they may be integers or markers.

     If BUFFER is omitted, OVERLAY stays in the same buffer it was
     already associated with; if OVERLAY was deleted, it goes into the
     current buffer.

     The return value is OVERLAY.

     This is the only valid way to change the endpoints of an overlay.
     Do not try modifying the markers in the overlay by hand, as that
     fails to update other vital data structures and can cause some
     overlays to be "lost."

 -- Function: remove-overlays &optional start end name value
     This function removes all the overlays between START and END whose
     property NAME has the value VALUE.  It can move the endpoints of
     the overlays in the region, or split them.

     If NAME is omitted or `nil', it means to delete all overlays in
     the specified region.  If START and/or END are omitted or `nil',
     that means the beginning and end of the buffer respectively.
     Therefore, `(remove-overlays)' removes all the overlays in the
     current buffer.

   Here are some examples:

     ;; Create an overlay.
     (setq foo (make-overlay 1 10))
          => #<overlay from 1 to 10 in display.texi>
     (overlay-start foo)
          => 1
     (overlay-end foo)
          => 10
     (overlay-buffer foo)
          => #<buffer display.texi>
     ;; Give it a property we can check later.
     (overlay-put foo 'happy t)
          => t
     ;; Verify the property is present.
     (overlay-get foo 'happy)
          => t
     ;; Move the overlay.
     (move-overlay foo 5 20)
          => #<overlay from 5 to 20 in display.texi>
     (overlay-start foo)
          => 5
     (overlay-end foo)
          => 20
     ;; Delete the overlay.
     (delete-overlay foo)
          => nil
     ;; Verify it is deleted.
     foo
          => #<overlay in no buffer>
     ;; A deleted overlay has no position.
     (overlay-start foo)
          => nil
     (overlay-end foo)
          => nil
     (overlay-buffer foo)
          => nil
     ;; Undelete the overlay.
     (move-overlay foo 1 20)
          => #<overlay from 1 to 20 in display.texi>
     ;; Verify the results.
     (overlay-start foo)
          => 1
     (overlay-end foo)
          => 20
     (overlay-buffer foo)
          => #<buffer display.texi>
     ;; Moving and deleting the overlay does not change its properties.
     (overlay-get foo 'happy)
          => t

   Emacs stores the overlays of each buffer in two lists, divided
around an arbitrary "center position."  One list extends backwards
through the buffer from that center position, and the other extends
forwards from that center position.  The center position can be anywhere
in the buffer.

 -- Function: overlay-recenter pos
     This function recenters the overlays of the current buffer around
     position POS.  That makes overlay lookup faster for positions near
     POS, but slower for positions far away from POS.

   A loop that scans the buffer forwards, creating overlays, can run
faster if you do `(overlay-recenter (point-max))' first.


File: elisp,  Node: Overlay Properties,  Next: Finding Overlays,  Prev: Managing Overlays,  Up: Overlays

38.9.2 Overlay Properties
-------------------------

Overlay properties are like text properties in that the properties that
alter how a character is displayed can come from either source.  But in
most respects they are different.  *Note Text Properties::, for
comparison.

   Text properties are considered a part of the text; overlays and
their properties are specifically considered not to be part of the
text.  Thus, copying text between various buffers and strings preserves
text properties, but does not try to preserve overlays.  Changing a
buffer's text properties marks the buffer as modified, while moving an
overlay or changing its properties does not.  Unlike text property
changes, overlay property changes are not recorded in the buffer's undo
list.

   These functions read and set the properties of an overlay:

 -- Function: overlay-get overlay prop
     This function returns the value of property PROP recorded in
     OVERLAY, if any.  If OVERLAY does not record any value for that
     property, but it does have a `category' property which is a
     symbol, that symbol's PROP property is used.  Otherwise, the value
     is `nil'.

 -- Function: overlay-put overlay prop value
     This function sets the value of property PROP recorded in OVERLAY
     to VALUE.  It returns VALUE.

 -- Function: overlay-properties overlay
     This returns a copy of the property list of OVERLAY.

   See also the function `get-char-property' which checks both overlay
properties and text properties for a given character.  *Note Examining
Properties::.

   Many overlay properties have special meanings; here is a table of
them:

`priority'
     This property's value (which should be a nonnegative integer
     number) determines the priority of the overlay.  The priority
     matters when two or more overlays cover the same character and
     both specify the same property; the one whose `priority' value is
     larger takes priority over the other.  For the `face' property,
     the higher priority value does not completely replace the other;
     instead, its face attributes override the face attributes of the
     lower priority `face' property.

     Currently, all overlays take priority over text properties.  Please
     avoid using negative priority values, as we have not yet decided
     just what they should mean.

`window'
     If the `window' property is non-`nil', then the overlay applies
     only on that window.

`category'
     If an overlay has a `category' property, we call it the "category"
     of the overlay.  It should be a symbol.  The properties of the
     symbol serve as defaults for the properties of the overlay.

`face'
     This property controls the way text is displayed--for example,
     which font and which colors.  *Note Faces::, for more information.

     In the simplest case, the value is a face name.  It can also be a
     list; then each element can be any of these possibilities:

        * A face name (a symbol or string).

        * A property list of face attributes.  This has the form
          (KEYWORD VALUE ...), where each KEYWORD is a face attribute
          name and VALUE is a meaningful value for that attribute.  With
          this feature, you do not need to create a face each time you
          want to specify a particular attribute for certain text.
          *Note Face Attributes::.

        * A cons cell, either of the form `(foreground-color .
          COLOR-NAME)' or `(background-color . COLOR-NAME)'.  These
          elements specify just the foreground color or just the
          background color.

          `(foreground-color . COLOR-NAME)' has the same effect as
          `(:foreground COLOR-NAME)'; likewise for the background.

`mouse-face'
     This property is used instead of `face' when the mouse is within
     the range of the overlay.

`display'
     This property activates various features that change the way text
     is displayed.  For example, it can make text appear taller or
     shorter, higher or lower, wider or narrower, or replaced with an
     image.  *Note Display Property::.

`help-echo'
     If an overlay has a `help-echo' property, then when you move the
     mouse onto the text in the overlay, Emacs displays a help string
     in the echo area, or in the tooltip window.  For details see *note
     Text help-echo::.

`modification-hooks'
     This property's value is a list of functions to be called if any
     character within the overlay is changed or if text is inserted
     strictly within the overlay.

     The hook functions are called both before and after each change.
     If the functions save the information they receive, and compare
     notes between calls, they can determine exactly what change has
     been made in the buffer text.

     When called before a change, each function receives four
     arguments: the overlay, `nil', and the beginning and end of the
     text range to be modified.

     When called after a change, each function receives five arguments:
     the overlay, `t', the beginning and end of the text range just
     modified, and the length of the pre-change text replaced by that
     range.  (For an insertion, the pre-change length is zero; for a
     deletion, that length is the number of characters deleted, and the
     post-change beginning and end are equal.)

     If these functions modify the buffer, they should bind
     `inhibit-modification-hooks' to `t' around doing so, to avoid
     confusing the internal mechanism that calls these hooks.

     Text properties also support the `modification-hooks' property,
     but the details are somewhat different (*note Special
     Properties::).

`insert-in-front-hooks'
     This property's value is a list of functions to be called before
     and after inserting text right at the beginning of the overlay.
     The calling conventions are the same as for the
     `modification-hooks' functions.

`insert-behind-hooks'
     This property's value is a list of functions to be called before
     and after inserting text right at the end of the overlay.  The
     calling conventions are the same as for the `modification-hooks'
     functions.

`invisible'
     The `invisible' property can make the text in the overlay
     invisible, which means that it does not appear on the screen.
     *Note Invisible Text::, for details.

`intangible'
     The `intangible' property on an overlay works just like the
     `intangible' text property.  *Note Special Properties::, for
     details.

`isearch-open-invisible'
     This property tells incremental search how to make an invisible
     overlay visible, permanently, if the final match overlaps it.
     *Note Invisible Text::.

`isearch-open-invisible-temporary'
     This property tells incremental search how to make an invisible
     overlay visible, temporarily, during the search.  *Note Invisible
     Text::.

`before-string'
     This property's value is a string to add to the display at the
     beginning of the overlay.  The string does not appear in the
     buffer in any sense--only on the screen.

`after-string'
     This property's value is a string to add to the display at the end
     of the overlay.  The string does not appear in the buffer in any
     sense--only on the screen.

`evaporate'
     If this property is non-`nil', the overlay is deleted automatically
     if it becomes empty (i.e., if its length becomes zero).  If you
     give an empty overlay a non-`nil' `evaporate' property, that
     deletes it immediately.

`local-map'
     If this property is non-`nil', it specifies a keymap for a portion
     of the text.  The property's value replaces the buffer's local
     map, when the character after point is within the overlay.  *Note
     Active Keymaps::.

`keymap'
     The `keymap' property is similar to `local-map' but overrides the
     buffer's local map (and the map specified by the `local-map'
     property) rather than replacing it.


File: elisp,  Node: Finding Overlays,  Prev: Overlay Properties,  Up: Overlays

38.9.3 Searching for Overlays
-----------------------------

 -- Function: overlays-at pos
     This function returns a list of all the overlays that cover the
     character at position POS in the current buffer.  The list is in
     no particular order.  An overlay contains position POS if it
     begins at or before POS, and ends after POS.

     To illustrate usage, here is a Lisp function that returns a list
     of the overlays that specify property PROP for the character at
     point:

          (defun find-overlays-specifying (prop)
            (let ((overlays (overlays-at (point)))
                  found)
              (while overlays
                (let ((overlay (car overlays)))
                  (if (overlay-get overlay prop)
                      (setq found (cons overlay found))))
                (setq overlays (cdr overlays)))
              found))

 -- Function: overlays-in beg end
     This function returns a list of the overlays that overlap the
     region BEG through END.  "Overlap" means that at least one
     character is contained within the overlay and also contained
     within the specified region; however, empty overlays are included
     in the result if they are located at BEG, or strictly between BEG
     and END.

 -- Function: next-overlay-change pos
     This function returns the buffer position of the next beginning or
     end of an overlay, after POS.  If there is none, it returns
     `(point-max)'.

 -- Function: previous-overlay-change pos
     This function returns the buffer position of the previous
     beginning or end of an overlay, before POS.  If there is none, it
     returns `(point-min)'.

   As an example, here's a simplified (and inefficient) version of the
primitive function `next-single-char-property-change' (*note Property
Search::).  It searches forward from position POS for the next position
where the value of a given property `prop', as obtained from either
overlays or text properties, changes.

     (defun next-single-char-property-change (position prop)
       (save-excursion
         (goto-char position)
         (let ((propval (get-char-property (point) prop)))
           (while (and (not (eobp))
                       (eq (get-char-property (point) prop) propval))
             (goto-char (min (next-overlay-change (point))
                             (next-single-property-change (point) prop)))))
         (point)))


File: elisp,  Node: Width,  Next: Line Height,  Prev: Overlays,  Up: Display

38.10 Width
===========

Since not all characters have the same width, these functions let you
check the width of a character.  *Note Primitive Indent::, and *note
Screen Lines::, for related functions.

 -- Function: char-width char
     This function returns the width in columns of the character CHAR,
     if it were displayed in the current buffer and the selected window.

 -- Function: string-width string
     This function returns the width in columns of the string STRING,
     if it were displayed in the current buffer and the selected window.

 -- Function: truncate-string-to-width string width &optional
          start-column padding ellipsis
     This function returns the part of STRING that fits within WIDTH
     columns, as a new string.

     If STRING does not reach WIDTH, then the result ends where STRING
     ends.  If one multi-column character in STRING extends across the
     column WIDTH, that character is not included in the result.  Thus,
     the result can fall short of WIDTH but cannot go beyond it.

     The optional argument START-COLUMN specifies the starting column.
     If this is non-`nil', then the first START-COLUMN columns of the
     string are omitted from the value.  If one multi-column character
     in STRING extends across the column START-COLUMN, that character
     is not included.

     The optional argument PADDING, if non-`nil', is a padding
     character added at the beginning and end of the result string, to
     extend it to exactly WIDTH columns.  The padding character is used
     at the end of the result if it falls short of WIDTH.  It is also
     used at the beginning of the result if one multi-column character
     in STRING extends across the column START-COLUMN.

     If ELLIPSIS is non-`nil', it should be a string which will replace
     the end of STR (including any padding) if it extends beyond
     END-COLUMN, unless the display width of STR is equal to or less
     than the display width of ELLIPSIS.  If ELLIPSIS is non-`nil' and
     not a string, it stands for `"..."'.

          (truncate-string-to-width "\tab\t" 12 4)
               => "ab"
          (truncate-string-to-width "\tab\t" 12 4 ?\s)
               => "    ab  "


File: elisp,  Node: Line Height,  Next: Faces,  Prev: Width,  Up: Display

38.11 Line Height
=================

The total height of each display line consists of the height of the
contents of the line, plus optional additional vertical line spacing
above or below the display line.

   The height of the line contents is the maximum height of any
character or image on that display line, including the final newline if
there is one.  (A display line that is continued doesn't include a
final newline.)  That is the default line height, if you do nothing to
specify a greater height.  (In the most common case, this equals the
height of the default frame font.)

   There are several ways to explicitly specify a larger line height,
either by specifying an absolute height for the display line, or by
specifying vertical space.  However, no matter what you specify, the
actual line height can never be less than the default.

   A newline can have a `line-height' text or overlay property that
controls the total height of the display line ending in that newline.

   If the property value is `t', the newline character has no effect on
the displayed height of the line--the visible contents alone determine
the height.  This is useful for tiling small images (or image slices)
without adding blank areas between the images.

   If the property value is a list of the form `(HEIGHT TOTAL)', that
adds extra space _below_ the display line.  First Emacs uses HEIGHT as
a height spec to control extra space _above_ the line; then it adds
enough space _below_ the line to bring the total line height up to
TOTAL.  In this case, the other ways to specify the line spacing are
ignored.

   Any other kind of property value is a height spec, which translates
into a number--the specified line height.  There are several ways to
write a height spec; here's how each of them translates into a number:

`INTEGER'
     If the height spec is a positive integer, the height value is that
     integer.

`FLOAT'
     If the height spec is a float, FLOAT, the numeric height value is
     FLOAT times the frame's default line height.

`(FACE . RATIO)'
     If the height spec is a cons of the format shown, the numeric
     height is RATIO times the height of face FACE.  RATIO can be any
     type of number, or `nil' which means a ratio of 1.  If FACE is
     `t', it refers to the current face.

`(nil . RATIO)'
     If the height spec is a cons of the format shown, the numeric
     height is RATIO times the height of the contents of the line.

   Thus, any valid height spec determines the height in pixels, one way
or another.  If the line contents' height is less than that, Emacs adds
extra vertical space above the line to achieve the specified total
height.

   If you don't specify the `line-height' property, the line's height
consists of the contents' height plus the line spacing.  There are
several ways to specify the line spacing for different parts of Emacs
text.

   You can specify the line spacing for all lines in a frame with the
`line-spacing' frame parameter (*note Layout Parameters::).  However,
if the variable `default-line-spacing' is non-`nil', it overrides the
frame's `line-spacing' parameter.  An integer value specifies the
number of pixels put below lines on graphical displays.  A floating
point number specifies the spacing relative to the frame's default line
height.

   You can specify the line spacing for all lines in a buffer via the
buffer-local `line-spacing' variable.  An integer value specifies the
number of pixels put below lines on graphical displays.  A floating
point number specifies the spacing relative to the default frame line
height.  This overrides line spacings specified for the frame.

   Finally, a newline can have a `line-spacing' text or overlay
property that overrides the default frame line spacing and the buffer
local `line-spacing' variable, for the display line ending in that
newline.

   One way or another, these mechanisms specify a Lisp value for the
spacing of each line.  The value is a height spec, and it translates
into a Lisp value as described above.  However, in this case the
numeric height value specifies the line spacing, rather than the line
height.


File: elisp,  Node: Faces,  Next: Fringes,  Prev: Line Height,  Up: Display

38.12 Faces
===========

A "face" is a named collection of graphical attributes: font family,
foreground color, background color, optional underlining, and many
others.  Faces are used in Emacs to control the style of display of
particular parts of the text or the frame.  *Note Standard Faces:
(emacs)Standard Faces, for the list of faces Emacs normally comes with.

   Each face has its own "face number", which distinguishes faces at
low levels within Emacs.  However, for most purposes, you refer to
faces in Lisp programs by the symbols that name them.

 -- Function: facep object
     This function returns `t' if OBJECT is a face name string or
     symbol.  It returns `nil' otherwise.

   Each face name is meaningful for all frames, and by default it has
the same meaning in all frames.  But you can arrange to give a
particular face name a special meaning in one frame if you wish.

* Menu:

* Defining Faces::      How to define a face with `defface'.
* Face Attributes::     What is in a face?
* Attribute Functions::  Functions to examine and set face attributes.
* Displaying Faces::     How Emacs combines the faces specified for a character.
* Font Selection::      Finding the best available font for a face.
* Face Functions::      How to define and examine faces.
* Auto Faces::          Hook for automatic face assignment.
* Font Lookup::         Looking up the names of available fonts
                          and information about them.
* Fontsets::            A fontset is a collection of fonts
                          that handle a range of character sets.


File: elisp,  Node: Defining Faces,  Next: Face Attributes,  Up: Faces

38.12.1 Defining Faces
----------------------

The way to define a new face is with `defface'.  This creates a kind of
customization item (*note Customization::) which the user can customize
using the Customization buffer (*note Easy Customization: (emacs)Easy
Customization.).

 -- Macro: defface face spec doc [keyword value]...
     This declares FACE as a customizable face that defaults according
     to SPEC.  You should not quote the symbol FACE, and it should not
     end in `-face' (that would be redundant).  The argument DOC
     specifies the face documentation.  The keywords you can use in
     `defface' are the same as in `defgroup' and `defcustom' (*note
     Common Keywords::).

     When `defface' executes, it defines the face according to SPEC,
     then uses any customizations that were read from the init file
     (*note Init File::) to override that specification.

     When you evaluate a `defface' form with `C-M-x' in Emacs Lisp mode
     (`eval-defun'), a special feature of `eval-defun' overrides any
     customizations of the face.  This way, the face reflects exactly
     what the `defface' says.

     The purpose of SPEC is to specify how the face should appear on
     different kinds of terminals.  It should be an alist whose elements
     have the form `(DISPLAY ATTS)'.  Each element's CAR, DISPLAY,
     specifies a class of terminals.  (The first element, if its CAR is
     `default', is special--it specifies defaults for the remaining
     elements).  The element's CADR, ATTS, is a list of face attributes
     and their values; it specifies what the face should look like on
     that kind of terminal.  The possible attributes are defined in the
     value of `custom-face-attributes'.

     The DISPLAY part of an element of SPEC determines which frames the
     element matches.  If more than one element of SPEC matches a given
     frame, the first element that matches is the one used for that
     frame.  There are three possibilities for DISPLAY:

    `default'
          This element of SPEC doesn't match any frames; instead, it
          specifies defaults that apply to all frames.  This kind of
          element, if used, must be the first element of SPEC.  Each of
          the following elements can override any or all of these
          defaults.

    `t'
          This element of SPEC matches all frames.  Therefore, any
          subsequent elements of SPEC are never used.  Normally `t' is
          used in the last (or only) element of SPEC.

    a list
          If DISPLAY is a list, each element should have the form
          `(CHARACTERISTIC VALUE...)'.  Here CHARACTERISTIC specifies a
          way of classifying frames, and the VALUEs are possible
          classifications which DISPLAY should apply to.  Here are the
          possible values of CHARACTERISTIC:

         `type'
               The kind of window system the frame uses--either
               `graphic' (any graphics-capable display), `x', `pc' (for
               the MS-DOS console), `w32' (for MS Windows 9X/NT/2K/XP),
               `mac' (for the Macintosh display), or `tty' (a
               non-graphics-capable display).  *Note window-system:
               Window Systems.

         `class'
               What kinds of colors the frame supports--either `color',
               `grayscale', or `mono'.

         `background'
               The kind of background--either `light' or `dark'.

         `min-colors'
               An integer that represents the minimum number of colors
               the frame should support.  This matches a frame if its
               `display-color-cells' value is at least the specified
               integer.

         `supports'
               Whether or not the frame can display the face attributes
               given in VALUE... (*note Face Attributes::).  See the
               documentation for the function
               `display-supports-face-attributes-p' for more
               information on exactly how this testing is done.  *Note
               Display Face Attribute Testing::.

          If an element of DISPLAY specifies more than one VALUE for a
          given CHARACTERISTIC, any of those values is acceptable.  If
          DISPLAY has more than one element, each element should
          specify a different CHARACTERISTIC; then _each_
          characteristic of the frame must match one of the VALUEs
          specified for it in DISPLAY.

   Here's how the standard face `region' is defined:

     (defface region
       '((((class color) (min-colors 88) (background dark))
          :background "blue3")
         (((class color) (min-colors 88) (background light))
          :background "lightgoldenrod2")
         (((class color) (min-colors 16) (background dark))
          :background "blue3")
         (((class color) (min-colors 16) (background light))
          :background "lightgoldenrod2")
         (((class color) (min-colors 8))
          :background "blue" :foreground "white")
         (((type tty) (class mono))
          :inverse-video t)
         (t :background "gray"))
       "Basic face for highlighting the region."
       :group 'basic-faces)

   Internally, `defface' uses the symbol property `face-defface-spec'
to record the face attributes specified in `defface', `saved-face' for
the attributes saved by the user with the customization buffer,
`customized-face' for the attributes customized by the user for the
current session, but not saved, and `face-documentation' for the
documentation string.

 -- User Option: frame-background-mode
     This option, if non-`nil', specifies the background type to use for
     interpreting face definitions.  If it is `dark', then Emacs treats
     all frames as if they had a dark background, regardless of their
     actual background colors.  If it is `light', then Emacs treats all
     frames as if they had a light background.


File: elisp,  Node: Face Attributes,  Next: Attribute Functions,  Prev: Defining Faces,  Up: Faces

38.12.2 Face Attributes
-----------------------

The effect of using a face is determined by a fixed set of "face
attributes".  This table lists all the face attributes, and what they
mean.  You can specify more than one face for a given piece of text;
Emacs merges the attributes of all the faces to determine how to
display the text.  *Note Displaying Faces::.

   Any attribute in a face can have the value `unspecified'.  This
means the face doesn't specify that attribute.  In face merging, when
the first face fails to specify a particular attribute, that means the
next face gets a chance.  However, the `default' face must specify all
attributes.

   Some of these font attributes are meaningful only on certain kinds of
displays--if your display cannot handle a certain attribute, the
attribute is ignored.  (The attributes `:family', `:width', `:height',
`:weight', and `:slant' correspond to parts of an X Logical Font
Descriptor.)

`:family'
     Font family name, or fontset name (*note Fontsets::).  If you
     specify a font family name, the wild-card characters `*' and `?'
     are allowed.

`:width'
     Relative proportionate width, also known as the character set
     width or set width.  This should be one of the symbols
     `ultra-condensed', `extra-condensed', `condensed',
     `semi-condensed', `normal', `semi-expanded', `expanded',
     `extra-expanded', or `ultra-expanded'.

`:height'
     Either the font height, an integer in units of 1/10 point, a
     floating point number specifying the amount by which to scale the
     height of any underlying face, or a function, which is called with
     the old height (from the underlying face), and should return the
     new height.

`:weight'
     Font weight--a symbol from this series (from most dense to most
     faint): `ultra-bold', `extra-bold', `bold', `semi-bold', `normal',
     `semi-light', `light', `extra-light', or `ultra-light'.

     On a text-only terminal, any weight greater than normal is
     displayed as extra bright, and any weight less than normal is
     displayed as half-bright (provided the terminal supports the
     feature).

`:slant'
     Font slant--one of the symbols `italic', `oblique', `normal',
     `reverse-italic', or `reverse-oblique'.

     On a text-only terminal, slanted text is displayed as half-bright,
     if the terminal supports the feature.

`:foreground'
     Foreground color, a string.  The value can be a system-defined
     color name, or a hexadecimal color specification of the form
     `#RRGGBB'.  (`#000000' is black, `#ff0000' is red, `#00ff00' is
     green, `#0000ff' is blue, and `#ffffff' is white.)

`:background'
     Background color, a string, like the foreground color.

`:inverse-video'
     Whether or not characters should be displayed in inverse video.
     The value should be `t' (yes) or `nil' (no).

`:stipple'
     The background stipple, a bitmap.

     The value can be a string; that should be the name of a file
     containing external-format X bitmap data.  The file is found in
     the directories listed in the variable `x-bitmap-file-path'.

     Alternatively, the value can specify the bitmap directly, with a
     list of the form `(WIDTH HEIGHT DATA)'.  Here, WIDTH and HEIGHT
     specify the size in pixels, and DATA is a string containing the
     raw bits of the bitmap, row by row.  Each row occupies (WIDTH + 7)
     / 8 consecutive bytes in the string (which should be a unibyte
     string for best results).  This means that each row always
     occupies at least one whole byte.

     If the value is `nil', that means use no stipple pattern.

     Normally you do not need to set the stipple attribute, because it
     is used automatically to handle certain shades of gray.

`:underline'
     Whether or not characters should be underlined, and in what color.
     If the value is `t', underlining uses the foreground color of the
     face.  If the value is a string, underlining uses that color.  The
     value `nil' means do not underline.

`:overline'
     Whether or not characters should be overlined, and in what color.
     The value is used like that of `:underline'.

`:strike-through'
     Whether or not characters should be strike-through, and in what
     color.  The value is used like that of `:underline'.

`:inherit'
     The name of a face from which to inherit attributes, or a list of
     face names.  Attributes from inherited faces are merged into the
     face like an underlying face would be, with higher priority than
     underlying faces.  If a list of faces is used, attributes from
     faces earlier in the list override those from later faces.

`:box'
     Whether or not a box should be drawn around characters, its color,
     the width of the box lines, and 3D appearance.

   Here are the possible values of the `:box' attribute, and what they
mean:

`nil'
     Don't draw a box.

`t'
     Draw a box with lines of width 1, in the foreground color.

COLOR
     Draw a box with lines of width 1, in color COLOR.

`(:line-width WIDTH :color COLOR :style STYLE)'
     This way you can explicitly specify all aspects of the box.  The
     value WIDTH specifies the width of the lines to draw; it defaults
     to 1.

     The value COLOR specifies the color to draw with.  The default is
     the foreground color of the face for simple boxes, and the
     background color of the face for 3D boxes.

     The value STYLE specifies whether to draw a 3D box.  If it is
     `released-button', the box looks like a 3D button that is not being
     pressed.  If it is `pressed-button', the box looks like a 3D button
     that is being pressed.  If it is `nil' or omitted, a plain 2D box
     is used.

   In older versions of Emacs, before `:family', `:height', `:width',
`:weight', and `:slant' existed, these attributes were used to specify
the type face.  They are now semi-obsolete, but they still work:

`:font'
     This attribute specifies the font name.

`:bold'
     A non-`nil' value specifies a bold font.

`:italic'
     A non-`nil' value specifies an italic font.

   For compatibility, you can still set these "attributes," even though
they are not real face attributes.  Here is what that does:

`:font'
     You can specify an X font name as the "value" of this "attribute";
     that sets the `:family', `:width', `:height', `:weight', and
     `:slant' attributes according to the font name.

     If the value is a pattern with wildcards, the first font that
     matches the pattern is used to set these attributes.

`:bold'
     A non-`nil' makes the face bold; `nil' makes it normal.  This
     actually works by setting the `:weight' attribute.

`:italic'
     A non-`nil' makes the face italic; `nil' makes it normal.  This
     actually works by setting the `:slant' attribute.

 -- Variable: x-bitmap-file-path
     This variable specifies a list of directories for searching for
     bitmap files, for the `:stipple' attribute.

 -- Function: bitmap-spec-p object
     This returns `t' if OBJECT is a valid bitmap specification,
     suitable for use with `:stipple' (see above).  It returns `nil'
     otherwise.


File: elisp,  Node: Attribute Functions,  Next: Displaying Faces,  Prev: Face Attributes,  Up: Faces

38.12.3 Face Attribute Functions
--------------------------------

This section describes the functions for accessing and modifying the
attributes of an existing face.

 -- Function: set-face-attribute face frame &rest arguments
     This function sets one or more attributes of face FACE for frame
     FRAME.  The attributes you specify this way override whatever the
     `defface' says.

     The extra arguments ARGUMENTS specify the attributes to set, and
     the values for them.  They should consist of alternating attribute
     names (such as `:family' or `:underline') and corresponding values.
     Thus,

          (set-face-attribute 'foo nil
                              :width 'extended
                              :weight 'bold
                              :underline "red")

     sets the attributes `:width', `:weight' and `:underline' to the
     corresponding values.

     If FRAME is `t', this function sets the default attributes for new
     frames.  Default attribute values specified this way override the
     `defface' for newly created frames.

     If FRAME is `nil', this function sets the attributes for all
     existing frames, and the default for new frames.

 -- Function: face-attribute face attribute &optional frame inherit
     This returns the value of the ATTRIBUTE attribute of face FACE on
     FRAME.  If FRAME is `nil', that means the selected frame (*note
     Input Focus::).

     If FRAME is `t', this returns whatever new-frames default value
     you previously specified with `set-face-attribute' for the
     ATTRIBUTE attribute of FACE.  If you have not specified one, it
     returns `nil'.

     If INHERIT is `nil', only attributes directly defined by FACE are
     considered, so the return value may be `unspecified', or a
     relative value.  If INHERIT is non-`nil', FACE's definition of
     ATTRIBUTE is merged with the faces specified by its `:inherit'
     attribute; however the return value may still be `unspecified' or
     relative.  If INHERIT is a face or a list of faces, then the
     result is further merged with that face (or faces), until it
     becomes specified and absolute.

     To ensure that the return value is always specified and absolute,
     use a value of `default' for INHERIT; this will resolve any
     unspecified or relative values by merging with the `default' face
     (which is always completely specified).

     For example,

          (face-attribute 'bold :weight)
               => bold

 -- Function: face-attribute-relative-p attribute value
     This function returns non-`nil' if VALUE, when used as the value
     of the face attribute ATTRIBUTE, is relative.  This means it would
     modify, rather than completely override, any value that comes from
     a subsequent face in the face list or that is inherited from
     another face.

     `unspecified' is a relative value for all attributes.  For
     `:height', floating point values are also relative.

     For example:

          (face-attribute-relative-p :height 2.0)
               => t

 -- Function: merge-face-attribute attribute value1 value2
     If VALUE1 is a relative value for the face attribute ATTRIBUTE,
     returns it merged with the underlying value VALUE2; otherwise, if
     VALUE1 is an absolute value for the face attribute ATTRIBUTE,
     returns VALUE1 unchanged.

   The functions above did not exist before Emacs 21.  For compatibility
with older Emacs versions, you can use the following functions to set
and examine the face attributes which existed in those versions.  They
use values of `t' and `nil' for FRAME just like `set-face-attribute'
and `face-attribute'.

 -- Function: set-face-foreground face color &optional frame
 -- Function: set-face-background face color &optional frame
     These functions set the foreground (or background, respectively)
     color of face FACE to COLOR.  The argument COLOR should be a
     string, the name of a color.

     Certain shades of gray are implemented by stipple patterns on
     black-and-white screens.

 -- Function: set-face-stipple face pattern &optional frame
     This function sets the background stipple pattern of face FACE to
     PATTERN.  The argument PATTERN should be the name of a stipple
     pattern defined by the X server, or actual bitmap data (*note Face
     Attributes::), or `nil' meaning don't use stipple.

     Normally there is no need to pay attention to stipple patterns,
     because they are used automatically to handle certain shades of
     gray.

 -- Function: set-face-font face font &optional frame
     This function sets the font of face FACE.  This actually sets the
     attributes `:family', `:width', `:height', `:weight', and `:slant'
     according to the font name FONT.

 -- Function: set-face-bold-p face bold-p &optional frame
     This function specifies whether FACE should be bold.  If BOLD-P is
     non-`nil', that means yes; `nil' means no.  This actually sets the
     `:weight' attribute.

 -- Function: set-face-italic-p face italic-p &optional frame
     This function specifies whether FACE should be italic.  If
     ITALIC-P is non-`nil', that means yes; `nil' means no.  This
     actually sets the `:slant' attribute.

 -- Function: set-face-underline-p face underline &optional frame
     This function sets the underline attribute of face FACE.
     Non-`nil' means do underline; `nil' means don't.  If UNDERLINE is
     a string, underline with that color.

 -- Function: set-face-inverse-video-p face inverse-video-p &optional
          frame
     This function sets the `:inverse-video' attribute of face FACE.

 -- Function: invert-face face &optional frame
     This function swaps the foreground and background colors of face
     FACE.

   These functions examine the attributes of a face.  If you don't
specify FRAME, they refer to the selected frame; `t' refers to the
default data for new frames.  They return the symbol `unspecified' if
the face doesn't define any value for that attribute.

 -- Function: face-foreground face &optional frame inherit
 -- Function: face-background face &optional frame inherit
     These functions return the foreground color (or background color,
     respectively) of face FACE, as a string.

     If INHERIT is `nil', only a color directly defined by the face is
     returned.  If INHERIT is non-`nil', any faces specified by its
     `:inherit' attribute are considered as well, and if INHERIT is a
     face or a list of faces, then they are also considered, until a
     specified color is found.  To ensure that the return value is
     always specified, use a value of `default' for INHERIT.

 -- Function: face-stipple face &optional frame inherit
     This function returns the name of the background stipple pattern
     of face FACE, or `nil' if it doesn't have one.

     If INHERIT is `nil', only a stipple directly defined by the face
     is returned.  If INHERIT is non-`nil', any faces specified by its
     `:inherit' attribute are considered as well, and if INHERIT is a
     face or a list of faces, then they are also considered, until a
     specified stipple is found.  To ensure that the return value is
     always specified, use a value of `default' for INHERIT.

 -- Function: face-font face &optional frame
     This function returns the name of the font of face FACE.

 -- Function: face-bold-p face &optional frame
     This function returns `t' if FACE is bold--that is, if it is
     bolder than normal.  It returns `nil' otherwise.

 -- Function: face-italic-p face &optional frame
     This function returns `t' if FACE is italic or oblique, `nil'
     otherwise.

 -- Function: face-underline-p face &optional frame
     This function returns the `:underline' attribute of face FACE.

 -- Function: face-inverse-video-p face &optional frame
     This function returns the `:inverse-video' attribute of face FACE.


File: elisp,  Node: Displaying Faces,  Next: Font Selection,  Prev: Attribute Functions,  Up: Faces

38.12.4 Displaying Faces
------------------------

Here are the ways to specify which faces to use for display of text:

   * With defaults.  The `default' face is used as the ultimate default
     for all text.  (In Emacs 19 and 20, the `default' face is used
     only when no other face is specified.)

   * For a mode line or header line, the face `mode-line' or
     `mode-line-inactive', or `header-line', is merged in just before
     `default'.

   * With text properties.  A character can have a `face' property; if
     so, the faces and face attributes specified there apply.  *Note
     Special Properties::.

     If the character has a `mouse-face' property, that is used instead
     of the `face' property when the mouse is "near enough" to the
     character.

   * With overlays.  An overlay can have `face' and `mouse-face'
     properties too; they apply to all the text covered by the overlay.

   * With a region that is active.  In Transient Mark mode, the region
     is highlighted with the face `region' (*note Standard Faces:
     (emacs)Standard Faces.).

   * With special glyphs.  Each glyph can specify a particular face
     number.  *Note Glyphs::.

   If these various sources together specify more than one face for a
particular character, Emacs merges the attributes of the various faces
specified.  For each attribute, Emacs tries first the face of any
special glyph; then the face for region highlighting, if appropriate;
then the faces specified by overlays, followed by those specified by
text properties, then the `mode-line' or `mode-line-inactive' or
`header-line' face (if in a mode line or a header line), and last the
`default' face.

   When multiple overlays cover one character, an overlay with higher
priority overrides those with lower priority.  *Note Overlays::.


File: elisp,  Node: Font Selection,  Next: Face Functions,  Prev: Displaying Faces,  Up: Faces

38.12.5 Font Selection
----------------------

"Selecting a font" means mapping the specified face attributes for a
character to a font that is available on a particular display.  The
face attributes, as determined by face merging, specify most of the
font choice, but not all.  Part of the choice depends on what character
it is.

   If the face specifies a fontset name, that fontset determines a
pattern for fonts of the given charset.  If the face specifies a font
family, a font pattern is constructed.

   Emacs tries to find an available font for the given face attributes
and character's registry and encoding.  If there is a font that matches
exactly, it is used, of course.  The hard case is when no available font
exactly fits the specification.  Then Emacs looks for one that is
"close"--one attribute at a time.  You can specify the order to
consider the attributes.  In the case where a specified font family is
not available, you can specify a set of mappings for alternatives to
try.

 -- Variable: face-font-selection-order
     This variable specifies the order of importance of the face
     attributes `:width', `:height', `:weight', and `:slant'.  The
     value should be a list containing those four symbols, in order of
     decreasing importance.

     Font selection first finds the best available matches for the first
     attribute listed; then, among the fonts which are best in that
     way, it searches for the best matches in the second attribute, and
     so on.

     The attributes `:weight' and `:width' have symbolic values in a
     range centered around `normal'.  Matches that are more extreme
     (farther from `normal') are somewhat preferred to matches that are
     less extreme (closer to `normal'); this is designed to ensure that
     non-normal faces contrast with normal ones, whenever possible.

     The default is `(:width :height :weight :slant)', which means first
     find the fonts closest to the specified `:width', then--among the
     fonts with that width--find a best match for the specified font
     height, and so on.

     One example of a case where this variable makes a difference is
     when the default font has no italic equivalent.  With the default
     ordering, the `italic' face will use a non-italic font that is
     similar to the default one.  But if you put `:slant' before
     `:height', the `italic' face will use an italic font, even if its
     height is not quite right.

 -- Variable: face-font-family-alternatives
     This variable lets you specify alternative font families to try,
     if a given family is specified and doesn't exist.  Each element
     should have this form:

          (FAMILY ALTERNATE-FAMILIES...)

     If FAMILY is specified but not available, Emacs will try the other
     families given in ALTERNATE-FAMILIES, one by one, until it finds a
     family that does exist.

 -- Variable: face-font-registry-alternatives
     This variable lets you specify alternative font registries to try,
     if a given registry is specified and doesn't exist.  Each element
     should have this form:

          (REGISTRY ALTERNATE-REGISTRIES...)

     If REGISTRY is specified but not available, Emacs will try the
     other registries given in ALTERNATE-REGISTRIES, one by one, until
     it finds a registry that does exist.

   Emacs can make use of scalable fonts, but by default it does not use
them, since the use of too many or too big scalable fonts can crash
XFree86 servers.

 -- Variable: scalable-fonts-allowed
     This variable controls which scalable fonts to use.  A value of
     `nil', the default, means do not use scalable fonts.  `t' means to
     use any scalable font that seems appropriate for the text.

     Otherwise, the value must be a list of regular expressions.  Then a
     scalable font is enabled for use if its name matches any regular
     expression in the list.  For example,

          (setq scalable-fonts-allowed '("muleindian-2$"))

     allows the use of scalable fonts with registry `muleindian-2'.

 -- Variable: face-font-rescale-alist
     This variable specifies scaling for certain faces.  Its value
     should be a list of elements of the form

          (FONTNAME-REGEXP . SCALE-FACTOR)

     If FONTNAME-REGEXP matches the font name that is about to be used,
     this says to choose a larger similar font according to the factor
     SCALE-FACTOR.  You would use this feature to normalize the font
     size if certain fonts are bigger or smaller than their nominal
     heights and widths would suggest.


File: elisp,  Node: Face Functions,  Next: Auto Faces,  Prev: Font Selection,  Up: Faces

38.12.6 Functions for Working with Faces
----------------------------------------

Here are additional functions for creating and working with faces.

 -- Function: make-face name
     This function defines a new face named NAME, initially with all
     attributes `nil'.  It does nothing if there is already a face named
     NAME.

 -- Function: face-list
     This function returns a list of all defined face names.

 -- Function: copy-face old-face new-name &optional frame new-frame
     This function defines a face named NEW-NAME as a copy of the
     existing face named OLD-FACE.  It creates the face NEW-NAME if that
     doesn't already exist.

     If the optional argument FRAME is given, this function applies
     only to that frame.  Otherwise it applies to each frame
     individually, copying attributes from OLD-FACE in each frame to
     NEW-FACE in the same frame.

     If the optional argument NEW-FRAME is given, then `copy-face'
     copies the attributes of OLD-FACE in FRAME to NEW-NAME in
     NEW-FRAME.

 -- Function: face-id face
     This function returns the face number of face FACE.

 -- Function: face-documentation face
     This function returns the documentation string of face FACE, or
     `nil' if none was specified for it.

 -- Function: face-equal face1 face2 &optional frame
     This returns `t' if the faces FACE1 and FACE2 have the same
     attributes for display.

 -- Function: face-differs-from-default-p face &optional frame
     This returns non-`nil' if the face FACE displays differently from
     the default face.

   A "face alias" provides an equivalent name for a face.  You can
define a face alias by giving the alias symbol the `face-alias'
property, with a value of the target face name.  The following example
makes `modeline' an alias for the `mode-line' face.

     (put 'modeline 'face-alias 'mode-line)


File: elisp,  Node: Auto Faces,  Next: Font Lookup,  Prev: Face Functions,  Up: Faces

38.12.7 Automatic Face Assignment
---------------------------------

This hook is used for automatically assigning faces to text in the
buffer.  It is part of the implementation of Jit-Lock mode, used by
Font-Lock.

 -- Variable: fontification-functions
     This variable holds a list of functions that are called by Emacs
     redisplay as needed to assign faces automatically to text in the
     buffer.

     The functions are called in the order listed, with one argument, a
     buffer position POS.  Each function should attempt to assign faces
     to the text in the current buffer starting at POS.

     Each function should record the faces they assign by setting the
     `face' property.  It should also add a non-`nil' `fontified'
     property for all the text it has assigned faces to.  That property
     tells redisplay that faces have been assigned to that text already.

     It is probably a good idea for each function to do nothing if the
     character after POS already has a non-`nil' `fontified' property,
     but this is not required.  If one function overrides the
     assignments made by a previous one, the properties as they are
     after the last function finishes are the ones that really matter.

     For efficiency, we recommend writing these functions so that they
     usually assign faces to around 400 to 600 characters at each call.


File: elisp,  Node: Font Lookup,  Next: Fontsets,  Prev: Auto Faces,  Up: Faces

38.12.8 Looking Up Fonts
------------------------

 -- Function: x-list-fonts pattern &optional face frame maximum
     This function returns a list of available font names that match
     PATTERN.  If the optional arguments FACE and FRAME are specified,
     then the list is limited to fonts that are the same size as FACE
     currently is on FRAME.

     The argument PATTERN should be a string, perhaps with wildcard
     characters: the `*' character matches any substring, and the `?'
     character matches any single character.  Pattern matching of font
     names ignores case.

     If you specify FACE and FRAME, FACE should be a face name (a
     symbol) and FRAME should be a frame.

     The optional argument MAXIMUM sets a limit on how many fonts to
     return.  If this is non-`nil', then the return value is truncated
     after the first MAXIMUM matching fonts.  Specifying a small value
     for MAXIMUM can make this function much faster, in cases where
     many fonts match the pattern.

 -- Function: x-family-fonts &optional family frame
     This function returns a list describing the available fonts for
     family FAMILY on FRAME.  If FAMILY is omitted or `nil', this list
     applies to all families, and therefore, it contains all available
     fonts.  Otherwise, FAMILY must be a string; it may contain the
     wildcards `?' and `*'.

     The list describes the display that FRAME is on; if FRAME is
     omitted or `nil', it applies to the selected frame's display
     (*note Input Focus::).

     The list contains a vector of the following form for each font:

          [FAMILY WIDTH POINT-SIZE WEIGHT SLANT
           FIXED-P FULL REGISTRY-AND-ENCODING]

     The first five elements correspond to face attributes; if you
     specify these attributes for a face, it will use this font.

     The last three elements give additional information about the font.
     FIXED-P is non-`nil' if the font is fixed-pitch.  FULL is the full
     name of the font, and REGISTRY-AND-ENCODING is a string giving the
     registry and encoding of the font.

     The result list is sorted according to the current face font sort
     order.

 -- Function: x-font-family-list &optional frame
     This function returns a list of the font families available for
     FRAME's display.  If FRAME is omitted or `nil', it describes the
     selected frame's display (*note Input Focus::).

     The value is a list of elements of this form:

          (FAMILY . FIXED-P)

     Here FAMILY is a font family, and FIXED-P is non-`nil' if fonts of
     that family are fixed-pitch.

 -- Variable: font-list-limit
     This variable specifies maximum number of fonts to consider in font
     matching.  The function `x-family-fonts' will not return more than
     that many fonts, and font selection will consider only that many
     fonts when searching a matching font for face attributes.  The
     default is currently 100.


File: elisp,  Node: Fontsets,  Prev: Font Lookup,  Up: Faces

38.12.9 Fontsets
----------------

A "fontset" is a list of fonts, each assigned to a range of character
codes.  An individual font cannot display the whole range of characters
that Emacs supports, but a fontset can.  Fontsets have names, just as
fonts do, and you can use a fontset name in place of a font name when
you specify the "font" for a frame or a face.  Here is information
about defining a fontset under Lisp program control.

 -- Function: create-fontset-from-fontset-spec fontset-spec &optional
          style-variant-p noerror
     This function defines a new fontset according to the specification
     string FONTSET-SPEC.  The string should have this format:

          FONTPATTERN, [CHARSETNAME:FONTNAME]...

     Whitespace characters before and after the commas are ignored.

     The first part of the string, FONTPATTERN, should have the form of
     a standard X font name, except that the last two fields should be
     `fontset-ALIAS'.

     The new fontset has two names, one long and one short.  The long
     name is FONTPATTERN in its entirety.  The short name is
     `fontset-ALIAS'.  You can refer to the fontset by either name.  If
     a fontset with the same name already exists, an error is signaled,
     unless NOERROR is non-`nil', in which case this function does
     nothing.

     If optional argument STYLE-VARIANT-P is non-`nil', that says to
     create bold, italic and bold-italic variants of the fontset as
     well.  These variant fontsets do not have a short name, only a
     long one, which is made by altering FONTPATTERN to indicate the
     bold or italic status.

     The specification string also says which fonts to use in the
     fontset.  See below for the details.

   The construct `CHARSET:FONT' specifies which font to use (in this
fontset) for one particular character set.  Here, CHARSET is the name
of a character set, and FONT is the font to use for that character set.
You can use this construct any number of times in the specification
string.

   For the remaining character sets, those that you don't specify
explicitly, Emacs chooses a font based on FONTPATTERN: it replaces
`fontset-ALIAS' with a value that names one character set.  For the
ASCII character set, `fontset-ALIAS' is replaced with `ISO8859-1'.

   In addition, when several consecutive fields are wildcards, Emacs
collapses them into a single wildcard.  This is to prevent use of
auto-scaled fonts.  Fonts made by scaling larger fonts are not usable
for editing, and scaling a smaller font is not useful because it is
better to use the smaller font in its own size, which Emacs does.

   Thus if FONTPATTERN is this,

     -*-fixed-medium-r-normal-*-24-*-*-*-*-*-fontset-24

the font specification for ASCII characters would be this:

     -*-fixed-medium-r-normal-*-24-*-ISO8859-1

and the font specification for Chinese GB2312 characters would be this:

     -*-fixed-medium-r-normal-*-24-*-gb2312*-*

   You may not have any Chinese font matching the above font
specification.  Most X distributions include only Chinese fonts that
have `song ti' or `fangsong ti' in the FAMILY field.  In such a case,
`Fontset-N' can be specified as below:

     Emacs.Fontset-0: -*-fixed-medium-r-normal-*-24-*-*-*-*-*-fontset-24,\
             chinese-gb2312:-*-*-medium-r-normal-*-24-*-gb2312*-*

Then, the font specifications for all but Chinese GB2312 characters have
`fixed' in the FAMILY field, and the font specification for Chinese
GB2312 characters has a wild card `*' in the FAMILY field.

 -- Function: set-fontset-font name character fontname &optional frame
     This function modifies the existing fontset NAME to use the font
     name FONTNAME for the character CHARACTER.

     If NAME is `nil', this function modifies the default fontset,
     whose short name is `fontset-default'.

     CHARACTER may be a cons; `(FROM . TO)', where FROM and TO are
     non-generic characters.  In that case, use FONTNAME for all
     characters in the range FROM and TO (inclusive).

     CHARACTER may be a charset.  In that case, use FONTNAME for all
     character in the charsets.

     FONTNAME may be a cons; `(FAMILY . REGISTRY)', where FAMILY is a
     family name of a font (possibly including a foundry name at the
     head), REGISTRY is a registry name of a font (possibly including
     an encoding name at the tail).

     For instance, this changes the default fontset to use a font of
     which registry name is `JISX0208.1983' for all characters
     belonging to the charset `japanese-jisx0208'.

          (set-fontset-font nil 'japanese-jisx0208 '(nil . "JISX0208.1983"))

 -- Function: char-displayable-p char
     This function returns `t' if Emacs ought to be able to display
     CHAR.  More precisely, if the selected frame's fontset has a font
     to display the character set that CHAR belongs to.

     Fontsets can specify a font on a per-character basis; when the
     fontset does that, this function's value may not be accurate.


File: elisp,  Node: Fringes,  Next: Scroll Bars,  Prev: Faces,  Up: Display

38.13 Fringes
=============

The "fringes" of a window are thin vertical strips down the sides that
are used for displaying bitmaps that indicate truncation, continuation,
horizontal scrolling, and the overlay arrow.

* Menu:

* Fringe Size/Pos::     Specifying where to put the window fringes.
* Fringe Indicators::   Displaying indicator icons in the window fringes.
* Fringe Cursors::      Displaying cursors in the right fringe.
* Fringe Bitmaps::      Specifying bitmaps for fringe indicators.
* Customizing Bitmaps:: Specifying your own bitmaps to use in the fringes.
* Overlay Arrow::       Display of an arrow to indicate position.


File: elisp,  Node: Fringe Size/Pos,  Next: Fringe Indicators,  Up: Fringes

38.13.1 Fringe Size and Position
--------------------------------

The following buffer-local variables control the position and width of
the window fringes.

 -- Variable: fringes-outside-margins
     The fringes normally appear between the display margins and the
     window text.  If the value is non-`nil', they appear outside the
     display margins.  *Note Display Margins::.

 -- Variable: left-fringe-width
     This variable, if non-`nil', specifies the width of the left
     fringe in pixels.  A value of `nil' means to use the left fringe
     width from the window's frame.

 -- Variable: right-fringe-width
     This variable, if non-`nil', specifies the width of the right
     fringe in pixels.  A value of `nil' means to use the right fringe
     width from the window's frame.

   The values of these variables take effect when you display the
buffer in a window.  If you change them while the buffer is visible,
you can call `set-window-buffer' to display it once again in the same
window, to make the changes take effect.

 -- Function: set-window-fringes window left &optional right
          outside-margins
     This function sets the fringe widths of window WINDOW.  If WINDOW
     is `nil', the selected window is used.

     The argument LEFT specifies the width in pixels of the left
     fringe, and likewise RIGHT for the right fringe.  A value of `nil'
     for either one stands for the default width.  If OUTSIDE-MARGINS
     is non-`nil', that specifies that fringes should appear outside of
     the display margins.

 -- Function: window-fringes &optional window
     This function returns information about the fringes of a window
     WINDOW.  If WINDOW is omitted or `nil', the selected window is
     used.  The value has the form `(LEFT-WIDTH RIGHT-WIDTH
     OUTSIDE-MARGINS)'.


File: elisp,  Node: Fringe Indicators,  Next: Fringe Cursors,  Prev: Fringe Size/Pos,  Up: Fringes

38.13.2 Fringe Indicators
-------------------------

The "fringe indicators" are tiny icons Emacs displays in the window
fringe (on a graphic display) to indicate truncated or continued lines,
buffer boundaries, overlay arrow, etc.

 -- User Option: indicate-empty-lines
     When this is non-`nil', Emacs displays a special glyph in the
     fringe of each empty line at the end of the buffer, on graphical
     displays.  *Note Fringes::.  This variable is automatically
     buffer-local in every buffer.

 -- Variable: indicate-buffer-boundaries
     This buffer-local variable controls how the buffer boundaries and
     window scrolling are indicated in the window fringes.

     Emacs can indicate the buffer boundaries--that is, the first and
     last line in the buffer--with angle icons when they appear on the
     screen.  In addition, Emacs can display an up-arrow in the fringe
     to show that there is text above the screen, and a down-arrow to
     show there is text below the screen.

     There are three kinds of basic values:

    `nil'
          Don't display any of these fringe icons.

    `left'
          Display the angle icons and arrows in the left fringe.

    `right'
          Display the angle icons and arrows in the right fringe.

    any non-alist
          Display the angle icons in the left fringe and don't display
          the arrows.

     Otherwise the value should be an alist that specifies which fringe
     indicators to display and where.  Each element of the alist should
     have the form `(INDICATOR . POSITION)'.  Here, INDICATOR is one of
     `top', `bottom', `up', `down', and `t' (which covers all the icons
     not yet specified), while POSITION is one of `left', `right' and
     `nil'.

     For example, `((top . left) (t . right))' places the top angle
     bitmap in left fringe, and the bottom angle bitmap as well as both
     arrow bitmaps in right fringe.  To show the angle bitmaps in the
     left fringe, and no arrow bitmaps, use `((top .  left) (bottom .
     left))'.

 -- Variable: default-indicate-buffer-boundaries
     The value of this variable is the default value for
     `indicate-buffer-boundaries' in buffers that do not override it.

 -- Variable: fringe-indicator-alist
     This buffer-local variable specifies the mapping from logical
     fringe indicators to the actual bitmaps displayed in the window
     fringes.

     These symbols identify the logical fringe indicators:

    Truncation and continuation line indicators:
          `truncation', `continuation'.

    Buffer position indicators:
          `up', `down', `top', `bottom', `top-bottom'.

    Empty line indicator:
          `empty-line'.

    Overlay arrow indicator:
          `overlay-arrow'.

    Unknown bitmap indicator:
          `unknown'.

     The value is an alist where each element `(INDICATOR . BITMAPS)'
     specifies the fringe bitmaps used to display a specific logical
     fringe indicator.

     Here, INDICATOR specifies the logical indicator type, and BITMAPS
     is list of symbols `(LEFT RIGHT [LEFT1 RIGHT1])' which specifies
     the actual bitmap shown in the left or right fringe for the
     logical indicator.

     The LEFT and RIGHT symbols specify the bitmaps shown in the left
     and/or right fringe for the specific indicator.  The LEFT1 or
     RIGHT1 bitmaps are used only for the `bottom' and `top-bottom
     indicators when the last (only) line in has no final newline.
     Alternatively, BITMAPS may be a single symbol which is used in
     both left and right fringes.

     When `fringe-indicator-alist' has a buffer-local value, and there
     is no bitmap defined for a logical indicator, or the bitmap is
     `t', the corresponding value from the (non-local)
     `default-fringe-indicator-alist' is used.

     To completely hide a specific indicator, set the bitmap to `nil'.

 -- Variable: default-fringe-indicator-alist
     The value of this variable is the default value for
     `fringe-indicator-alist' in buffers that do not override it.

   Standard fringe bitmaps for indicators:
     left-arrow right-arrow up-arrow down-arrow
     left-curly-arrow right-curly-arrow
     left-triangle right-triangle
     top-left-angle top-right-angle
     bottom-left-angle bottom-right-angle
     left-bracket right-bracket
     filled-rectangle hollow-rectangle
     filled-square hollow-square
     vertical-bar horizontal-bar
     empty-line question-mark


File: elisp,  Node: Fringe Cursors,  Next: Fringe Bitmaps,  Prev: Fringe Indicators,  Up: Fringes

38.13.3 Fringe Cursors
----------------------

When a line is exactly as wide as the window, Emacs displays the cursor
in the right fringe instead of using two lines.  Different bitmaps are
used to represent the cursor in the fringe depending on the current
buffer's cursor type.

Logical cursor types:
     `box' , `hollow', `bar', `hbar', `hollow-small'.

   The `hollow-small' type is used instead of `hollow' when the normal
`hollow-rectangle' bitmap is too tall to fit on a specific display line.

 -- Variable: overflow-newline-into-fringe
     If this is non-`nil', lines exactly as wide as the window (not
     counting the final newline character) are not continued.  Instead,
     when point is at the end of the line, the cursor appears in the
     right fringe.

 -- Variable: fringe-cursor-alist
     This variable specifies the mapping from logical cursor type to the
     actual fringe bitmaps displayed in the right fringe.  The value is
     an alist where each element `(CURSOR . BITMAP)' specifies the
     fringe bitmaps used to display a specific logical cursor type in
     the fringe.  Here, CURSOR specifies the logical cursor type and
     BITMAP is a symbol specifying the fringe bitmap to be displayed
     for that logical cursor type.

     When `fringe-cursor-alist' has a buffer-local value, and there is
     no bitmap defined for a cursor type, the corresponding value from
     the (non-local) `default-fringes-indicator-alist' is used.

 -- Variable: default-fringes-cursor-alist
     The value of this variable is the default value for
     `fringe-cursor-alist' in buffers that do not override it.

   Standard bitmaps for displaying the cursor in right fringe:
     filled-rectangle hollow-rectangle filled-square hollow-square
     vertical-bar horizontal-bar


File: elisp,  Node: Fringe Bitmaps,  Next: Customizing Bitmaps,  Prev: Fringe Cursors,  Up: Fringes

38.13.4 Fringe Bitmaps
----------------------

The "fringe bitmaps" are the actual bitmaps which represent the logical
fringe indicators for truncated or continued lines, buffer boundaries,
overlay arrow, etc.  Fringe bitmap symbols have their own name space.
The fringe bitmaps are shared by all frames and windows.  You can
redefine the built-in fringe bitmaps, and you can define new fringe
bitmaps.

   The way to display a bitmap in the left or right fringes for a given
line in a window is by specifying the `display' property for one of the
characters that appears in it.  Use a display specification of the form
`(left-fringe BITMAP [FACE])' or `(right-fringe BITMAP [FACE])' (*note
Display Property::).  Here, BITMAP is a symbol identifying the bitmap
you want, and FACE (which is optional) is the name of the face whose
colors should be used for displaying the bitmap, instead of the default
`fringe' face.  FACE is automatically merged with the `fringe' face, so
normally FACE need only specify the foreground color for the bitmap.

 -- Function: fringe-bitmaps-at-pos &optional pos window
     This function returns the fringe bitmaps of the display line
     containing position POS in window WINDOW.  The return value has
     the form `(LEFT RIGHT OV)', where LEFT is the symbol for the
     fringe bitmap in the left fringe (or `nil' if no bitmap), RIGHT is
     similar for the right fringe, and OV is non-`nil' if there is an
     overlay arrow in the left fringe.

     The value is `nil' if POS is not visible in WINDOW.  If WINDOW is
     `nil', that stands for the selected window.  If POS is `nil', that
     stands for the value of point in WINDOW.


File: elisp,  Node: Customizing Bitmaps,  Next: Overlay Arrow,  Prev: Fringe Bitmaps,  Up: Fringes

38.13.5 Customizing Fringe Bitmaps
----------------------------------

 -- Function: define-fringe-bitmap bitmap bits &optional height width
          align
     This function defines the symbol BITMAP as a new fringe bitmap, or
     replaces an existing bitmap with that name.

     The argument BITS specifies the image to use.  It should be either
     a string or a vector of integers, where each element (an integer)
     corresponds to one row of the bitmap.  Each bit of an integer
     corresponds to one pixel of the bitmap, where the low bit
     corresponds to the rightmost pixel of the bitmap.

     The height is normally the length of BITS.  However, you can
     specify a different height with non-`nil' HEIGHT.  The width is
     normally 8, but you can specify a different width with non-`nil'
     WIDTH.  The width must be an integer between 1 and 16.

     The argument ALIGN specifies the positioning of the bitmap
     relative to the range of rows where it is used; the default is to
     center the bitmap.  The allowed values are `top', `center', or
     `bottom'.

     The ALIGN argument may also be a list `(ALIGN PERIODIC)' where
     ALIGN is interpreted as described above.  If PERIODIC is
     non-`nil', it specifies that the rows in `bits' should be repeated
     enough times to reach the specified height.

 -- Function: destroy-fringe-bitmap bitmap
     This function destroy the fringe bitmap identified by BITMAP.  If
     BITMAP identifies a standard fringe bitmap, it actually restores
     the standard definition of that bitmap, instead of eliminating it
     entirely.

 -- Function: set-fringe-bitmap-face bitmap &optional face
     This sets the face for the fringe bitmap BITMAP to FACE.  If FACE
     is `nil', it selects the `fringe' face.  The bitmap's face
     controls the color to draw it in.

     FACE is merged with the `fringe' face, so normally FACE should
     specify only the foreground color.


File: elisp,  Node: Overlay Arrow,  Prev: Customizing Bitmaps,  Up: Fringes

38.13.6 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.  This feature has nothing to do with "overlays"
(*note Overlays::).

 -- 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.  On
     a graphical display the contents of the string are ignored;
     instead a glyph is displayed in the fringe area to the left of the
     display area.

 -- 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.  On a
     non-graphical display 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-arrow string is displayed in any given buffer if the
     value of `overlay-arrow-position' in that buffer points into that
     buffer.  Thus, it works to can display multiple overlay arrow
     strings by creating buffer-local bindings of
     `overlay-arrow-position'.  However, it is usually cleaner to use
     `overlay-arrow-variable-list' to achieve this result.

   You can do a similar job by creating an overlay with a
`before-string' property.  *Note Overlay Properties::.

   You can define multiple overlay arrows via the variable
`overlay-arrow-variable-list'.

 -- Variable: overlay-arrow-variable-list
     This variable's value is a list of variables, each of which
     specifies the position of an overlay arrow.  The variable
     `overlay-arrow-position' has its normal meaning because it is on
     this list.

   Each variable on this list can have properties
`overlay-arrow-string' and `overlay-arrow-bitmap' that specify an
overlay arrow string (for text-only terminals) or fringe bitmap (for
graphical terminals) to display at the corresponding overlay arrow
position.  If either property is not set, the default
`overlay-arrow-string' or `overlay-arrow' fringe indicator is used.


File: elisp,  Node: Scroll Bars,  Next: Display Property,  Prev: Fringes,  Up: Display

38.14 Scroll Bars
=================

Normally the frame parameter `vertical-scroll-bars' controls whether
the windows in the frame have vertical scroll bars, and whether they
are on the left or right.  The frame parameter `scroll-bar-width'
specifies how wide they are (`nil' meaning the default).  *Note Layout
Parameters::.

 -- Function: frame-current-scroll-bars &optional frame
     This function reports the scroll bar type settings for frame
     FRAME.  The value is a cons cell `(VERTICAL-TYPE .
     HORIZONTAL-TYPE)', where VERTICAL-TYPE is either `left', `right',
     or `nil' (which means no scroll bar.)  HORIZONTAL-TYPE is meant to
     specify the horizontal scroll bar type, but since they are not
     implemented, it is always `nil'.

   You can enable or disable scroll bars for a particular buffer, by
setting the variable `vertical-scroll-bar'.  This variable
automatically becomes buffer-local when set.  The possible values are
`left', `right', `t', which means to use the frame's default, and `nil'
for no scroll bar.

   You can also control this for individual windows.  Call the function
`set-window-scroll-bars' to specify what to do for a specific window:

 -- Function: set-window-scroll-bars window width &optional
          vertical-type horizontal-type
     This function sets the width and type of scroll bars for window
     WINDOW.

     WIDTH specifies the scroll bar width in pixels (`nil' means use
     the width specified for the frame).  VERTICAL-TYPE specifies
     whether to have a vertical scroll bar and, if so, where.  The
     possible values are `left', `right' and `nil', just like the
     values of the `vertical-scroll-bars' frame parameter.

     The argument HORIZONTAL-TYPE is meant to specify whether and where
     to have horizontal scroll bars, but since they are not
     implemented, it has no effect.  If WINDOW is `nil', the selected
     window is used.

 -- Function: window-scroll-bars &optional window
     Report the width and type of scroll bars specified for WINDOW.  If
     WINDOW is omitted or `nil', the selected window is used.  The
     value is a list of the form `(WIDTH COLS VERTICAL-TYPE
     HORIZONTAL-TYPE)'.  The value WIDTH is the value that was
     specified for the width (which may be `nil'); COLS is the number
     of columns that the scroll bar actually occupies.

     HORIZONTAL-TYPE is not actually meaningful.

   If you don't specify these values for a window with
`set-window-scroll-bars', the buffer-local variables `scroll-bar-mode'
and `scroll-bar-width' in the buffer being displayed control the
window's vertical scroll bars.  The function `set-window-buffer'
examines these variables.  If you change them in a buffer that is
already visible in a window, you can make the window take note of the
new values by calling `set-window-buffer' specifying the same buffer
that is already displayed.

 -- Variable: scroll-bar-mode
     This variable, always local in all buffers, controls whether and
     where to put scroll bars in windows displaying the buffer.  The
     possible values are `nil' for no scroll bar, `left' to put a
     scroll bar on the left, and `right' to put a scroll bar on the
     right.

 -- Function: window-current-scroll-bars &optional window
     This function reports the scroll bar type for window WINDOW.  If
     WINDOW is omitted or `nil', the selected window is used.  The
     value is a cons cell `(VERTICAL-TYPE . HORIZONTAL-TYPE)'.  Unlike
     `window-scroll-bars', this reports the scroll bar type actually
     used, once frame defaults and `scroll-bar-mode' are taken into
     account.

 -- Variable: scroll-bar-width
     This variable, always local in all buffers, specifies the width of
     the buffer's scroll bars, measured in pixels.  A value of `nil'
     means to use the value specified by the frame.


File: elisp,  Node: Display Property,  Next: Images,  Prev: Scroll Bars,  Up: Display

38.15 The `display' Property
============================

The `display' text property (or overlay property) is used to insert
images into text, and also control other aspects of how text displays.
The value of the `display' property should be a display specification,
or a list or vector containing several display specifications.  Display
specifications in the same `display' property value generally apply in
parallel to the text they cover.

   If several sources (overlays and/or a text property) specify values
for the `display' property, only one of the values takes effect,
following the rules of `get-char-property'.  *Note Examining
Properties::.

   The rest of this section describes several kinds of display
specifications and what they mean.

* Menu:

* Replacing Specs::      Display specs that replace the text.
* Specified Space::      Displaying one space with a specified width.
* Pixel Specification::  Specifying space width or height in pixels.
* Other Display Specs::  Displaying an image; magnifying text; moving it
                          up or down on the page; adjusting the width
                          of spaces within text.
* Display Margins::     Displaying text or images to the side of the main text.


File: elisp,  Node: Replacing Specs,  Next: Specified Space,  Up: Display Property

38.15.1 Display Specs That Replace The Text
-------------------------------------------

Some kinds of `display' specifications specify something to display
instead of the text that has the property.  These are called
"replacing" display specifications.  Emacs does not allow the user to
interactively move point into the middle of buffer text that is
replaced in this way.

   If a list of display specifications includes more than one replacing
display specification, the first overrides the rest.  Replacing display
specifications make most other display specifications irrelevant, since
those don't apply to the replacement.

   For replacing display specifications, "the text that has the
property" means all the consecutive characters that have the same Lisp
object as their `display' property; these characters are replaced as a
single unit.  By contrast, characters that have similar but distinct
Lisp objects as their `display' properties are handled separately.
Here's a function that illustrates this point:

     (defun foo ()
       (goto-char (point-min))
       (dotimes (i 5)
         (let ((string (concat "A")))
           (put-text-property (point) (1+ (point)) 'display string)
           (forward-char 1)
           (put-text-property (point) (1+ (point)) 'display string)
           (forward-char 1))))

It gives each of the first ten characters in the buffer string `"A"' as
the `display' property, but they don't all get the same string.  The
first two characters get the same string, so they together are replaced
with one `A'.  The next two characters get a second string, so they
together are replaced with one `A'.  Likewise for each following pair
of characters.  Thus, the ten characters appear as five A's.  This
function would have the same results:

     (defun foo ()
       (goto-char (point-min))
       (dotimes (i 5)
         (let ((string (concat "A")))
           (put-text-property (point) (+ 2 (point)) 'display string)
           (put-text-property (point) (1+ (point)) 'display string)
           (forward-char 2))))

This illustrates that what matters is the property value for each
character.  If two consecutive characters have the same object as the
`display' property value, it's irrelevant whether they got this
property from a single call to `put-text-property' or from two
different calls.


File: elisp,  Node: Specified Space,  Next: Pixel Specification,  Prev: Replacing Specs,  Up: Display Property

38.15.2 Specified Spaces
------------------------

To display a space of specified width and/or height, use a display
specification of the form `(space . PROPS)', where PROPS is a property
list (a list of alternating properties and values).  You can put this
property on one or more consecutive characters; a space of the
specified height and width is displayed in place of _all_ of those
characters.  These are the properties you can use in PROPS to specify
the weight of the space:

`:width WIDTH'
     If WIDTH is an integer or floating point number, it specifies that
     the space width should be WIDTH times the normal character width.
     WIDTH can also be a "pixel width" specification (*note Pixel
     Specification::).

`:relative-width FACTOR'
     Specifies that the width of the stretch should be computed from the
     first character in the group of consecutive characters that have
     the same `display' property.  The space width is the width of that
     character, multiplied by FACTOR.

`:align-to HPOS'
     Specifies that the space should be wide enough to reach HPOS.  If
     HPOS is a number, it is measured in units of the normal character
     width.  HPOS can also be a "pixel width" specification (*note
     Pixel Specification::).

   You should use one and only one of the above properties.  You can
also specify the height of the space, with these properties:

`:height HEIGHT'
     Specifies the height of the space.  If HEIGHT is an integer or
     floating point number, it specifies that the space height should
     be HEIGHT times the normal character height.  The HEIGHT may also
     be a "pixel height" specification (*note Pixel Specification::).

`:relative-height FACTOR'
     Specifies the height of the space, multiplying the ordinary height
     of the text having this display specification by FACTOR.

`:ascent ASCENT'
     If the value of ASCENT is a non-negative number no greater than
     100, it specifies that ASCENT percent of the height of the space
     should be considered as the ascent of the space--that is, the part
     above the baseline.  The ascent may also be specified in pixel
     units with a "pixel ascent" specification (*note Pixel
     Specification::).


   Don't use both `:height' and `:relative-height' together.

   The `:width' and `:align-to' properties are supported on non-graphic
terminals, but the other space properties in this section are not.


File: elisp,  Node: Pixel Specification,  Next: Other Display Specs,  Prev: Specified Space,  Up: Display Property

38.15.3 Pixel Specification for Spaces
--------------------------------------

The value of the `:width', `:align-to', `:height', and `:ascent'
properties can be a special kind of expression that is evaluated during
redisplay.  The result of the evaluation is used as an absolute number
of pixels.

   The following expressions are supported:

       EXPR ::= NUM | (NUM) | UNIT | ELEM | POS | IMAGE | FORM
       NUM  ::= INTEGER | FLOAT | SYMBOL
       UNIT ::= in | mm | cm | width | height
       ELEM ::= left-fringe | right-fringe | left-margin | right-margin
             |  scroll-bar | text
       POS  ::= left | center | right
       FORM ::= (NUM . EXPR) | (OP EXPR ...)
       OP   ::= + | -

   The form NUM specifies a fraction of the default frame font height
or width.  The form `(NUM)' specifies an absolute number of pixels.  If
NUM is a symbol, SYMBOL, its buffer-local variable binding is used.

   The `in', `mm', and `cm' units specify the number of pixels per
inch, millimeter, and centimeter, respectively.  The `width' and
`height' units correspond to the default width and height of the
current face.  An image specification `image' corresponds to the width
or height of the image.

   The `left-fringe', `right-fringe', `left-margin', `right-margin',
`scroll-bar', and `text' elements specify to the width of the
corresponding area of the window.

   The `left', `center', and `right' positions can be used with
`:align-to' to specify a position relative to the left edge, center, or
right edge of the text area.

   Any of the above window elements (except `text') can also be used
with `:align-to' to specify that the position is relative to the left
edge of the given area.  Once the base offset for a relative position
has been set (by the first occurrence of one of these symbols), further
occurrences of these symbols are interpreted as the width of the
specified area.  For example, to align to the center of the
left-margin, use

     :align-to (+ left-margin (0.5 . left-margin))

   If no specific base offset is set for alignment, it is always
relative to the left edge of the text area.  For example, `:align-to 0'
in a header-line aligns with the first text column in the text area.

   A value of the form `(NUM . EXPR)' stands for the product of the
values of NUM and EXPR.  For example, `(2 . in)' specifies a width of 2
inches, while `(0.5 .  IMAGE)' specifies half the width (or height) of
the specified image.

   The form `(+ EXPR ...)' adds up the value of the expressions.  The
form `(- EXPR ...)' negates or subtracts the value of the expressions.


File: elisp,  Node: Other Display Specs,  Next: Display Margins,  Prev: Pixel Specification,  Up: Display Property

38.15.4 Other Display Specifications
------------------------------------

Here are the other sorts of display specifications that you can use in
the `display' text property.

`STRING'
     Display STRING instead of the text that has this property.

     Recursive display specifications are not supported--STRING's
     `display' properties, if any, are not used.

`(image . IMAGE-PROPS)'
     This kind of display specification is an image descriptor (*note
     Images::).  When used as a display specification, it means to
     display the image instead of the text that has the display
     specification.

`(slice X Y WIDTH HEIGHT)'
     This specification together with `image' specifies a "slice" (a
     partial area) of the image to display.  The elements Y and X
     specify the top left corner of the slice, within the image; WIDTH
     and HEIGHT specify the width and height of the slice.  Integer
     values are numbers of pixels.  A floating point number in the
     range 0.0-1.0 stands for that fraction of the width or height of
     the entire image.

`((margin nil) STRING)'
     A display specification of this form means to display STRING
     instead of the text that has the display specification, at the same
     position as that text.  It is equivalent to using just STRING, but
     it is done as a special case of marginal display (*note Display
     Margins::).

`(space-width FACTOR)'
     This display specification affects all the space characters within
     the text that has the specification.  It displays all of these
     spaces FACTOR times as wide as normal.  The element FACTOR should
     be an integer or float.  Characters other than spaces are not
     affected at all; in particular, this has no effect on tab
     characters.

`(height HEIGHT)'
     This display specification makes the text taller or shorter.  Here
     are the possibilities for HEIGHT:

    `(+ N)'
          This means to use a font that is N steps larger.  A "step" is
          defined by the set of available fonts--specifically, those
          that match what was otherwise specified for this text, in all
          attributes except height.  Each size for which a suitable
          font is available counts as another step.  N should be an
          integer.

    `(- N)'
          This means to use a font that is N steps smaller.

    a number, FACTOR
          A number, FACTOR, means to use a font that is FACTOR times as
          tall as the default font.

    a symbol, FUNCTION
          A symbol is a function to compute the height.  It is called
          with the current height as argument, and should return the
          new height to use.

    anything else, FORM
          If the HEIGHT value doesn't fit the previous possibilities,
          it is a form.  Emacs evaluates it to get the new height, with
          the symbol `height' bound to the current specified font
          height.

`(raise FACTOR)'
     This kind of display specification raises or lowers the text it
     applies to, relative to the baseline of the line.

     FACTOR must be a number, which is interpreted as a multiple of the
     height of the affected text.  If it is positive, that means to
     display the characters raised.  If it is negative, that means to
     display them lower down.

     If the text also has a `height' display specification, that does
     not affect the amount of raising or lowering, which is based on the
     faces used for the text.

   You can make any display specification conditional.  To do that,
package it in another list of the form `(when CONDITION . SPEC)'.  Then
the specification SPEC applies only when CONDITION evaluates to a
non-`nil' value.  During the evaluation, `object' is bound to the
string or buffer having the conditional `display' property.  `position'
and `buffer-position' are bound to the position within `object' and the
buffer position where the `display' property was found, respectively.
Both positions can be different when `object' is a string.


File: elisp,  Node: Display Margins,  Prev: Other Display Specs,  Up: Display Property

38.15.5 Displaying in the Margins
---------------------------------

A buffer can have blank areas called "display margins" on the left and
on the right.  Ordinary text never appears in these areas, but you can
put things into the display margins using the `display' property.
There is currently no way to make text or images in the margin
mouse-sensitive.

   The way to display something in the margins is to specify it in a
margin display specification in the `display' property of some text.
This is a replacing display specification, meaning that the text you
put it on does not get displayed; the margin display appears, but that
text does not.

   A margin display specification looks like `((margin right-margin)
SPEC' or `((margin left-margin) SPEC)'.  Here, SPEC is another display
specification that says what to display in the margin.  Typically it is
a string of text to display, or an image descriptor.

   To display something in the margin _in association with_ certain
buffer text, without altering or preventing the display of that text,
put a `before-string' property on the text and put the margin display
specification on the contents of the before-string.

   Before the display margins can display anything, you must give them
a nonzero width.  The usual way to do that is to set these variables:

 -- Variable: left-margin-width
     This variable specifies the width of the left margin.  It is
     buffer-local in all buffers.

 -- Variable: right-margin-width
     This variable specifies the width of the right margin.  It is
     buffer-local in all buffers.

   Setting these variables does not immediately affect the window.
These variables are checked when a new buffer is displayed in the
window.  Thus, you can make changes take effect by calling
`set-window-buffer'.

   You can also set the margin widths immediately.

 -- Function: set-window-margins window left &optional right
     This function specifies the margin widths for window WINDOW.  The
     argument LEFT controls the left margin and RIGHT controls the
     right margin (default `0').

 -- Function: window-margins &optional window
     This function returns the left and right margins of WINDOW as a
     cons cell of the form `(LEFT . RIGHT)'.  If WINDOW is `nil', the
     selected window is used.


File: elisp,  Node: Images,  Next: Buttons,  Prev: Display Property,  Up: Display

38.16 Images
============

To display an image in an Emacs buffer, you must first create an image
descriptor, then use it as a display specifier in the `display'
property of text that is displayed (*note Display Property::).

   Emacs is usually able to display images when it is run on a
graphical terminal.  Images cannot be displayed in a text terminal, on
certain graphical terminals that lack the support for this, or if Emacs
is compiled without image support.  You can use the function
`display-images-p' to determine if images can in principle be displayed
(*note Display Feature Testing::).

   Emacs can display a number of different image formats; some of them
are supported only if particular support libraries are installed on
your machine.  In some environments, Emacs can load image libraries on
demand; if so, the variable `image-library-alist' can be used to modify
the set of known names for these dynamic libraries (though it is not
possible to add new image formats).

   The supported image formats include XBM, XPM (this requires the
libraries `libXpm' version 3.4k and `libz'), GIF (requiring `libungif'
4.1.0), PostScript, PBM, JPEG (requiring the `libjpeg' library version
v6a), TIFF (requiring `libtiff' v3.4), and PNG (requiring `libpng'
1.0.2).

   You specify one of these formats with an image type symbol.  The
image type symbols are `xbm', `xpm', `gif', `postscript', `pbm',
`jpeg', `tiff', and `png'.

 -- Variable: image-types
     This variable contains a list of those image type symbols that are
     potentially supported in the current configuration.  _Potentially_
     here means that Emacs knows about the image types, not necessarily
     that they can be loaded (they could depend on unavailable dynamic
     libraries, for example).

     To know which image types are really available, use
     `image-type-available-p'.

 -- Variable: image-library-alist
     This in an alist of image types vs external libraries needed to
     display them.

     Each element is a list `(IMAGE-TYPE LIBRARY...)', where the car is
     a supported image format from `image-types', and the rest are
     strings giving alternate filenames for the corresponding external
     libraries to load.

     Emacs tries to load the libraries in the order they appear on the
     list; if none is loaded, the running session of Emacs won't support
     the image type.  `pbm' and `xbm' don't need to be listed; they're
     always supported.

     This variable is ignored if the image libraries are statically
     linked into Emacs.

 -- Function: image-type-available-p type
     This function returns non-`nil' if image type TYPE is available,
     i.e., if images of this type can be loaded and displayed in Emacs.
     TYPE should be one of the types contained in `image-types'.

     For image types whose support libraries are statically linked, this
     function always returns `t'; for other image types, it returns `t'
     if the dynamic library could be loaded, `nil' otherwise.

* Menu:

* Image Descriptors::   How to specify an image for use in `:display'.
* XBM Images::          Special features for XBM format.
* XPM Images::          Special features for XPM format.
* GIF Images::          Special features for GIF format.
* PostScript Images::   Special features for PostScript format.
* Other Image Types::   Various other formats are supported.
* Defining Images::     Convenient ways to define an image for later use.
* Showing Images::      Convenient ways to display an image once it is defined.
* Image Cache::         Internal mechanisms of image display.


File: elisp,  Node: Image Descriptors,  Next: XBM Images,  Up: Images

38.16.1 Image Descriptors
-------------------------

An image description is a list of the form `(image . PROPS)', where
PROPS is a property list containing alternating keyword symbols
(symbols whose names start with a colon) and their values.  You can use
any Lisp object as a property, but the only properties that have any
special meaning are certain symbols, all of them keywords.

   Every image descriptor must contain the property `:type TYPE' to
specify the format of the image.  The value of TYPE should be an image
type symbol; for example, `xpm' for an image in XPM format.

   Here is a list of other properties that are meaningful for all image
types:

`:file FILE'
     The `:file' property says to load the image from file FILE.  If
     FILE is not an absolute file name, it is expanded in
     `data-directory'.

`:data DATA'
     The `:data' property says the actual contents of the image.  Each
     image must use either `:data' or `:file', but not both.  For most
     image types, the value of the `:data' property should be a string
     containing the image data; we recommend using a unibyte string.

     Before using `:data', look for further information in the section
     below describing the specific image format.  For some image types,
     `:data' may not be supported; for some, it allows other data types;
     for some, `:data' alone is not enough, so you need to use other
     image properties along with `:data'.

`:margin MARGIN'
     The `:margin' property specifies how many pixels to add as an
     extra margin around the image.  The value, MARGIN, must be a
     non-negative number, or a pair `(X . Y)' of such numbers.  If it
     is a pair, X specifies how many pixels to add horizontally, and Y
     specifies how many pixels to add vertically.  If `:margin' is not
     specified, the default is zero.

`:ascent ASCENT'
     The `:ascent' property specifies the amount of the image's height
     to use for its ascent--that is, the part above the baseline.  The
     value, ASCENT, must be a number in the range 0 to 100, or the
     symbol `center'.

     If ASCENT is a number, that percentage of the image's height is
     used for its ascent.

     If ASCENT is `center', the image is vertically centered around a
     centerline which would be the vertical centerline of text drawn at
     the position of the image, in the manner specified by the text
     properties and overlays that apply to the image.

     If this property is omitted, it defaults to 50.

`:relief RELIEF'
     The `:relief' property, if non-`nil', adds a shadow rectangle
     around the image.  The value, RELIEF, specifies the width of the
     shadow lines, in pixels.  If RELIEF is negative, shadows are drawn
     so that the image appears as a pressed button; otherwise, it
     appears as an unpressed button.

`:conversion ALGORITHM'
     The `:conversion' property, if non-`nil', specifies a conversion
     algorithm that should be applied to the image before it is
     displayed; the value, ALGORITHM, specifies which algorithm.

    `laplace'
    `emboss'
          Specifies the Laplace edge detection algorithm, which blurs
          out small differences in color while highlighting larger
          differences.  People sometimes consider this useful for
          displaying the image for a "disabled" button.

    `(edge-detection :matrix MATRIX :color-adjust ADJUST)'
          Specifies a general edge-detection algorithm.  MATRIX must be
          either a nine-element list or a nine-element vector of
          numbers.  A pixel at position x/y in the transformed image is
          computed from original pixels around that position.  MATRIX
          specifies, for each pixel in the neighborhood of x/y, a
          factor with which that pixel will influence the transformed
          pixel; element 0 specifies the factor for the pixel at
          x-1/y-1, element 1 the factor for the pixel at x/y-1 etc., as
          shown below:
                 (x-1/y-1  x/y-1  x+1/y-1
                  x-1/y    x/y    x+1/y
                  x-1/y+1  x/y+1  x+1/y+1)

          The resulting pixel is computed from the color intensity of
          the color resulting from summing up the RGB values of
          surrounding pixels, multiplied by the specified factors, and
          dividing that sum by the sum of the factors' absolute values.

          Laplace edge-detection currently uses a matrix of
                 (1  0  0
                  0  0  0
                  9  9 -1)

          Emboss edge-detection uses a matrix of
                 ( 2 -1  0
                  -1  0  1
                   0  1 -2)

    `disabled'
          Specifies transforming the image so that it looks "disabled."

`:mask MASK'
     If MASK is `heuristic' or `(heuristic BG)', build a clipping mask
     for the image, so that the background of a frame is visible behind
     the image.  If BG is not specified, or if BG is `t', determine the
     background color of the image by looking at the four corners of
     the image, assuming the most frequently occurring color from the
     corners is the background color of the image.  Otherwise, BG must
     be a list `(RED GREEN BLUE)' specifying the color to assume for
     the background of the image.

     If MASK is `nil', remove a mask from the image, if it has one.
     Images in some formats include a mask which can be removed by
     specifying `:mask nil'.

`:pointer SHAPE'
     This specifies the pointer shape when the mouse pointer is over
     this image.  *Note Pointer Shape::, for available pointer shapes.

`:map MAP'
     This associates an image map of "hot spots" with this image.

     An image map is an alist where each element has the format `(AREA
     ID PLIST)'.  An AREA is specified as either a rectangle, a circle,
     or a polygon.

     A rectangle is a cons `(rect . ((X0 . Y0) . (X1 . Y1)))' which
     specifies the pixel coordinates of the upper left and bottom right
     corners of the rectangle area.

     A circle is a cons `(circle . ((X0 . Y0) . R))' which specifies
     the center and the radius of the circle; R may be a float or
     integer.

     A polygon is a cons `(poly . [X0 Y0 X1 Y1 ...])' where each pair
     in the vector describes one corner in the polygon.

     When the mouse pointer lies on a hot-spot area of an image, the
     PLIST of that hot-spot is consulted; if it contains a `help-echo'
     property, that defines a tool-tip for the hot-spot, and if it
     contains a `pointer' property, that defines the shape of the mouse
     cursor when it is on the hot-spot.  *Note Pointer Shape::, for
     available pointer shapes.

     When you click the mouse when the mouse pointer is over a
     hot-spot, an event is composed by combining the ID of the hot-spot
     with the mouse event; for instance, `[area4 mouse-1]' if the
     hot-spot's ID is `area4'.

 -- Function: image-mask-p spec &optional frame
     This function returns `t' if image SPEC has a mask bitmap.  FRAME
     is the frame on which the image will be displayed.  FRAME `nil' or
     omitted means to use the selected frame (*note Input Focus::).


File: elisp,  Node: XBM Images,  Next: XPM Images,  Prev: Image Descriptors,  Up: Images

38.16.2 XBM Images
------------------

To use XBM format, specify `xbm' as the image type.  This image format
doesn't require an external library, so images of this type are always
supported.

   Additional image properties supported for the `xbm' image type are:

`:foreground FOREGROUND'
     The value, FOREGROUND, should be a string specifying the image
     foreground color, or `nil' for the default color.  This color is
     used for each pixel in the XBM that is 1.  The default is the
     frame's foreground color.

`:background BACKGROUND'
     The value, BACKGROUND, should be a string specifying the image
     background color, or `nil' for the default color.  This color is
     used for each pixel in the XBM that is 0.  The default is the
     frame's background color.

   If you specify an XBM image using data within Emacs instead of an
external file, use the following three properties:

`:data DATA'
     The value, DATA, specifies the contents of the image.  There are
     three formats you can use for DATA:

        * A vector of strings or bool-vectors, each specifying one line
          of the image.  Do specify `:height' and `:width'.

        * A string containing the same byte sequence as an XBM file
          would contain.  You must not specify `:height' and `:width'
          in this case, because omitting them is what indicates the
          data has the format of an XBM file.  The file contents
          specify the height and width of the image.

        * A string or a bool-vector containing the bits of the image
          (plus perhaps some extra bits at the end that will not be
          used).  It should contain at least WIDTH * `height' bits.  In
          this case, you must specify `:height' and `:width', both to
          indicate that the string contains just the bits rather than a
          whole XBM file, and to specify the size of the image.

`:width WIDTH'
     The value, WIDTH, specifies the width of the image, in pixels.

`:height HEIGHT'
     The value, HEIGHT, specifies the height of the image, in pixels.


File: elisp,  Node: XPM Images,  Next: GIF Images,  Prev: XBM Images,  Up: Images

38.16.3 XPM Images
------------------

To use XPM format, specify `xpm' as the image type.  The additional
image property `:color-symbols' is also meaningful with the `xpm' image
type:

`:color-symbols SYMBOLS'
     The value, SYMBOLS, should be an alist whose elements have the
     form `(NAME . COLOR)'.  In each element, NAME is the name of a
     color as it appears in the image file, and COLOR specifies the
     actual color to use for displaying that name.


File: elisp,  Node: GIF Images,  Next: PostScript Images,  Prev: XPM Images,  Up: Images

38.16.4 GIF Images
------------------

For GIF images, specify image type `gif'.

`:index INDEX'
     You can use `:index' to specify one image from a GIF file that
     contains more than one image.  This property specifies use of image
     number INDEX from the file.  If the GIF file doesn't contain an
     image with index INDEX, the image displays as a hollow box.


File: elisp,  Node: PostScript Images,  Next: Other Image Types,  Prev: GIF Images,  Up: Images

38.16.5 PostScript Images
-------------------------

To use PostScript for an image, specify image type `postscript'.  This
works only if you have Ghostscript installed.  You must always use
these three properties:

`:pt-width WIDTH'
     The value, WIDTH, specifies the width of the image measured in
     points (1/72 inch).  WIDTH must be an integer.

`:pt-height HEIGHT'
     The value, HEIGHT, specifies the height of the image in points
     (1/72 inch).  HEIGHT must be an integer.

`:bounding-box BOX'
     The value, BOX, must be a list or vector of four integers, which
     specifying the bounding box of the PostScript image, analogous to
     the `BoundingBox' comment found in PostScript files.

          %%BoundingBox: 22 171 567 738

   Displaying PostScript images from Lisp data is not currently
implemented, but it may be implemented by the time you read this.  See
the `etc/NEWS' file to make sure.


File: elisp,  Node: Other Image Types,  Next: Defining Images,  Prev: PostScript Images,  Up: Images

38.16.6 Other Image Types
-------------------------

For PBM images, specify image type `pbm'.  Color, gray-scale and
monochromatic images are supported.   For mono PBM images, two
additional image properties are supported.

`:foreground FOREGROUND'
     The value, FOREGROUND, should be a string specifying the image
     foreground color, or `nil' for the default color.  This color is
     used for each pixel in the XBM that is 1.  The default is the
     frame's foreground color.

`:background BACKGROUND'
     The value, BACKGROUND, should be a string specifying the image
     background color, or `nil' for the default color.  This color is
     used for each pixel in the XBM that is 0.  The default is the
     frame's background color.

   For JPEG images, specify image type `jpeg'.

   For TIFF images, specify image type `tiff'.

   For PNG images, specify image type `png'.


File: elisp,  Node: Defining Images,  Next: Showing Images,  Prev: Other Image Types,  Up: Images

38.16.7 Defining Images
-----------------------

The functions `create-image', `defimage' and `find-image' provide
convenient ways to create image descriptors.

 -- Function: create-image file-or-data &optional type data-p &rest
          props
     This function creates and returns an image descriptor which uses
     the data in FILE-OR-DATA.  FILE-OR-DATA can be a file name or a
     string containing the image data; DATA-P should be `nil' for the
     former case, non-`nil' for the latter case.

     The optional argument TYPE is a symbol specifying the image type.
     If TYPE is omitted or `nil', `create-image' tries to determine the
     image type from the file's first few bytes, or else from the
     file's name.

     The remaining arguments, PROPS, specify additional image
     properties--for example,

          (create-image "foo.xpm" 'xpm nil :heuristic-mask t)

     The function returns `nil' if images of this type are not
     supported.  Otherwise it returns an image descriptor.

 -- Macro: defimage symbol specs &optional doc
     This macro defines SYMBOL as an image name.  The arguments SPECS
     is a list which specifies how to display the image.  The third
     argument, DOC, is an optional documentation string.

     Each argument in SPECS has the form of a property list, and each
     one should specify at least the `:type' property and either the
     `:file' or the `:data' property.  The value of `:type' should be a
     symbol specifying the image type, the value of `:file' is the file
     to load the image from, and the value of `:data' is a string
     containing the actual image data.  Here is an example:

          (defimage test-image
            ((:type xpm :file "~/test1.xpm")
             (:type xbm :file "~/test1.xbm")))

     `defimage' tests each argument, one by one, to see if it is
     usable--that is, if the type is supported and the file exists.  The
     first usable argument is used to make an image descriptor which is
     stored in SYMBOL.

     If none of the alternatives will work, then SYMBOL is defined as
     `nil'.

 -- Function: find-image specs
     This function provides a convenient way to find an image
     satisfying one of a list of image specifications SPECS.

     Each specification in SPECS is a property list with contents
     depending on image type.  All specifications must at least contain
     the properties `:type TYPE' and either `:file FILE' or
     `:data DATA', where TYPE is a symbol specifying the image type,
     e.g. `xbm', FILE is the file to load the image from, and DATA is a
     string containing the actual image data.  The first specification
     in the list whose TYPE is supported, and FILE exists, is used to
     construct the image specification to be returned.  If no
     specification is satisfied, `nil' is returned.

     The image is looked for in `image-load-path'.

 -- Variable: image-load-path
     This variable's value is a list of locations in which to search for
     image files.  If an element is a string or a variable symbol whose
     value is a string, the string is taken to be the name of a
     directory to search.  If an element is a variable symbol whose
     value is a list, that is taken to be a list of directory names to
     search.

     The default is to search in the `images' subdirectory of the
     directory specified by `data-directory', then the directory
     specified by `data-directory', and finally in the directories in
     `load-path'.  Subdirectories are not automatically included in the
     search, so if you put an image file in a subdirectory, you have to
     supply the subdirectory name explicitly.  For example, to find the
     image `images/foo/bar.xpm' within `data-directory', you should
     specify the image as follows:

          (defimage foo-image '((:type xpm :file "foo/bar.xpm")))

 -- Function: image-load-path-for-library library image &optional path
          no-error
     This function returns a suitable search path for images used by the
     Lisp package LIBRARY.

     The function searches for IMAGE first using `image-load-path',
     excluding ``data-directory'/images', and then in `load-path',
     followed by a path suitable for LIBRARY, which includes
     `../../etc/images' and `../etc/images' relative to the library
     file itself, and finally in ``data-directory'/images'.

     Then this function returns a list of directories which contains
     first the directory in which IMAGE was found, followed by the
     value of `load-path'.  If PATH is given, it is used instead of
     `load-path'.

     If NO-ERROR is non-`nil' and a suitable path can't be found, don't
     signal an error.  Instead, return a list of directories as before,
     except that `nil' appears in place of the image directory.

     Here is an example that uses a common idiom to provide
     compatibility with versions of Emacs that lack the variable
     `image-load-path':

          (defvar image-load-path) ; shush compiler
          (let* ((load-path (image-load-path-for-library
                                  "mh-e" "mh-logo.xpm"))
                 (image-load-path (cons (car load-path)
                                        (when (boundp 'image-load-path)
                                          image-load-path))))
            (mh-tool-bar-folder-buttons-init))


File: elisp,  Node: Showing Images,  Next: Image Cache,  Prev: Defining Images,  Up: Images

38.16.8 Showing Images
----------------------

You can use an image descriptor by setting up the `display' property
yourself, but it is easier to use the functions in this section.

 -- Function: insert-image image &optional string area slice
     This function inserts IMAGE in the current buffer at point.  The
     value IMAGE should be an image descriptor; it could be a value
     returned by `create-image', or the value of a symbol defined with
     `defimage'.  The argument STRING specifies the text to put in the
     buffer to hold the image.  If it is omitted or `nil',
     `insert-image' uses `" "' by default.

     The argument AREA specifies whether to put the image in a margin.
     If it is `left-margin', the image appears in the left margin;
     `right-margin' specifies the right margin.  If AREA is `nil' or
     omitted, the image is displayed at point within the buffer's text.

     The argument SLICE specifies a slice of the image to insert.  If
     SLICE is `nil' or omitted the whole image is inserted.  Otherwise,
     SLICE is a list `(X Y WIDTH HEIGHT)' which specifies the X and Y
     positions and WIDTH and HEIGHT of the image area to insert.
     Integer values are in units of pixels.  A floating point number in
     the range 0.0-1.0 stands for that fraction of the width or height
     of the entire image.

     Internally, this function inserts STRING in the buffer, and gives
     it a `display' property which specifies IMAGE.  *Note Display
     Property::.

 -- Function: insert-sliced-image image &optional string area rows cols
     This function inserts IMAGE in the current buffer at point, like
     `insert-image', but splits the image into ROWSxCOLS equally sized
     slices.

 -- Function: put-image image pos &optional string area
     This function puts image IMAGE in front of POS in the current
     buffer.  The argument POS should be an integer or a marker.  It
     specifies the buffer position where the image should appear.  The
     argument STRING specifies the text that should hold the image as
     an alternative to the default.

     The argument IMAGE must be an image descriptor, perhaps returned
     by `create-image' or stored by `defimage'.

     The argument AREA specifies whether to put the image in a margin.
     If it is `left-margin', the image appears in the left margin;
     `right-margin' specifies the right margin.  If AREA is `nil' or
     omitted, the image is displayed at point within the buffer's text.

     Internally, this function creates an overlay, and gives it a
     `before-string' property containing text that has a `display'
     property whose value is the image.  (Whew!)

 -- Function: remove-images start end &optional buffer
     This function removes images in BUFFER between positions START and
     END.  If BUFFER is omitted or `nil', images are removed from the
     current buffer.

     This removes only images that were put into BUFFER the way
     `put-image' does it, not images that were inserted with
     `insert-image' or in other ways.

 -- Function: image-size spec &optional pixels frame
     This function returns the size of an image as a pair
     `(WIDTH . HEIGHT)'.  SPEC is an image specification.  PIXELS
     non-`nil' means return sizes measured in pixels, otherwise return
     sizes measured in canonical character units (fractions of the
     width/height of the frame's default font).  FRAME is the frame on
     which the image will be displayed.  FRAME null or omitted means
     use the selected frame (*note Input Focus::).

 -- Variable: max-image-size
     This variable is used to define the maximum size of image that
     Emacs will load.  Emacs will refuse to load (and display) any
     image that is larger than this limit.

     If the value is an integer, it directly specifies the maximum
     image height and width, measured in pixels.  If it is a floating
     point number, it specifies the maximum image height and width as a
     ratio to the frame height and width.  If the value is non-numeric,
     there is no explicit limit on the size of images.

     The purpose of this variable is to prevent unreasonably large
     images from accidentally being loaded into Emacs.  It only takes
     effect the first time an image is loaded.  Once an image is placed
     in the image cache, it can always be displayed, even if the value
     of MAX-IMAGE-SIZE is subsequently changed (*note Image Cache::).


File: elisp,  Node: Image Cache,  Prev: Showing Images,  Up: Images

38.16.9 Image Cache
-------------------

Emacs stores images in an image cache so that it can display them again
more efficiently.  When Emacs displays an image, it searches the image
cache for an existing image specification `equal' to the desired
specification.  If a match is found, the image is displayed from the
cache; otherwise, Emacs loads the image normally.

   Occasionally, you may need to tell Emacs to refresh the images
associated with a given image specification.  For example, suppose you
display an image using a specification that contains a `:file'
property.  The image is loaded from the given file and stored in the
image cache.  If you later display the image again, using the same
image specification, the image is displayed from the image cache.
Normally, this is not a problem.  However, if the image file has
changed in the meantime, Emacs would be displaying the old version of
the image.  In such a situation, it is necessary to "refresh" the image
using `image-refresh'.

 -- Function: image-refresh spec &optional frame
     This function refreshes any images having image specifications
     `equal' to SPEC on frame FRAME.  If FRAME is `nil', the selected
     frame is used.  If FRAME is `t', the refresh is applied to all
     existing frames.

     This works by removing all image with image specifications matching
     SPEC from the image cache.  Thus, the next time the image is
     displayed, Emacs will load the image again.

 -- Function: clear-image-cache &optional frame
     This function clears the entire image cache.  If FRAME is
     non-`nil', only the cache for that frame is cleared.  Otherwise,
     all frames' caches are cleared.

   If an image in the image cache has not been displayed for a specified
period of time, Emacs removes it from the cache and frees the
associated memory.

 -- Variable: image-cache-eviction-delay
     This variable specifies the number of seconds an image can remain
     in the cache without being displayed.  When an image is not
     displayed for this length of time, Emacs removes it from the image
     cache.

     If the value is `nil', Emacs does not remove images from the cache
     except when you explicitly clear it.  This mode can be useful for
     debugging.


File: elisp,  Node: Buttons,  Next: Abstract Display,  Prev: Images,  Up: Display

38.17 Buttons
=============

The _button_ package defines functions for inserting and manipulating
clickable (with the mouse, or via keyboard commands) buttons in Emacs
buffers, such as might be used for help hyper-links, etc.  Emacs uses
buttons for the hyper-links in help text and the like.

   A button is essentially a set of properties attached (via text
properties or overlays) to a region of text in an Emacs buffer.  These
properties are called "button properties".

   One of these properties (`action') is a function, which will be
called when the user invokes it using the keyboard or the mouse.  The
invoked function may then examine the button and use its other
properties as desired.

   In some ways the Emacs button package duplicates functionality
offered by the widget package (*note Introduction: (widget)Top.), but
the button package has the advantage that it is much faster, much
smaller, and much simpler to use (for elisp programmers--for users, the
result is about the same).  The extra speed and space savings are
useful mainly if you need to create many buttons in a buffer (for
instance an `*Apropos*' buffer uses buttons to make entries clickable,
and may contain many thousands of entries).

* Menu:

* Button Properties::      Button properties with special meanings.
* Button Types::           Defining common properties for classes of buttons.
* Making Buttons::         Adding buttons to Emacs buffers.
* Manipulating Buttons::   Getting and setting properties of buttons.
* Button Buffer Commands:: Buffer-wide commands and bindings for buttons.


File: elisp,  Node: Button Properties,  Next: Button Types,  Up: Buttons

38.17.1 Button Properties
-------------------------

Buttons have an associated list of properties defining their appearance
and behavior, and other arbitrary properties may be used for
application specific purposes.  Some properties that have special
meaning to the button package include:

`action'
     The function to call when the user invokes the button, which is
     passed the single argument BUTTON.  By default this is `ignore',
     which does nothing.

`mouse-action'
     This is similar to `action', and when present, will be used
     instead of `action' for button invocations resulting from
     mouse-clicks (instead of the user hitting <RET>).  If not present,
     mouse-clicks use `action' instead.

`face'
     This is an Emacs face controlling how buttons of this type are
     displayed; by default this is the `button' face.

`mouse-face'
     This is an additional face which controls appearance during
     mouse-overs (merged with the usual button face); by default this is
     the usual Emacs `highlight' face.

`keymap'
     The button's keymap, defining bindings active within the button
     region.  By default this is the usual button region keymap, stored
     in the variable `button-map', which defines <RET> and <mouse-2> to
     invoke the button.

`type'
     The button-type of the button.  When creating a button, this is
     usually specified using the `:type' keyword argument.  *Note
     Button Types::.

`help-echo'
     A string displayed by the Emacs tool-tip help system; by default,
     `"mouse-2, RET: Push this button"'.

`follow-link'
     The follow-link property, defining how a <Mouse-1> click behaves
     on this button, *Note Links and Mouse-1::.

`button'
     All buttons have a non-`nil' `button' property, which may be useful
     in finding regions of text that comprise buttons (which is what the
     standard button functions do).

   There are other properties defined for the regions of text in a
button, but these are not generally interesting for typical uses.


File: elisp,  Node: Button Types,  Next: Making Buttons,  Prev: Button Properties,  Up: Buttons

38.17.2 Button Types
--------------------

Every button has a button _type_, which defines default values for the
button's properties.  Button types are arranged in a hierarchy, with
specialized types inheriting from more general types, so that it's easy
to define special-purpose types of buttons for specific tasks.

 -- Function: define-button-type name &rest properties
     Define a `button type' called NAME.  The remaining arguments form
     a sequence of PROPERTY VALUE pairs, specifying default property
     values for buttons with this type (a button's type may be set by
     giving it a `type' property when creating the button, using the
     `:type' keyword argument).

     In addition, the keyword argument `:supertype' may be used to
     specify a button-type from which NAME inherits its default
     property values.  Note that this inheritance happens only when
     NAME is defined; subsequent changes to a supertype are not
     reflected in its subtypes.

   Using `define-button-type' to define default properties for buttons
is not necessary--buttons without any specified type use the built-in
button-type `button'--but it is encouraged, since doing so usually
makes the resulting code clearer and more efficient.


File: elisp,  Node: Making Buttons,  Next: Manipulating Buttons,  Prev: Button Types,  Up: Buttons

38.17.3 Making Buttons
----------------------

Buttons are associated with a region of text, using an overlay or text
properties to hold button-specific information, all of which are
initialized from the button's type (which defaults to the built-in
button type `button').  Like all Emacs text, the appearance of the
button is governed by the `face' property; by default (via the `face'
property inherited from the `button' button-type) this is a simple
underline, like a typical web-page link.

   For convenience, there are two sorts of button-creation functions,
those that add button properties to an existing region of a buffer,
called `make-...button', and those that also insert the button text,
called `insert-...button'.

   The button-creation functions all take the `&rest' argument
PROPERTIES, which should be a sequence of PROPERTY VALUE pairs,
specifying properties to add to the button; see *note Button
Properties::.  In addition, the keyword argument `:type' may be used to
specify a button-type from which to inherit other properties; see *note
Button Types::.  Any properties not explicitly specified during
creation will be inherited from the button's type (if the type defines
such a property).

   The following functions add a button using an overlay (*note
Overlays::) to hold the button properties:

 -- Function: make-button beg end &rest properties
     This makes a button from BEG to END in the current buffer, and
     returns it.

 -- Function: insert-button label &rest properties
     This insert a button with the label LABEL at point, and returns it.

   The following functions are similar, but use Emacs text properties
(*note Text Properties::) to hold the button properties, making the
button actually part of the text instead of being a property of the
buffer.  Buttons using text properties do not create markers into the
buffer, which is important for speed when you use extremely large
numbers of buttons.  Both functions return the position of the start of
the new button:

 -- Function: make-text-button beg end &rest properties
     This makes a button from BEG to END in the current buffer, using
     text properties.

 -- Function: insert-text-button label &rest properties
     This inserts a button with the label LABEL at point, using text
     properties.


File: elisp,  Node: Manipulating Buttons,  Next: Button Buffer Commands,  Prev: Making Buttons,  Up: Buttons

38.17.4 Manipulating Buttons
----------------------------

These are functions for getting and setting properties of buttons.
Often these are used by a button's invocation function to determine
what to do.

   Where a BUTTON parameter is specified, it means an object referring
to a specific button, either an overlay (for overlay buttons), or a
buffer-position or marker (for text property buttons).  Such an object
is passed as the first argument to a button's invocation function when
it is invoked.

 -- Function: button-start button
     Return the position at which BUTTON starts.

 -- Function: button-end button
     Return the position at which BUTTON ends.

 -- Function: button-get button prop
     Get the property of button BUTTON named PROP.

 -- Function: button-put button prop val
     Set BUTTON's PROP property to VAL.

 -- Function: button-activate button &optional use-mouse-action
     Call BUTTON's `action' property (i.e., invoke it).  If
     USE-MOUSE-ACTION is non-`nil', try to invoke the button's
     `mouse-action' property instead of `action'; if the button has no
     `mouse-action' property, use `action' as normal.

 -- Function: button-label button
     Return BUTTON's text label.

 -- Function: button-type button
     Return BUTTON's button-type.

 -- Function: button-has-type-p button type
     Return `t' if BUTTON has button-type TYPE, or one of TYPE's
     subtypes.

 -- Function: button-at pos
     Return the button at position POS in the current buffer, or `nil'.

 -- Function: button-type-put type prop val
     Set the button-type TYPE's PROP property to VAL.

 -- Function: button-type-get type prop
     Get the property of button-type TYPE named PROP.

 -- Function: button-type-subtype-p type supertype
     Return `t' if button-type TYPE is a subtype of SUPERTYPE.


File: elisp,  Node: Button Buffer Commands,  Prev: Manipulating Buttons,  Up: Buttons

38.17.5 Button Buffer Commands
------------------------------

These are commands and functions for locating and operating on buttons
in an Emacs buffer.

   `push-button' is the command that a user uses to actually `push' a
button, and is bound by default in the button itself to <RET> and to
<mouse-2> using a region-specific keymap.  Commands that are useful
outside the buttons itself, such as `forward-button' and
`backward-button' are additionally available in the keymap stored in
`button-buffer-map'; a mode which uses buttons may want to use
`button-buffer-map' as a parent keymap for its keymap.

   If the button has a non-`nil' `follow-link' property, and
MOUSE-1-CLICK-FOLLOWS-LINK is set, a quick <Mouse-1> click will also
activate the `push-button' command.  *Note Links and Mouse-1::.

 -- Command: push-button &optional pos use-mouse-action
     Perform the action specified by a button at location POS.  POS may
     be either a buffer position or a mouse-event.  If USE-MOUSE-ACTION
     is non-`nil', or POS is a mouse-event (*note Mouse Events::), try
     to invoke the button's `mouse-action' property instead of
     `action'; if the button has no `mouse-action' property, use
     `action' as normal.  POS defaults to point, except when
     `push-button' is invoked interactively as the result of a
     mouse-event, in which case, the mouse event's position is used.
     If there's no button at POS, do nothing and return `nil',
     otherwise return `t'.

 -- Command: forward-button n &optional wrap display-message
     Move to the Nth next button, or Nth previous button if N is
     negative.  If N is zero, move to the start of any button at point.
     If WRAP is non-`nil', moving past either end of the buffer
     continues from the other end.  If DISPLAY-MESSAGE is non-`nil',
     the button's help-echo string is displayed.  Any button with a
     non-`nil' `skip' property is skipped over.  Returns the button
     found.

 -- Command: backward-button n &optional wrap display-message
     Move to the Nth previous button, or Nth next button if N is
     negative.  If N is zero, move to the start of any button at point.
     If WRAP is non-`nil', moving past either end of the buffer
     continues from the other end.  If DISPLAY-MESSAGE is non-`nil',
     the button's help-echo string is displayed.  Any button with a
     non-`nil' `skip' property is skipped over.  Returns the button
     found.

 -- Function: next-button pos &optional count-current
 -- Function: previous-button pos &optional count-current
     Return the next button after (for `next-button' or before (for
     `previous-button') position POS in the current buffer.  If
     COUNT-CURRENT is non-`nil', count any button at POS in the search,
     instead of starting at the next button.


File: elisp,  Node: Abstract Display,  Next: Blinking,  Prev: Buttons,  Up: Display

38.18 Abstract Display
======================

The Ewoc package constructs buffer text that represents a structure of
Lisp objects, and updates the text to follow changes in that structure.
This is like the "view" component in the "model/view/controller" design
paradigm.

   An "ewoc" is a structure that organizes information required to
construct buffer text that represents certain Lisp data.  The buffer
text of the ewoc has three parts, in order: first, fixed "header" text;
next, textual descriptions of a series of data elements (Lisp objects
that you specify); and last, fixed "footer" text.  Specifically, an
ewoc contains information on:

   * The buffer which its text is generated in.

   * The text's start position in the buffer.

   * The header and footer strings.

   * A doubly-linked chain of "nodes", each of which contains:

        * A "data element", a single Lisp object.

        * Links to the preceding and following nodes in the chain.

   * A "pretty-printer" function which is responsible for inserting the
     textual representation of a data element value into the current
     buffer.

   Typically, you define an ewoc with `ewoc-create', and then pass the
resulting ewoc structure to other functions in the Ewoc package to
build nodes within it, and display it in the buffer.  Once it is
displayed in the buffer, other functions determine the correspondance
between buffer positions and nodes, move point from one node's textual
representation to another, and so forth.  *Note Abstract Display
Functions::.

   A node "encapsulates" a data element much the way a variable holds a
value.  Normally, encapsulation occurs as a part of adding a node to
the ewoc.  You can retrieve the data element value and place a new
value in its place, like so:

     (ewoc-data NODE)
     => value

     (ewoc-set-data NODE NEW-VALUE)
     => NEW-VALUE

You can also use, as the data element value, a Lisp object (list or
vector) that is a container for the "real" value, or an index into some
other structure.  The example (*note Abstract Display Example::) uses
the latter approach.

   When the data changes, you will want to update the text in the
buffer.  You can update all nodes by calling `ewoc-refresh', or just
specific nodes using `ewoc-invalidate', or all nodes satisfying a
predicate using `ewoc-map'.  Alternatively, you can delete invalid
nodes using `ewoc-delete' or `ewoc-filter', and add new nodes in their
place.  Deleting a node from an ewoc deletes its associated textual
description from buffer, as well.

* Menu:

* Abstract Display Functions::
* Abstract Display Example::


File: elisp,  Node: Abstract Display Functions,  Next: Abstract Display Example,  Up: Abstract Display

38.18.1 Abstract Display Functions
----------------------------------

In this subsection, EWOC and NODE stand for the structures described
above (*note Abstract Display::), while DATA stands for an arbitrary
Lisp object used as a data element.

 -- Function: ewoc-create pretty-printer &optional header footer nosep
     This constructs and returns a new ewoc, with no nodes (and thus no
     data elements).  PRETTY-PRINTER should be a function that takes one
     argument, a data element of the sort you plan to use in this ewoc,
     and inserts its textual description at point using `insert' (and
     never `insert-before-markers', because that would interfere with
     the Ewoc package's internal mechanisms).

     Normally, a newline is automatically inserted after the header,
     the footer and every node's textual description.  If NOSEP is
     non-`nil', no newline is inserted.  This may be useful for
     displaying an entire ewoc on a single line, for example, or for
     making nodes "invisible" by arranging for PRETTY-PRINTER to do
     nothing for those nodes.

     An ewoc maintains its text in the buffer that is current when you
     create it, so switch to the intended buffer before calling
     `ewoc-create'.

 -- Function: ewoc-buffer ewoc
     This returns the buffer where EWOC maintains its text.

 -- Function: ewoc-get-hf ewoc
     This returns a cons cell `(HEADER . FOOTER)' made from EWOC's
     header and footer.

 -- Function: ewoc-set-hf ewoc header footer
     This sets the header and footer of EWOC to the strings HEADER and
     FOOTER, respectively.

 -- Function: ewoc-enter-first ewoc data
 -- Function: ewoc-enter-last ewoc data
     These add a new node encapsulating DATA, putting it, respectively,
     at the beginning or end of EWOC's chain of nodes.

 -- Function: ewoc-enter-before ewoc node data
 -- Function: ewoc-enter-after ewoc node data
     These add a new node encapsulating DATA, adding it to EWOC before
     or after NODE, respectively.

 -- Function: ewoc-prev ewoc node
 -- Function: ewoc-next ewoc node
     These return, respectively, the previous node and the next node of
     NODE in EWOC.

 -- Function: ewoc-nth ewoc n
     This returns the node in EWOC found at zero-based index N.  A
     negative N means count from the end.  `ewoc-nth' returns `nil' if
     N is out of range.

 -- Function: ewoc-data node
     This extracts the data encapsulated by NODE and returns it.

 -- Function: ewoc-set-data node data
     This sets the data encapsulated by NODE to DATA.

 -- Function: ewoc-locate ewoc &optional pos guess
     This determines the node in EWOC which contains point (or POS if
     specified), and returns that node.  If EWOC has no nodes, it
     returns `nil'.  If POS is before the first node, it returns the
     first node; if POS is after the last node, it returns the last
     node.  The optional third arg GUESS should be a node that is
     likely to be near POS; this doesn't alter the result, but makes
     the function run faster.

 -- Function: ewoc-location node
     This returns the start position of NODE.

 -- Function: ewoc-goto-prev ewoc arg
 -- Function: ewoc-goto-next ewoc arg
     These move point to the previous or next, respectively, ARGth node
     in EWOC.  `ewoc-goto-prev' does not move if it is already at the
     first node or if EWOC is empty, whereas `ewoc-goto-next' moves
     past the last node, returning `nil'.  Excepting this special case,
     these functions return the node moved to.

 -- Function: ewoc-goto-node ewoc node
     This moves point to the start of NODE in EWOC.

 -- Function: ewoc-refresh ewoc
     This function regenerates the text of EWOC.  It works by deleting
     the text between the header and the footer, i.e., all the data
     elements' representations, and then calling the pretty-printer
     function for each node, one by one, in order.

 -- Function: ewoc-invalidate ewoc &rest nodes
     This is similar to `ewoc-refresh', except that only NODES in EWOC
     are updated instead of the entire set.

 -- Function: ewoc-delete ewoc &rest nodes
     This deletes each node in NODES from EWOC.

 -- Function: ewoc-filter ewoc predicate &rest args
     This calls PREDICATE for each data element in EWOC and deletes
     those nodes for which PREDICATE returns `nil'.  Any ARGS are
     passed to PREDICATE.

 -- Function: ewoc-collect ewoc predicate &rest args
     This calls PREDICATE for each data element in EWOC and returns a
     list of those elements for which PREDICATE returns non-`nil'.  The
     elements in the list are ordered as in the buffer.  Any ARGS are
     passed to PREDICATE.

 -- Function: ewoc-map map-function ewoc &rest args
     This calls MAP-FUNCTION for each data element in EWOC and updates
     those nodes for which MAP-FUNCTION returns non-`nil'.  Any ARGS
     are passed to MAP-FUNCTION.


File: elisp,  Node: Abstract Display Example,  Prev: Abstract Display Functions,  Up: Abstract Display

38.18.2 Abstract Display Example
--------------------------------

Here is a simple example using functions of the ewoc package to
implement a "color components display," an area in a buffer that
represents a vector of three integers (itself representing a 24-bit RGB
value) in various ways.

     (setq colorcomp-ewoc nil
           colorcomp-data nil
           colorcomp-mode-map nil
           colorcomp-labels ["Red" "Green" "Blue"])

     (defun colorcomp-pp (data)
       (if data
           (let ((comp (aref colorcomp-data data)))
             (insert (aref colorcomp-labels data) "\t: #x"
                     (format "%02X" comp) " "
                     (make-string (ash comp -2) ?#) "\n"))
         (let ((cstr (format "#%02X%02X%02X"
                             (aref colorcomp-data 0)
                             (aref colorcomp-data 1)
                             (aref colorcomp-data 2)))
               (samp " (sample text) "))
           (insert "Color\t: "
                   (propertize samp 'face `(foreground-color . ,cstr))
                   (propertize samp 'face `(background-color . ,cstr))
                   "\n"))))

     (defun colorcomp (color)
       "Allow fiddling with COLOR in a new buffer.
     The buffer is in Color Components mode."
       (interactive "sColor (name or #RGB or #RRGGBB): ")
       (when (string= "" color)
         (setq color "green"))
       (unless (color-values color)
         (error "No such color: %S" color))
       (switch-to-buffer
        (generate-new-buffer (format "originally: %s" color)))
       (kill-all-local-variables)
       (setq major-mode 'colorcomp-mode
             mode-name "Color Components")
       (use-local-map colorcomp-mode-map)
       (erase-buffer)
       (buffer-disable-undo)
       (let ((data (apply 'vector (mapcar (lambda (n) (ash n -8))
                                          (color-values color))))
             (ewoc (ewoc-create 'colorcomp-pp
                                "\nColor Components\n\n"
                                (substitute-command-keys
                                 "\n\\{colorcomp-mode-map}"))))
         (set (make-local-variable 'colorcomp-data) data)
         (set (make-local-variable 'colorcomp-ewoc) ewoc)
         (ewoc-enter-last ewoc 0)
         (ewoc-enter-last ewoc 1)
         (ewoc-enter-last ewoc 2)
         (ewoc-enter-last ewoc nil)))

   This example can be extended to be a "color selection widget" (in
other words, the controller part of the "model/view/controller" design
paradigm) by defining commands to modify `colorcomp-data' and to
"finish" the selection process, and a keymap to tie it all together
conveniently.

     (defun colorcomp-mod (index limit delta)
       (let ((cur (aref colorcomp-data index)))
         (unless (= limit cur)
           (aset colorcomp-data index (+ cur delta)))
         (ewoc-invalidate
          colorcomp-ewoc
          (ewoc-nth colorcomp-ewoc index)
          (ewoc-nth colorcomp-ewoc -1))))

     (defun colorcomp-R-more () (interactive) (colorcomp-mod 0 255 1))
     (defun colorcomp-G-more () (interactive) (colorcomp-mod 1 255 1))
     (defun colorcomp-B-more () (interactive) (colorcomp-mod 2 255 1))
     (defun colorcomp-R-less () (interactive) (colorcomp-mod 0 0 -1))
     (defun colorcomp-G-less () (interactive) (colorcomp-mod 1 0 -1))
     (defun colorcomp-B-less () (interactive) (colorcomp-mod 2 0 -1))

     (defun colorcomp-copy-as-kill-and-exit ()
       "Copy the color components into the kill ring and kill the buffer.
     The string is formatted #RRGGBB (hash followed by six hex digits)."
       (interactive)
       (kill-new (format "#%02X%02X%02X"
                         (aref colorcomp-data 0)
                         (aref colorcomp-data 1)
                         (aref colorcomp-data 2)))
       (kill-buffer nil))

     (setq colorcomp-mode-map
           (let ((m (make-sparse-keymap)))
             (suppress-keymap m)
             (define-key m "i" 'colorcomp-R-less)
             (define-key m "o" 'colorcomp-R-more)
             (define-key m "k" 'colorcomp-G-less)
             (define-key m "l" 'colorcomp-G-more)
             (define-key m "," 'colorcomp-B-less)
             (define-key m "." 'colorcomp-B-more)
             (define-key m " " 'colorcomp-copy-as-kill-and-exit)
             m))

   Note that we never modify the data in each node, which is fixed when
the ewoc is created to be either `nil' or an index into the vector
`colorcomp-data', the actual color components.


File: elisp,  Node: Blinking,  Next: Usual Display,  Prev: Abstract Display,  Up: Display

38.19 Blinking Parentheses
==========================

This section describes the mechanism by which Emacs 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.

 -- User Option: blink-matching-paren
     If this variable is `nil', then `blink-matching-open' does nothing.

 -- User Option: blink-matching-paren-distance
     This variable specifies the maximum distance to scan for a matching
     parenthesis before giving up.

 -- User Option: blink-matching-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: elisp,  Node: Usual Display,  Next: Display Tables,  Prev: Blinking,  Up: Display

38.20 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.

     On MS-DOS terminals, Emacs arranges by default for the character
     code 127 to be mapped to the glyph code 127, which normally
     displays as an empty polygon.  This glyph is used to display
     non-ASCII characters that the MS-DOS terminal doesn't support.
     *Note MS-DOS and MULE: (emacs)MS-DOS and MULE.

   * 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 character code in octal.  (A
     display table can specify a glyph to use instead of `\'.)

   * Multibyte character codes above 256 are displayed as themselves,
     or as a question mark or empty box if the terminal cannot display
     that character.

   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 special behavior.

   These display rules apply to carriage return (character code 13),
when it appears in the buffer.  But that character may not appear in the
buffer where you expect it, if it was eliminated as part of end-of-line
conversion (*note Coding System Basics::).

   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.  These variables
also affect how the mode line is displayed; if you want to force
redisplay of the mode line using the new values, call the function
`force-mode-line-update' (*note Mode Line Format::).

 -- 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 buffer-local variable is the spacing between tab
     stops used for displaying tab characters in Emacs buffers.  The
     value is in units of columns, and the default is 8.  Note that
     this feature is completely independent of the user-settable tab
     stops used by the command `tab-to-tab-stop'.  *Note Indent Tabs::.


File: elisp,  Node: Display Tables,  Next: Beeping,  Prev: Usual Display,  Up: Display

38.21 Display Tables
====================

You can use the "display table" feature to control how all 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
"glyphs", each glyph being a graphic that takes up one character
position on the screen.  You can also define how to display each glyph
on your terminal, using the "glyph table".

   Display tables affect how the mode line is displayed; if you want to
force redisplay of the mode line using a new display table, call
`force-mode-line-update' (*note Mode Line Format::).

* Menu:

* Display Table Format::  What a display table consists of.
* Active Display Table::  How Emacs selects a display table to use.
* Glyphs::              How to define a glyph, and what glyphs mean.


File: elisp,  Node: Display Table Format,  Next: Active Display Table,  Up: Display Tables

38.21.1 Display Table Format
----------------------------

A display table is actually a char-table (*note Char-Tables::) with
`display-table' as its subtype.

 -- Function: make-display-table
     This creates and returns a display table.  The table initially has
     `nil' in all elements.

   The ordinary elements of the display table are indexed by character
codes; the element at index C says how to display the character code C.
The value should be `nil' or a vector of the glyphs to be output (*note
Glyphs::).  `nil' says to display the character C according to the
usual display conventions (*note Usual Display::).

   *Warning:* if you use the display table to change the display of
newline characters, the whole buffer will be displayed as one long
"line."

   The display table also has six "extra slots" which serve special
purposes.  Here is a table of their meanings; `nil' in any slot means
to use the default for that slot, as stated below.

0
     The glyph for the end of a truncated screen line (the default for
     this is `$').  *Note Glyphs::.  On graphical terminals, Emacs uses
     arrows in the fringes to indicate truncation, so the display table
     has no effect.

1
     The glyph for the end of a continued line (the default is `\').
     On graphical terminals, Emacs uses curved arrows in the fringes to
     indicate continuation, so the display table has no effect.

2
     The glyph for indicating a character displayed as an octal
     character code (the default is `\').

3
     The glyph for indicating a control character (the default is `^').

4
     A vector of glyphs for indicating the presence of invisible lines
     (the default is `...').  *Note Selective Display::.

5
     The glyph used to draw the border between side-by-side windows (the
     default is `|').  *Note Splitting Windows::.  This takes effect
     only when there are no scroll bars; if scroll bars are supported
     and in use, a scroll bar separates the two windows.

   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 (vector ?^ (+ i 64))))
         (setq i (1+ i)))
       (aset disptab 127 (vector ?^ ??)))

 -- Function: display-table-slot display-table slot
     This function returns the value of the extra slot SLOT of
     DISPLAY-TABLE.  The argument SLOT may be a number from 0 to 5
     inclusive, or a slot name (symbol).  Valid symbols are
     `truncation', `wrap', `escape', `control', `selective-display',
     and `vertical-border'.

 -- Function: set-display-table-slot display-table slot value
     This function stores VALUE in the extra slot SLOT of
     DISPLAY-TABLE.  The argument SLOT may be a number from 0 to 5
     inclusive, or a slot name (symbol).  Valid symbols are
     `truncation', `wrap', `escape', `control', `selective-display',
     and `vertical-border'.

 -- Function: describe-display-table display-table
     This function displays a description of the display table
     DISPLAY-TABLE in a help buffer.

 -- Command: describe-current-display-table
     This command displays a description of the current display table
     in a help buffer.

