procyberian/emacs
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

(Swapping Text): New section, documents `buffer-swap-text'.

Browse source
This commit is contained in:
Eli Zaretskii 2008-10-21 10:00:47 +00:00
parent 834b54855c
commit 2aaaf0dd17
1 changed files with 39 additions and 0 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

39
doc/lispref/buffers.texi
View file

@ -30,6 +30,7 @@ not be displayed in any windows.
* Creating Buffers:: Functions that create buffers.
* Killing Buffers:: Buffers exist until explicitly killed.
* Indirect Buffers:: An indirect buffer shares text with some other buffer.
* Swapping Text:: Swapping text between two buffers.
* Buffer Gap:: The gap in the buffer.
@end menu
@ -1136,6 +1137,44 @@ to the current buffer. If @var{buffer} is not indirect, the value is
indirect buffer.
@end defun
@node Swapping Text
@section Swapping Text Between Two Buffers
@cindex swap text between buffers
@cindex virtual buffers
Specialized modes sometimes need to let the user access from the
same buffer several vastly different types of text. For example, you
may need to display a summary of the buffer text, in addition to
letting the user access the text itself.
This could be implemented with multiple buffers (kept in sync when
the user edits the text), or with narrowing (@pxref{Narrowing}). But
these alternatives might sometimes become tedious or prohibitively
expensive, especially if each type of text requires expensive
buffer-global operations in order to provide correct display and
editing commands.
Emacs provides another facility for such modes: you can quickly swap
buffer text between two buffers with @code{buffer-swap-text}. This
function is very fast because it doesn't move any text, it only
changes the internal data structures of the buffer object to point to
a different chunk of text. Using it, you can pretend that a group of
two or more buffers are actually a single virtual buffer that holds
the contents of all the individual buffers together.
@defun buffer-swap-text buffer
This function swaps text between the current buffer and its argument
@var{buffer}. It signals an error if one of the two buffers is an
indirect buffer (@pxref{Indirect Buffers}) or is a base buffer of an
indirect buffer.
All the buffer properties that are related to the buffer text are
swapped as well: the positions of point and mark, all the markers, the
overlays, the text properties, the undo list, the value of the
@code{enable-multibyte-characters} flag (@pxref{Text Representations,
enable-multibyte-characters}), etc.
@end defun
@node Buffer Gap
@section The Buffer Gap