-This is ../info/lispref.info, produced by makeinfo version 4.6 from
+This is ../info/lispref.info, produced by makeinfo version 4.8 from
lispref/lispref.texi.
INFO-DIR-SECTION XEmacs Editor
Foundation instead of in the original English.
\1f
+File: lispref.info, Node: User Name Completion, Prev: File Name Completion, Up: File Names
+
+35.8.7 User Name Completion
+---------------------------
+
+This section describes low-level subroutines for completing a user
+name. For other completion functions, see *Note Completion::.
+
+ -- Function: user-name-all-completions partial-username
+ This function returns a list of all possible completions for a
+ user name starting with PARTIAL-USERNAME. The order of the
+ completions is unpredictable and conveys no useful information.
+
+ The argument PARTIAL-USERNAME must be a partial user name
+ containing no tilde character and no slash.
+
+ -- Function: user-name-completion partial-username
+ This function completes a user name from PARTIAL-USERNAME. It
+ returns the longest prefix common to all user names that start with
+ PARTIAL-USERNAME.
+
+ If only one match exists and PARTIAL-USERNAME matches it exactly,
+ the function returns `t'. The function returns `nil' if no user
+ name starting with PARTIAL-USERNAME exists.
+
+ -- Function: user-name-completion-1 partial-username
+ This function completes the partial user name PARTIAL-USERNAME,
+ like `user-name-completion', differing only in the return value.
+ This function returns the cons of the completion returned by
+ `user-name-completion', and a boolean indicating whether that
+ completion was unique.
+
+\1f
+File: lispref.info, Node: Contents of Directories, Next: Create/Delete Dirs, Prev: File Names, Up: Files
+
+35.9 Contents of Directories
+============================
+
+A directory is a kind of file that contains other files entered under
+various names. Directories are a feature of the file system.
+
+ XEmacs can list the names of the files in a directory as a Lisp list,
+or display the names in a buffer using the `ls' shell command. In the
+latter case, it can optionally display information about each file,
+depending on the value of switches passed to the `ls' command.
+
+ -- Function: directory-files directory &optional full-name
+ match-regexp nosort files-only
+ This function returns a list of the names of the files in the
+ directory DIRECTORY. By default, the list is in alphabetical
+ order.
+
+ If FULL-NAME is non-`nil', the function returns the files'
+ absolute file names. Otherwise, it returns just the names
+ relative to the specified directory.
+
+ If MATCH-REGEXP is non-`nil', this function returns only those
+ file names that contain that regular expression--the other file
+ names are discarded from the list.
+
+ If NOSORT is non-`nil', `directory-files' does not sort the list,
+ so you get the file names in no particular order. Use this if you
+ want the utmost possible speed and don't care what order the files
+ are processed in. If the order of processing is visible to the
+ user, then the user will probably be happier if you do sort the
+ names.
+
+ If FILES-ONLY is the symbol `t', then only the "files" in the
+ directory will be returned; subdirectories will be excluded. If
+ FILES-ONLY is not `nil' and not `t', then only the subdirectories
+ will be returned. Otherwise, if FILES-ONLY is `nil' (the default)
+ then both files and subdirectories will be returned.
+
+ (directory-files "~lewis")
+ => ("#foo#" "#foo.el#" "." ".."
+ "dired-mods.el" "files.texi"
+ "files.texi.~1~")
+
+ An error is signaled if DIRECTORY is not the name of a directory
+ that can be read.
+
+ -- Function: insert-directory file switches &optional wildcard
+ full-directory-p
+ This function inserts (in the current buffer) a directory listing
+ for directory FILE, formatted with `ls' according to SWITCHES. It
+ leaves point after the inserted text.
+
+ The argument FILE may be either a directory name or a file
+ specification including wildcard characters. If WILDCARD is
+ non-`nil', that means treat FILE as a file specification with
+ wildcards.
+
+ If FULL-DIRECTORY-P is non-`nil', that means FILE is a directory
+ and switches do not contain `-d', so that the listing should show
+ the full contents of the directory. (The `-d' option to `ls' says
+ to describe a directory itself rather than its contents.)
+
+ This function works by running a directory listing program whose
+ name is in the variable `insert-directory-program'. If WILDCARD is
+ non-`nil', it also runs the shell specified by `shell-file-name',
+ to expand the wildcards.
+
+ -- Variable: insert-directory-program
+ This variable's value is the program to run to generate a
+ directory listing for the function `insert-directory'.
+
+\1f
File: lispref.info, Node: Create/Delete Dirs, Next: Magic File Names, Prev: Contents of Directories, Up: Files
-Creating and Deleting Directories
-=================================
+35.10 Creating and Deleting Directories
+=======================================
Most XEmacs Lisp file-manipulation functions get errors when used on
files that are directories. For example, you cannot delete a directory
with `delete-file'. These special functions exist to create and delete
directories.
- - Command: make-directory dirname &optional parents
+ -- Command: make-directory dirname &optional parents
This function creates a directory named DIRNAME. Interactively,
the default choice of directory to create is the current default
directory for file names. That is useful when you have visited a
create parent directories if they don't exist. (Interactively, this
always happens.)
- - Command: delete-directory dirname
+ -- Command: delete-directory dirname
This function deletes the directory named DIRNAME. The function
`delete-file' does not work for files that are directories; you
must use `delete-directory' in that case.
\1f
File: lispref.info, Node: Magic File Names, Next: Partial Files, Prev: Create/Delete Dirs, Up: Files
-Making Certain File Names "Magic"
-=================================
+35.11 Making Certain File Names "Magic"
+=======================================
You can implement special handling for certain file names. This is
called making those names "magic". You must supply a regular
proper behavior in the case of multiple handlers, and for operations
that have two file names that may each have handlers.
- - Variable: inhibit-file-name-handlers
+ -- Variable: inhibit-file-name-handlers
This variable holds a list of handlers whose use is presently
inhibited for a certain operation.
- - Variable: inhibit-file-name-operation
+ -- Variable: inhibit-file-name-operation
The operation for which certain handlers are presently inhibited.
- - Function: find-file-name-handler filename &optional operation
+ -- Function: find-file-name-handler filename &optional operation
This function returns the handler function for file name FILENAME,
or `nil' if there is none. The argument OPERATION should be the
operation to be performed on the file--the value you will pass to
the handler as its first argument when you call it. The operation
is needed for comparison with `inhibit-file-name-operation'.
- - Function: file-local-copy filename
+ -- Function: file-local-copy filename
This function copies file FILENAME to an ordinary non-magic file,
if it isn't one already.
If FILENAME is an ordinary file name, not magic, then this function
does nothing and returns `nil'.
- - Function: unhandled-file-name-directory filename
+ -- Function: unhandled-file-name-directory filename
This function returns the name of a directory that is not magic.
It uses the directory part of FILENAME if that is not magic.
Otherwise, it asks the handler what to do.
\1f
File: lispref.info, Node: Partial Files, Next: Format Conversion, Prev: Magic File Names, Up: Files
-Partial Files
-=============
+35.12 Partial Files
+===================
* Menu:
\1f
File: lispref.info, Node: Intro to Partial Files, Next: Creating a Partial File, Up: Partial Files
-Intro to Partial Files
-----------------------
+35.12.1 Intro to Partial Files
+------------------------------
A "partial file" is a section of a buffer (called the "master buffer")
that is placed in its own buffer and treated as its own file. Changes
\1f
File: lispref.info, Node: Creating a Partial File, Next: Detached Partial Files, Prev: Intro to Partial Files, Up: Partial Files
-Creating a Partial File
------------------------
+35.12.2 Creating a Partial File
+-------------------------------
- - Command: make-file-part &optional start end name buffer
+ -- Command: make-file-part &optional start end name buffer
Make a file part on buffer BUFFER out of the region. Call it
NAME. This command creates a new buffer containing the contents
of the region and marks the buffer as referring to the specified
\1f
File: lispref.info, Node: Detached Partial Files, Prev: Creating a Partial File, Up: Partial Files
-Detached Partial Files
-----------------------
+35.12.3 Detached Partial Files
+------------------------------
Every partial file has an extent in the master buffer associated with it
(called the "master extent"), marking where in the master buffer the
\1f
File: lispref.info, Node: Format Conversion, Next: Files and MS-DOS, Prev: Partial Files, Up: Files
-File Format Conversion
-======================
+35.13 File Format Conversion
+============================
The variable `format-alist' defines a list of "file formats", which
describe textual representations used in files for the data (text,
Emacs performs format conversion if appropriate when reading and writing
files.
- - Variable: format-alist
+ -- Variable: format-alist
This list contains one format definition for each defined file
format.
format that it decodes. It stores a list of the format names in the
buffer-local variable `buffer-file-format'.
- - Variable: buffer-file-format
+ -- Variable: buffer-file-format
This variable states the format of the visited file. More
precisely, this is a list of the file format names that were
decoded in the course of visiting the current buffer's file. It
encoding functions for the formats listed in `buffer-file-format', in
the order of appearance in the list.
- - Command: format-write-file file format
+ -- Command: format-write-file file format
This command writes the current buffer contents into the file FILE
in format FORMAT, and makes that format the default for future
saves of the buffer. The argument FORMAT is a list of format
names.
- - Command: format-find-file file format
+ -- Command: format-find-file file format
This command finds the file FILE, converting it according to
format FORMAT. It also makes FORMAT the default if the buffer is
saved later.
`nil', no conversion takes place. Interactively, typing just
<RET> for FORMAT specifies `nil'.
- - Command: format-insert-file file format &optional start end
+ -- Command: format-insert-file file format &optional start end
This command inserts the contents of file FILE, converting it
according to format FORMAT. If START and END are non-`nil', they
specify which part of the file to read, as in
`nil', no conversion takes place. Interactively, typing just
<RET> for FORMAT specifies `nil'.
- - Variable: auto-save-file-format
+ -- Variable: auto-save-file-format
This variable specifies the format to use for auto-saving. Its
value is a list of format names, just like the value of
`buffer-file-format'; but it is used instead of
\1f
File: lispref.info, Node: Files and MS-DOS, Prev: Format Conversion, Up: Files
-Files and MS-DOS
-================
+35.14 Files and MS-DOS
+======================
Emacs on MS-DOS makes a distinction between text files and binary
files. This is necessary because ordinary text files on MS-DOS use a
*Note MS-DOS Subprocesses::, for a related feature for subprocesses.
- - Variable: buffer-file-type
+ -- Variable: buffer-file-type
This variable, automatically local in each buffer, records the
file type of the buffer's visited file. The value is `nil' for
text, `t' for binary.
- - Function: find-buffer-file-type filename
+ -- Function: find-buffer-file-type filename
This function determines whether file FILENAME is a text file or a
binary file. It returns `nil' for text, `t' for binary.
- - User Option: file-name-buffer-file-type-alist
+ -- User Option: file-name-buffer-file-type-alist
This variable holds an alist for distinguishing text files from
binary files. Each element has the form (REGEXP . TYPE), where
REGEXP is matched against the file name, and TYPE may be is `nil'
If it is a function, then it is called with a single argument (the
file name) and should return `t' or `nil'.
- - User Option: default-buffer-file-type
+ -- User Option: default-buffer-file-type
This variable specifies the default file type for files whose names
don't indicate anything in particular. Its value should be `nil'
for text, or `t' for binary.
- - Command: find-file-text filename
+ -- Command: find-file-text filename
Like `find-file', but treat the file as text regardless of its
name.
- - Command: find-file-binary filename
+ -- Command: find-file-binary filename
Like `find-file', but treat the file as binary regardless of its
name.
\1f
File: lispref.info, Node: Backups and Auto-Saving, Next: Buffers, Prev: Files, Up: Top
-Backups and Auto-Saving
-***********************
+36 Backups and Auto-Saving
+**************************
Backup files and auto-save files are two methods by which XEmacs tries
to protect the user from the consequences of crashes or of the user's
\1f
File: lispref.info, Node: Backup Files, Next: Auto-Saving, Up: Backups and Auto-Saving
-Backup Files
-============
+36.1 Backup Files
+=================
A "backup file" is a copy of the old contents of a file you are
editing. XEmacs makes a backup file the first time you save a buffer
\1f
File: lispref.info, Node: Making Backups, Next: Rename or Copy, Up: Backup Files
-Making Backup Files
--------------------
+36.1.1 Making Backup Files
+--------------------------
- - Function: backup-buffer
+ -- Function: backup-buffer
This function makes a backup of the file visited by the current
buffer, if appropriate. It is called by `save-buffer' before
saving the buffer the first time.
- - Variable: buffer-backed-up
+ -- Variable: buffer-backed-up
This buffer-local variable indicates whether this buffer's file has
been backed up on account of this buffer. If it is non-`nil', then
the backup file has been written. Otherwise, the file should be
backed up when it is next saved (if backups are enabled). This is
a permanent local; `kill-local-variables' does not alter it.
- - User Option: make-backup-files
+ -- User Option: make-backup-files
This variable determines whether or not to make backup files. If
it is non-`nil', then XEmacs creates a backup of each file when it
is saved for the first time--provided that `backup-inhibited' is
'make-backup-files)
(setq make-backup-files nil))))
- - Variable: backup-enable-predicate
+ -- Variable: backup-enable-predicate
This variable's value is a function to be called on certain
occasions to decide whether a file should have backup files. The
function receives one argument, a file name to consider. If the
(not (string-equal "/tmp/"
(substring name 0 5)))))
- - Variable: backup-inhibited
+ -- Variable: backup-inhibited
If this variable is non-`nil', backups are inhibited. It records
the result of testing `backup-enable-predicate' on the visited file
name. It can also coherently be used by other mechanisms that
\1f
File: lispref.info, Node: Rename or Copy, Next: Numbered Backups, Prev: Making Backups, Up: Backup Files
-Backup by Renaming or by Copying?
----------------------------------
+36.1.2 Backup by Renaming or by Copying?
+----------------------------------------
There are two ways that XEmacs can make a backup file:
non-`nil', also has this effect (as a sideline of its main
significance). *Note Saving Buffers::.
- - Variable: backup-by-copying
+ -- Variable: backup-by-copying
If this variable is non-`nil', XEmacs always makes backup files by
copying.
to be used in certain special cases. They have no effect on the
treatment of files that don't fall into the special cases.
- - Variable: backup-by-copying-when-linked
+ -- Variable: backup-by-copying-when-linked
If this variable is non-`nil', XEmacs makes backups by copying for
files with multiple names (hard links).
This variable is significant only if `backup-by-copying' is `nil',
since copying is always used when that variable is non-`nil'.
- - Variable: backup-by-copying-when-mismatch
+ -- Variable: backup-by-copying-when-mismatch
If this variable is non-`nil', XEmacs makes backups by copying in
cases where renaming would change either the owner or the group of
the file.
\1f
File: lispref.info, Node: Numbered Backups, Next: Backup Names, Prev: Rename or Copy, Up: Backup Files
-Making and Deleting Numbered Backup Files
------------------------------------------
+36.1.3 Making and Deleting Numbered Backup Files
+------------------------------------------------
If a file's name is `foo', the names of its numbered backup versions
are `foo.~V~', for various integers V, like this: `foo.~1~', `foo.~2~',
`foo.~3~', ..., `foo.~259~', and so on.
- - User Option: version-control
+ -- User Option: version-control
This variable controls whether to make a single non-numbered backup
file or multiple numbered backups.
backup versions, which must then be deleted. XEmacs can do this
automatically or it can ask the user whether to delete them.
- - User Option: kept-new-versions
+ -- User Option: kept-new-versions
The value of this variable is the number of newest versions to keep
when a new numbered backup is made. The newly made backup is
included in the count. The default value is 2.
- - User Option: kept-old-versions
+ -- User Option: kept-old-versions
The value of this variable is the number of oldest versions to keep
when a new numbered backup is made. The default value is 2.
(*note Backup Names::) is responsible for determining which backup
versions to delete, but does not delete them itself.
- - User Option: delete-old-versions
+ -- User Option: delete-old-versions
If this variable is non-`nil', then saving a file deletes excess
backup versions silently. Otherwise, it asks the user whether to
delete them.
- - User Option: dired-kept-versions
+ -- User Option: dired-kept-versions
This variable specifies how many of the newest backup versions to
keep in the Dired command `.' (`dired-clean-directory'). That's
the same thing `kept-new-versions' specifies when you make a new
\1f
File: lispref.info, Node: Backup Names, Prev: Numbered Backups, Up: Backup Files
-Naming Backup Files
--------------------
+36.1.4 Naming Backup Files
+--------------------------
The functions in this section are documented mainly because you can
customize the naming conventions for backup files by redefining them.
If you change one, you probably need to change the rest.
- - Function: backup-file-name-p filename
+ -- Function: backup-file-name-p filename
This function returns a non-`nil' value if FILENAME is a possible
name for a backup file. A file with the name FILENAME need not
exist; the function just checks the name.
This simple expression is placed in a separate function to make it
easy to redefine for customization.
- - Function: make-backup-file-name filename
+ -- Function: make-backup-file-name filename
This function returns a string that is the name to use for a
non-numbered backup file for file FILENAME. On Unix, this is just
FILENAME with a tilde appended.
(defun make-backup-file-name (filename)
(concat "." filename "~"))
-
+
(make-backup-file-name "backups.texi")
=> ".backups.texi~"
- - Function: find-backup-file-name filename
+ -- Function: find-backup-file-name filename
This function computes the file name for a new backup file for
FILENAME. It may also propose certain existing backup files for
deletion. `find-backup-file-name' returns a list whose CAR is the
(find-backup-file-name "~rms/foo")
=> ("~rms/foo.~5~" "~rms/foo.~3~")
- - Function: file-newest-backup filename
+ -- Function: file-newest-backup filename
This function returns the name of the most recent backup file for
FILENAME, or `nil' if that file has no backup files.
\1f
File: lispref.info, Node: Auto-Saving, Next: Reverting, Prev: Backup Files, Up: Backups and Auto-Saving
-Auto-Saving
-===========
+36.2 Auto-Saving
+================
XEmacs periodically saves all files that you are visiting; this is
called "auto-saving". Auto-saving prevents you from losing more than a
users. Here we describe the functions used to implement auto-saving
and the variables that control them.
- - Variable: buffer-auto-save-file-name
+ -- Variable: buffer-auto-save-file-name
This buffer-local variable is the name of the file used for
auto-saving the current buffer. It is `nil' if the buffer should
not be auto-saved.
buffer-auto-save-file-name
=> "/xcssun/users/rms/lewis/#files.texi#"
- - Command: auto-save-mode arg
+ -- Command: auto-save-mode arg
When used interactively without an argument, this command is a
toggle switch: it turns on auto-saving of the current buffer if it
is off, and vice-versa. With an argument ARG, the command turns
auto-saving on if the value of ARG is `t', a nonempty list, or a
positive integer. Otherwise, it turns auto-saving off.
- - Function: auto-save-file-name-p filename
+ -- Function: auto-save-file-name-p filename
This function returns a non-`nil' value if FILENAME is a string
that could be the name of an auto-save file. It works based on
knowledge of the naming convention for auto-save files: a name that
it, be sure to redefine the function `make-auto-save-file-name'
correspondingly.
- - Function: make-auto-save-file-name &optional filename
+ -- Function: make-auto-save-file-name &optional filename
This function returns the file name to use for auto-saving the
current buffer. This is just the file name with hash marks (`#')
appended and prepended to it. This function does not look at the
customize the naming convention for auto-save files. Be sure to
change `auto-save-file-name-p' in a corresponding way.
- - Variable: auto-save-visited-file-name
+ -- Variable: auto-save-visited-file-name
If this variable is non-`nil', XEmacs auto-saves buffers in the
files they are visiting. That is, the auto-save is done in the
same file that you are editing. Normally, this variable is `nil',
buffer. If auto-save mode is already enabled, auto-saves continue
to go in the same file name until `auto-save-mode' is called again.
- - Function: recent-auto-save-p
+ -- Function: recent-auto-save-p
This function returns `t' if the current buffer has been
auto-saved since the last time it was read in or saved.
- - Function: set-buffer-auto-saved
+ -- Function: set-buffer-auto-saved
This function marks the current buffer as auto-saved. The buffer
will not be auto-saved again until the buffer text is changed
again. The function returns `nil'.
- - User Option: auto-save-interval
+ -- User Option: auto-save-interval
The value of this variable is the number of characters that XEmacs
reads from the keyboard between auto-saves. Each time this many
more characters are read, auto-saving is done for all buffers in
which it is enabled.
- - User Option: auto-save-timeout
+ -- User Option: auto-save-timeout
The value of this variable is the number of seconds of idle time
that should cause auto-saving. Each time the user pauses for this
long, XEmacs auto-saves any buffers that need it. (Actually, the
specified timeout is multiplied by a factor depending on the size
of the current buffer.)
- - Variable: auto-save-hook
+ -- Variable: auto-save-hook
This normal hook is run whenever an auto-save is about to happen.
- - User Option: auto-save-default
+ -- User Option: auto-save-default
If this variable is non-`nil', buffers that are visiting files
have auto-saving enabled by default. Otherwise, they do not.
- - Command: do-auto-save &optional no-message current-only
+ -- Command: do-auto-save &optional no-message current-only
This function auto-saves all buffers that need to be auto-saved.
It saves all buffers for which auto-saving is enabled and that
have been changed since the previous auto-save.
If CURRENT-ONLY is non-`nil', only the current buffer is
auto-saved.
- - Function: delete-auto-save-file-if-necessary
+ -- Function: delete-auto-save-file-if-necessary
This function deletes the current buffer's auto-save file if
`delete-auto-save-files' is non-`nil'. It is called every time a
buffer is saved.
- - Variable: delete-auto-save-files
+ -- Variable: delete-auto-save-files
This variable is used by the function
`delete-auto-save-file-if-necessary'. If it is non-`nil', Emacs
deletes auto-save files when a true save is done (in the visited
file). This saves disk space and unclutters your directory.
- - Function: rename-auto-save-file
+ -- Function: rename-auto-save-file
This function adjusts the current buffer's auto-save file name if
the visited file name has changed. It also renames an existing
auto-save file. If the visited file name has not changed, this
function does nothing.
- - Variable: buffer-saved-size
+ -- Variable: buffer-saved-size
The value of this buffer-local variable is the length of the
current buffer as of the last time it was read in, saved, or
auto-saved. This is used to detect a substantial decrease in
auto-saving. Turning auto-save mode off or on also alters this
variable.
- - Variable: auto-save-list-file-name
+ -- Variable: auto-save-list-file-name
This variable (if non-`nil') specifies a file for recording the
names of all the auto-save files. Each time XEmacs does
auto-saving, it writes two lines into this file for each buffer
\1f
File: lispref.info, Node: Reverting, Prev: Auto-Saving, Up: Backups and Auto-Saving
-Reverting
-=========
+36.3 Reverting
+==============
If you have made extensive changes to a file and then change your mind
about them, you can get rid of them by reading in the previous version
of the file with the `revert-buffer' command. *Note Reverting a
Buffer: (xemacs)Reverting.
- - Command: revert-buffer &optional check-auto-save noconfirm
+ -- Command: revert-buffer &optional check-auto-save noconfirm
preserve-modes
This command replaces the buffer text with the text of the visited
file on disk. This action undoes all changes since the file was
You can customize how `revert-buffer' does its work by setting these
variables--typically, as buffer-local variables.
- - Variable: revert-buffer-function
+ -- Variable: revert-buffer-function
The value of this variable is the function to use to revert this
buffer. If non-`nil', it is called as a function with no
arguments to do the work of reverting. If the value is `nil',
fashion, give this variable a buffer-local value that is a
function to regenerate the contents.
- - Variable: revert-buffer-insert-file-contents-function
+ -- Variable: revert-buffer-insert-file-contents-function
The value of this variable, if non-`nil', is the function to use to
insert the updated contents when reverting this buffer. The
function receives two arguments: first the file name to use;
second, `t' if the user has asked to read the auto-save file.
- - Variable: before-revert-hook
+ -- Variable: before-revert-hook
This normal hook is run by `revert-buffer' before actually
inserting the modified contents--but only if
`revert-buffer-function' is `nil'.
Font Lock mode uses this hook to record that the buffer contents
are no longer fontified.
- - Variable: after-revert-hook
+ -- Variable: after-revert-hook
This normal hook is run by `revert-buffer' after actually inserting
the modified contents--but only if `revert-buffer-function' is
`nil'.
\1f
File: lispref.info, Node: Buffers, Next: Windows, Prev: Backups and Auto-Saving, Up: Top
-Buffers
-*******
+37 Buffers
+**********
A "buffer" is a Lisp object containing text to be edited. Buffers are
used to hold the contents of files that are being visited; there may
\1f
File: lispref.info, Node: Buffer Basics, Next: Current Buffer, Up: Buffers
-Buffer Basics
-=============
+37.1 Buffer Basics
+==================
A "buffer" is a Lisp object containing text to be edited. Buffers are
used to hold the contents of files that are being visited; there may
variables related to the display of buffers in windows, see *Note
Buffers and Windows::.
- - Function: bufferp object
+ -- Function: bufferp object
This function returns `t' if OBJECT is a buffer, `nil' otherwise.
\1f
File: lispref.info, Node: Current Buffer, Next: Buffer Names, Prev: Buffer Basics, Up: Buffers
-The Current Buffer
-==================
+37.2 The Current Buffer
+=======================
There are, in general, many buffers in an Emacs session. At any time,
one of them is designated as the "current buffer". This is the buffer
(set-buffer ...)
...))
- - Function: current-buffer
+ -- Function: current-buffer
This function returns the current buffer.
(current-buffer)
=> #<buffer buffers.texi>
- - Function: set-buffer buffer-or-name
+ -- Function: set-buffer buffer-or-name
This function makes BUFFER-OR-NAME the current buffer. It does
not display the buffer in the currently selected window or in any
other window, so the user cannot necessarily see the buffer. But
\1f
File: lispref.info, Node: Buffer Names, Next: Buffer File Name, Prev: Current Buffer, Up: Buffers
-Buffer Names
-============
+37.3 Buffer Names
+=================
Each buffer has a unique name, which is a string. Many of the
functions that work on buffers accept either a buffer or a buffer name
`buffer-menu' commands don't mention them. A name starting with space
also initially disables recording undo information; see *Note Undo::.
- - Function: buffer-name &optional buffer
+ -- Function: buffer-name &optional buffer
This function returns the name of BUFFER as a string. If BUFFER
is not supplied, it defaults to the current buffer.
(buffer-name)
=> "buffers.texi"
-
+
(setq foo (get-buffer "temp"))
=> #<buffer temp>
(kill-buffer foo)
foo
=> #<killed buffer>
- - Command: rename-buffer newname &optional unique
+ -- Command: rename-buffer newname &optional unique
This function renames the current buffer to NEWNAME. An error is
signaled if NEWNAME is not a string, or if there is already a
buffer with that name. The function returns `nil'.
to some other name, thus making it possible to create a second
shell buffer under the name `*shell*'.
- - Function: get-buffer buffer-or-name
+ -- Function: get-buffer buffer-or-name
This function returns the buffer named BUFFER-OR-NAME. If
BUFFER-OR-NAME is a string and there is no buffer with that name,
the value is `nil'. If BUFFER-OR-NAME is actually a buffer, it is
See also the function `get-buffer-create' in *Note Creating
Buffers::.
- - Function: generate-new-buffer-name starting-name &optional ignore
+ -- Function: generate-new-buffer-name starting-name &optional ignore
This function returns a name that would be unique for a new
buffer--but does not create the buffer. It starts with
STARTING-NAME, and produces a name not currently in use for any
\1f
File: lispref.info, Node: Buffer File Name, Next: Buffer Modification, Prev: Buffer Names, Up: Buffers
-Buffer File Name
-================
+37.4 Buffer File Name
+=====================
The "buffer file name" is the name of the file that is visited in that
buffer. When a buffer is not visiting a file, its buffer file name is
the buffer name are distinct and can be set independently. *Note
Visiting Files::.
- - Function: buffer-file-name &optional buffer
+ -- Function: buffer-file-name &optional buffer
This function returns the absolute file name of the file that
BUFFER is visiting. If BUFFER is not visiting any file,
`buffer-file-name' returns `nil'. If BUFFER is not supplied, it
(buffer-file-name (other-buffer))
=> "/usr/user/lewis/manual/files.texi"
- - Variable: buffer-file-name
+ -- Variable: buffer-file-name
This buffer-local variable contains the name of the file being
visited in the current buffer, or `nil' if it is not visiting a
file. It is a permanent local, unaffected by
buffer name, are not strictly necessary, but others are essential
to avoid confusing XEmacs.
- - Variable: buffer-file-truename
+ -- Variable: buffer-file-truename
This buffer-local variable holds the truename of the file visited
in the current buffer, or `nil' if no file is visited. It is a
permanent local, unaffected by `kill-local-variables'. *Note
Truenames::.
- - Variable: buffer-file-number
+ -- Variable: buffer-file-number
This buffer-local variable holds the file number and directory
device number of the file visited in the current buffer, or `nil'
if no file or a nonexistent file is visited. It is a permanent
accessible on the system. See the function `file-attributes', in
*Note File Attributes::, for more information about them.
- - Function: get-file-buffer filename
+ -- Function: get-file-buffer filename
This function returns the buffer visiting file FILENAME. If there
is no such buffer, it returns `nil'. The argument FILENAME, which
must be a string, is expanded (*note File Name Expansion::), then
visiting the same file name. In such cases, this function returns
the first such buffer in the buffer list.
- - Command: set-visited-file-name filename
+ -- Command: set-visited-file-name filename
If FILENAME is a non-empty string, this function changes the name
of the file visited in current buffer to FILENAME. (If the buffer
had no visited file, this gives it one.) The _next time_ the
See also `clear-visited-file-modtime' and
`verify-visited-file-modtime' in *Note Buffer Modification::.
- - Variable: list-buffers-directory
+ -- Variable: list-buffers-directory
This buffer-local variable records a string to display in a buffer
listing in place of the visited file name, for buffers that don't
have a visited file name. Dired buffers use this variable.
\1f
File: lispref.info, Node: Buffer Modification, Next: Modification Time, Prev: Buffer File Name, Up: Buffers
-Buffer Modification
-===================
+37.5 Buffer Modification
+========================
XEmacs keeps a flag called the "modified flag" for each buffer, to
record whether you have changed the text of the buffer. This flag is
The functions that modify the contents of buffers are described in
*Note Text::.
- - Function: buffer-modified-p &optional buffer
+ -- Function: buffer-modified-p &optional buffer
This function returns `t' if the buffer BUFFER has been modified
since it was last read in from a file or saved, or `nil'
otherwise. If BUFFER is not supplied, the current buffer is
tested.
- - Function: set-buffer-modified-p flag &optional buffer
+ -- Function: set-buffer-modified-p flag &optional buffer
This function marks BUFFER as modified if FLAG is non-`nil', or as
unmodified if the flag is `nil'. BUFFER defaults to the current
buffer.
(set-buffer-modified-p (buffer-modified-p))
- - Command: not-modified &optional arg
+ -- Command: not-modified &optional arg
This command marks the current buffer as unmodified, and not
needing to be saved. (If ARG is non-`nil', the buffer is instead
marked as modified.) Don't use this function in programs, since it
prints a message in the echo area; use `set-buffer-modified-p'
(above) instead.
- - Function: buffer-modified-tick &optional buffer
+ -- Function: buffer-modified-tick &optional buffer
This function returns BUFFER`s modification-count. This is a
counter that increments every time the buffer is modified. If
BUFFER is `nil' (or omitted), the current buffer is used.
\1f
File: lispref.info, Node: Modification Time, Next: Read Only Buffers, Prev: Buffer Modification, Up: Buffers
-Comparison of Modification Time
-===============================
+37.6 Comparison of Modification Time
+====================================
Suppose that you visit a file and make changes in its buffer, and
meanwhile the file itself is changed on disk. At this point, saving the
XEmacs therefore checks the file's modification time using the functions
described below before saving the file.
- - Function: verify-visited-file-modtime buffer
+ -- Function: verify-visited-file-modtime buffer
This function compares what BUFFER has recorded for the
modification time of its visited file against the actual
modification time of the file as recorded by the operating system.
The function returns `t' if the last actual modification time and
XEmacs's recorded modification time are the same, `nil' otherwise.
- - Function: clear-visited-file-modtime
+ -- Function: clear-visited-file-modtime
This function clears out the record of the last modification time
of the file being visited by the current buffer. As a result, the
next attempt to save this buffer will not complain of a
exceptional places where the usual test to avoid overwriting a
changed file should not be done.
- - Function: visited-file-modtime
+ -- Function: visited-file-modtime
This function returns the buffer's recorded last file modification
time, as a list of the form `(HIGH . LOW)'. (This is the same
format that `file-attributes' uses to return time values; see
*Note File Attributes::.)
- - Function: set-visited-file-modtime &optional time
+ -- Function: set-visited-file-modtime &optional time
This function updates the buffer's record of the last modification
time of the visited file, to the value specified by TIME if TIME
is not `nil', and otherwise to the last modification time of the
normally, or if the file itself has been changed for some known
benign reason.
- - Function: ask-user-about-supersession-threat filename
+ -- Function: ask-user-about-supersession-threat filename
This function is used to ask a user how to proceed after an
attempt to modify an obsolete buffer visiting file FILENAME. An
"obsolete buffer" is an unmodified buffer for which the associated
\1f
File: lispref.info, Node: Read Only Buffers, Next: The Buffer List, Prev: Modification Time, Up: Buffers
-Read-Only Buffers
-=================
+37.7 Read-Only Buffers
+======================
If a buffer is "read-only", then you cannot change its contents,
although you may change your view of the contents by scrolling and
`nil' (with `let') or bind `inhibit-read-only' to `t' around the
places where they change the text.
- - Variable: buffer-read-only
+ -- Variable: buffer-read-only
This buffer-local variable specifies whether the buffer is
read-only. The buffer is read-only if this variable is non-`nil'.
- - Variable: inhibit-read-only
+ -- Variable: inhibit-read-only
If this variable is non-`nil', then read-only buffers and read-only
characters may be modified. Read-only characters in a buffer are
those that have non-`nil' `read-only' properties (either text
`read-only' character properties have no effect if they are members
of the list (comparison is done with `eq').
- - Command: toggle-read-only &optional arg
+ -- Command: toggle-read-only &optional arg
This command changes whether the current buffer is read-only.
Interactively, if a prefix arg ARG is supplied, set the current
buffer read only if and only if ARG is positive.
whether you want the read-only flag on or off; so you can set
`buffer-read-only' explicitly to the proper value, `t' or `nil'.
- - Function: barf-if-buffer-read-only &optional buffer start end
+ -- Function: barf-if-buffer-read-only &optional buffer start end
This function signals a `buffer-read-only' error if BUFFER is
read-only. BUFFER defaults to the current buffer. *Note
Interactive Call::, for another way to signal an error if the
\1f
File: lispref.info, Node: The Buffer List, Next: Creating Buffers, Prev: Read Only Buffers, Up: Buffers
-The Buffer List
-===============
+37.8 The Buffer List
+====================
The "buffer list" is a list of all live buffers. Creating a buffer
adds it to this list, and killing a buffer deletes it. The order of
Note that the different buffer lists all contain the same elements.
It is only the order of those elements that is different.
- - Function: buffer-list &optional frame
+ -- Function: buffer-list &optional frame
This function returns a list of all buffers, including those whose
names begin with a space. The elements are actual buffers, not
their names. The order of the list is specific to FRAME, which
=> (#<buffer buffers.texi>
#<buffer *Minibuf-1*> #<buffer buffer.c>
#<buffer *Help*> #<buffer TAGS>)
-
+
;; Note that the name of the minibuffer
;; begins with a space!
(mapcar (function buffer-name) (buffer-list))
This list is a copy of a list used inside XEmacs; modifying it has
no effect on the buffers.
- - Function: other-buffer &optional buffer-or-name frame visible-ok
+ -- Function: other-buffer &optional buffer-or-name frame visible-ok
This function returns the first buffer in the buffer list other
than BUFFER-OR-NAME, in FRAME's ordering for the buffer list.
(FRAME defaults to the current frame. If FRAME is `t', then the
Note that in FSF Emacs 19, there is no FRAME argument, and
VISIBLE-OK is the second argument instead of the third.
- - Command: list-buffers &optional files-only
+ -- Command: list-buffers &optional files-only
This function displays a listing of the names of existing buffers.
It clears the buffer `*Buffer List*', then inserts the listing
into that buffer and displays it in a window. `list-buffers' is
intended for interactive use, and is described fully in `The XEmacs
Reference Manual'. It returns `nil'.
- - Command: bury-buffer &optional buffer-or-name before
+ -- Command: bury-buffer &optional buffer-or-name before
This function puts BUFFER-OR-NAME at the end of the buffer list
without changing the order of any of the other buffers on the list.
This buffer therefore becomes the least desirable candidate for
\1f
File: lispref.info, Node: Creating Buffers, Next: Killing Buffers, Prev: The Buffer List, Up: Buffers
-Creating Buffers
-================
+37.9 Creating Buffers
+=====================
This section describes the two primitives for creating buffers.
`get-buffer-create' creates a buffer if it finds no existing buffer
`create-file-buffer' (*note Visiting Files::). Starting a subprocess
can also create a buffer (*note Processes::).
- - Function: get-buffer-create name
+ -- Function: get-buffer-create name
This function returns a buffer named NAME. It returns an existing
buffer with that name, if one exists; otherwise, it creates a new
buffer. The buffer does not become the current buffer--this
variable `default-major-mode' is handled at a higher level. *Note
Auto Major Mode::.
- - Function: generate-new-buffer name
+ -- Function: generate-new-buffer name
This function returns a newly created, empty buffer, but does not
make it current. If there is no buffer named NAME, then that is
the name of the new buffer. If that name is in use, this function
\1f
File: lispref.info, Node: Killing Buffers, Next: Indirect Buffers, Prev: Creating Buffers, Up: Buffers
-Killing Buffers
-===============
+37.10 Killing Buffers
+=====================
"Killing a buffer" makes its name unknown to XEmacs and makes its text
space available for other use.
buffer has been killed, you can either use this feature or the function
`buffer-live-p'.
- - Function: buffer-live-p object
+ -- Function: buffer-live-p object
This function returns `t' if OBJECT is an editor buffer that has
not been deleted, `nil' otherwise.
- - Command: kill-buffer buffer-or-name
+ -- Command: kill-buffer buffer-or-name
This function kills the buffer BUFFER-OR-NAME, freeing all its
memory for use as space for other buffers. (Emacs version 18 and
older was unable to return the memory to the operating system.)
(kill-buffer "foo.unchanged")
=> nil
(kill-buffer "foo.changed")
-
+
---------- Buffer: Minibuffer ----------
Buffer foo.changed modified; kill anyway? (yes or no) yes
---------- Buffer: Minibuffer ----------
-
+
=> nil
- - Variable: kill-buffer-query-functions
+ -- Variable: kill-buffer-query-functions
After confirming unsaved changes, `kill-buffer' calls the functions
in the list `kill-buffer-query-functions', in order of appearance,
with no arguments. The buffer being killed is the current buffer
confirmation from the user for various nonstandard reasons. If
any of them returns `nil', `kill-buffer' spares the buffer's life.
- - Variable: kill-buffer-hook
+ -- Variable: kill-buffer-hook
This is a normal hook run by `kill-buffer' after asking all the
questions it is going to ask, just before actually killing the
buffer. The buffer to be killed is current when the hook
functions run. *Note Hooks::.
- - Variable: buffer-offer-save
+ -- Variable: buffer-offer-save
This variable, if non-`nil' in a particular buffer, tells
`save-buffers-kill-emacs' and `save-some-buffers' to offer to save
that buffer, just as they offer to save file-visiting buffers. The
\1f
File: lispref.info, Node: Indirect Buffers, Prev: Killing Buffers, Up: Buffers
-Indirect Buffers
-================
+37.11 Indirect Buffers
+======================
An "indirect buffer" shares the text of some other buffer, which is
called the "base buffer" of the indirect buffer. In some ways it is
Killing an indirect buffer has no effect on its base buffer. Killing
the base buffer kills all its indirect children.
- - Command: make-indirect-buffer base-buffer name
+ -- Command: make-indirect-buffer base-buffer name
This creates an indirect buffer named NAME whose base buffer is
BASE-BUFFER. The argument BASE-BUFFER may be a buffer or a string.
(make-indirect-buffer "*scratch*" "indirect")
=> #<buffer "indirect">
- - Function: buffer-base-buffer &optional buffer
+ -- Function: buffer-base-buffer &optional buffer
This function returns the base buffer of BUFFER. If BUFFER is not
indirect, the value is `nil'. Otherwise, the value is another
buffer, which is never an indirect buffer. If BUFFER is not
(buffer-base-buffer (get-buffer "indirect"))
=> #<buffer "*scratch*">
- - Function: buffer-indirect-children &optional buffer
+ -- Function: buffer-indirect-children &optional buffer
This function returns a list of all indirect buffers whose base
buffer is BUFFER. If BUFFER is indirect, the return value will
always be `nil'; see `make-indirect-buffer'. If BUFFER is not
\1f
File: lispref.info, Node: Windows, Next: Frames, Prev: Buffers, Up: Top
-Windows
-*******
+38 Windows
+**********
This chapter describes most of the functions and variables related to
Emacs windows. See *Note Display::, for information on how text is
\1f
File: lispref.info, Node: Basic Windows, Next: Splitting Windows, Up: Windows
-Basic Concepts of Emacs Windows
-===============================
+38.1 Basic Concepts of Emacs Windows
+====================================
A "window" in XEmacs is the physical area of the screen in which a
buffer is displayed. The term is also used to refer to a Lisp object
In each frame, at any time, one and only one window is designated as
"selected within the frame". The frame's cursor appears in that
-window. At ant time, one frame is the selected frame; and the window
+window. At any time, one frame is the selected frame; and the window
selected within that frame is "the selected window". The selected
window's buffer is usually the current buffer (except when `set-buffer'
has been used). *Note Current Buffer::.
*Note Display::, for information on how the contents of the window's
buffer are displayed in the window.
- - Function: windowp object
+ -- Function: windowp object
This function returns `t' if OBJECT is a window.
\1f
File: lispref.info, Node: Splitting Windows, Next: Deleting Windows, Prev: Basic Windows, Up: Windows
-Splitting Windows
-=================
+38.2 Splitting Windows
+======================
The functions described here are the primitives used to split a window
into two windows. Two higher level functions sometimes split a window,
The two "halves" of the split window initially display the same buffer
previously visible in the window that was split.
- - Function: one-window-p &optional nomini which-frames which-devices
+ -- Function: one-window-p &optional nomini which-frames which-devices
This function returns non-`nil' if there is only one window. The
argument NOMINI, if non-`nil', means don't count the minibuffer
even if it is active; otherwise, the minibuffer window is
The remaining arguments controls which set of windows are counted,
as with `next-window'.
- - Command: split-window &optional window size horizontal
+ -- Command: split-window &optional window size horizontal
This function splits WINDOW into two windows. The original window
WINDOW remains the selected window, but occupies only part of its
former screen area. The rest is occupied by a newly created
=> #<window 8 on windows.texi>
(window-edges) ; Edges in order:
=> (0 0 80 50) ; left-top-right-bottom
-
+
;; Returns window created
(setq w2 (split-window w 15))
=> #<window 28 on windows.texi>
or `|' characters. The display table can specify alternative
border characters; see *Note Display Tables::.
- - Command: split-window-vertically &optional size
+ -- Command: split-window-vertically &optional size
This function splits the selected window into two windows, one
above the other, leaving the selected window with SIZE lines.
(interactive "P")
(split-window nil (and arg (prefix-numeric-value arg))))
- - Command: split-window-horizontally &optional size
+ -- Command: split-window-horizontally &optional size
This function splits the selected window into two windows
side-by-side, leaving the selected window with SIZE columns.
\1f
File: lispref.info, Node: Deleting Windows, Next: Selecting Windows, Prev: Splitting Windows, Up: Windows
-Deleting Windows
-================
+38.3 Deleting Windows
+=====================
A window remains visible on its frame unless you "delete" it by calling
certain functions that delete windows. A deleted window cannot appear
adjacent sibling. (In Emacs version 18, the space was divided evenly
among all the siblings.)
- - Function: window-live-p window
+ -- Function: window-live-p window
This function returns `nil' if WINDOW is deleted, and `t'
otherwise.
*Warning:* Erroneous information or fatal errors may result from
using a deleted window as if it were live.
- - Command: delete-window &optional window force
+ -- Command: delete-window &optional window force
This function removes WINDOW from the display. If WINDOW is
omitted, then the selected window is deleted. If window is the
only one on its frame, the frame is deleted as well.
When `delete-window' is called interactively, the selected window
is deleted.
- - Command: delete-other-windows &optional window
+ -- Command: delete-other-windows &optional window
This function makes WINDOW the only window on its frame, by
deleting the other windows in that frame. If WINDOW is omitted or
`nil', then the selected window is used by default.
The result is `nil'.
- - Command: delete-windows-on buffer &optional which-frames
+ -- Command: delete-windows-on buffer &optional which-frames
which-devices
This function deletes all windows showing BUFFER. If there are no
windows showing BUFFER, it does nothing.
\1f
File: lispref.info, Node: Selecting Windows, Next: Cyclic Window Ordering, Prev: Deleting Windows, Up: Windows
-Selecting Windows
-=================
+38.4 Selecting Windows
+======================
When a window is selected, the buffer in the window becomes the current
buffer, and the cursor will appear in it.
- - Function: selected-window &optional device
+ -- Function: selected-window &optional device
This function returns the selected window. This is the window in
which the cursor appears and to which many commands apply. Each
separate device can have its own selected window, which is
argument DEVICE specifies which device to return the selected
window for, and defaults to the selected device.
- - Function: select-window window &optional norecord
+ -- Function: select-window window &optional norecord
This function makes WINDOW the selected window. The cursor then
appears in WINDOW (on redisplay). The buffer being displayed in
WINDOW is immediately designated the current buffer.
(select-window w)
=> #<window 65 on windows.texi>
- - Special Form: save-selected-window forms...
+ -- Special Form: save-selected-window forms...
This special form records the selected window, executes FORMS in
sequence, then restores the earlier selected window. It does not
save or restore anything about the sizes, arrangement or contents
The following functions choose one of the windows on the screen,
offering various criteria for the choice.
- - Function: get-lru-window &optional which-frames which-devices
+ -- Function: get-lru-window &optional which-frames which-devices
This function returns the window least recently "used" (that is,
selected). The selected window is always the most recently used
window.
Consider all devices without restriction.
- - Function: get-largest-window &optional which-frames which-devices
+ -- Function: get-largest-window &optional which-frames which-devices
This function returns the window with the largest area (height
times width). If there are no side-by-side windows, then this is
the window with the most lines. A minibuffer window is never a
\1f
File: lispref.info, Node: Cyclic Window Ordering, Next: Buffers and Windows, Prev: Selecting Windows, Up: Windows
-Cyclic Ordering of Windows
-==========================
+38.5 Cyclic Ordering of Windows
+===============================
When you use the command `C-x o' (`other-window') to select the next
window, it moves through all the windows on the screen in a specific
In general, within each set of siblings at any level in the window tree,
the order is left to right, or top to bottom.
- - Function: next-window &optional window minibuf which-frames
+ -- Function: next-window &optional window minibuf which-frames
which-devices
This function returns the window following WINDOW in the cyclic
ordering of windows. This is the window that `C-x o' would select
(next-window (next-window (selected-window)))
=> #<window 56 on windows.texi>
- - Function: previous-window &optional window minibuf which-frames
+ -- Function: previous-window &optional window minibuf which-frames
which-devices
This function returns the window preceding WINDOW in the cyclic
ordering of windows. The other arguments specify which windows to
include in the cycle, as in `next-window'.
- - Command: other-window count &optional which-frames which-devices
+ -- Command: other-window count &optional which-frames which-devices
This function selects the COUNTth following window in the cyclic
order. If COUNT is negative, then it selects the -COUNTth
preceding window. It returns `nil'.
The other arguments specify which windows to include in the cycle,
as in `next-window'.
- - Function: walk-windows function &optional minibuf which-frames
+ -- Function: walk-windows function &optional minibuf which-frames
which-devices
This function cycles through all windows, calling `function' once
for each window with the window as its sole argument.
\1f
File: lispref.info, Node: Buffers and Windows, Next: Displaying Buffers, Prev: Cyclic Window Ordering, Up: Windows
-Buffers and Windows
-===================
+38.6 Buffers and Windows
+========================
This section describes low-level functions to examine windows or to
display buffers in windows in a precisely controlled fashion. *Note
to use than these, but they employ heuristics in choosing or creating a
window; use these functions when you need complete control.
- - Function: set-window-buffer window buffer-or-name &optional norecord
+ -- Function: set-window-buffer window buffer-or-name &optional norecord
This function makes WINDOW display BUFFER-OR-NAME as its contents.
BUFFER-OR-NAME can be a buffer or a buffer name.
(set-window-buffer (selected-window) "foo")
=> nil
- - Function: window-buffer &optional window
+ -- Function: window-buffer &optional window
This function returns the buffer that WINDOW is displaying. If
WINDOW is omitted, this function returns the buffer for the
selected window.
(window-buffer)
=> #<buffer windows.texi>
- - Function: get-buffer-window buffer-or-name &optional which-frames
+ -- Function: get-buffer-window buffer-or-name &optional which-frames
which-devices
This function returns a window currently displaying
BUFFER-OR-NAME, or `nil' if there is none. If there are several
\1f
File: lispref.info, Node: Displaying Buffers, Next: Choosing Window, Prev: Buffers and Windows, Up: Windows
-Displaying Buffers in Windows
-=============================
+38.7 Displaying Buffers in Windows
+==================================
In this section we describe convenient functions that choose a window
automatically and use it to display a specified buffer. These functions
Excursions::), which designate buffers as current for programmed access
without affecting the display of buffers in windows.
- - Command: switch-to-buffer buffer-or-name &optional norecord
+ -- Command: switch-to-buffer buffer-or-name &optional norecord
This function makes BUFFER-OR-NAME the current buffer, and also
displays the buffer in the selected window. This means that a
human can see the buffer and subsequent keyboard commands will
the binding of `C-x b'. It is also used frequently in programs.
It always returns `nil'.
- - Command: switch-to-buffer-other-window buffer-or-name
+ -- Command: switch-to-buffer-other-window buffer-or-name
This function makes BUFFER-OR-NAME the current buffer and displays
it in a window not currently selected. It then selects that
window. The handling of the buffer is the same as in
already displaying the buffer, then it continues to do so, but
another window is nonetheless found to display it in as well.
- - Function: pop-to-buffer buffer-or-name &optional other-window
+ -- Function: pop-to-buffer buffer-or-name &optional other-window
on-frame
This function makes BUFFER-OR-NAME the current buffer and switches
to it in some window, preferably not the window previously
An example use of this function is found at the end of *Note
Filter Functions::.
- - Command: replace-buffer-in-windows buffer &optional which-frames
+ -- Command: replace-buffer-in-windows buffer &optional which-frames
which-devices
This function replaces BUFFER with some other buffer in all
windows displaying it. The other buffer used is chosen with
\1f
File: lispref.info, Node: Choosing Window, Next: Window Point, Prev: Displaying Buffers, Up: Windows
-Choosing a Window for Display
-=============================
+38.8 Choosing a Window for Display
+==================================
This section describes the basic facility that chooses a window to
display a buffer in--`display-buffer'. All the higher-level functions
and commands use this subroutine. Here we describe how to use
`display-buffer' and how to customize it.
- - Command: display-buffer buffer-or-name &optional not-this-window
+ -- Command: display-buffer buffer-or-name &optional not-this-window
override-frame
This command makes BUFFER-OR-NAME appear in some window, like
`pop-to-buffer', but it does not select that window and does not
XEmacs will not automatically change which buffer appears in the
window, such as `display-buffer' might normally do.
- - Function: window-dedicated-p window
+ -- Function: window-dedicated-p window
This function returns WINDOW's dedicated object, usually `t' or
`nil'.
- - Function: set-window-buffer-dedicated window buffer
+ -- Function: set-window-buffer-dedicated window buffer
This function makes WINDOW display BUFFER and be dedicated to that
buffer. Then XEmacs will not automatically change which buffer
appears in WINDOW. If BUFFER is `nil', this function makes WINDOW
not be dedicated (but doesn't change which buffer appears in it
currently).
- - User Option: pop-up-windows
+ -- User Option: pop-up-windows
This variable controls whether `display-buffer' makes new windows.
If it is non-`nil' and there is only one window, then that window
is split. If it is `nil', then `display-buffer' does not split
the single window, but uses it whole.
- - User Option: split-height-threshold
+ -- User Option: split-height-threshold
This variable determines when `display-buffer' may split a window,
if there are multiple windows. `display-buffer' always splits the
largest window if it has at least this many lines. If the largest
window is not this tall, it is split only if it is the sole window
and `pop-up-windows' is non-`nil'.
- - User Option: pop-up-frames
+ -- User Option: pop-up-frames
This variable controls whether `display-buffer' makes new frames.
If it is non-`nil', `display-buffer' looks for an existing window
already displaying the desired buffer, on any visible frame. If
*Note Frames::, for more information.
- - Variable: pop-up-frame-function
+ -- Variable: pop-up-frame-function
This variable specifies how to make a new frame if `pop-up-frames'
is non-`nil'.
variable is a function that creates a frame using properties from
`pop-up-frame-plist'.
- - Variable: pop-up-frame-plist
+ -- Variable: pop-up-frame-plist
This variable holds a plist specifying frame properties used when
`display-buffer' makes a new frame. *Note Frame Properties::, for
more information about frame properties.
- - Variable: special-display-buffer-names
+ -- Variable: special-display-buffer-names
A list of buffer names for buffers that should be displayed
specially. If the buffer's name is in this list, `display-buffer'
handles the buffer specially.
first argument is always the buffer to be displayed; the arguments
from the list come after that.)
- - Variable: special-display-regexps
+ -- Variable: special-display-regexps
A list of regular expressions that specify buffers that should be
displayed specially. If the buffer's name matches any of the
regular expressions in this list, `display-buffer' handles the
to create the frame. See above, under
`special-display-buffer-names'.
- - Variable: special-display-function
+ -- Variable: special-display-function
This variable holds the function to call to display a buffer
specially. It receives the buffer as an argument, and should
return the window in which it is displayed.
The default value of this variable is
`special-display-popup-frame'.
- - Function: special-display-popup-frame buffer
+ -- Function: special-display-popup-frame buffer
This function makes BUFFER visible in a frame of its own. If
BUFFER is already displayed in a window in some frame, it makes
the frame visible and raises it, to use that window. Otherwise, it
variables in your init file, before BUFFER was created, then
presumably the window was previously made by this function.
- - User Option: special-display-frame-plist
+ -- User Option: special-display-frame-plist
This variable holds frame properties for
`special-display-popup-frame' to use when it creates a frame.
- - Variable: same-window-buffer-names
+ -- Variable: same-window-buffer-names
A list of buffer names for buffers that should be displayed in the
selected window. If the buffer's name is in this list,
`display-buffer' handles the buffer by switching to it in the
selected window.
- - Variable: same-window-regexps
+ -- Variable: same-window-regexps
A list of regular expressions that specify buffers that should be
displayed in the selected window. If the buffer's name matches
any of the regular expressions in this list, `display-buffer'
handles the buffer by switching to it in the selected window.
- - Variable: display-buffer-function
+ -- Variable: display-buffer-function
This variable is the most flexible way to customize the behavior of
`display-buffer'. If it is non-`nil', it should be a function
that `display-buffer' calls to do the work. The function should
A window can be marked as "dedicated" to its buffer. Then
`display-buffer' does not try to use that window.
- - Function: window-dedicated-p window
+ -- Function: window-dedicated-p window
This function returns `t' if WINDOW is marked as dedicated;
otherwise `nil'.
- - Function: set-window-dedicated-p window flag
+ -- Function: set-window-dedicated-p window flag
This function marks WINDOW as dedicated if FLAG is non-`nil', and
nondedicated otherwise.
\1f
File: lispref.info, Node: Window Point, Next: Window Start, Prev: Choosing Window, Up: Windows
-Windows and Point
-=================
+38.9 Windows and Point
+======================
Each window has its own value of point, independent of the value of
point in other windows displaying the same buffer. This makes it useful
when the user switches to another buffer, the cursor jumps to the
position of point in that buffer.
- - Function: window-point &optional window
+ -- Function: window-point &optional window
This function returns the current position of point in WINDOW.
For a non-selected window, this is the value point would have (in
that window's buffer) if that window were selected.
"top-level" value of point, outside of any `save-excursion' forms.
But that value is hard to find.
- - Function: set-window-point window position
+ -- Function: set-window-point window position
This function positions point in WINDOW at position POSITION in
WINDOW's buffer.
\1f
File: lispref.info, Node: Window Start, Next: Vertical Scrolling, Prev: Window Point, Up: Windows
-The Window Start Position
-=========================
+38.10 The Window Start Position
+===============================
Each window contains a marker used to keep track of a buffer position
that specifies where in the buffer display should start. This position
the upper left corner of the window. It is usually, but not
inevitably, at the beginning of a text line.
- - Function: window-start &optional window
+ -- Function: window-start &optional window
This function returns the display-start position of window WINDOW.
If WINDOW is `nil', the selected window is used. For example,
For a realistic example, see the description of `count-lines' in
*Note Text Lines::.
- - Function: window-end &optional window guarantee
+ -- Function: window-end &optional window guarantee
This function returns the position of the end of the display in
window WINDOW. If WINDOW is `nil', the selected window is used.
set.
- - Function: set-window-start window position &optional noforce
+ -- Function: set-window-start window position &optional noforce
This function sets the display-start position of WINDOW to
POSITION in WINDOW's buffer. It returns POSITION.
;; Here is what `foo' looks like before executing
;; the `set-window-start' expression.
-
+
---------- Buffer: foo ----------
-!-This is the contents of buffer foo.
2
5
6
---------- Buffer: foo ----------
-
+
(set-window-start
(selected-window)
(1+ (window-start)))
=> 2
-
+
;; Here is what `foo' looks like after executing
;; the `set-window-start' expression.
---------- Buffer: foo ----------
at the next redisplay, then redisplay computes a new window-start
position that works well with point, and thus POSITION is not used.
- - Function: pos-visible-in-window-p &optional position window
+ -- Function: pos-visible-in-window-p &optional position window
This function returns `t' if POSITION is within the range of text
currently visible on the screen in WINDOW. It returns `nil' if
POSITION is scrolled vertically out of view. The argument
\1f
File: lispref.info, Node: Vertical Scrolling, Next: Horizontal Scrolling, Prev: Window Start, Up: Windows
-Vertical Scrolling
-==================
+38.11 Vertical Scrolling
+========================
Vertical scrolling means moving the text up or down in a window. It
works by changing the value of the window's display-start location. It
unpredictable results if the current buffer is different from the buffer
that is displayed in the selected window. *Note Current Buffer::.
- - Command: scroll-up &optional lines
+ -- Command: scroll-up &optional lines
This function scrolls the text in the selected window upward LINES
lines. If LINES is negative, scrolling is actually downward.
`scroll-up' returns `nil'.
- - Command: scroll-down &optional lines
+ -- Command: scroll-down &optional lines
This function scrolls the text in the selected window downward
LINES lines. If LINES is negative, scrolling is actually upward.
`scroll-down' returns `nil'.
- - Command: scroll-other-window &optional lines
+ -- Command: scroll-other-window &optional lines
This function scrolls the text in another window upward LINES
lines. Negative values of LINES, or `nil', are handled as in
`scroll-up'.
to, so the line reappears after the echo area momentarily displays
the message "Beginning of buffer".
- - Variable: other-window-scroll-buffer
+ -- Variable: other-window-scroll-buffer
If this variable is non-`nil', it tells `scroll-other-window'
which buffer to scroll.
- - User Option: scroll-step
+ -- User Option: scroll-step
This variable controls how scrolling is done automatically when
point moves off the screen. If the value is zero, then redisplay
scrolls the text to center point vertically in the window. If the
screen by scrolling N lines in either direction, if possible;
otherwise, it centers point. The default value is zero.
- - User Option: scroll-conservatively
+ -- User Option: scroll-conservatively
This variable controls how many lines Emacs tries to scroll before
recentering. If you set it to a small number, then when you move
point a short distance off the screen, XEmacs will scroll the
that does not exceed `scroll-conservatively' lines. This variable
overrides the redisplay preemption.
- - User Option: next-screen-context-lines
+ -- User Option: next-screen-context-lines
The value of this variable is the number of lines of continuity to
retain when scrolling by full screens. For example, `scroll-up'
with an argument of `nil' scrolls so that this many lines at the
bottom of the window appear instead at the top. The default value
is `2'.
- - Command: recenter &optional location window
+ -- Command: recenter &optional location window
This function scrolls WINDOW (which defaults to the selected
window) to put the text where point is located at a specified
vertical position within the window.
Replaces three keystroke sequence C-u 0 C-l."
(interactive)
(recenter 0))
-
+
(global-set-key [kp-multiply] 'line-to-top-of-window)
\1f
File: lispref.info, Node: Horizontal Scrolling, Next: Size of Window, Prev: Vertical Scrolling, Up: Windows
-Horizontal Scrolling
-====================
+38.12 Horizontal Scrolling
+==========================
Because we read English first from top to bottom and second from left
to right, horizontal scrolling is not like vertical scrolling. Vertical
to how far left you can scroll, but eventually all the text will
disappear off the left edge.
- - Command: scroll-left &optional count
+ -- Command: scroll-left &optional count
This function scrolls the selected window COUNT columns to the
left (or to the right if COUNT is negative). The return value is
the total amount of leftward horizontal scrolling in effect after
the change--just like the value returned by `window-hscroll'
(below).
- - Command: scroll-right &optional count
+ -- Command: scroll-right &optional count
This function scrolls the selected window COUNT columns to the
right (or to the left if COUNT is negative). The return value is
the total amount of leftward horizontal scrolling in effect after
normal position where the total leftward scrolling is zero,
attempts to scroll any farther right have no effect.
- - Function: window-hscroll &optional window
+ -- Function: window-hscroll &optional window
This function returns the total leftward horizontal scrolling of
WINDOW--the number of columns by which the text in WINDOW is
scrolled left past the left margin.
(window-hscroll)
=> 5
- - Function: set-window-hscroll window columns
+ -- Function: set-window-hscroll window columns
This function sets the number of columns from the left margin that
WINDOW is scrolled to the value of COLUMNS. The argument COLUMNS
should be zero or positive; if not, it is taken as zero.
\1f
File: lispref.info, Node: Size of Window, Next: Position of Window, Prev: Horizontal Scrolling, Up: Windows
-The Size of a Window
-====================
+38.13 The Size of a Window
+==========================
An Emacs window is rectangular, and its size information consists of
the height (in lines or pixels) and the width (in character positions
The following functions return size information about a window:
- - Function: window-height &optional window
+ -- Function: window-height &optional window
This function returns the number of lines in WINDOW, including its
modeline but not including the horizontal scrollbar, if any (this
is different from `window-pixel-height'). If WINDOW is `nil', the
(window-height)
=> 20
- - Function: window-width &optional window
+ -- Function: window-width &optional window
This function returns the number of columns in WINDOW, not
including any left margin, right margin, or vertical scrollbar
(this is different from `window-pixel-width'). If WINDOW is
not for full-frame windows. You can change this using the variables
`truncate-lines' and `truncate-partial-width-windows'.)
- - Function: window-pixel-height &optional window
+ -- Function: window-pixel-height &optional window
This function returns the height of WINDOW in pixels, including
its modeline and horizontal scrollbar, if any. If WINDOW is
`nil', the function uses the selected window.
(window-pixel-height)
=> 300
- - Function: window-pixel-width &optional window
+ -- Function: window-pixel-width &optional window
This function returns the width of WINDOW in pixels, including any
left margin, right margin, or vertical scrollbar that may be
displayed alongside it. If WINDOW is `nil', the function uses the
(window-pixel-height)
=> 600
- - Function: window-text-area-pixel-height &optional window
+ -- Function: window-text-area-pixel-height &optional window
This function returns the height in pixels of the text displaying
portion of WINDOW, which defaults to the selected window. Unlike
`window-pixel-height', the space occupied by the modeline and
horizontal scrollbar, if any, is not counted.
- - Function: window-text-area-pixel-width &optional window
+ -- Function: window-text-area-pixel-width &optional window
This function returns the width in pixels of the text displaying
portion of WINDOW, which defaults to the selected window. Unlike
`window-pixel-width', the space occupied by the vertical scrollbar
and divider, if any, is not counted.
- - Function: window-displayed-text-pixel-height &optional window
+ -- Function: window-displayed-text-pixel-height &optional window
noclipped
This function returns the height in pixels of the text displayed in
WINDOW, which defaults to the selected window. Unlike
\1f
File: lispref.info, Node: Position of Window, Next: Resizing Windows, Prev: Size of Window, Up: Windows
-The Position of a Window
-========================
+38.14 The Position of a Window
+==============================
XEmacs provides functions to determine the absolute location of windows
within a frame, and the relative location of a window in comparison to
other windows in the same frame.
- - Function: window-pixel-edges &optional window
+ -- Function: window-pixel-edges &optional window
This function returns a list of the pixel edge coordinates of
WINDOW. If WINDOW is `nil', the selected window is used.
make sense in a world with variable-width and variable-height lines, as
are allowed in XEmacs.
- - Function: window-highest-p window
+ -- Function: window-highest-p window
This function returns non-`nil' if WINDOW is along the top of its
frame.
- - Function: window-lowest-p window
+ -- Function: window-lowest-p window
This function returns non-`nil' if WINDOW is along the bottom of
its frame.
- - Function: window-text-area-pixel-edges &optional window
+ -- Function: window-text-area-pixel-edges &optional window
This function allows one to determine the location of the
text-displaying portion of WINDOW, which defaults to the selected
window, with respect to the top left corner of the window. It
\1f
File: lispref.info, Node: Resizing Windows, Next: Window Configurations, Prev: Position of Window, Up: Windows
-Changing the Size of a Window
-=============================
+38.15 Changing the Size of a Window
+===================================
The window size functions fall into two classes: high-level commands
that change the size of windows and low-level functions that access
window size. XEmacs does not permit overlapping windows or gaps between
windows, so resizing one window affects other windows.
- - Command: enlarge-window count &optional horizontal window
+ -- Command: enlarge-window count &optional horizontal window
This function makes the selected window COUNT lines taller,
stealing lines from neighboring windows. It takes the lines from
one window at a time until that window is used up, then takes from
`enlarge-window' returns `nil'.
- - Command: enlarge-window-horizontally columns
+ -- Command: enlarge-window-horizontally columns
This function makes the selected window COLUMNS wider. It could
be defined as follows:
(defun enlarge-window-horizontally (columns)
(enlarge-window columns t))
- - Command: enlarge-window-pixels count &optional side window
+ -- Command: enlarge-window-pixels count &optional side window
This function makes the selected window COUNT pixels larger. When
called from Lisp, optional second argument SIDE non-`nil' means to
grow sideways COUNT pixels, and optional third argument WINDOW
specifies the window to change instead of the selected window.
- - Command: shrink-window count &optional horizontal window
+ -- Command: shrink-window count &optional horizontal window
This function is like `enlarge-window' but negates the argument
COUNT, making the selected window smaller by giving lines (or
columns) to the other windows. If the window shrinks below
If WINDOW is non-`nil', it specifies a window to change instead of
the selected window.
- - Command: shrink-window-horizontally columns
+ -- Command: shrink-window-horizontally columns
This function makes the selected window COLUMNS narrower. It
could be defined as follows:
(defun shrink-window-horizontally (columns)
(shrink-window columns t))
- - Command: shrink-window-pixels count &optional side window
+ -- Command: shrink-window-pixels count &optional side window
This function makes the selected window COUNT pixels smaller.
When called from Lisp, optional second argument SIDE non-`nil'
means to shrink sideways COUNT pixels, and optional third argument
The following two variables constrain the window-size-changing
functions to a minimum height and width.
- - User Option: window-min-height
+ -- User Option: window-min-height
The value of this variable determines how short a window may become
before it is automatically deleted. Making a window smaller than
`window-min-height' automatically deletes it, and no window may be
display). Actions that change window sizes reset this variable to
two if it is less than two. The default value is 4.
- - User Option: window-min-width
+ -- User Option: window-min-width
The value of this variable determines how narrow a window may
become before it automatically deleted. Making a window smaller
than `window-min-width' automatically deletes it, and no window
may be created narrower than this. The absolute minimum width is
one; any value below that is ignored. The default value is 10.
- - Variable: window-size-change-functions
+ -- Variable: window-size-change-functions
This variable holds a list of functions to be called if the size
of any window changes for any reason. The functions are called
just once per redisplay, and just once for each frame on which
\1f
File: lispref.info, Node: Window Configurations, Prev: Resizing Windows, Up: Windows
-Window Configurations
-=====================
+38.16 Window Configurations
+===========================
A "window configuration" records the entire layout of a frame--all
windows, their sizes, which buffers they contain, what part of each
configuration instead of a window configuration. *Note Frame
Configurations::.
- - Function: current-window-configuration &optional frame
+ -- Function: current-window-configuration &optional frame
This function returns a new object representing the current window
configuration of FRAME, namely the number of windows, their sizes
and current buffers, which window is the selected window, and for
FRAME defaults to the selected frame.
- - Function: set-window-configuration configuration
+ -- Function: set-window-configuration configuration
This function restores the configuration of XEmacs's windows and
buffers to the state specified by CONFIGURATION. The argument
CONFIGURATION must be a value that was previously returned by
...)
(set-window-configuration config)))
- - Special Form: save-window-excursion forms...
+ -- Special Form: save-window-excursion forms...
This special form records the window configuration, executes FORMS
in sequence, then restores the earlier window configuration. The
window configuration includes the value of point and the portion
=> do-something
;; The frame is now split again.
- - Function: window-configuration-p object
+ -- Function: window-configuration-p object
This function returns `t' if OBJECT is a window configuration.
Primitives to look inside of window configurations would make sense,
\1f
File: lispref.info, Node: Frames, Next: Consoles and Devices, Prev: Windows, Up: Top
-Frames
-******
+39 Frames
+*********
A FRAME is a rectangle on the screen that contains one or more XEmacs
windows (*note Windows::). A frame initially contains a single main
display multiple X window frames at the same time, each in its own X
window.
- - Function: framep object
+ -- Function: framep object
This predicate returns `t' if OBJECT is a frame, and `nil'
otherwise.
\1f
File: lispref.info, Node: Creating Frames, Next: Frame Properties, Up: Frames
-Creating Frames
-===============
+39.1 Creating Frames
+====================
To create a new frame, call the function `make-frame'.
- - Command: make-frame &optional props device
+ -- Command: make-frame &optional props device
This function creates a new frame on DEVICE, if DEVICE permits
creation of frames. (An X server does; an ordinary terminal does
not (yet).) DEVICE defaults to the selected device if omitted.
\1f
File: lispref.info, Node: Frame Properties, Next: Frame Titles, Prev: Creating Frames, Up: Frames
-Frame Properties
-================
+39.2 Frame Properties
+=====================
A frame has many properties that control its appearance and behavior.
Just what properties a frame has depends on which display mechanism it
\1f
File: lispref.info, Node: Property Access, Next: Initial Properties, Up: Frame Properties
-Access to Frame Properties
---------------------------
+39.2.1 Access to Frame Properties
+---------------------------------
These functions let you read and change the properties of a frame.
- - Function: frame-properties &optional frame
+ -- Function: frame-properties &optional frame
This function returns a plist listing all the properties of FRAME
and their values.
- - Function: frame-property frame property &optional default
+ -- Function: frame-property frame property &optional default
This function returns FRAME's value for the property PROPERTY, or
DEFAULT if there is no such property.
- - Function: set-frame-properties frame plist
+ -- Function: set-frame-properties frame plist
This function alters the properties of frame FRAME based on the
elements of property list PLIST. If you don't mention a property
in PLIST, its value doesn't change.
- - Function: set-frame-property frame property value
+ -- Function: set-frame-property frame property value
This function sets the property PROPERTY of frame FRAME to the
value VALUE.
\1f
File: lispref.info, Node: Initial Properties, Next: X Frame Properties, Prev: Property Access, Up: Frame Properties
-Initial Frame Properties
-------------------------
+39.2.2 Initial Frame Properties
+-------------------------------
You can specify the properties for the initial startup frame by setting
`initial-frame-plist' in your `.emacs' file.
- - Variable: initial-frame-plist
+ -- Variable: initial-frame-plist
This variable's value is a plist of alternating property-value
pairs used when creating the initial X window frame.
`minibuffer' property of `nil', and you have not yet created one,
XEmacs creates one for you.
- - Variable: minibuffer-frame-plist
+ -- Variable: minibuffer-frame-plist
This variable's value is a plist of properties used when creating
an initial minibuffer-only frame--if such a frame is needed,
according to the properties for the main initial frame.
- - Variable: default-frame-plist
+ -- Variable: default-frame-plist
This is a plist specifying default values of frame properties for
subsequent XEmacs frames (not the initial ones).
\1f
File: lispref.info, Node: X Frame Properties, Next: Size and Position, Prev: Initial Properties, Up: Frame Properties
-X Window Frame Properties
--------------------------
+39.2.3 X Window Frame Properties
+--------------------------------
Just what properties a frame has depends on what display mechanism it
uses. Here is a table of the properties of an X window frame; of these,
\1f
File: lispref.info, Node: Size and Position, Next: Frame Name, Prev: X Frame Properties, Up: Frame Properties
-Frame Size And Position
------------------------
+39.2.4 Frame Size And Position
+------------------------------
You can read or change the size and position of a frame using the frame
properties `left', `top', `height', and `width'. Whatever geometry
Here are some special features for working with sizes and positions:
- - Function: set-frame-position frame left top
+ -- Function: set-frame-position frame left top
This function sets the position of the top left corner of FRAME to
LEFT and TOP. These arguments are measured in pixels, and count
from the top left corner of the screen. Negative property values
count up or rightward from the top left corner of the screen.
- - Function: frame-height &optional frame
- - Function: frame-width &optional frame
+ -- Function: frame-height &optional frame
+ -- Function: frame-width &optional frame
These functions return the height and width of FRAME, measured in
lines and columns. If you don't supply FRAME, they use the
selected frame.
- - Function: frame-pixel-height &optional frame
- - Function: frame-pixel-width &optional frame
+ -- Function: frame-pixel-height &optional frame
+ -- Function: frame-pixel-width &optional frame
These functions return the height and width of FRAME, measured in
pixels. If you don't supply FRAME, they use the selected frame.
- - Function: set-frame-size frame cols rows &optional pretend
+ -- Function: set-frame-size frame cols rows &optional pretend
This function sets the size of FRAME, measured in characters; COLS
and ROWS specify the new width and height. (If PRETEND is
non-`nil', it means that redisplay should act as if the frame's
\1f
File: lispref.info, Node: Frame Name, Prev: Size and Position, Up: Frame Properties
-The Name of a Frame (As Opposed to Its Title)
----------------------------------------------
+39.2.5 The Name of a Frame (As Opposed to Its Title)
+----------------------------------------------------
Under X, every frame has a name, which is not the same as the title of
the frame. A frame's name is used to look up its resources and does
not normally change over the lifetime of a frame. It is perfectly
allowable, and quite common, for multiple frames to have the same name.
- - Function: frame-name &optional frame
+ -- Function: frame-name &optional frame
This function returns the name of FRAME, which defaults to the
selected frame if not specified. The name of a frame can also be
obtained from the frame's properties. *Note Frame Properties::.
- - Variable: default-frame-name
+ -- Variable: default-frame-name
This variable holds the default name to assign to newly-created
frames. This can be overridden by arguments to `make-frame'. This
must be a string.
\1f
File: lispref.info, Node: Frame Titles, Next: Deleting Frames, Prev: Frame Properties, Up: Frames
-Frame Titles
-============
+39.3 Frame Titles
+=================
Every frame has a title; most window managers display the frame title at
the top of the frame. You can specify an explicit title with the
XEmacs computes the frame title based on a template stored in the
variable `frame-title-format'.
- - Variable: frame-title-format
+ -- Variable: frame-title-format
This variable specifies how to compute a title for a frame when
you have not explicitly specified one.
The variable's value is actually a modeline construct, just like
`modeline-format'. *Note Modeline Data::.
- - Variable: frame-icon-title-format
+ -- Variable: frame-icon-title-format
This variable specifies how to compute the title for an iconified
frame, when you have not explicitly specified the frame title.
This title appears in the icon itself.
- - Function: x-set-frame-icon-pixmap frame pixmap &optional mask
+ -- Function: x-set-frame-icon-pixmap frame pixmap &optional mask
This function sets the icon of the given frame to the given image
instance, which should be an image instance object (as returned by
`make-image-instance'), a glyph object (as returned by
\1f
File: lispref.info, Node: Deleting Frames, Next: Finding All Frames, Prev: Frame Titles, Up: Frames
-Deleting Frames
-===============
+39.4 Deleting Frames
+====================
Frames remain potentially visible until you explicitly "delete" them.
A deleted frame cannot appear on the screen, but continues to exist as
a Lisp object until there are no references to it.
- - Command: delete-frame &optional frame force
+ -- Command: delete-frame &optional frame force
This function deletes the frame FRAME. By default, FRAME is the
selected frame.
delete the last frame. (This will automatically call
`save-buffers-kill-emacs'.)
- - Function: frame-live-p frame
+ -- Function: frame-live-p frame
The function `frame-live-p' returns non-`nil' if the frame FRAME
has not been deleted.
\1f
File: lispref.info, Node: Finding All Frames, Next: Frames and Windows, Prev: Deleting Frames, Up: Frames
-Finding All Frames
-==================
+39.5 Finding All Frames
+=======================
- - Function: frame-list
+ -- Function: frame-list
The function `frame-list' returns a list of all the frames that
have not been deleted. It is analogous to `buffer-list' for
buffers. The list that you get is newly created, so modifying the
list doesn't have any effect on the internals of XEmacs.
- - Function: device-frame-list &optional device
+ -- Function: device-frame-list &optional device
This function returns a list of all frames on DEVICE. If DEVICE
is `nil', the selected device will be used.
- - Function: visible-frame-list &optional device
+ -- Function: visible-frame-list &optional device
This function returns a list of just the currently visible frames.
If DEVICE is specified only frames on that device will be returned.
*Note Visibility of Frames::. (TTY frames always count as
"visible", even though only the selected one is actually
displayed.)
- - Function: next-frame &optional frame which-frames which-devices
+ -- Function: next-frame &optional frame which-frames which-devices
The function `next-frame' lets you cycle conveniently through all
the frames from an arbitrary starting point. It returns the "next"
frame after FRAME in the cycle. If FRAME defaults to the selected
anything else
Consider all devices without restriction.
- - Function: previous-frame &optional frame which-frames which-devices
+ -- Function: previous-frame &optional frame which-frames which-devices
Like `next-frame', but cycles through all frames in the opposite
direction.
\1f
File: lispref.info, Node: Frames and Windows, Next: Minibuffers and Frames, Prev: Finding All Frames, Up: Frames
-Frames and Windows
-==================
+39.6 Frames and Windows
+=======================
Each window is part of one and only one frame; you can get the frame
with `window-frame'.
- - Function: frame-root-window &optional frame
+ -- Function: frame-root-window &optional frame
This returns the root window of frame FRAME. FRAME defaults to
the selected frame if not specified.
- - Function: window-frame &optional window
+ -- Function: window-frame &optional window
This function returns the frame that WINDOW is on. WINDOW
defaults to the selected window if omitted.
the lower right corner (always the minibuffer window, if the frame has
one), and then it moves back to the top.
- - Function: frame-highest-window &optional frame position
+ -- Function: frame-highest-window &optional frame position
This function returns the topmost, leftmost window of frame FRAME
at position POSITION.
The following three functions work similarly.
- - Function: frame-lowest-window &optional frame position
+ -- Function: frame-lowest-window &optional frame position
This function returns the lowest window on FRAME which is at
POSITION.
- - Function: frame-leftmost-window &optional frame position
+ -- Function: frame-leftmost-window &optional frame position
This function returns the leftmost window on FRAME which is at
POSITION.
- - Function: frame-rightmost-window &optional frame position
+ -- Function: frame-rightmost-window &optional frame position
This function returns the rightmost window on FRAME which is at
POSITION.
frame also selects this window. You can get the frame's current
selected window with `frame-selected-window'.
- - Function: frame-selected-window &optional frame
+ -- Function: frame-selected-window &optional frame
This function returns the window on FRAME that is selected within
FRAME. FRAME defaults to the selected frame if not specified.
\1f
File: lispref.info, Node: Minibuffers and Frames, Next: Input Focus, Prev: Frames and Windows, Up: Frames
-Minibuffers and Frames
-======================
+39.7 Minibuffers and Frames
+===========================
Normally, each frame has its own minibuffer window at the bottom, which
is used whenever that frame is selected. If the frame has a minibuffer,
`default-minibuffer-frame'. Its value should be a frame which does
have a minibuffer.
- - Variable: default-minibuffer-frame
+ -- Variable: default-minibuffer-frame
This variable specifies the frame to use for the minibuffer
window, by default.
\1f
File: lispref.info, Node: Input Focus, Next: Visibility of Frames, Prev: Minibuffers and Frames, Up: Frames
-Input Focus
-===========
+39.8 Input Focus
+================
At any time, one frame in XEmacs is the "selected frame". The selected
window always resides on the selected frame. As the focus moves from
device to device, the selected frame on each device is remembered and
restored when the focus moves back to that device.
- - Function: selected-frame &optional device
+ -- Function: selected-frame &optional device
This function returns the selected frame on DEVICE. If DEVICE is
not specified, the selected device will be used. If no frames
exist on the device, `nil' is returned.
number of the selected frame appears in the mode line after the word
`XEmacs' (*note Modeline Variables::).
- - Function: select-frame frame
+ -- Function: select-frame frame
This function selects frame FRAME, temporarily disregarding the
focus of the X server if any. The selection of FRAME lasts until
the next time the user does something to select a different frame,
`set-buffer'. In order to effect a permanent focus change use
`focus-frame'.
- - Function: focus-frame frame
+ -- Function: focus-frame frame
This function selects FRAME and gives it the window system focus.
The operation of `focus-frame' is not affected by the value of
`focus-follows-mouse'.
- - Special Form: save-selected-frame forms...
+ -- Special Form: save-selected-frame forms...
This special form records the selected frame, executes FORMS in
sequence, then restores the earlier selected frame. The value
returned is the value of the last form.
- - Special Form: with-selected-frame frame forms...
+ -- Special Form: with-selected-frame frame forms...
This special form records the selected frame, then selects FRAME
and executes FORMS in sequence. After the last form is finished,
the earlier selected frame is restored. The value returned is the
\1f
File: lispref.info, Node: Visibility of Frames, Next: Raising and Lowering, Prev: Input Focus, Up: Frames
-Visibility of Frames
-====================
+39.9 Visibility of Frames
+=========================
An frame on a window system may be "visible", "invisible", or
"iconified". If it is visible, you can see its contents. If it is
Visibility is meaningless for TTY frames, since only the selected
one is actually displayed in any case.
- - Function: make-frame-visible &optional frame
+ -- Function: make-frame-visible &optional frame
This function makes frame FRAME visible. If you omit FRAME, it
makes the selected frame visible.
- - Function: make-frame-invisible &optional frame force
+ -- Function: make-frame-invisible &optional frame force
This function makes frame FRAME invisible.
- - Command: iconify-frame &optional frame
+ -- Command: iconify-frame &optional frame
This function iconifies frame FRAME.
- - Function: Command deiconify-frame &optional frame
+ -- Function: Command deiconify-frame &optional frame
This function de-iconifies frame FRAME. Under a window system,
this is equivalent to `make-frame-visible'.
- - Function: frame-visible-p &optional frame
+ -- Function: frame-visible-p &optional frame
This returns whether FRAME is currently "visible" (actually in use
for display). A frame that is not visible is not updated, and, if
it works through a window system, may not show at all.
- - Function: frame-iconified-p &optional frame
+ -- Function: frame-iconified-p &optional frame
This returns whether FRAME is iconified. Not all window managers
use icons; some merely unmap the window, so this function is not
the inverse of `frame-visible-p'. It is possible for a frame to
functionality of this function is obtained through
`frame-visible-p'.)
- - Function: frame-totally-visible-p &optional frame
+ -- Function: frame-totally-visible-p &optional frame
This returns whether FRAME is not obscured by any other X windows.
On TTY frames, this is the same as `frame-visible-p'.
\1f
File: lispref.info, Node: Raising and Lowering, Next: Frame Configurations, Prev: Visibility of Frames, Up: Frames
-Raising and Lowering Frames
-===========================
+39.10 Raising and Lowering Frames
+=================================
The X Window System uses a desktop metaphor. Part of this metaphor is
the idea that windows are stacked in a notional third dimension
You can raise and lower XEmacs's X windows with these functions:
- - Command: raise-frame &optional frame
+ -- Command: raise-frame &optional frame
This function raises frame FRAME.
- - Command: lower-frame &optional frame
+ -- Command: lower-frame &optional frame
This function lowers frame FRAME.
You can also specify auto-raise (raising automatically when a frame
functionality is provided through the `auto-raise' and `auto-lower'
frame properties.)
- - Variable: auto-raise-frame
+ -- Variable: auto-raise-frame
This variable's value is `t' if frames will be raised to the top
when selected.
- - Variable: auto-lower-frame
+ -- Variable: auto-lower-frame
This variable's value is `t' if frames will be lowered to the
bottom when no longer selected.
Hooks::). Under normal circumstances, you should not call these
functions directly.
- - Function: default-select-frame-hook
+ -- Function: default-select-frame-hook
This hook function implements the `auto-raise-frame' variable; it
is for use as the value of `select-frame-hook'.
- - Function: default-deselect-frame-hook
+ -- Function: default-deselect-frame-hook
This hook function implements the `auto-lower-frame' variable; it
is for use as the value of `deselect-frame-hook'.
\1f
File: lispref.info, Node: Frame Configurations, Next: Frame Hooks, Prev: Raising and Lowering, Up: Frames
-Frame Configurations
-====================
+39.11 Frame Configurations
+==========================
A "frame configuration" records the current arrangement of frames, all
their properties, and the window configuration of each one.
- - Function: current-frame-configuration
+ -- Function: current-frame-configuration
This function returns a frame configuration list that describes
the current arrangement of frames and their contents.
- - Function: set-frame-configuration configuration &optional nodelete
+ -- Function: set-frame-configuration configuration &optional nodelete
This function restores the state of frames described by
CONFIGURATION, which should be the return value from a previous
call to `current-frame-configuration'.
\1f
File: lispref.info, Node: Frame Hooks, Prev: Frame Configurations, Up: Frames
-Hooks for Customizing Frame Behavior
-====================================
+39.12 Hooks for Customizing Frame Behavior
+==========================================
XEmacs provides many hooks that are called at various times during a
frame's lifetime. *Note Hooks::.
- - Variable: create-frame-hook
+ -- Variable: create-frame-hook
This hook is called each time a frame is created. The functions
are called with one argument, the newly-created frame.
- - Variable: delete-frame-hook
+ -- Variable: delete-frame-hook
This hook is called each time a frame is deleted. The functions
are called with one argument, the about-to-be-deleted frame.
- - Variable: select-frame-hook
+ -- Variable: select-frame-hook
This is a normal hook that is run just after a frame is selected.
The function `default-select-frame-hook', which implements
auto-raising (*note Raising and Lowering::), is normally attached
the next time that XEmacs is waiting for an event, and even then,
the window manager may refuse the focus-change request.
- - Variable: deselect-frame-hook
+ -- Variable: deselect-frame-hook
This is a normal hook that is run just before a frame is deselected
(and another frame is selected). The function
`default-deselect-frame-hook', which implements auto-lowering
(*note Raising and Lowering::), is normally attached to this hook.
- - Variable: map-frame-hook
+ -- Variable: map-frame-hook
This hook is called each time a frame is mapped (i.e. made
visible). The functions are called with one argument, the newly
mapped frame.
- - Variable: unmap-frame-hook
+ -- Variable: unmap-frame-hook
This hook is called each time a frame is unmapped (i.e. made
invisible or iconified). The functions are called with one
argument, the newly unmapped frame.
\1f
File: lispref.info, Node: Consoles and Devices, Next: Positions, Prev: Frames, Up: Top
-Consoles and Devices
-********************
+40 Consoles and Devices
+***********************
A "console" is an object representing a single input connection to
XEmacs, such as an X display or a TTY connection. It is possible for
specifying which device the function pertains to. If the argument is
omitted, it defaults to the selected device (see below).
- - Function: consolep object
+ -- Function: consolep object
This returns non-`nil' if OBJECT is a console.
- - Function: devicep object
+ -- Function: devicep object
This returns non-`nil' if OBJECT is a device.
* Menu:
\1f
File: lispref.info, Node: Basic Console Functions, Next: Basic Device Functions, Up: Consoles and Devices
-Basic Console Functions
-=======================
+40.1 Basic Console Functions
+============================
- - Function: console-list
+ -- Function: console-list
This function returns a list of all existing consoles.
- - Function: console-device-list &optional console
+ -- Function: console-device-list &optional console
This function returns a list of all devices on CONSOLE. If
CONSOLE is `nil', the selected console will be used.
\1f
File: lispref.info, Node: Basic Device Functions, Next: Console Types and Device Classes, Prev: Basic Console Functions, Up: Consoles and Devices
-Basic Device Functions
-======================
+40.2 Basic Device Functions
+===========================
- - Function: device-list
+ -- Function: device-list
This function returns a list of all existing devices.
- - Function: device-or-frame-p object
+ -- Function: device-or-frame-p object
This function returns non-`nil' if OBJECT is a device or frame.
This function is useful because devices and frames are similar in
many respects and many functions can operate on either one.
- - Function: device-frame-list &optional device
+ -- Function: device-frame-list &optional device
This function returns a list of all frames on DEVICE. DEVICE
defaults to the currently selected device.
- - Function: frame-device &optional frame
+ -- Function: frame-device &optional frame
This function returns the device that FRAME is on. FRAME defaults
to the currently selected frame.
\1f
File: lispref.info, Node: Console Types and Device Classes, Next: Connecting to a Console or Device, Prev: Basic Device Functions, Up: Consoles and Devices
-Console Types and Device Classes
-================================
+40.3 Console Types and Device Classes
+=====================================
Every device is of a particular "type", which describes how the
connection to that device is made and how the device operates, and a
`mono'
A device that can only display two colors (e.g. black and white).
- - Function: device-type &optional device
+ -- Function: device-type &optional device
This function returns the type of DEVICE. This is a symbol whose
name is one of the device types mentioned above. DEVICE defaults
to the selected device.
- - Function: device-or-frame-type device-or-frame
+ -- Function: device-or-frame-type device-or-frame
This function returns the type of DEVICE-OR-FRAME.
- - Function: device-class &optional device
+ -- Function: device-class &optional device
This function returns the class (color behavior) of DEVICE. This
is a symbol whose name is one of the device classes mentioned
above.
- - Function: valid-device-type-p device-type
+ -- Function: valid-device-type-p device-type
This function returns whether DEVICE-TYPE (which should be a
symbol) specifies a valid device type.
- - Function: valid-device-class-p device-class
+ -- Function: valid-device-class-p device-class
This function returns whether DEVICE-CLASS (which should be a
symbol) specifies a valid device class.
- - Variable: terminal-device
+ -- Variable: terminal-device
This variable holds the initial terminal device object, which
represents XEmacs's stdout.
\1f
File: lispref.info, Node: Connecting to a Console or Device, Next: The Selected Console and Device, Prev: Console Types and Device Classes, Up: Consoles and Devices
-Connecting to a Console or Device
-=================================
+40.4 Connecting to a Console or Device
+======================================
- - Function: make-device type connection &optional props
+ -- Function: make-device type connection &optional props
This function creates a new device.
The following two functions create devices of specific types and are
written in terms of `make-device'.
- - Function: make-tty-device &optional tty terminal-type
+ -- Function: make-tty-device &optional tty terminal-type
This function creates a new tty device on TTY. This also creates
the tty's first frame. TTY should be a string giving the name of
a tty device file (e.g. `/dev/ttyp3' under SunOS et al.), as
If it is `nil', the terminal type will be inferred from the
`TERM' environment variable.
- - Function: make-x-device &optional display argv-list
+ -- Function: make-x-device &optional display argv-list
This function creates a new device connected to DISPLAY. Optional
argument ARGV-LIST is a list of strings describing command line
options.
- - Function: delete-device device &optional force
+ -- Function: delete-device device &optional force
This function deletes DEVICE, permanently eliminating it from use.
This disconnects XEmacs's connection to the device.
- - Variable: create-device-hook
+ -- Variable: create-device-hook
This variable, if non-`nil', should contain a list of functions,
which are called when a device is created.
- - Variable: delete-device-hook
+ -- Variable: delete-device-hook
This variable, if non-`nil', should contain a list of functions,
which are called when a device is deleted.
- - Function: console-live-p object
+ -- Function: console-live-p object
This function returns non-`nil' if OBJECT is a console that has
not been deleted.
- - Function: device-live-p object
+ -- Function: device-live-p object
This function returns non-`nil' if OBJECT is a device that has not
been deleted.
- - Function: device-x-display device
+ -- Function: device-x-display device
This function returns the X display which DEVICE is connected to,
if DEVICE is an X device.
\1f
File: lispref.info, Node: The Selected Console and Device, Next: Console and Device I/O, Prev: Connecting to a Console or Device, Up: Consoles and Devices
-The Selected Console and Device
-===============================
+40.5 The Selected Console and Device
+====================================
- - Function: select-console console
+ -- Function: select-console console
This function selects the console CONSOLE. Subsequent editing
commands apply to its selected device, selected frame, and selected
window. The selection of CONSOLE lasts until the next time the
user does something to select a different console, or until the
next time this function is called.
- - Function: selected-console
+ -- Function: selected-console
This function returns the console which is currently active.
- - Function: select-device device
+ -- Function: select-device device
This function selects the device DEVICE.
- - Function: selected-device &optional console
+ -- Function: selected-device &optional console
This function returns the device which is currently active. If
optional CONSOLE is non-`nil', this function returns the device
that would be currently active if CONSOLE were the selected
\1f
File: lispref.info, Node: Console and Device I/O, Prev: The Selected Console and Device, Up: Consoles and Devices
-Console and Device I/O
-======================
+40.6 Console and Device I/O
+===========================
- - Function: console-disable-input console
+ -- Function: console-disable-input console
This function disables input on console CONSOLE.
- - Function: console-enable-input console
+ -- Function: console-enable-input console
This function enables input on console CONSOLE.
Each device has a "baud rate" value associated with it. On most
systems, changing this value will affect the amount of padding and
other strategic decisions made during redisplay.
- - Function: device-baud-rate &optional device
+ -- Function: device-baud-rate &optional device
This function returns the output baud rate of DEVICE.
- - Function: set-device-baud-rate device rate
+ -- Function: set-device-baud-rate device rate
This function sets the output baud rate of DEVICE to RATE.
\1f
File: lispref.info, Node: Positions, Next: Markers, Prev: Consoles and Devices, Up: Top
-Positions
-*********
+41 Positions
+************
A "position" is the index of a character in the text of a buffer. More
precisely, a position identifies the place between two characters (or
\1f
File: lispref.info, Node: Point, Next: Motion, Up: Positions
-Point
-=====
+41.1 Point
+==========
"Point" is a special buffer position used by many editing commands,
including the self-inserting typed characters and text insertion
so the distinction is rarely important. *Note Window Point::, for more
details.
- - Function: point &optional buffer
+ -- Function: point &optional buffer
This function returns the value of point in BUFFER, as an integer.
BUFFER defaults to the current buffer if omitted.
(point)
=> 175
- - Function: point-min &optional buffer
+ -- Function: point-min &optional buffer
This function returns the minimum accessible value of point in
BUFFER. This is normally 1, but if narrowing is in effect, it is
the position of the start of the region that you narrowed to.
(*Note Narrowing::.) BUFFER defaults to the current buffer if
omitted.
- - Function: point-max &optional buffer
+ -- Function: point-max &optional buffer
This function returns the maximum accessible value of point in
BUFFER. This is `(1+ (buffer-size buffer))', unless narrowing is
in effect, in which case it is the position of the end of the
region that you narrowed to. (*note Narrowing::). BUFFER defaults
to the current buffer if omitted.
- - Function: buffer-end flag &optional buffer
+ -- Function: buffer-end flag &optional buffer
This function returns `(point-min buffer)' if FLAG is less than 1,
`(point-max buffer)' otherwise. The argument FLAG must be a
number. BUFFER defaults to the current buffer if omitted.
- - Function: buffer-size &optional buffer
+ -- Function: buffer-size &optional buffer
This function returns the total number of characters in BUFFER.
In the absence of any narrowing (*note Narrowing::), `point-max'
returns a value one larger than this. BUFFER defaults to the
(point-max)
=> 36
- - Variable: buffer-saved-size
+ -- Variable: buffer-saved-size
The value of this buffer-local variable is the former length of the
current buffer, as of the last time it was read in, saved or
auto-saved.
\1f
File: lispref.info, Node: Motion, Next: Excursions, Prev: Point, Up: Positions
-Motion
-======
+41.2 Motion
+===========
Motion functions change the value of point, either relative to the
current value of point, relative to the beginning or end of the buffer,
\1f
File: lispref.info, Node: Character Motion, Next: Word Motion, Up: Motion
-Motion by Characters
---------------------
+41.2.1 Motion by Characters
+---------------------------
These functions move point based on a count of characters. `goto-char'
is the fundamental primitive; the other functions use that.
- - Command: goto-char position &optional buffer
+ -- Command: goto-char position &optional buffer
This function sets point in `buffer' to the value POSITION. If
POSITION is less than 1, it moves point to the beginning of the
buffer. If POSITION is greater than the length of the buffer, it
`goto-char' returns POSITION.
- - Command: forward-char &optional count buffer
+ -- Command: forward-char &optional count buffer
This function moves point COUNT characters forward, towards the
end of the buffer (or backward, towards the beginning of the
buffer, if COUNT is negative). If the function attempts to move
In an interactive call, COUNT is the numeric prefix argument.
- - Command: backward-char &optional count buffer
+ -- Command: backward-char &optional count buffer
This function moves point COUNT characters backward, towards the
beginning of the buffer (or forward, towards the end of the
buffer, if COUNT is negative). If the function attempts to move
\1f
File: lispref.info, Node: Word Motion, Next: Buffer End Motion, Prev: Character Motion, Up: Motion
-Motion by Words
----------------
+41.2.2 Motion by Words
+----------------------
These functions for parsing words use the syntax table to decide
whether a given character is part of a word. *Note Syntax Tables::.
- - Command: forward-word &optional count buffer
+ -- Command: forward-word &optional count buffer
This function moves point forward COUNT words (or backward if
COUNT is negative). Normally it returns `t'. If this motion
encounters the beginning or end of the buffer, or the limits of the
In an interactive call, COUNT is set to the numeric prefix
argument.
- - Command: backward-word &optional count buffer
+ -- Command: backward-word &optional count buffer
This function is just like `forward-word', except that it moves
backward until encountering the front of a word, rather than
forward. BUFFER defaults to the current buffer if omitted.
In an interactive call, COUNT is set to the numeric prefix
argument.
- - Variable: words-include-escapes
+ -- Variable: words-include-escapes
This variable affects the behavior of `forward-word' and everything
that uses it. If it is non-`nil', then characters in the "escape"
and "character quote" syntax classes count as part of words.
\1f
File: lispref.info, Node: Buffer End Motion, Next: Text Lines, Prev: Word Motion, Up: Motion
-Motion to an End of the Buffer
-------------------------------
+41.2.3 Motion to an End of the Buffer
+-------------------------------------
To move point to the beginning of the buffer, write:
documented here to warn you not to use them in Lisp programs, because
they set the mark and display messages in the echo area.
- - Command: beginning-of-buffer &optional count
+ -- Command: beginning-of-buffer &optional count
This function moves point to the beginning of the buffer (or the
limits of the accessible portion, when narrowing is in effect),
setting the mark at the previous position. If COUNT is non-`nil',
Don't use this function in Lisp programs!
- - Command: end-of-buffer &optional count
+ -- Command: end-of-buffer &optional count
This function moves point to the end of the buffer (or the limits
of the accessible portion, when narrowing is in effect), setting
the mark at the previous position. If COUNT is non-`nil', then it
\1f
File: lispref.info, Node: Text Lines, Next: Screen Lines, Prev: Buffer End Motion, Up: Motion
-Motion by Text Lines
---------------------
+41.2.4 Motion by Text Lines
+---------------------------
Text lines are portions of the buffer delimited by newline characters,
which are regarded as part of the previous line. The first text line
of the window, by line continuation in display, or by how tabs and
control characters are displayed.
- - Command: goto-line line
+ -- Command: goto-line line
This function moves point to the front of the LINEth line,
counting from line 1 at beginning of the buffer. If LINE is less
than 1, it moves point to the beginning of the buffer. If LINE is
In an interactive call, LINE is the numeric prefix argument if one
has been provided. Otherwise LINE is read in the minibuffer.
- - Command: beginning-of-line &optional count buffer
+ -- Command: beginning-of-line &optional count buffer
This function moves point to the beginning of the current line.
With an argument COUNT not `nil' or 1, it moves forward COUNT-1
lines and then to the beginning of the line. BUFFER defaults to
accessible portion, if narrowing is in effect), it positions point
there. No error is signaled.
- - Command: end-of-line &optional count buffer
+ -- Command: end-of-line &optional count buffer
This function moves point to the end of the current line. With an
argument COUNT not `nil' or 1, it moves forward COUNT-1 lines and
then to the end of the line. BUFFER defaults to the current
accessible portion, if narrowing is in effect), it positions point
there. No error is signaled.
- - Command: forward-line &optional count buffer
+ -- Command: forward-line &optional count buffer
This function moves point forward COUNT lines, to the beginning of
the line. If COUNT is negative, it moves point -COUNT lines
backward, to the beginning of a line. If COUNT is zero, it moves
In an interactive call, COUNT is the numeric prefix argument.
- - Function: count-lines start end &optional ignore-invisible-lines-flag
+ -- Function: count-lines start end &optional
+ ignore-invisible-lines-flag
This function returns the number of lines between the positions
START and END in the current buffer. If START and END are equal,
then it returns 0. Otherwise it returns at least 1, even if START
With optional IGNORE-INVISIBLE-LINES-FLAG non-`nil', lines
collapsed with selective-display are excluded from the line count.
- *Note:* The expression to return the current line number is not
+ *N.B.* The expression to return the current line number is not
obvious:
(1+ (count-lines 1 (point-at-bol)))
\1f
File: lispref.info, Node: Screen Lines, Next: List Motion, Prev: Text Lines, Up: Motion
-Motion by Screen Lines
-----------------------
+41.2.5 Motion by Screen Lines
+-----------------------------
The line functions in the previous section count text lines, delimited
only by newline characters. By contrast, these functions count screen
use them heavily, Emacs provides caches which may improve the
performance of your code. *Note cache-long-line-scans: Text Lines.
- - Function: vertical-motion count &optional window pixels
+ -- Function: vertical-motion count &optional window pixels
This function moves point to the start of the frame line COUNT
frame lines down from the frame line containing point. If COUNT
is negative, it moves up instead. The optional second argument
WINDOW's point. (This differs from FSF Emacs, which buggily always
sets current buffer's point, regardless of WINDOW.)
- - Function: vertical-motion-pixels count &optional window how
+ -- Function: vertical-motion-pixels count &optional window how
This function moves point to the start of the frame line PIXELS
vertical pixels down from the frame line containing point, or up if
PIXELS is negative. The optional second argument WINDOW is the
least PIXELS. Any other value indicates that the motion should be
as close as possible to PIXELS.
- - Command: move-to-window-line count &optional window
+ -- Command: move-to-window-line count &optional window
This function moves point with respect to the text currently
displayed in WINDOW, which defaults to the selected window. It
moves point to the beginning of the screen line COUNT screen lines
\1f
File: lispref.info, Node: List Motion, Next: Skipping Characters, Prev: Screen Lines, Up: Motion
-Moving over Balanced Expressions
---------------------------------
+41.2.6 Moving over Balanced Expressions
+---------------------------------------
Here are several functions concerned with balanced-parenthesis
expressions (also called "sexps" in connection with moving across them
sexps. For user-level commands, see *Note Lists and Sexps:
(xemacs)Lists and Sexps.
- - Command: forward-list &optional arg
+ -- Command: forward-list &optional arg
This function moves forward across ARG balanced groups of
parentheses. (Other syntactic entities such as words or paired
string quotes are ignored.) ARG defaults to 1 if omitted. If ARG
is negative, move backward across that many groups of parentheses.
- - Command: backward-list &optional count
+ -- Command: backward-list &optional count
This function moves backward across COUNT balanced groups of
parentheses. (Other syntactic entities such as words or paired
string quotes are ignored.) COUNT defaults to 1 if omitted. If
COUNT is negative, move forward across that many groups of
parentheses.
- - Command: up-list &optional count
+ -- Command: up-list &optional count
This function moves forward out of COUNT levels of parentheses. A
negative argument means move backward but still to a less deep
spot.
- - Command: down-list &optional count
+ -- Command: down-list &optional count
This function moves forward into COUNT levels of parentheses. A
negative argument means move backward but still go deeper in
parentheses (-COUNT levels).
- - Command: forward-sexp &optional count
+ -- Command: forward-sexp &optional count
This function moves forward across COUNT balanced expressions.
Balanced expressions include both those delimited by parentheses
and other kinds, such as words and string constants. COUNT
---------- Buffer: foo ----------
(concat-!- "foo " (car x) y z)
---------- Buffer: foo ----------
-
+
(forward-sexp 3)
=> nil
-
+
---------- Buffer: foo ----------
(concat "foo " (car x) y-!- z)
---------- Buffer: foo ----------
- - Command: backward-sexp &optional count
+ -- Command: backward-sexp &optional count
This function moves backward across COUNT balanced expressions.
COUNT defaults to 1 if omitted. If COUNT is negative, move
forward across that many balanced expressions.
- - Command: beginning-of-defun &optional count
+ -- Command: beginning-of-defun &optional count
This function moves back to the COUNTth beginning of a defun. If
COUNT is negative, this actually moves forward, but it still moves
to the beginning of a defun, not to the end of one. COUNT
defaults to 1 if omitted.
- - Command: end-of-defun &optional count
+ -- Command: end-of-defun &optional count
This function moves forward to the COUNTth end of a defun. If
COUNT is negative, this actually moves backward, but it still
moves to the end of a defun, not to the beginning of one. COUNT
defaults to 1 if omitted.
- - User Option: defun-prompt-regexp
+ -- User Option: defun-prompt-regexp
If non-`nil', this variable holds a regular expression that
specifies what text can appear before the open-parenthesis that
starts a defun. That is to say, a defun begins on a line that
\1f
File: lispref.info, Node: Skipping Characters, Prev: List Motion, Up: Motion
-Skipping Characters
--------------------
+41.2.7 Skipping Characters
+--------------------------
The following two functions move point over a specified set of
characters. For example, they are often used to skip whitespace. For
related functions, see *Note Motion and Syntax::.
- - Function: skip-chars-forward character-set &optional limit buffer
+ -- Function: skip-chars-forward character-set &optional limit buffer
This function moves point in BUFFER forward, skipping over a given
set of characters. It examines the character following point,
then advances point if the character matches CHARACTER-SET. This
I read "-!-The cat in the hat
comes back" twice.
---------- Buffer: foo ----------
-
+
(skip-chars-forward "a-zA-Z ")
=> nil
-
+
---------- Buffer: foo ----------
I read "The cat in the hat-!-
comes back" twice.
---------- Buffer: foo ----------
- - Function: skip-chars-backward character-set &optional limit buffer
+ -- Function: skip-chars-backward character-set &optional limit buffer
This function moves point backward, skipping characters that match
CHARACTER-SET, until LIMIT. It just like `skip-chars-forward'
except for the direction of motion.
\1f
File: lispref.info, Node: Excursions, Next: Narrowing, Prev: Motion, Up: Positions
-Excursions
-==========
+41.3 Excursions
+===============
It is often useful to move point "temporarily" within a localized
portion of the program, or to switch buffers temporarily. This is
described elsewhere (see *Note Window Configurations:: and *note Frame
Configurations::).
- - Special Form: save-excursion forms...
+ -- Special Form: save-excursion forms...
The `save-excursion' special form saves the identity of the current
buffer and the values of point and the mark in it, evaluates
FORMS, and finally restores the buffer and its saved values of
(goto-char old-pnt)
(set-marker (mark-marker) old-mark)))
- - Special Form: save-current-buffer forms...
+ -- Special Form: save-current-buffer forms...
This special form is similar to `save-excursion' but it only saves
and restores the current buffer. Beginning with XEmacs 20.3,
`save-current-buffer' is a primitive.
- - Special Form: with-current-buffer buffer forms...
+ -- Special Form: with-current-buffer buffer forms...
This special form evaluates FORMS with BUFFER as the current
buffer. It returns the value of the last form.
- - Special Form: with-temp-file filename forms...
+ -- Special Form: with-temp-file filename forms...
This special form creates a new buffer, evaluates FORMS there, and
writes the buffer to FILENAME. It returns the value of the last
form evaluated.
- - Special Form: save-selected-window forms...
+ -- Special Form: save-selected-window forms...
This special form is similar to `save-excursion' but it saves and
restores the selected window and nothing else.
\1f
File: lispref.info, Node: Narrowing, Prev: Excursions, Up: Positions
-Narrowing
-=========
+41.4 Narrowing
+==============
"Narrowing" means limiting the text addressable by XEmacs editing
commands to a limited range of characters in a buffer. The text that
The commands for saving buffers are unaffected by narrowing; they
save the entire buffer regardless of any narrowing.
- - Command: narrow-to-region start end &optional buffer
+ -- Command: narrow-to-region start end &optional buffer
This function sets the accessible portion of BUFFER to start at
START and end at END. Both arguments should be character
positions. BUFFER defaults to the current buffer if omitted.
In an interactive call, START and END are set to the bounds of the
current region (point and the mark, with the smallest first).
- - Command: narrow-to-page &optional move-count
+ -- Command: narrow-to-page &optional move-count
This function sets the accessible portion of the current buffer to
include just the current page. An optional first argument
MOVE-COUNT non-`nil' means to move forward or backward by
In an interactive call, MOVE-COUNT is set to the numeric prefix
argument.
- - Command: widen &optional buffer
+ -- Command: widen &optional buffer
This function cancels any narrowing in BUFFER, so that the entire
contents are accessible. This is called "widening". It is
equivalent to the following expression:
BUFFER defaults to the current buffer if omitted.
- - Special Form: save-restriction body...
+ -- Special Form: save-restriction body...
This special form saves the current bounds of the accessible
portion, evaluates the BODY forms, and finally restores the saved
bounds, thus restoring the same state of narrowing (or absence
This is the contents of foo
This is the contents of foo-!-
---------- Buffer: foo ----------
-
+
(save-excursion
(save-restriction
(goto-char 1)
(narrow-to-region 1 (point))
(goto-char (point-min))
(replace-string "foo" "bar")))
-
+
---------- Buffer: foo ----------
This is the contents of bar
This is the contents of bar
\1f
File: lispref.info, Node: Markers, Next: Text, Prev: Positions, Up: Top
-Markers
-*******
+42 Markers
+**********
A "marker" is a Lisp object used to specify a position in a buffer
relative to the surrounding text. A marker changes its offset from the
\1f
File: lispref.info, Node: Overview of Markers, Next: Predicates on Markers, Up: Markers
-Overview of Markers
-===================
+42.1 Overview of Markers
+========================
A marker specifies a buffer and a position in that buffer. The marker
can be used to represent a position in the functions that require one,
;; Make a new marker that initially does not point anywhere:
(setq m1 (make-marker))
=> #<marker in no buffer>
-
+
;; Set `m1' to point between the 99th and 100th characters
;; in the current buffer:
(set-marker m1 100)
=> #<marker at 100 in markers.texi>
-
+
;; Now insert one character at the beginning of the buffer:
(goto-char (point-min))
=> 1
(insert "Q")
=> nil
-
+
;; `m1' is updated appropriately.
m1
=> #<marker at 101 in markers.texi>
-
+
;; Two markers that point to the same position
;; are not `eq', but they are `equal'.
(setq m2 (copy-marker m1))
=> nil
(equal m1 m2)
=> t
-
+
;; When you are finished using a marker, make it point nowhere.
(set-marker m1 nil)
=> #<marker in no buffer>
\1f
File: lispref.info, Node: Predicates on Markers, Next: Creating Markers, Prev: Overview of Markers, Up: Markers
-Predicates on Markers
-=====================
+42.2 Predicates on Markers
+==========================
You can test an object to see whether it is a marker, or whether it is
either an integer or a marker or either an integer, a character, or a
marker. The latter tests are useful in connection with the arithmetic
functions that work with any of markers, integers, or characters.
- - Function: markerp object
+ -- Function: markerp object
This function returns `t' if OBJECT is a marker, `nil' otherwise.
Note that integers are not markers, even though many functions
will accept either a marker or an integer.
- - Function: integer-or-marker-p object
+ -- Function: integer-or-marker-p object
This function returns `t' if OBJECT is an integer or a marker,
`nil' otherwise.
- - Function: integer-char-or-marker-p object
+ -- Function: integer-char-or-marker-p object
This function returns `t' if OBJECT is an integer, a character, or
a marker, `nil' otherwise.
- - Function: number-or-marker-p object
+ -- Function: number-or-marker-p object
This function returns `t' if OBJECT is a number (either kind) or a
marker, `nil' otherwise.
- - Function: number-char-or-marker-p object
+ -- Function: number-char-or-marker-p object
This function returns `t' if OBJECT is a number (either kind), a
character, or a marker, `nil' otherwise.
\1f
File: lispref.info, Node: Creating Markers, Next: Information from Markers, Prev: Predicates on Markers, Up: Markers
-Functions That Create Markers
-=============================
+42.3 Functions That Create Markers
+==================================
When you create a new marker, you can make it point nowhere, or point
to the present position of point, or to the beginning or end of the
accessible portion of the buffer, or to the same place as another given
marker.
- - Function: make-marker
+ -- Function: make-marker
This functions returns a newly created marker that does not point
anywhere.
(make-marker)
=> #<marker in no buffer>
- - Function: point-marker &optional dont-copy-p buffer
+ -- Function: point-marker &optional dont-copy-p buffer
This function returns a marker that points to the present position
of point in BUFFER, which defaults to the current buffer. *Note
Point::. For an example, see `copy-marker', below.
modifying the position of this marker will move point. It is
illegal to change the buffer of it, or make it point nowhere.
- - Function: point-min-marker &optional buffer
+ -- Function: point-min-marker &optional buffer
This function returns a new marker that points to the beginning of
the accessible portion of BUFFER, which defaults to the current
buffer. This will be the beginning of the buffer unless narrowing
is in effect. *Note Narrowing::.
- - Function: point-max-marker &optional buffer
+ -- Function: point-max-marker &optional buffer
This function returns a new marker that points to the end of the
accessible portion of BUFFER, which defaults to the current
buffer. This will be the end of the buffer unless narrowing is in
=> #<marker at 1 in markers.texi>
(point-max-marker)
=> #<marker at 15573 in markers.texi>
-
+
(narrow-to-region 100 200)
=> nil
(point-min-marker)
(point-max-marker)
=> #<marker at 200 in markers.texi>
- - Function: copy-marker marker-or-integer &optional marker-type
+ -- Function: copy-marker marker-or-integer &optional marker-type
If passed a marker as its argument, `copy-marker' returns a new
marker that points to the same place and the same buffer as does
MARKER-OR-INTEGER. If passed an integer as its argument,
(setq p (point-marker))
=> #<marker at 2139 in markers.texi>
-
+
(setq q (copy-marker p))
=> #<marker at 2139 in markers.texi>
-
+
(eq p q)
=> nil
-
+
(equal p q)
=> t
-
+
(point)
=> 2139
-
+
(set-marker p 3000)
=> #<marker at 3000 in markers.texi>
-
+
(point)
=> 2139
-
+
(setq p (point-marker t))
=> #<marker at 2139 in markers.texi>
-
+
(set-marker p 3000)
=> #<marker at 3000 in markers.texi>
-
+
(point)
=> 3000
-
+
(copy-marker 0)
=> #<marker at 1 in markers.texi>
-
+
(copy-marker 20000)
=> #<marker at 7572 in markers.texi>
\1f
File: lispref.info, Node: Information from Markers, Next: Changing Markers, Prev: Creating Markers, Up: Markers
-Information from Markers
-========================
+42.4 Information from Markers
+=============================
This section describes the functions for accessing the components of a
marker object.
- - Function: marker-position marker
+ -- Function: marker-position marker
This function returns the position that MARKER points to, or `nil'
if it points nowhere.
- - Function: marker-buffer marker
+ -- Function: marker-buffer marker
This function returns the buffer that MARKER points into, or `nil'
if it points nowhere.
=> nil
(marker-buffer m)
=> nil
-
+
(set-marker m 3770 (current-buffer))
=> #<marker at 3770 in markers.texi>
(marker-buffer m)
\1f
File: lispref.info, Node: Changing Markers, Next: The Mark, Prev: Information from Markers, Up: Markers
-Changing Marker Positions
-=========================
+42.5 Changing Marker Positions
+==============================
This section describes how to change the position of an existing
marker. When you do this, be sure you know whether the marker is used
moving it--otherwise, confusing things may happen in other parts of
Emacs.
- - Function: set-marker marker position &optional buffer
+ -- Function: set-marker marker position &optional buffer
This function moves MARKER to POSITION in BUFFER. If BUFFER is
not provided, it defaults to the current buffer.
(set-marker m 0 b)
=> #<marker at 1 in foo>
- - Function: move-marker marker position &optional buffer
+ -- Function: move-marker marker position &optional buffer
This is another name for `set-marker'.
\1f
File: lispref.info, Node: The Mark, Next: The Region, Prev: Changing Markers, Up: Markers
-The Mark
-========
+42.6 The Mark
+=============
One special marker in each buffer is designated "the mark". It records
a position for the user for the sake of commands such as `C-w' and `C-x
maximum number of entries in the mark ring; once the list becomes this
long, adding a new element deletes the last element.
- - Function: mark &optional force buffer
+ -- Function: mark &optional force buffer
This function returns BUFFER's mark position as an integer.
BUFFER defaults to the current buffer if omitted.
If you are using this in an editing command, you are most likely
making a mistake; see the documentation of `set-mark' below.
- - Function: mark-marker &optional force buffer
+ -- Function: mark-marker &optional force buffer
This function returns BUFFER's mark. BUFFER defaults to the
current buffer if omitted. This is the very marker that records
the mark location inside XEmacs, not a copy. Therefore, changing
other than the one of which it is the mark. If you do, it will
yield perfectly consistent, but rather odd, results.
- - Function: set-mark position &optional buffer
+ -- Function: set-mark position &optional buffer
This function sets `buffer''s mark to POSITION, and activates the
mark. BUFFER defaults to the current buffer if omitted. The old
value of the mark is _not_ pushed onto the mark ring.
(forward-line 1)
(delete-region start (point))).
- - Command: exchange-point-and-mark &optional dont-activate-region
+ -- Command: exchange-point-and-mark &optional dont-activate-region
This function exchanges the positions of point and the mark. It
is intended for interactive use. The mark is also activated
unless DONT-ACTIVATE-REGION is non-`nil'.
- - Function: push-mark &optional position nomsg activate buffer
+ -- Function: push-mark &optional position nomsg activate buffer
This function sets BUFFER's mark to POSITION, and pushes a copy of
the previous mark onto `mark-ring'. BUFFER defaults to the
current buffer if omitted. If POSITION is `nil', then the value
A `Mark set' message is displayed unless NOMSG is non-`nil'.
- - Function: pop-mark
+ -- Function: pop-mark
This function pops off the top element of `mark-ring' and makes
that mark become the buffer's actual mark. This does not move
point in the buffer, and it does nothing if `mark-ring' is empty.
The return value is not meaningful.
- - Variable: mark-ring
+ -- Variable: mark-ring
The value of this buffer-local variable is the list of saved former
marks of the current buffer, most recent first.
#<marker at 10832 in markers.texi>
...)
- - User Option: mark-ring-max
+ -- User Option: mark-ring-max
The value of this variable is the maximum size of `mark-ring'. If
more marks than this are pushed onto the `mark-ring', `push-mark'
discards an old mark when it adds a new one.
ring". Marks are pushed onto the global mark ring the first time you
set a mark after switching buffers.
- - Variable: global-mark-ring
+ -- Variable: global-mark-ring
The value of this variable is the list of saved former global
marks, most recent first.
- - User Option: mark-ring-max
+ -- User Option: mark-ring-max
The value of this variable is the maximum size of
`global-mark-ring'. If more marks than this are pushed onto the
`global-mark-ring', `push-mark' discards an old mark when it adds
a new one.
- - Command: pop-global-mark
+ -- Command: pop-global-mark
This function pops a mark off the global mark ring and jumps to
that location.
\1f
File: lispref.info, Node: The Region, Prev: The Mark, Up: Markers
-The Region
-==========
+42.7 The Region
+===============
The text between point and the mark is known as "the region". Various
functions operate on text delimited by point and the mark, but only
time can exist--i.e. only one buffer's region is active at a time.
*Note The Mark::, for more information about active regions.
- - User Option: zmacs-regions
+ -- User Option: zmacs-regions
If non-`nil' (the default), active regions are used. *Note The
Mark::, for a detailed explanation of what this means.
specify the bounds explicitly as arguments and automatically respects
the user's setting for `zmacs-regions'. (*Note Interactive Codes::.)
- - Function: region-beginning &optional buffer
+ -- Function: region-beginning &optional buffer
This function returns the position of the beginning of BUFFER's
region (as an integer). This is the position of either point or
the mark, whichever is smaller. BUFFER defaults to the current
If the mark does not point anywhere, an error is signaled. Note
that this function ignores whether the region is active.
- - Function: region-end &optional buffer
+ -- Function: region-end &optional buffer
This function returns the position of the end of BUFFER's region
(as an integer). This is the position of either point or the mark,
whichever is larger. BUFFER defaults to the current buffer if
If the mark does not point anywhere, an error is signaled. Note
that this function ignores whether the region is active.
- - Function: region-exists-p
+ -- Function: region-exists-p
This function is non-`nil' if the region exists. If active regions
are in use (i.e. `zmacs-regions' is true), this means that the
region is active. Otherwise, this means that the user has pushed
returns `nil', a function that uses the `r' interactive
specification will cause an error when called interactively.
- - Function: region-active-p
+ -- Function: region-active-p
If `zmacs-regions' is true, this is equivalent to
`region-exists-p'. Otherwise, this function always returns false.
This function is used by commands such as
operate either on the active region or on something else (e.g. the
word or paragraph at point).
- - Variable: zmacs-region-stays
+ -- Variable: zmacs-region-stays
If a command sets this variable to true, the currently active
region will remain activated when the command finishes. (Normally
the region is deactivated when each command terminates.) If
interactive specification `_' instead, if you want the region to
remain active.
- - Function: zmacs-activate-region
+ -- Function: zmacs-activate-region
This function activates the region in the current buffer (this is
equivalent to activating the current buffer's mark). This will
normally also highlight the text in the active region and set
`zmacs-region-stays' to `t'. (If `zmacs-regions' is false,
however, this function has no effect.)
- - Function: zmacs-deactivate-region
+ -- Function: zmacs-deactivate-region
This function deactivates the region in the current buffer (this is
equivalent to deactivating the current buffer's mark). This will
normally also unhighlight the text in the active region and set
`zmacs-region-stays' to `nil'. (If `zmacs-regions' is false,
however, this function has no effect.)
- - Function: zmacs-update-region
+ -- Function: zmacs-update-region
This function updates the active region, if it's currently active.
(If there is no active region, this function does nothing.) This
has the effect of updating the highlighting on the text in the
when appropriate. Calling this function will call the hook
`zmacs-update-region-hook', if the region is active.
- - Variable: zmacs-activate-region-hook
+ -- Variable: zmacs-activate-region-hook
This normal hook is called when a region becomes active. (Usually
this happens as a result of a command that activates the region,
such as `set-mark-command', `activate-region', or
already active. If `zmacs-regions' is false, however, this hook
will never get called under any circumstances.
- - Variable: zmacs-deactivate-region-hook
+ -- Variable: zmacs-deactivate-region-hook
This normal hook is called when an active region becomes inactive.
(Calling `zmacs-deactivate-region' when the region is inactive will
_not_ cause this hook to be called.) If `zmacs-regions' is false,
this hook will never get called.
- - Variable: zmacs-update-region-hook
+ -- Variable: zmacs-update-region-hook
This normal hook is called when an active region is "updated" by
`zmacs-update-region'. This normally gets called at the end of
each command that sets `zmacs-region-stays' to `t', indicating
\1f
File: lispref.info, Node: Text, Next: Searching and Matching, Prev: Markers, Up: Top
-Text
-****
+43 Text
+*******
This chapter describes the functions that deal with the text in a
buffer. Most examine, insert, or delete text in the current buffer,
\1f
File: lispref.info, Node: Near Point, Next: Buffer Contents, Up: Text
-Examining Text Near Point
-=========================
+43.1 Examining Text Near Point
+==============================
Many functions are provided to look at the characters around point.
Several simple functions are described here. See also `looking-at' in
usually did not have these optional BUFFER arguments and always
operated on the current buffer.)
- - Function: char-after &optional position buffer
+ -- Function: char-after &optional position buffer
This function returns the character in the buffer at (i.e.,
immediately after) position POSITION. If POSITION is out of range
for this purpose, either before the beginning of the buffer, or at
(char-to-string (char-after 1))
=> "@"
- - Function: char-before &optional position buffer
+ -- Function: char-before &optional position buffer
This function returns the character in the current buffer
immediately before position POSITION. If POSITION is out of range
for this purpose, either at or before the beginning of the buffer,
POSITION is point. If optional argument BUFFER is `nil', the
current buffer is assumed.
- - Function: following-char &optional buffer
+ -- Function: following-char &optional buffer
This function returns the character following point in the buffer.
This is similar to `(char-after (point))'. However, if point is at
the end of the buffer, then the result of `following-char' is 0.
Gentlemen may cry ``Pea-!-ce! Peace!,''
but there is no peace.
---------- Buffer: foo ----------
-
+
(char-to-string (preceding-char))
=> "a"
(char-to-string (following-char))
=> "c"
- - Function: preceding-char &optional buffer
+ -- Function: preceding-char &optional buffer
This function returns the character preceding point in the buffer.
See above, under `following-char', for an example. If point is at
the beginning of the buffer, `preceding-char' returns 0. If
optional argument BUFFER is `nil', the current buffer is assumed.
- - Function: bobp &optional buffer
+ -- Function: bobp &optional buffer
This function returns `t' if point is at the beginning of the
buffer. If narrowing is in effect, this means the beginning of the
accessible portion of the text. If optional argument BUFFER is
`nil', the current buffer is assumed. See also `point-min' in
*Note Point::.
- - Function: eobp &optional buffer
+ -- Function: eobp &optional buffer
This function returns `t' if point is at the end of the buffer.
If narrowing is in effect, this means the end of accessible
portion of the text. If optional argument BUFFER is `nil', the
current buffer is assumed. See also `point-max' in *Note Point::.
- - Function: bolp &optional buffer
+ -- Function: bolp &optional buffer
This function returns `t' if point is at the beginning of a line.
If optional argument BUFFER is `nil', the current buffer is
assumed. *Note Text Lines::. The beginning of the buffer (or its
accessible portion) always counts as the beginning of a line.
- - Function: eolp &optional buffer
+ -- Function: eolp &optional buffer
This function returns `t' if point is at the end of a line. The
end of the buffer is always considered the end of a line. If
optional argument BUFFER is `nil', the current buffer is assumed.
\1f
File: lispref.info, Node: Buffer Contents, Next: Comparing Text, Prev: Near Point, Up: Text
-Examining Buffer Contents
-=========================
+43.2 Examining Buffer Contents
+==============================
This section describes two functions that allow a Lisp program to
convert any portion of the text in the buffer into a string.
- - Function: buffer-substring start end &optional buffer
- - Function: buffer-string start end &optional buffer
+ -- Function: buffer-substring start end &optional buffer
+ -- Function: buffer-string start end &optional buffer
These functions are equivalent and return a string containing a
copy of the text of the region defined by positions START and END
in the buffer. If the arguments are not positions in the
---------- Buffer: foo ----------
This is the contents of buffer foo
-
+
---------- Buffer: foo ----------
-
+
(buffer-substring 1 10)
=> "This is t"
(buffer-substring (point-max) 10)
\1f
File: lispref.info, Node: Comparing Text, Next: Insertion, Prev: Buffer Contents, Up: Text
-Comparing Text
-==============
+43.3 Comparing Text
+===================
This function lets you compare portions of the text in a buffer, without
copying them into strings first.
- - Function: compare-buffer-substrings buffer1 start1 end1 buffer2
+ -- Function: compare-buffer-substrings buffer1 start1 end1 buffer2
start2 end2
This function lets you compare two substrings of the same buffer
or two different buffers. The first three arguments specify one
\1f
File: lispref.info, Node: Insertion, Next: Commands for Insertion, Prev: Comparing Text, Up: Text
-Inserting Text
-==============
+43.4 Inserting Text
+===================
"Insertion" means adding new text to a buffer. The inserted text goes
at point--between the character before point and the character after
characters specified as separate arguments, not part of a string or
buffer, inherit their text properties from the neighboring text.
- - Function: insert &rest args
+ -- Function: insert &rest args
This function inserts the strings and/or characters ARGS into the
current buffer, at point, moving point forward. In other words, it
inserts the text before point. An error is signaled unless all
ARGS are either strings or characters. The value is `nil'.
- - Function: insert-before-markers &rest args
+ -- Function: insert-before-markers &rest args
This function inserts the strings and/or characters ARGS into the
current buffer, at point, moving point forward. An error is
signaled unless all ARGS are either strings or characters. The
relocates markers initially pointing at the insertion point, to
point after the inserted text.
- - Function: insert-string string &optional buffer
+ -- Function: insert-string string &optional buffer
This function inserts STRING into BUFFER before point. BUFFER
defaults to the current buffer if omitted. This function is
chiefly useful if you want to insert a string in a buffer other
than the current one (otherwise you could just use `insert').
- - Function: insert-char character &optional count ignored buffer
+ -- Function: insert-char character &optional count ignored buffer
This function inserts COUNT instances of CHARACTER into BUFFER
before point. COUNT must be a number, and CHARACTER must be a
character.
This function always returns `nil'.
- - Function: insert-buffer-substring from-buffer-or-name &optional
+ -- Function: insert-buffer-substring from-buffer-or-name &optional
start end
This function inserts a portion of buffer FROM-BUFFER-OR-NAME
(which must already exist) into the current buffer before point.
---------- Buffer: foo ----------
We hold these truths to be self-evident, that all
---------- Buffer: foo ----------
-
+
(insert-buffer-substring "foo" 1 20)
=> nil
-
+
---------- Buffer: bar ----------
We hold these truth-!-
---------- Buffer: bar ----------
\1f
File: lispref.info, Node: Commands for Insertion, Next: Deletion, Prev: Insertion, Up: Text
-User-Level Insertion Commands
-=============================
+43.5 User-Level Insertion Commands
+==================================
This section describes higher-level commands for inserting text,
commands intended primarily for the user but useful also in Lisp
programs.
- - Command: insert-buffer from-buffer-or-name
+ -- Command: insert-buffer from-buffer-or-name
This command inserts the entire contents of FROM-BUFFER-OR-NAME
(which must exist) into the current buffer after point. It leaves
the mark after the inserted text. The value is `nil'.
- - Command: self-insert-command count
+ -- Command: self-insert-command count
This command inserts the last character typed; it does so COUNT
times, before point, and returns `nil'. Most printing characters
are bound to this command. In routine use, `self-insert-command'
the inserted character has close parenthesis syntax (*note
Blinking::).
- - Command: newline &optional count
+ -- Command: newline &optional count
This command inserts newlines into the current buffer before point.
If COUNT is supplied, that many newline characters are inserted.
The value returned is `nil'. In an interactive call, COUNT is the
numeric prefix argument.
- - Command: split-line
+ -- Command: split-line
This command splits the current line, moving the portion of the
line after point down vertically so that it is on the next line
directly below where it was before. Whitespace is inserted as
Programs hardly ever use this function.
- - Variable: overwrite-mode
+ -- Variable: overwrite-mode
This variable controls whether overwrite mode is in effect: a
non-`nil' value enables the mode. It is automatically made
buffer-local when set in any fashion.
\1f
File: lispref.info, Node: Deletion, Next: User-Level Deletion, Prev: Commands for Insertion, Up: Text
-Deleting Text
-=============
+43.6 Deleting Text
+==================
Deletion means removing part of the text in a buffer, without saving it
in the kill ring (*note The Kill Ring::). Deleted text can't be
All of the deletion functions operate on the current buffer, and all
return a value of `nil'.
- - Command: erase-buffer &optional buffer
+ -- Command: erase-buffer &optional buffer
This function deletes the entire text of BUFFER, leaving it empty.
If the buffer is read-only, it signals a `buffer-read-only'
error. Otherwise, it deletes the text without asking for any
future text is not really related to the former text, and its size
should not be compared with that of the former text.
- - Command: delete-region start end &optional buffer
+ -- Command: delete-region start end &optional buffer
This command deletes the text in BUFFER in the region defined by
START and END. The value is `nil'. If optional argument BUFFER
is `nil', the current buffer is assumed.
- - Command: delete-char &optional count killp
+ -- Command: delete-char &optional count killp
This command deletes COUNT characters directly after point, or
before point if COUNT is negative. COUNT defaults to `1'. If
KILLP is non-`nil', then it saves the deleted characters in the
The value returned is always `nil'.
- - Command: delete-backward-char &optional count killp
+ -- Command: delete-backward-char &optional count killp
This command deletes COUNT characters directly before point, or
after point if COUNT is negative. COUNT defaults to 1. If KILLP
is non-`nil', then it saves the deleted characters in the kill
The value returned is always `nil'.
- - Command: backward-delete-char-untabify count &optional killp
+ -- Command: backward-delete-char-untabify count &optional killp
This command deletes COUNT characters backward, changing tabs into
spaces. When the next character to be deleted is a tab, it is
first replaced with the proper number of spaces to preserve
\1f
File: lispref.info, Node: User-Level Deletion, Next: The Kill Ring, Prev: Deletion, Up: Text
-User-Level Deletion Commands
-============================
+43.7 User-Level Deletion Commands
+=================================
This section describes higher-level commands for deleting text,
commands intended primarily for the user but useful also in Lisp
programs.
- - Command: delete-horizontal-space
+ -- Command: delete-horizontal-space
This function deletes all spaces and tabs around point. It returns
`nil'.
We-!- thought
Yo-!-u thought
---------- Buffer: foo ----------
-
+
(delete-horizontal-space) ; Four times.
=> nil
-
+
---------- Buffer: foo ----------
Ithought
Ithought
You thought
---------- Buffer: foo ----------
- - Command: delete-indentation &optional join-following-p
+ -- Command: delete-indentation &optional join-following-p
This function joins the line point is on to the previous line,
deleting any whitespace at the join and in some cases replacing it
with one space. If JOIN-FOLLOWING-P is non-`nil',
When in the course of human
-!- events, it becomes necessary
---------- Buffer: foo ----------
-
+
(delete-indentation)
=> nil
-
+
---------- Buffer: foo ----------
When in the course of human-!- events, it becomes necessary
---------- Buffer: foo ----------
After the lines are joined, the function `fixup-whitespace' is
responsible for deciding whether to leave a space at the junction.
- - Command: fixup-whitespace
+ -- Command: fixup-whitespace
This function replaces all the white space surrounding point with
either one space or no space, according to the context. It
returns `nil'.
This has too many -!-spaces
This has too many spaces at the start of (-!- this list)
---------- Buffer: foo ----------
-
+
(fixup-whitespace)
=> nil
(fixup-whitespace)
=> nil
-
+
---------- Buffer: foo ----------
This has too many spaces
This has too many spaces at the start of (this list)
---------- Buffer: foo ----------
- - Command: just-one-space
+ -- Command: just-one-space
This command replaces any spaces and tabs around point with a
single space. It returns `nil'.
- - Command: delete-blank-lines
+ -- Command: delete-blank-lines
This function deletes blank lines surrounding point. If point is
on a blank line with one or more blank lines before or after it,
then all but one of them are deleted. If point is on an isolated
\1f
File: lispref.info, Node: The Kill Ring, Next: Undo, Prev: User-Level Deletion, Up: Text
-The Kill Ring
-=============
+43.8 The Kill Ring
+==================
"Kill" functions delete text like the deletion functions, but save it
so that the user can reinsert it by "yanking". Most of these functions
\1f
File: lispref.info, Node: Kill Ring Concepts, Next: Kill Functions, Up: The Kill Ring
-Kill Ring Concepts
-------------------
+43.8.1 Kill Ring Concepts
+-------------------------
The kill ring records killed text as strings in a list, most recent
first. A short kill ring, for example, might look like this:
\1f
File: lispref.info, Node: Kill Functions, Next: Yank Commands, Prev: Kill Ring Concepts, Up: The Kill Ring
-Functions for Killing
----------------------
+43.8.2 Functions for Killing
+----------------------------
`kill-region' is the usual subroutine for killing text. Any command
that calls this function is a "kill command" (and should probably have
previous command was a kill command, and if so appends the killed text
to the most recent entry.
- - Command: kill-region start end &optional verbose
+ -- Command: kill-region start end &optional verbose
This function kills the text in the region defined by START and
END. The text is deleted but saved in the kill ring, along with
its text properties. The value is always `nil'.
This is convenient because it lets the user use all the kill
commands to copy text into the kill ring from a read-only buffer.
- - Command: copy-region-as-kill start end
+ -- Command: copy-region-as-kill start end
This command saves the region defined by START and END on the kill
ring (including text properties), but does not delete the text
from the buffer. It returns `nil'. It also indicates the extent
\1f
File: lispref.info, Node: Yank Commands, Next: Low-Level Kill Ring, Prev: Kill Functions, Up: The Kill Ring
-Functions for Yanking
----------------------
+43.8.3 Functions for Yanking
+----------------------------
"Yanking" means reinserting an entry of previously killed text from the
kill ring. The text properties are copied too.
- - Command: yank &optional arg
+ -- Command: yank &optional arg
This command inserts before point the text in the first entry in
the kill ring. It positions the mark at the beginning of that
text, and point at the end.
`yank' does not alter the contents of the kill ring or rotate it.
It returns `nil'.
- - Command: yank-pop arg
+ -- Command: yank-pop arg
This command replaces the just-yanked entry from the kill ring
with a different entry from the kill ring.
\1f
File: lispref.info, Node: Low-Level Kill Ring, Next: Internals of Kill Ring, Prev: Yank Commands, Up: The Kill Ring
-Low-Level Kill Ring
--------------------
+43.8.4 Low-Level Kill Ring
+--------------------------
These functions and variables provide access to the kill ring at a lower
level, but still convenient for use in Lisp programs. They take care of
interaction with X Window selections. They do not exist in Emacs
version 18.
- - Function: current-kill count &optional do-not-move
+ -- Function: current-kill count &optional do-not-move
The function `current-kill' rotates the yanking pointer which
designates the "front" of the kill ring by COUNT places (from newer
kills to older ones), and returns the text at that place in the
`current-kill' calls the value of `interprogram-paste-function'
(documented below) before consulting the kill ring.
- - Function: kill-new string &optional replace
+ -- Function: kill-new string &optional replace
This function makes the text STRING the latest entry in the kill
ring, and sets `kill-ring-yank-pointer' to point to it.
This function runs the functions on `kill-hooks', and also invokes
the value of `interprogram-cut-function' (see below).
- - Function: kill-append string before-p
+ -- Function: kill-append string before-p
This function appends the text STRING to the first entry in the
kill ring. Normally STRING goes at the end of the entry, but if
BEFORE-P is non-`nil', it goes at the beginning. This function
also invokes the value of `interprogram-cut-function' (see below).
- - Variable: interprogram-paste-function
+ -- Variable: interprogram-paste-function
This variable provides a way of transferring killed text from other
programs, when you are using a window system. Its value should be
`nil' or a function of no arguments.
selection as the most recent kill, even if the selection belongs
to another X client. *Note X Selections::.
- - Variable: interprogram-cut-function
+ -- Variable: interprogram-cut-function
This variable provides a way of communicating killed text to other
programs, when you are using a window system. Its value should be
`nil' or a function of one argument.
The normal use of this hook is to set the X server's primary
selection to the newly killed text.
-\1f
-File: lispref.info, Node: Internals of Kill Ring, Prev: Low-Level Kill Ring, Up: The Kill Ring
-
-Internals of the Kill Ring
---------------------------
-
-The variable `kill-ring' holds the kill ring contents, in the form of a
-list of strings. The most recent kill is always at the front of the
-list.
-
- The `kill-ring-yank-pointer' variable points to a link in the kill
-ring list, whose CAR is the text to yank next. We say it identifies
-the "front" of the ring. Moving `kill-ring-yank-pointer' to a
-different link is called "rotating the kill ring". We call the kill
-ring a "ring" because the functions that move the yank pointer wrap
-around from the end of the list to the beginning, or vice-versa.
-Rotation of the kill ring is virtual; it does not change the value of
-`kill-ring'.
-
- Both `kill-ring' and `kill-ring-yank-pointer' are Lisp variables
-whose values are normally lists. The word "pointer" in the name of the
-`kill-ring-yank-pointer' indicates that the variable's purpose is to
-identify one element of the list for use by the next yank command.
-
- The value of `kill-ring-yank-pointer' is always `eq' to one of the
-links in the kill ring list. The element it identifies is the CAR of
-that link. Kill commands, which change the kill ring, also set this
-variable to the value of `kill-ring'. The effect is to rotate the ring
-so that the newly killed text is at the front.
-
- Here is a diagram that shows the variable `kill-ring-yank-pointer'
-pointing to the second entry in the kill ring `("some text" "a
-different piece of text" "yet older text")'.
-
- kill-ring kill-ring-yank-pointer
- | |
- | ___ ___ ---> ___ ___ ___ ___
- --> |___|___|------> |___|___|--> |___|___|--> nil
- | | |
- | | |
- | | -->"yet older text"
- | |
- | --> "a different piece of text"
- |
- --> "some text"
-
-This state of affairs might occur after `C-y' (`yank') immediately
-followed by `M-y' (`yank-pop').
-
- - Variable: kill-ring
- This variable holds the list of killed text sequences, most
- recently killed first.
-
- - Variable: kill-ring-yank-pointer
- This variable's value indicates which element of the kill ring is
- at the "front" of the ring for yanking. More precisely, the value
- is a tail of the value of `kill-ring', and its CAR is the kill
- string that `C-y' should yank.
-
- - User Option: kill-ring-max
- The value of this variable is the maximum length to which the kill
- ring can grow, before elements are thrown away at the end. The
- default value for `kill-ring-max' is 30.
-
-\1f
-File: lispref.info, Node: Undo, Next: Maintaining Undo, Prev: The Kill Ring, Up: Text
-
-Undo
-====
-
-Most buffers have an "undo list", which records all changes made to the
-buffer's text so that they can be undone. (The buffers that don't have
-one are usually special-purpose buffers for which XEmacs assumes that
-undoing is not useful.) All the primitives that modify the text in the
-buffer automatically add elements to the front of the undo list, which
-is in the variable `buffer-undo-list'.
-
- - Variable: buffer-undo-list
- This variable's value is the undo list of the current buffer. A
- value of `t' disables the recording of undo information.
-
- Here are the kinds of elements an undo list can have:
-
-`INTEGER'
- This kind of element records a previous value of point. Ordinary
- cursor motion does not get any sort of undo record, but deletion
- commands use these entries to record where point was before the
- command.
-
-`(START . END)'
- This kind of element indicates how to delete text that was
- inserted. Upon insertion, the text occupied the range START-END
- in the buffer.
-
-`(TEXT . POSITION)'
- This kind of element indicates how to reinsert text that was
- deleted. The deleted text itself is the string TEXT. The place to
- reinsert it is `(abs POSITION)'.
-
-`(t HIGH . LOW)'
- This kind of element indicates that an unmodified buffer became
- modified. The elements HIGH and LOW are two integers, each
- recording 16 bits of the visited file's modification time as of
- when it was previously visited or saved. `primitive-undo' uses
- those values to determine whether to mark the buffer as unmodified
- once again; it does so only if the file's modification time
- matches those numbers.
-
-`(nil PROPERTY VALUE START . END)'
- This kind of element records a change in a text property. Here's
- how you might undo the change:
-
- (put-text-property START END PROPERTY VALUE)
-
-`POSITION'
- This element indicates where point was at an earlier time.
- Undoing this element sets point to POSITION. Deletion normally
- creates an element of this kind as well as a reinsertion element.
-
-`nil'
- This element is a boundary. The elements between two boundaries
- are called a "change group"; normally, each change group
- corresponds to one keyboard command, and undo commands normally
- undo an entire group as a unit.
-
- - Function: undo-boundary
- This function places a boundary element in the undo list. The undo
- command stops at such a boundary, and successive undo commands undo
- to earlier and earlier boundaries. This function returns `nil'.
-
- The editor command loop automatically creates an undo boundary
- before each key sequence is executed. Thus, each undo normally
- undoes the effects of one command. Self-inserting input
- characters are an exception. The command loop makes a boundary
- for the first such character; the next 19 consecutive
- self-inserting input characters do not make boundaries, and then
- the 20th does, and so on as long as self-inserting characters
- continue.
-
- All buffer modifications add a boundary whenever the previous
- undoable change was made in some other buffer. This way, a
- command that modifies several buffers makes a boundary in each
- buffer it changes.
-
- Calling this function explicitly is useful for splitting the
- effects of a command into more than one unit. For example,
- `query-replace' calls `undo-boundary' after each replacement, so
- that the user can undo individual replacements one by one.
-
- - Function: primitive-undo count list
- This is the basic function for undoing elements of an undo list.
- It undoes the first COUNT elements of LIST, returning the rest of
- LIST. You could write this function in Lisp, but it is convenient
- to have it in C.
-
- `primitive-undo' adds elements to the buffer's undo list when it
- changes the buffer. Undo commands avoid confusion by saving the
- undo list value at the beginning of a sequence of undo operations.
- Then the undo operations use and update the saved value. The new
- elements added by undoing are not part of this saved value, so
- they don't interfere with continuing to undo.
-
projects / chise / xemacs-chise.git.1 / blobdiff