X-Git-Url: https://code.delx.au/gnu-emacs/blobdiff_plain/fdc9061358d3654e14bfc1419632e1d6c6c5c13e..dc1ce9aa18bacf51e434a0957d9ae5c54835b782:/doc/lispref/text.texi?ds=sidebyside diff --git a/doc/lispref/text.texi b/doc/lispref/text.texi index 5b935bc6e2..72a2feda68 100644 --- a/doc/lispref/text.texi +++ b/doc/lispref/text.texi @@ -1,7 +1,7 @@ @c -*-texinfo-*- @c This is part of the GNU Emacs Lisp Reference Manual. @c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2000, 2001, -@c 2002, 2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc. +@c 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009 Free Software Foundation, Inc. @c See the file elisp.texi for copying conditions. @setfilename ../../info/text @node Text, Non-ASCII Characters, Markers, Top @@ -1057,12 +1057,14 @@ If @var{n} is zero, indicating a request for the latest kill, @code{current-kill} calls the value of @code{interprogram-paste-function} (documented below) before consulting the kill ring. If that value is a function and calling it -returns a string, @code{current-kill} pushes that string onto the kill -ring and returns it. It also sets the yanking pointer to point to -that new entry, regardless of the value of @var{do-not-move}. -Otherwise, @code{current-kill} does not treat a zero value for @var{n} -specially: it returns the entry pointed at by the yanking pointer and -does not move the yanking pointer. +returns a string or a list of several string, @code{current-kill} +pushes the strings onto the kill ring and returns the first string. +It also sets the yanking pointer to point to the kill-ring entry of +the first string returned by @code{interprogram-paste-function}, +regardless of the value of @var{do-not-move}. Otherwise, +@code{current-kill} does not treat a zero value for @var{n} specially: +it returns the entry pointed at by the yanking pointer and does not +move the yanking pointer. @end defun @defun kill-new string &optional replace yank-handler @@ -1105,9 +1107,19 @@ If the value is a function, @code{current-kill} calls it to get the then that value is used as the ``most recent kill.'' If it returns @code{nil}, then the front of the kill ring is used. -The normal use of this hook is to get the window system's primary +To facilitate support for window systems that support multiple +selections, this function may also return a list of strings. In that +case, the first string is used as the ``most recent kill'', and all +the other strings are pushed onto the kill ring, for easy access by +@code{yank-pop}. + +The normal use of this function is to get the window system's primary selection as the most recent kill, even if the selection belongs to -another application. @xref{Window System Selections}. +another application. @xref{Window System Selections}. However, if +the selection was provided by the current Emacs session, this function +should return @code{nil}. (If it is hard to tell whether Emacs or +some other program provided the selection, it should be good enough to +use @code{string=} to compare it with the last text Emacs provided.) @end defvar @defvar interprogram-cut-function @@ -1121,7 +1133,7 @@ The second, optional, argument has the same meaning as the @var{push} argument to @code{x-set-cut-buffer} (@pxref{Definition of x-set-cut-buffer}) and only affects the second and later cut buffers. -The normal use of this hook is to set the window system's primary +The normal use of this function is to set the window system's primary selection (and first cut buffer) from the newly killed text. @xref{Window System Selections}. @end defvar @@ -2990,31 +3002,28 @@ time you want to specify a particular attribute for certain text. @xref{Face Attributes}. @item -A cons cell with the form @code{(foreground-color . @var{color-name})} or -@code{(background-color . @var{color-name})}. These elements specify -just the foreground color or just the background color. @xref{Color -Names}, for the supported forms of @var{color-name}. - -A cons cell of @code{(foreground-color . @var{color-name})} is equivalent to -specifying @code{(:foreground @var{color-name})}; likewise for the -background. +A cons cell with the form @code{(foreground-color . @var{color-name})} +or @code{(background-color . @var{color-name})}. These are older, +deprecated equivalents for @code{(:foreground @var{color-name})} and +@code{(:background @var{color-name})}. Please convert code that uses +them. @end itemize -You can use Font Lock Mode (@pxref{Font Lock Mode}), to dynamically -update @code{face} properties based on the contents of the text. +It works to use the latter two forms directly as the value +of the @code{face} property. + +Font Lock mode (@pxref{Font Lock Mode}) works in most buffers by +dynamically updating the @code{face} property of characters based on +the context. @item font-lock-face @kindex font-lock-face @r{(text property)} -The @code{font-lock-face} property is the same in all respects as the -@code{face} property, but its state of activation is controlled by -@code{font-lock-mode}. This can be advantageous for special buffers -which are not intended to be user-editable, or for static areas of -text which are always fontified in the same way. -@xref{Precalculated Fontification}. +The @code{font-lock-face} property is equivalent to the @code{face} +property when Font Lock mode is enabled. When Font Lock mode is disabled, +@code{font-lock-face} has no effect. -Strictly speaking, @code{font-lock-face} is not a built-in text -property; rather, it is implemented in Font Lock mode using -@code{char-property-alias-alist}. @xref{Examining Properties}. +The @code{font-lock-mode} property is useful for special modes that +implement their own highlighting. @xref{Precalculated Fontification}. This property is new in Emacs 22.1. @@ -3173,6 +3182,29 @@ A newline can have a @code{line-height} text or overlay property that controls the total height of the display line ending in that newline. @xref{Line Height}. +@item wrap-prefix +If text has a @code{wrap-prefix} property, the prefix it defines will +be added at display-time to the beginning of every continuation line +due to text wrapping (so if lines are truncated, the wrap-prefix is +never used). It may be a string, an image, or a stretch-glyph such as +used by the @code{display} text-property. @xref{Display Property}. + +A wrap-prefix may also be specified for an entire buffer using the +@code{wrap-prefix} buffer-local variable (however, a +@code{wrap-prefix} text-property takes precedence over the value of +the @code{wrap-prefix} variable). @xref{Truncation}. + +@item line-prefix +If text has a @code{line-prefix} property, the prefix it defines will +be added at display-time to the beginning of every non-continuation +line. It may be a string, an image, or a stretch-glyph such as used +by the @code{display} text-property. @xref{Display Property}. + +A line-prefix may also be specified for an entire buffer using the +@code{line-prefix} buffer-local variable (however, a +@code{line-prefix} text-property takes precedence over the value of +the @code{line-prefix} variable). @xref{Truncation}. + @item modification-hooks @cindex change hooks for a character @cindex hooks for changing a character @@ -3634,7 +3666,7 @@ a @key{Mouse-1} click shall be translated to @key{RET}: @defun mouse-on-link-p pos This function returns non-@code{nil} if position @var{pos} in the current buffer is on a link. @var{pos} can also be a mouse event -location, as returned by @code{event-start} (@pxref{Accessing Events}). +location, as returned by @code{event-start} (@pxref{Accessing Mouse}). @end defun @node Fields