Mercurial > emacs
comparison lispref/display.texi @ 79010:3d90e1da8878
(Display Margins): Correct the description of margin display specifications.
(Replacing Specs): New subnode broken out of Display Property.
author | Richard M. Stallman <rms@gnu.org> |
---|---|
date | Tue, 09 Oct 2007 01:24:28 +0000 |
parents | e9ee93a009f5 |
children | dbd4308fbdba |
comparison
equal
deleted
inserted
replaced
79009:d88e1a701613 | 79010:3d90e1da8878 |
---|---|
3235 | 3235 |
3236 The @code{display} text property (or overlay property) is used to | 3236 The @code{display} text property (or overlay property) is used to |
3237 insert images into text, and also control other aspects of how text | 3237 insert images into text, and also control other aspects of how text |
3238 displays. The value of the @code{display} property should be a | 3238 displays. The value of the @code{display} property should be a |
3239 display specification, or a list or vector containing several display | 3239 display specification, or a list or vector containing several display |
3240 specifications. Display specifications generally apply in parallel to | 3240 specifications. Display specifications in the same @code{display} |
3241 the text they cover. | 3241 property value generally apply in parallel to the text they cover. |
3242 | |
3243 If several sources (overlays and/or a text property) specify values | |
3244 for the @code{display} property, only one of the values takes effect, | |
3245 following the rules of @code{get-char-property}. @xref{Examining | |
3246 Properties}. | |
3247 | |
3248 The rest of this section describes several kinds of | |
3249 display specifications and what they mean. | |
3250 | |
3251 @menu | |
3252 * Replacing Specs:: Display specs that replace the text. | |
3253 * Specified Space:: Displaying one space with a specified width. | |
3254 * Pixel Specification:: Specifying space width or height in pixels. | |
3255 * Other Display Specs:: Displaying an image; magnifying text; moving it | |
3256 up or down on the page; adjusting the width | |
3257 of spaces within text. | |
3258 * Display Margins:: Displaying text or images to the side of the main text. | |
3259 @end menu | |
3260 | |
3261 @node Replacing Specs | |
3262 @subsection Display Specs That Replace The Text | |
3242 | 3263 |
3243 Some kinds of @code{display} specifications specify something to | 3264 Some kinds of @code{display} specifications specify something to |
3244 display instead of the text that has the property. If a list of | 3265 display instead of the text that has the property. These are called |
3245 display specifications includes more than one of this kind, the first | 3266 @dfn{replacing} display specifications. Emacs does not allow the user |
3246 is effective and the rest are ignored. You cannot interactively move | 3267 to interactively move point into the middle of buffer text that is |
3247 point into the middle of the text that is thus replaced. | 3268 replaced in this way. |
3248 | 3269 |
3249 For these specifications, ``the text that has the property'' means | 3270 If a list of display specifications includes more than one replacing |
3250 all the consecutive characters that have the same Lisp object as their | 3271 display specification, the first overrides the rest. Replacing |
3251 @code{display} property; these characters are replaced as a single | 3272 display specifications make most other display specifications |
3252 unit. By contrast, characters that have similar but distinct Lisp | 3273 irrelevant, since those don't apply to the replacement. |
3253 objects as their @code{display} properties are handled separately. | 3274 |
3254 Here's a function that illustrates this point: | 3275 For replacing display specifications, ``the text that has the |
3276 property'' means all the consecutive characters that have the same | |
3277 Lisp object as their @code{display} property; these characters are | |
3278 replaced as a single unit. By contrast, characters that have similar | |
3279 but distinct Lisp objects as their @code{display} properties are | |
3280 handled separately. Here's a function that illustrates this point: | |
3255 | 3281 |
3256 @smallexample | 3282 @smallexample |
3257 (defun foo () | 3283 (defun foo () |
3258 (goto-char (point-min)) | 3284 (goto-char (point-min)) |
3259 (dotimes (i 5) | 3285 (dotimes (i 5) |
3288 This illustrates that what matters is the property value for | 3314 This illustrates that what matters is the property value for |
3289 each character. If two consecutive characters have the same | 3315 each character. If two consecutive characters have the same |
3290 object as the @code{display} property value, it's irrelevant | 3316 object as the @code{display} property value, it's irrelevant |
3291 whether they got this property from a single call to | 3317 whether they got this property from a single call to |
3292 @code{put-text-property} or from two different calls. | 3318 @code{put-text-property} or from two different calls. |
3293 | |
3294 The rest of this section describes several kinds of | |
3295 display specifications and what they mean. | |
3296 | |
3297 @menu | |
3298 * Specified Space:: Displaying one space with a specified width. | |
3299 * Pixel Specification:: Specifying space width or height in pixels. | |
3300 * Other Display Specs:: Displaying an image; magnifying text; moving it | |
3301 up or down on the page; adjusting the width | |
3302 of spaces within text. | |
3303 * Display Margins:: Displaying text or images to the side of the main text. | |
3304 @end menu | |
3305 | 3319 |
3306 @node Specified Space | 3320 @node Specified Space |
3307 @subsection Specified Spaces | 3321 @subsection Specified Spaces |
3308 @cindex spaces, specified height or width | 3322 @cindex spaces, specified height or width |
3309 @cindex variable-width spaces | 3323 @cindex variable-width spaces |
3539 @node Display Margins | 3553 @node Display Margins |
3540 @subsection Displaying in the Margins | 3554 @subsection Displaying in the Margins |
3541 @cindex display margins | 3555 @cindex display margins |
3542 @cindex margins, display | 3556 @cindex margins, display |
3543 | 3557 |
3544 A buffer can have blank areas called @dfn{display margins} on the left | 3558 A buffer can have blank areas called @dfn{display margins} on the |
3545 and on the right. Ordinary text never appears in these areas, but you | 3559 left and on the right. Ordinary text never appears in these areas, |
3546 can put things into the display margins using the @code{display} | 3560 but you can put things into the display margins using the |
3547 property. | 3561 @code{display} property. There is currently no way to make text or |
3548 | 3562 images in the margin mouse-sensitive. |
3549 To put text in the left or right display margin of the window, use a | 3563 |
3550 display specification of the form @code{(margin right-margin)} or | 3564 The way to display something in the margins is to specify it in a |
3551 @code{(margin left-margin)} on it. To put an image in a display margin, | 3565 margin display specification in the @code{display} property of some |
3552 use that display specification along with the display specification for | 3566 text. This is a replacing display specification, meaning that the |
3553 the image. Unfortunately, there is currently no way to make | 3567 text you put it on does not get displayed; the margin display appears, |
3554 text or images in the margin mouse-sensitive. | 3568 but that text does not. |
3555 | 3569 |
3556 If you put such a display specification directly on text in the | 3570 A margin display specification looks like @code{((margin |
3557 buffer, the specified margin display appears @emph{instead of} that | 3571 right-margin) @var{spec}} or @code{((margin left-margin) @var{spec})}. |
3558 buffer text itself. To put something in the margin @emph{in | 3572 Here, @var{spec} is another display specification that says what to |
3559 association with} certain buffer text without preventing or altering | 3573 display in the margin. Typically it is a string of text to display, |
3560 the display of that text, put a @code{before-string} property on the | 3574 or an image descriptor. |
3561 text and put the display specification on the contents of the | 3575 |
3562 before-string. | 3576 To display something in the margin @emph{in association with} |
3577 certain buffer text, without altering or preventing the display of | |
3578 that text, put a @code{before-string} property on the text and put the | |
3579 margin display specification on the contents of the before-string. | |
3563 | 3580 |
3564 Before the display margins can display anything, you must give | 3581 Before the display margins can display anything, you must give |
3565 them a nonzero width. The usual way to do that is to set these | 3582 them a nonzero width. The usual way to do that is to set these |
3566 variables: | 3583 variables: |
3567 | 3584 |