Mercurial > hg > xemacs-beta
annotate man/lispref/annotations.texi @ 5937:9e308c7501d1 cygwin
6 years later, not sure about movemail
| author | Henry Thompson <ht@markup.co.uk> |
|---|---|
| date | Thu, 02 Dec 2021 14:34:45 +0000 |
| parents | 9fae6227ede5 |
| children |
| rev | line source |
|---|---|
| 428 | 1 @c -*-texinfo-*- |
| 2 @c This is part of the XEmacs Lisp Reference Manual. | |
| 444 | 3 @c Copyright (C) 1990, 1991, 1992, 1993 Free Software Foundation, Inc. |
| 428 | 4 @c Copyright (C) 1995 Ben Wing. |
| 5 @c See the file lispref.texi for copying conditions. | |
| 6 @setfilename ../../info/annotations.info | |
|
5791
9fae6227ede5
Silence texinfo 5.2 warnings, primarily by adding next, prev, and up
Jerry James <james@xemacs.org>
parents:
444
diff
changeset
|
7 @node Annotations, Display, Glyphs, Top |
| 428 | 8 @chapter Annotations |
| 9 @cindex annotation | |
| 10 | |
| 11 An @dfn{annotation} is a pixmap or string that is not part of a buffer's | |
| 12 text but is displayed next to a particular location in a buffer. | |
| 13 Annotations can be displayed intermixed with text, in any whitespace at | |
| 14 the beginning or end of a line, or in a special area at the left or | |
| 15 right side of the frame called a @dfn{margin}, whose size is | |
| 16 controllable. Annotations are implemented using extents | |
| 17 (@pxref{Extents}); but you can work with annotations without knowing how | |
| 18 extents work. | |
| 19 | |
| 20 @menu | |
| 21 * Annotation Basics:: Introduction to annotations. | |
| 22 * Annotation Primitives:: Creating and deleting annotations. | |
| 23 * Annotation Properties:: Retrieving and changing the characteristics | |
| 24 of an annotation. | |
| 25 * Margin Primitives:: Controlling the size of the margins. | |
| 26 * Locating Annotations:: Looking for annotations in a buffer. | |
| 27 * Annotation Hooks:: Hooks called at certain times during an | |
| 28 annotation's lifetime. | |
| 29 @end menu | |
| 30 | |
|
5791
9fae6227ede5
Silence texinfo 5.2 warnings, primarily by adding next, prev, and up
Jerry James <james@xemacs.org>
parents:
444
diff
changeset
|
31 @node Annotation Basics, Annotation Primitives, Annotations, Annotations |
| 428 | 32 @section Annotation Basics |
| 33 | |
| 34 @cindex margin | |
| 35 Marginal annotations are notes associated with a particular location in | |
| 36 a buffer. They may be displayed in a margin created on the left-hand or | |
| 37 right-hand side of the frame, in any whitespace at the beginning or end | |
| 38 of a line, or inside of the text itself. Every annotation may have an | |
| 39 associated action to be performed when the annotation is selected. The | |
| 40 term @dfn{annotation} is used to refer to an individual note. The term | |
| 41 @dfn{margin} is generically used to refer to the whitespace before the | |
| 42 first character on a line or after the last character on a line. | |
| 43 | |
| 44 Each annotation has the following characteristics: | |
| 45 @table @var | |
| 46 @item glyph | |
| 47 This is a glyph object and is used as the displayed representation | |
| 48 of the annotation. | |
| 49 @item down-glyph | |
| 50 If given, this glyph is used as the displayed representation | |
| 51 of the annotation when the mouse is pressed down over the annotation. | |
| 52 @item face | |
| 53 The face with which to display the glyph. | |
| 54 @item side | |
| 55 Which side of the text (left or right) the annotation is displayed at. | |
| 56 @item action | |
| 57 If non-@code{nil}, this field must contain a function capable of being | |
| 58 the first argument to @code{funcall}. This function is normally | |
| 59 evaluated with a single argument, the value of the @var{data} field, | |
| 60 each time the annotation is selected. However, if the @var{with-event} | |
| 61 parameter to @code{make-annotation} is non-@code{nil}, the function | |
| 62 is called with two arguments. The first argument is the same as | |
| 63 before, and the second argument is the event (a button-up event, | |
| 64 usually) that activated the annotation. | |
| 65 @item data | |
| 66 Not used internally. This field can contain any E-Lisp object. It is | |
| 67 passed as the first argument to @var{action} described above. | |
| 68 @item menu | |
| 69 A menu displayed when the right mouse button is pressed over the | |
| 70 annotation. | |
| 71 @end table | |
| 72 | |
| 73 @cindex outside margin | |
| 74 @cindex inside margin | |
| 75 The margin is divided into @dfn{outside} and @dfn{inside}. The outside | |
| 76 margin is space on the left or right side of the frame which normal text | |
| 77 cannot be displayed in. The inside margin is that space between the | |
| 78 leftmost or rightmost point at which text can be displayed and where the | |
| 79 first or last character actually is. | |
| 80 | |
| 81 @cindex layout types | |
| 82 There are four different @dfn{layout types} which affect the exact | |
| 83 location an annotation appears. | |
| 84 | |
| 85 @table @code | |
| 86 @item outside-margin | |
| 87 The annotation is placed in the outside margin area. as close as | |
| 88 possible to the edge of the frame. If the outside margin is not wide | |
| 89 enough for an annotation to fit, it is not displayed. | |
| 90 | |
| 91 @item inside-margin | |
| 92 The annotation is placed in the inside margin area, as close as possible | |
| 93 to the edge of the frame. If the inside margin is not wide enough for | |
| 94 the annotation to fit, it will be displayed using any available outside | |
| 95 margin space if and only if the specifier @code{use-left-overflow} or | |
| 96 @code{use-right-overflow} (depending on which side the annotation | |
| 97 appears in) is non-@code{nil}. | |
| 98 | |
| 99 @item whitespace | |
| 100 The annotation is placed in the inside margin area, as close as possible | |
| 101 to the first or last non-whitespace character on a line. If the inside | |
| 102 margin is not wide enough for the annotation to fit, it will be | |
| 103 displayed if and only if the specifier @code{use-left-overflow} or | |
| 104 @code{use-right-overflow} (depending on which side the annotation | |
| 105 appears in) is non-@code{nil}. | |
| 106 | |
| 107 @item text | |
| 108 The annotation is placed at the position it is inserted. It will create | |
| 109 enough space for itself inside of the text area. It does not take up a | |
| 110 place in the logical buffer, only in the display of the buffer. | |
| 111 @end table | |
| 112 | |
| 113 @cindex layout policy | |
| 114 The current layout policy is that all @code{whitespace} annotations are | |
| 115 displayed first. Next, all @code{inside-margin} annotations are | |
| 116 displayed using any remaining space. Finally as many | |
| 117 @code{outside-margin} annotations are displayed as possible. The | |
| 118 @code{text} annotations will always display as they create their own | |
| 119 space to display in. | |
| 120 | |
| 121 | |
|
5791
9fae6227ede5
Silence texinfo 5.2 warnings, primarily by adding next, prev, and up
Jerry James <james@xemacs.org>
parents:
444
diff
changeset
|
122 @node Annotation Primitives, Annotation Properties, Annotation Basics, Annotations |
| 428 | 123 @section Annotation Primitives |
| 124 | |
| 125 @defun make-annotation glyph &optional position layout buffer with-event d-glyph rightp | |
| 444 | 126 This function creates a marginal annotation at position @var{position} in |
| 428 | 127 @var{buffer}. The annotation is displayed using @var{glyph}, which |
| 128 should be a glyph object or a string, and is positioned using layout | |
| 444 | 129 policy @var{layout}. If @var{position} is @code{nil}, point is used. If |
| 428 | 130 @var{layout} is @code{nil}, @code{whitespace} is used. If @var{buffer} |
| 131 is @code{nil}, the current buffer is used. | |
| 132 | |
| 133 If @var{with-event} is non-@code{nil}, then when an annotation is | |
| 134 activated, the triggering event is passed as the second arg to the | |
| 135 annotation function. If @var{d-glyph} is non-@code{nil} then it is used | |
| 136 as the glyph that will be displayed when button1 is down. If | |
| 137 @var{rightp} is non-@code{nil} then the glyph will be displayed on the | |
| 138 right side of the buffer instead of the left. | |
| 139 | |
| 140 The newly created annotation is returned. | |
| 141 @end defun | |
| 142 | |
| 143 @defun delete-annotation annotation | |
| 144 This function removes @var{annotation} from its buffer. This does not | |
| 145 modify the buffer text. | |
| 146 @end defun | |
| 147 | |
| 148 @defun annotationp annotation | |
| 149 This function returns @code{t} if @var{annotation} is an annotation, | |
| 150 @code{nil} otherwise. | |
| 151 @end defun | |
| 152 | |
|
5791
9fae6227ede5
Silence texinfo 5.2 warnings, primarily by adding next, prev, and up
Jerry James <james@xemacs.org>
parents:
444
diff
changeset
|
153 @node Annotation Properties, Locating Annotations, Annotation Primitives, Annotations |
| 428 | 154 @section Annotation Properties |
| 155 | |
| 156 @defun annotation-glyph annotation | |
| 157 This function returns the glyph object used to display @var{annotation}. | |
| 158 @end defun | |
| 159 | |
| 160 @defun set-annotation-glyph annotation glyph &optional layout side | |
| 161 This function sets the glyph of @var{annotation} to @var{glyph}, which | |
| 162 should be a glyph object. If @var{layout} is non-@code{nil}, set the | |
| 163 layout policy of @var{annotation} to @var{layout}. If @var{side} is | |
| 164 @code{left} or @code{right}, change the side of the buffer at which the | |
| 165 annotation is displayed to the given side. The new value of | |
| 166 @code{annotation-glyph} is returned. | |
| 167 @end defun | |
| 168 | |
| 169 @defun annotation-down-glyph annotation | |
| 170 This function returns the glyph used to display @var{annotation} when | |
| 171 the left mouse button is depressed on the annotation. | |
| 172 @end defun | |
| 173 | |
| 174 @defun set-annotation-down-glyph annotation glyph | |
| 175 This function returns the glyph used to display @var{annotation} when | |
| 176 the left mouse button is depressed on the annotation to @var{glyph}, | |
| 177 which should be a glyph object. | |
| 178 @end defun | |
| 179 | |
| 180 @defun annotation-face annotation | |
| 181 This function returns the face associated with @var{annotation}. | |
| 182 @end defun | |
| 444 | 183 |
| 428 | 184 @defun set-annotation-face annotation face |
| 185 This function sets the face associated with @var{annotation} to | |
| 186 @var{face}. | |
| 187 @end defun | |
| 188 | |
| 189 @defun annotation-layout annotation | |
| 190 This function returns the layout policy of @var{annotation}. | |
| 191 @end defun | |
| 192 | |
| 193 @defun set-annotation-layout annotation layout | |
| 194 This function sets the layout policy of @var{annotation} to | |
| 195 @var{layout}. | |
| 196 @end defun | |
| 197 | |
| 198 @defun annotation-side annotation | |
| 199 This function returns the side of the buffer that @var{annotation} is | |
| 200 displayed on. Return value is a symbol, either @code{left} or | |
| 201 @code{right}. | |
| 202 @end defun | |
| 203 | |
| 204 @defun annotation-data annotation | |
| 205 This function returns the data associated with @var{annotation}. | |
| 206 @end defun | |
| 207 | |
| 208 @defun set-annotation-data annotation data | |
| 209 This function sets the data field of @var{annotation} to @var{data}. | |
| 210 @var{data} is returned. | |
| 211 @end defun | |
| 212 | |
| 213 @defun annotation-action annotation | |
| 214 This function returns the action associated with @var{annotation}. | |
| 215 @end defun | |
| 216 | |
| 217 @defun set-annotation-action annotation action | |
| 218 This function sets the action field of @var{annotation} to @var{action}. | |
| 219 @var{action} is returned.. | |
| 220 @end defun | |
| 221 | |
| 222 @defun annotation-menu annotation | |
| 223 This function returns the menu associated with @var{annotation}. | |
| 224 @end defun | |
| 225 | |
| 226 @defun set-annotation-menu annotation menu | |
| 227 This function sets the menu associated with @var{annotation} to | |
| 228 @var{menu}. This menu will be displayed when the right mouse button is | |
| 229 pressed over the annotation. | |
| 230 @end defun | |
| 231 | |
| 232 @defun annotation-visible annotation | |
| 233 This function returns @code{t} if there is enough available space to | |
| 234 display @var{annotation}, @code{nil} otherwise. | |
| 235 @end defun | |
| 236 | |
| 237 @defun annotation-width annotation | |
| 238 This function returns the width of @var{annotation} in pixels. | |
| 239 @end defun | |
| 240 | |
| 241 @defun hide-annotation annotation | |
| 242 This function removes @var{annotation}'s glyph, making it invisible. | |
| 243 @end defun | |
| 244 | |
| 245 @defun reveal-annotation annotation | |
| 246 This function restores @var{annotation}'s glyph, making it visible. | |
| 247 @end defun | |
| 248 | |
|
5791
9fae6227ede5
Silence texinfo 5.2 warnings, primarily by adding next, prev, and up
Jerry James <james@xemacs.org>
parents:
444
diff
changeset
|
249 @node Locating Annotations, Margin Primitives, Annotation Properties, Annotations |
| 428 | 250 @section Locating Annotations |
| 251 | |
| 252 @defun annotations-in-region start end buffer | |
| 253 This function returns a list of all annotations in @var{buffer} which | |
| 254 are between @var{start} and @var{end} inclusively. | |
| 255 @end defun | |
| 256 | |
| 257 @defun annotations-at &optional position buffer | |
| 258 This function returns a list of all annotations at @var{position} in | |
| 259 @var{buffer}. If @var{position} is @code{nil} point is used. If | |
| 260 @var{buffer} is @code{nil} the current buffer is used. | |
| 261 @end defun | |
| 262 | |
| 263 @defun annotation-list &optional buffer | |
| 264 This function returns a list of all annotations in @var{buffer}. If | |
| 265 @var{buffer} is @code{nil}, the current buffer is used. | |
| 266 @end defun | |
| 267 | |
| 268 @defun all-annotations | |
| 269 This function returns a list of all annotations in all buffers in | |
| 270 existence. | |
| 271 @end defun | |
| 272 | |
|
5791
9fae6227ede5
Silence texinfo 5.2 warnings, primarily by adding next, prev, and up
Jerry James <james@xemacs.org>
parents:
444
diff
changeset
|
273 @node Margin Primitives, Annotation Hooks, Locating Annotations, Annotations |
| 428 | 274 @section Margin Primitives |
| 275 @cindex margin width | |
| 276 | |
| 277 The margin widths are controllable on a buffer-local, window-local, | |
| 278 frame-local, device-local, or device-type-local basis through the | |
| 279 use of specifiers. @xref{Specifiers}. | |
| 280 | |
| 281 @defvr Specifier left-margin-width | |
| 282 This is a specifier variable controlling the width of the left outside | |
| 283 margin, in characters. Use @code{set-specifier} to change its value. | |
| 284 @end defvr | |
| 285 | |
| 286 @defvr Specifier right-margin-width | |
| 287 This is a specifier variable controlling the width of the right outside | |
| 288 margin, in characters. Use @code{set-specifier} to change its value. | |
| 289 @end defvr | |
| 290 | |
| 291 @defvr Specifier use-left-overflow | |
| 292 If non-@code{nil}, use the left outside margin as extra whitespace when | |
| 293 displaying @code{whitespace} and @code{inside-margin} annotations. | |
| 294 Defaults to @code{nil}. This is a specifier variable; use | |
| 295 @code{set-specifier} to change its value. | |
| 296 @end defvr | |
| 297 | |
| 298 @defvr Specifier use-right-overflow | |
| 299 If non-@code{nil}, use the right outside margin as extra whitespace when | |
| 300 displaying @code{whitespace} and @code{inside-margin} annotations. | |
| 301 Defaults to @code{nil}. This is a specifier variable; use | |
| 302 @code{set-specifier} to change its value. | |
| 303 @end defvr | |
| 304 | |
| 305 @defun window-left-margin-pixel-width &optional window | |
| 306 This function returns the width in pixels of the left outside margin of | |
| 307 @var{window}. If @var{window} is @code{nil}, the selected window is | |
| 308 assumed. | |
| 309 @end defun | |
| 310 | |
| 311 @defun window-right-margin-pixel-width &optional window | |
| 312 This function returns the width in pixels of the right outside margin of | |
| 313 @var{window}. If @var{window} is @code{nil}, the selected window is | |
| 314 assumed. | |
| 315 @end defun | |
| 316 | |
| 317 The margin colors are controlled by the faces @code{left-margin} and | |
| 318 @code{right-margin}. These can be set using the X resources | |
| 319 @code{Emacs.left-margin.background} and | |
| 320 @code{Emacs.left-margin.foreground}; likewise for the right margin. | |
| 321 | |
| 322 | |
|
5791
9fae6227ede5
Silence texinfo 5.2 warnings, primarily by adding next, prev, and up
Jerry James <james@xemacs.org>
parents:
444
diff
changeset
|
323 @node Annotation Hooks, , Margin Primitives, Annotations |
| 428 | 324 @section Annotation Hooks |
| 325 @cindex annotation hooks | |
| 326 | |
| 327 The following three hooks are provided for use with the marginal annotations: | |
| 328 | |
| 329 @table @code | |
| 330 @item before-delete-annotation-hook | |
| 331 This hook is called immediately before an annotation is destroyed. It | |
| 332 is passed a single argument, the annotation being destroyed. | |
| 333 | |
| 334 @item after-delete-annotation-hook | |
| 335 This normal hook is called immediately after an annotation is destroyed. | |
| 336 | |
| 337 @item make-annotation-hook | |
| 338 This hook is called immediately after an annotation is created. It is | |
| 339 passed a single argument, the newly created annotation. | |
| 340 @end table |