Mercurial > emacs
comparison doc/lispref/display.texi @ 85311:591c29778a30
Merge from emacs--rel--22
Patches applied:
* emacs--rel--22 (patch 116-121)
- Update from CVS
Revision: emacs@sv.gnu.org/emacs--devo--0--patch-889
author | Miles Bader <miles@gnu.org> |
---|---|
date | Mon, 15 Oct 2007 02:07:53 +0000 |
parents | 5039706521c9 |
children | ec0ef12211d9 |
comparison
equal
deleted
inserted
replaced
85310:22c169d62199 | 85311:591c29778a30 |
---|---|
3243 | 3243 |
3244 The @code{display} text property (or overlay property) is used to | 3244 The @code{display} text property (or overlay property) is used to |
3245 insert images into text, and also control other aspects of how text | 3245 insert images into text, and also control other aspects of how text |
3246 displays. The value of the @code{display} property should be a | 3246 displays. The value of the @code{display} property should be a |
3247 display specification, or a list or vector containing several display | 3247 display specification, or a list or vector containing several display |
3248 specifications. Display specifications generally apply in parallel to | 3248 specifications. Display specifications in the same @code{display} |
3249 the text they cover. | 3249 property value generally apply in parallel to the text they cover. |
3250 | |
3251 If several sources (overlays and/or a text property) specify values | |
3252 for the @code{display} property, only one of the values takes effect, | |
3253 following the rules of @code{get-char-property}. @xref{Examining | |
3254 Properties}. | |
3255 | |
3256 The rest of this section describes several kinds of | |
3257 display specifications and what they mean. | |
3258 | |
3259 @menu | |
3260 * Replacing Specs:: Display specs that replace the text. | |
3261 * Specified Space:: Displaying one space with a specified width. | |
3262 * Pixel Specification:: Specifying space width or height in pixels. | |
3263 * Other Display Specs:: Displaying an image; magnifying text; moving it | |
3264 up or down on the page; adjusting the width | |
3265 of spaces within text. | |
3266 * Display Margins:: Displaying text or images to the side of the main text. | |
3267 @end menu | |
3268 | |
3269 @node Replacing Specs | |
3270 @subsection Display Specs That Replace The Text | |
3250 | 3271 |
3251 Some kinds of @code{display} specifications specify something to | 3272 Some kinds of @code{display} specifications specify something to |
3252 display instead of the text that has the property. If a list of | 3273 display instead of the text that has the property. These are called |
3253 display specifications includes more than one of this kind, the first | 3274 @dfn{replacing} display specifications. Emacs does not allow the user |
3254 is effective and the rest are ignored. You cannot interactively move | 3275 to interactively move point into the middle of buffer text that is |
3255 point into the middle of the text that is thus replaced. | 3276 replaced in this way. |
3256 | 3277 |
3257 For these specifications, ``the text that has the property'' means | 3278 If a list of display specifications includes more than one replacing |
3258 all the consecutive characters that have the same Lisp object as their | 3279 display specification, the first overrides the rest. Replacing |
3259 @code{display} property; these characters are replaced as a single | 3280 display specifications make most other display specifications |
3260 unit. By contrast, characters that have similar but distinct Lisp | 3281 irrelevant, since those don't apply to the replacement. |
3261 objects as their @code{display} properties are handled separately. | 3282 |
3262 Here's a function that illustrates this point: | 3283 For replacing display specifications, ``the text that has the |
3284 property'' means all the consecutive characters that have the same | |
3285 Lisp object as their @code{display} property; these characters are | |
3286 replaced as a single unit. By contrast, characters that have similar | |
3287 but distinct Lisp objects as their @code{display} properties are | |
3288 handled separately. Here's a function that illustrates this point: | |
3263 | 3289 |
3264 @smallexample | 3290 @smallexample |
3265 (defun foo () | 3291 (defun foo () |
3266 (goto-char (point-min)) | 3292 (goto-char (point-min)) |
3267 (dotimes (i 5) | 3293 (dotimes (i 5) |
3296 This illustrates that what matters is the property value for | 3322 This illustrates that what matters is the property value for |
3297 each character. If two consecutive characters have the same | 3323 each character. If two consecutive characters have the same |
3298 object as the @code{display} property value, it's irrelevant | 3324 object as the @code{display} property value, it's irrelevant |
3299 whether they got this property from a single call to | 3325 whether they got this property from a single call to |
3300 @code{put-text-property} or from two different calls. | 3326 @code{put-text-property} or from two different calls. |
3301 | |
3302 The rest of this section describes several kinds of | |
3303 display specifications and what they mean. | |
3304 | |
3305 @menu | |
3306 * Specified Space:: Displaying one space with a specified width. | |
3307 * Pixel Specification:: Specifying space width or height in pixels. | |
3308 * Other Display Specs:: Displaying an image; magnifying text; moving it | |
3309 up or down on the page; adjusting the width | |
3310 of spaces within text. | |
3311 * Display Margins:: Displaying text or images to the side of the main text. | |
3312 @end menu | |
3313 | 3327 |
3314 @node Specified Space | 3328 @node Specified Space |
3315 @subsection Specified Spaces | 3329 @subsection Specified Spaces |
3316 @cindex spaces, specified height or width | 3330 @cindex spaces, specified height or width |
3317 @cindex variable-width spaces | 3331 @cindex variable-width spaces |
3547 @node Display Margins | 3561 @node Display Margins |
3548 @subsection Displaying in the Margins | 3562 @subsection Displaying in the Margins |
3549 @cindex display margins | 3563 @cindex display margins |
3550 @cindex margins, display | 3564 @cindex margins, display |
3551 | 3565 |
3552 A buffer can have blank areas called @dfn{display margins} on the left | 3566 A buffer can have blank areas called @dfn{display margins} on the |
3553 and on the right. Ordinary text never appears in these areas, but you | 3567 left and on the right. Ordinary text never appears in these areas, |
3554 can put things into the display margins using the @code{display} | 3568 but you can put things into the display margins using the |
3555 property. | 3569 @code{display} property. There is currently no way to make text or |
3556 | 3570 images in the margin mouse-sensitive. |
3557 To put text in the left or right display margin of the window, use a | 3571 |
3558 display specification of the form @code{(margin right-margin)} or | 3572 The way to display something in the margins is to specify it in a |
3559 @code{(margin left-margin)} on it. To put an image in a display margin, | 3573 margin display specification in the @code{display} property of some |
3560 use that display specification along with the display specification for | 3574 text. This is a replacing display specification, meaning that the |
3561 the image. Unfortunately, there is currently no way to make | 3575 text you put it on does not get displayed; the margin display appears, |
3562 text or images in the margin mouse-sensitive. | 3576 but that text does not. |
3563 | 3577 |
3564 If you put such a display specification directly on text in the | 3578 A margin display specification looks like @code{((margin |
3565 buffer, the specified margin display appears @emph{instead of} that | 3579 right-margin) @var{spec}} or @code{((margin left-margin) @var{spec})}. |
3566 buffer text itself. To put something in the margin @emph{in | 3580 Here, @var{spec} is another display specification that says what to |
3567 association with} certain buffer text without preventing or altering | 3581 display in the margin. Typically it is a string of text to display, |
3568 the display of that text, put a @code{before-string} property on the | 3582 or an image descriptor. |
3569 text and put the display specification on the contents of the | 3583 |
3570 before-string. | 3584 To display something in the margin @emph{in association with} |
3585 certain buffer text, without altering or preventing the display of | |
3586 that text, put a @code{before-string} property on the text and put the | |
3587 margin display specification on the contents of the before-string. | |
3571 | 3588 |
3572 Before the display margins can display anything, you must give | 3589 Before the display margins can display anything, you must give |
3573 them a nonzero width. The usual way to do that is to set these | 3590 them a nonzero width. The usual way to do that is to set these |
3574 variables: | 3591 variables: |
3575 | 3592 |