Mercurial > hg > xemacs-beta
annotate man/lispref/glyphs.texi @ 5908:6174848f3e6c
Use parse_integer() in read_atom(); support bases with ratios like integers
src/ChangeLog addition:
2015-05-08 Aidan Kehoe <kehoea@parhasard.net>
* data.c (init_errors_once_early):
Move the Qunsupported_type here from numbers.c, so it's available
when the majority of our types are not supported.
* general-slots.h: Add it here, too.
* number.c: Remove the definition of Qunsupported_type from here.
* lread.c (read_atom):
Check if the first character could reflect a rational, if so, call
parse_integer(), don't check the syntax of the other
characters. This allows us to accept the non-ASCII digit
characters too.
If that worked partially, but not completely, and the next char is
a slash, try to parse as a ratio.
If that fails, try isfloat_string(), but only if the first
character could plausibly be part of a float.
Otherwise, treat as a symbol.
* lread.c (read_rational):
Rename from read_integer. Handle ratios with the same radix
specification as was used for integers.
* lread.c (read1):
Rename read_integer in this function. Support the Common Lisp
#NNNrMMM syntax for parsing a number MMM of arbitrary radix NNN.
man/ChangeLog addition:
2015-05-08 Aidan Kehoe <kehoea@parhasard.net>
* lispref/numbers.texi (Numbers):
Describe the newly-supported arbitrary-base syntax for rationals
(integers and ratios). Describe that ratios can take the same base
specification as integers, something also new.
tests/ChangeLog addition:
2015-05-08 Aidan Kehoe <kehoea@parhasard.net>
* automated/lisp-reader-tests.el:
Check the arbitrary-base integer reader syntax support, just
added. Check the reader base support for ratios, just added.
Check the non-ASCII-digit support in the reader, just added.
| author | Aidan Kehoe <kehoea@parhasard.net> |
|---|---|
| date | Sat, 09 May 2015 00:40:57 +0100 |
| parents | 9fae6227ede5 |
| children |
| rev | line source |
|---|---|
| 428 | 1 @c -*-texinfo-*- |
| 2 @c This is part of the XEmacs Lisp Reference Manual. | |
| 3 @c Copyright (C) 1995, 1996 Ben Wing. | |
| 4 @c See the file lispref.texi for copying conditions. | |
| 5 @setfilename ../../info/glyphs.info | |
|
5791
9fae6227ede5
Silence texinfo 5.2 warnings, primarily by adding next, prev, and up
Jerry James <james@xemacs.org>
parents:
5715
diff
changeset
|
6 @node Glyphs, Annotations, Faces and Window-System Objects, Top |
| 428 | 7 @chapter Glyphs |
| 8 @cindex glyphs | |
| 9 | |
| 2182 | 10 A @dfn{glyph} is an object that is used for pixmaps, widgets, and |
| 442 | 11 images of all sorts, as well as for things that ``act'' like pixmaps, |
| 12 such as non-textual strings (@dfn{annotations}) displayed in a buffer or | |
| 13 in the margins. It is used in begin-glyphs and end-glyphs attached to | |
| 14 extents, marginal and textual annotations, overlay arrows | |
| 15 (@code{overlay-arrow-*} variables), toolbar buttons, mouse pointers, | |
| 16 frame icons, truncation and continuation markers, and the | |
| 2182 | 17 like. Basically, any place there is an image or something that acts |
| 18 like an image, there will be a glyph object representing it. | |
| 428 | 19 |
| 20 @defun glyphp object | |
| 21 This function returns @code{t} if @var{object} is a glyph. | |
| 22 @end defun | |
| 23 | |
| 24 @menu | |
| 2182 | 25 * Glyph Intro:: Glyphs are abstract image specifications. |
| 26 * Images:: Specifying the appearance of glyphs. | |
| 27 * Using Glyphs:: Creating and displaying glyphs. | |
| 28 * Manipulating Glyphs:: Getting and setting glyph properties. | |
| 29 * Glyph Examples:: Examples of how to work with glyphs. | |
| 30 @end menu | |
| 31 | |
| 32 | |
|
5791
9fae6227ede5
Silence texinfo 5.2 warnings, primarily by adding next, prev, and up
Jerry James <james@xemacs.org>
parents:
5715
diff
changeset
|
33 @node Glyph Intro, Images, Glyphs, Glyphs |
| 2182 | 34 @section Glyph Introduction |
| 35 | |
| 36 In XEmacs, ``glyph'' does @strong{not} refer to a single unit of textual | |
| 37 display (the XEmacs term for that is @dfn{rune}, and runes are confined | |
| 38 to the internal implementation of redisplay), but rather is an | |
| 39 object encapsulating a graphical element, such as an image or widget (an | |
| 40 active GUI element such as a button or text entry field; X11 calls this a | |
| 41 @dfn{widget}, while MS Windows uses the term @dfn{control}). | |
| 42 This graphical element could appear in a buffer, a margin, a gutter, or | |
| 43 a toolbar, or even externally to XEmacs as a mouse pointer or an icon, | |
| 44 for example. | |
| 45 | |
| 46 On the other hand, by contrast with GNU Emacs 21, an XEmacs glyph is | |
| 47 not ``just'' an image. The actual image that is displayed (as opposed | |
| 48 to its position or clipping) is defined by an ``image specifier'' object | |
| 49 contained within the glyph. The separation between an image specifier | |
| 50 object and a glyph object is made because the glyph includes other | |
| 51 properties than just the actual image: e.g. the face it is displayed in, | |
| 52 the alignment of the image, @emph{etc}. Also, an image specifier is | |
| 53 used in at least one place in XEmacs in lieu of a glyphs, namely the | |
| 54 backing pixmap of a face. | |
| 55 | |
| 56 An image specifier is used because glyphs often have locale-specific | |
| 57 semantics. The most important example is semantics determined by the | |
| 58 display device: you can't usefully display a JPEG on stdout, or a color | |
| 59 image on a monochrome display. But because the image property is a | |
| 60 specifier in XEmacs, you can specify that a given glyph appear as a | |
| 61 monochrome image on monochrome displays, a color image on color | |
| 62 displays, and as a string on TTYs. (Specifying a string for the | |
| 63 @code{tty} device locale would give behavior like the @code{ALT} | |
| 64 attribute of an @code{IMG} element in HTML.) Another is semantics | |
| 65 determined by the buffer or mode. (Unfortunately, currently there are | |
| 66 no compelling examples of this for glyphs.) | |
| 67 | |
| 68 All this means that only one global glyph needs to exist for a | |
| 69 particular purpose (e.g. the icon used to represent an iconified frame, | |
| 70 the mouse pointer used over particular areas of a frame, etc.). Often | |
| 71 you need not (and should not!) create your own glyph, but rather modify | |
| 72 an existing one. | |
| 73 | |
| 74 In working with glyphs it is important to keep in mind the distinction | |
| 75 between a locale and a domain. A @dfn{locale} is specified by the | |
| 76 programmer, and is an abstract link between a specification (for a | |
| 77 glyph, its visual appearance) and a displayable object. The displayable | |
| 78 object may be a buffer or a window, or an object containing buffers or | |
| 79 windows such as frame, device, or console. A @dfn{domain} is an actual | |
| 80 display context, which must be concrete enough to enable XEmacs to | |
| 81 identify the device type. (Buffers may be displayed in windows on | |
| 82 different devices, even simultaneously, so a buffer cannot be a domain. | |
| 83 Similarly, the global locale cannot be a domain.) @ref{Specifiers}, for | |
| 84 more information about specifier locales and domains. | |
| 85 | |
| 86 | |
|
5791
9fae6227ede5
Silence texinfo 5.2 warnings, primarily by adding next, prev, and up
Jerry James <james@xemacs.org>
parents:
5715
diff
changeset
|
87 @node Images, Using Glyphs, Glyph Intro, Glyphs |
| 2182 | 88 @section Images |
| 89 | |
| 90 @menu | |
| 2953 | 91 * Image Instantiators:: Specifying an image's appearance. |
| 2182 | 92 * Image Instantiator Conversion:: Lazy realization of graphics. |
| 93 * Image Instantiator Formats:: A catalog of image descriptors. | |
| 94 * Image Instances:: Classes of graphical objects. | |
| 428 | 95 @end menu |
| 96 | |
| 2182 | 97 |
|
5791
9fae6227ede5
Silence texinfo 5.2 warnings, primarily by adding next, prev, and up
Jerry James <james@xemacs.org>
parents:
5715
diff
changeset
|
98 @node Image Instantiators, Image Instantiator Conversion, Images, Images |
| 2953 | 99 @subsection Image Instantiators |
| 100 @cindex image instantiators | |
| 2182 | 101 |
| 2953 | 102 An @dfn{image instantiator} is a description of the actual graphical |
| 2182 | 103 realization of a glyph. For example, a typical image description is |
| 104 @emph{the file system path to a PNG file}. Since redisplay doesn't know | |
| 105 about files, and in any case the image may need to be manipulated | |
| 106 (@emph{e.g.}, a face's background pixmap must be clipped and tiled), the | |
| 107 PNG file must be converted internally to a window system bitmap or | |
| 108 pixmap object. We describe this process by writing that when XEmacs | |
| 2953 | 109 displays the image, it @dfn{instantiates} the image instantiator |
| 2182 | 110 into an @dfn{image instance}. Image instances are an internal object |
| 111 type (similar to font instances and color instances), describing how the | |
| 112 image appears in a particular domain. On the other hand, image | |
| 113 instantiators, which are just descriptions of how the image should | |
| 114 appear, are represented using Lisp strings or vectors. | |
| 115 | |
| 116 Furthermore the graphical realization will vary, and for some devices | |
| 2953 | 117 may not even be a bitmapped graphic. These variations may be |
| 118 controlled by the program by specifying different instantiators in | |
| 2182 | 119 different locales. This is implemented with an @dfn{image specifier}, |
| 120 a specifier whose specifications are image instantiators. | |
| 121 | |
| 122 Image specifiers are rarely if ever found by themselves. However, an | |
| 123 image specifier results from calling @code{glyph-image} on a glyph, or | |
| 124 retrieving the @code{background-pixmap} property of a face, and you can | |
| 125 check if some random object is an image specifier. | |
| 126 | |
| 127 @defun image-specifier-p object | |
| 128 This function returns non-@code{nil} if @var{object} is an image specifier. | |
| 129 @end defun | |
| 130 | |
| 131 @defun make-image-specifier spec-list | |
| 132 This function creates a new image specifier object and initializes it | |
| 133 according to @var{spec-list}. @xref{Specifiers}. | |
| 134 @end defun | |
| 135 | |
| 136 This function exists mainly for completeness. In practice, you rarely, | |
| 137 if ever, need to actually create an image specifier. Instead, they are | |
| 138 implicitly created by the initialization of glyphs and faces, and the | |
| 139 specifier member of these objects cannot be changed after | |
| 140 initialization; you may only set the specifications it contains. | |
| 141 | |
| 142 Image instantiators come in many formats: @code{xbm}, @code{xpm}, | |
| 143 @code{gif}, @code{jpeg}, etc. These denote the format of the data | |
| 144 describing the image. The resulting image instances also come in many | |
| 145 types---@code{mono-pixmap}, @code{color-pixmap}, @code{text}, | |
| 146 @code{pointer}, etc. This refers to the behavior of the image and the | |
| 147 sorts of places it can appear. (For example, a color-pixmap image has | |
| 148 fixed colors specified for it, while a mono-pixmap image comes in two | |
| 149 unspecified shades ``foreground'' and ``background'' that are determined | |
| 150 from the face of the glyph or surrounding text; a text image appears as | |
| 151 a string of text and has an unspecified foreground, background, and | |
| 152 font; a pointer image behaves like a mono-pixmap image but can only be | |
| 153 used as a mouse pointer [mono-pixmap images cannot be used as mouse | |
| 154 pointers]; etc.) | |
| 155 | |
| 156 It is important to keep the distinction between image instantiator | |
| 157 format and image instance type in mind. Typically, a given image | |
| 158 instantiator format can result in many different image instance types. | |
| 2953 | 159 For example, @code{xpm} can be instantiated as @code{color-pixmap}, |
| 2182 | 160 @code{mono-pixmap}, or @code{pointer}; whereas @code{cursor-font} can be |
| 2953 | 161 instantiated only as @code{pointer}. On the other hand, a particular image |
| 2182 | 162 instance type can be generated by many different image instantiator |
| 163 formats (e.g. @code{color-pixmap} can be generated by @code{xpm}, | |
| 164 @code{gif}, @code{jpeg}, etc.). | |
| 165 | |
| 166 @xref{Image Instances}, for a more detailed discussion of image | |
| 167 instance types. | |
| 168 | |
| 169 An image instantiator should be a string or a vector of the form | |
| 170 | |
| 171 @example | |
| 172 @code{[@var{format} @var{:keyword} @var{value} ...]} | |
| 173 @end example | |
| 174 | |
| 175 i.e. a format symbol followed by zero or more alternating keyword-value | |
| 176 pairs. | |
| 177 | |
| 178 The form of an instantiator can be checked with | |
| 179 @code{valid-instantiator-p} with a @var{TYPE} of @code{image}, | |
| 180 @ref{Specifier Validation Functions}. | |
| 181 | |
| 182 For a complete list of the format symbols and their usage, | |
| 183 @ref{Image Instantiator Formats}. | |
| 184 | |
| 185 If the instantiator is a string, it will be converted into a vector by | |
| 186 looking it up according to the specs in the | |
| 187 @code{console-type-image-conversion-list} for the console type of the | |
| 188 domain (usually a window; sometimes a frame or device) over which the | |
| 189 image is being instantiated. | |
| 190 | |
| 191 If the instantiator specifies data from a file, the data will be read in | |
| 192 at the time that the instantiator is added to the image specifier (which | |
| 193 may be well before the image is actually displayed), and the | |
| 194 instantiator will be converted into one of the inline-data forms, with | |
| 195 the filename retained using a @code{:file} keyword. This implies that | |
| 196 the file must exist when the instantiator is added to the image, but | |
| 197 does not need to exist at any other time (e.g. it may safely be a | |
| 198 temporary file). | |
| 199 | |
| 200 The available keywords are given below. Note that some keywords are | |
| 201 generally available (for example, the @code{:data} keyword may be used | |
| 202 with any format except @code{nothing}), while others are only available | |
| 203 for one format (@code{resource-id} is unique to the | |
| 204 @code{mswindows-resource} format). | |
| 205 | |
| 206 @table @code | |
| 207 @item :data | |
| 208 Inline image data. If available for a given format, it may be specified | |
| 209 directly by the program, or it may be a cache of file data previously | |
| 210 read. When present, it is used to instantiate the image in preference | |
| 211 to the file named by the @code{:file} property. | |
| 212 | |
| 213 The format of inline data is image-format-specific. For example, in | |
| 214 pixmap formats, the value should be a string, which is interpreted as an | |
| 215 octet-stream representing a bitmap or pixmap. But for text formats, | |
| 216 it's string containing the text to be displayed, and for resource | |
| 217 formats, it's a string containing the name of the resource. | |
| 218 | |
| 219 @item :file | |
| 220 Data contained in a file. The value is the name of this file. If both | |
| 221 @code{:data} and @code{:file} are specified, the image is created from | |
| 222 what is specified in @code{:data} and the string in @code{:file} becomes | |
| 223 the value of the @code{image-instance-file-name} function when applied | |
| 224 to the resulting image-instance. Note that there is nothing to stop a | |
| 225 program from changing either the @code{:file} or the @code{:data} | |
| 226 property, and there is no way to detect such mischief. This means that | |
| 227 the data will @emph{not} be automatically reread if you change the | |
| 228 @code{file} property; you must force it by removing the @code{:data} | |
| 229 property. | |
| 230 @c #### If there are ways to do this in-place, describe them. | |
| 231 (One way to do this is replacing the whole specification with a new | |
| 232 vector.) This keyword is not valid for instantiator formats | |
| 233 @code{nothing}, @code{string}, @code{formatted-string}, | |
| 234 @code{cursor-font}, @code{font}, and @code{autodetect}. | |
| 235 | |
| 236 @item :mask-data | |
| 237 Inline data for @code{xbm} and @code{xface}. This specifies a mask to | |
| 238 be used with the bitmap. Pixels which are not set in the mask will not | |
| 239 be written to the imaging device. The format is a list of width, | |
| 240 height, and bits, as for @code{:data}. | |
| 241 | |
| 242 @item :mask-file | |
| 243 For @code{xbm} and @code{xface}. This specifies a file containing the | |
| 244 mask data. If neither a mask file nor inline mask data is given for an | |
| 245 XBM image, and the XBM image comes from a file, XEmacs will look for a | |
| 246 mask file with the same name as the image file but with @samp{Mask} or | |
| 247 @samp{msk} appended. For example, if you specify the XBM file | |
| 248 @file{left_ptr} [usually located in @file{/usr/include/X11/bitmaps}], | |
| 249 the associated mask file @file{left_ptrmsk} will automatically be picked | |
| 250 up. | |
| 251 | |
| 252 @item :resource-id | |
| 253 Only for @code{mswindows-resource}. This must be either an integer | |
| 254 (which directly specifies a resource number) or a string. See the | |
| 255 description of @code{mswindows-resource} for valid strings. @xref{Image | |
| 256 Instantiator Formats}. | |
| 257 | |
| 258 @item :foreground | |
| 259 @itemx :background | |
| 260 For @code{xbm}, @code{xface}, @code{cursor-font}, and @code{font}. | |
| 261 These keywords allow you to explicitly specify foreground and background | |
| 262 colors. The value should be anything acceptable to | |
| 263 @code{make-color-instance}. This will cause an external format that | |
| 264 would by default be instantiated as a @code{mono-pixmap} to instead be | |
| 265 instantiated as a two-color color-pixmap. This can be used to override | |
| 266 the colors specified by a glyph's face, for example. If the image is | |
| 267 instantiated as a pointer, they specify its foreground and/or | |
| 268 background, instead of the defaults of black and white. | |
| 269 | |
| 270 @item :hotspot-x | |
| 271 @itemx :hotspot-y | |
| 272 For @code{xbm} and @code{xface}. These keywords specify a hotspot if | |
| 273 the image is instantiated as a @code{pointer}. Note that if the XBM | |
| 274 image file specifies a hotspot, it will automatically be picked up if no | |
| 275 explicit hotspot is given. | |
| 276 | |
| 277 @item :color-symbols | |
| 278 Only for @code{xpm}. This specifies an alist that maps strings that | |
| 279 specify symbolic color names to the actual color to be used for that | |
| 280 symbolic color (in the form of a string or a color-specifier object). | |
| 281 If this is not specified, the contents of @code{xpm-color-symbols} are | |
| 282 used to generate the alist. | |
| 283 | |
| 284 @item :resource-type | |
| 285 Only for @code{mswindows-resource}. This must be a symbol, either | |
| 286 @code{cursor}, @code{icon}, or @code{bitmap}, specifying the type of | |
| 287 resource to be retrieved. | |
| 288 | |
| 289 @item :face | |
| 290 For @code{inherit} and the widget formats. This specifies the face to | |
| 291 inherit from. For widgets this specifies the face to use for display. | |
| 292 It defaults to gui-element-face. | |
| 293 | |
| 294 @item :selected | |
| 295 @itemx :active | |
| 296 @itemx :suffix | |
| 297 @itemx :keys | |
| 298 @itemx :style | |
| 299 @itemx :filter | |
| 300 @itemx :config | |
| 301 @itemx :included | |
|
5715
68f8d295be49
Support :visible in menu specifications.
Jerry James <james@xemacs.org>
parents:
4708
diff
changeset
|
302 @itemx :visible |
| 2182 | 303 @itemx :key-sequence |
| 304 @itemx :accelerator | |
| 305 @itemx :label | |
| 306 @itemx :callback | |
| 307 These keywords, accepted as menu item specs, are also accepted by images | |
| 308 instantiated as @code{widget}. For their semantics, @ref{Menu Format}. | |
| 309 @end table | |
| 310 | |
| 311 | |
|
5791
9fae6227ede5
Silence texinfo 5.2 warnings, primarily by adding next, prev, and up
Jerry James <james@xemacs.org>
parents:
5715
diff
changeset
|
312 @node Image Instantiator Conversion, Image Instantiator Formats, Image Instantiators, Images |
| 2182 | 313 @subsection Image Instantiator Conversion |
| 314 @cindex image instantiator conversion | |
| 315 @cindex conversion of image instantiators | |
| 316 | |
| 317 Conversion is applied to image instantiators at the time they are added | |
| 318 to an image specifier or at the time they are passed to | |
| 319 @code{make-image-instance}. | |
| 320 | |
| 321 @defun set-console-type-image-conversion-list console-type list | |
| 322 This function sets the image-conversion-list for consoles of the given | |
| 323 @var{console-type}. The image-conversion-list specifies how image | |
| 324 instantiators that are strings should be interpreted. Each element of | |
| 325 the list should be a list of two elements (a regular expression string | |
| 326 and a vector) or a list of three elements (the preceding two plus an | |
| 327 integer index into the vector). The string is converted to the vector | |
| 328 associated with the first matching regular expression. If a vector | |
| 329 index is specified, the string itself is substituted into that position | |
| 330 in the vector. | |
| 331 | |
| 332 Note: The conversion above is applied when the image instantiator is | |
| 333 added to an image specifier, not when the specifier is actually | |
| 334 instantiated. Therefore, changing the image-conversion-list only affects | |
| 335 newly-added instantiators. Existing instantiators in glyphs and image | |
| 336 specifiers will not be affected. | |
| 337 @end defun | |
| 338 | |
| 339 @defun console-type-image-conversion-list console-type | |
| 340 This function returns the image-conversion-list for consoles of the given | |
| 341 @var{console-type}. | |
| 342 @end defun | |
| 343 | |
| 344 | |
|
5791
9fae6227ede5
Silence texinfo 5.2 warnings, primarily by adding next, prev, and up
Jerry James <james@xemacs.org>
parents:
5715
diff
changeset
|
345 @node Image Instantiator Formats, Image Instances, Image Instantiator Conversion, Images |
| 2182 | 346 @subsection Image Instantiator Formats |
| 347 @cindex image instantiator formats | |
| 348 | |
| 349 The @dfn{format} field of an image instantiator should be a symbol | |
| 350 denoting a valid format. Which formats are valid will depend on the | |
| 351 features (such as image decoding libraries) available, on platform | |
| 352 support (MS Windows resource IDs make no sense on other platforms), and | |
| 353 on the locale. | |
| 354 | |
| 355 @defun valid-image-instantiator-format-p format &optional locale | |
| 356 This function returns non-@code{nil} if @var{format} is a valid image | |
| 357 instantiator format. | |
| 358 | |
| 359 If @var{locale} is non-@code{nil} then the format is checked in that locale. | |
| 360 If @var{locale} is @code{nil} the current console is used. | |
| 361 | |
| 362 Note that the return value for many formats listed above depends on | |
| 363 whether XEmacs was compiled with support for that format. | |
| 364 @end defun | |
| 365 | |
| 366 @defun image-instantiator-format-list | |
| 367 This function returns a list of valid image-instantiator formats. | |
| 368 @end defun | |
| 369 | |
| 370 Here is a table of image-instantiator formats, giving the keywords that | |
| 371 are usable with each, and the kinds of instances that may result. | |
| 372 | |
| 373 @table @code | |
| 374 @item nothing | |
| 375 Don't display anything; no keywords are valid for this format. Can only be | |
| 2953 | 376 instantiated as @code{nothing}. |
| 2182 | 377 |
| 378 @item string | |
| 2953 | 379 Display this image as a text string. Can only be instantiated |
| 380 as @code{text}, although support for instantiation as @code{mono-pixmap} | |
| 2182 | 381 should be added. The valid keyword is @code{:data}. The value should |
| 382 be a string, and it is interpreted as a string of characters. | |
| 383 | |
| 384 @item formatted-string | |
| 385 Display this image as a text string with replaceable fields, | |
| 386 similar to a modeline format string. The valid keyword is @code{:data}. | |
| 387 The value should be a string, and it is interpreted as a string of | |
| 388 characters containing format sequences. | |
| 389 | |
| 390 Not currently implemented. | |
| 391 | |
| 392 @item xbm | |
| 393 An X bitmap; available only if X support was compiled into this XEmacs. | |
| 394 | |
| 395 If used in a buffer glyph, icon glyph, or face background pixmap, it | |
| 396 will be instantiated as @code{mono-pixmap} unless the @code{:foreground} | |
| 397 or @code{:background} keywords are present. In the latter case it will | |
| 398 be instantiated as @code{color-pixmap} with the two specified colors. | |
| 399 @c #### Check this. | |
| 400 (Probably if @code{:foreground} or @code{:background} is omitted, it | |
| 401 defaults to black or white respectively.) If used in a pointer glyph, | |
| 402 it will be instantiated as an @code{pointer}. | |
| 403 | |
| 404 The valid keywords and their values are | |
| 405 @table @code | |
| 406 @item :data | |
| 407 A list containing the height and width of the bitmap as integers, and | |
| 408 a string interpreted as a bit vector according to the X11 standard XBM | |
| 409 bitmap format, in that order. | |
| 410 @item :file | |
| 411 The name of a file containing standard XBM-format data. If it contains | |
| 412 a hotspot specification, it will be parsed and used if the hotspot is | |
| 413 not explicitly specified. | |
| 414 @item :mask-data | |
| 415 A list containing the height and width of the bitmap as integers, and | |
| 416 a string interpreted as a bit vector according to the X11 standard XBM | |
| 417 bitmap format, in that order. This bitmap is interpreted as the | |
| 418 clipping region for the bitmap contained in the @code{:data} property. | |
| 419 @item :mask-file | |
| 420 The name of a file containing standard XBM-format data. Interpreted as | |
| 421 the clipping region for the bitmap contained in the @code{:data} property. | |
| 422 @item :foreground | |
| 423 @itemx :background | |
| 424 These keywords allow you to explicitly specify foreground and background | |
| 425 colors. The values should be acceptable to @code{make-color-instance}. | |
| 426 @item :hotspot-x | |
| 427 @itemx :hotspot-y | |
| 428 Integers denoting the hotspot (mouse pointer position), with (0,0) at | |
| 429 the top left corner. If given, these override any specification in the | |
| 430 XBM file. | |
| 431 @end table | |
| 432 | |
| 433 @item xpm | |
| 434 An XPM pixmap; only available if XPM support was compiled into this XEmacs. | |
| 435 | |
| 2953 | 436 Can be instantiated as @code{color-pixmap}, @code{mono-pixmap}, or |
| 2182 | 437 @code{pointer}. |
| 438 | |
| 439 XPM is an add-on library for X that was designed to rectify the | |
| 440 shortcomings of the XBM format. Many icons and labels used in the | |
| 441 XEmacs GUI are still distributed in XPM format (although we are moving | |
| 442 to standardize on the PNG format). It is therefore highly desirable | |
| 443 that XPM be available in your XEmacs. | |
| 444 | |
| 445 Most implementations of X include the XPM library as a standard part. | |
| 446 If your vendor does not, it is highly recommended that you download it | |
| 447 and install it. You can get it from the XEmacs FTP site and mirrors, as | |
| 448 well as from most sites that distribute X11. | |
| 449 | |
| 450 The valid keywords and their values are | |
| 451 @table @code | |
| 452 @item :data | |
| 453 A string interpreted as the contents of a standard XPM file. | |
| 454 @item :file | |
| 455 The name of a file containing standard XPM-format data. If it contains | |
| 456 a hotspot specification, it will be parsed and used if the hotspot is | |
| 457 not explicitly specified. | |
| 458 @c #### Does XPM provide for a hotspot? | |
| 459 @item :hotspot-x | |
| 460 @itemx :hotspot-y | |
| 461 Integers denoting the hotspot (mouse pointer position), with (0,0) at | |
| 462 the top left corner. If given, these override any specification in the | |
| 463 XBM file. | |
| 464 @c #### Check this. | |
| 465 (This may not be true. The original documentation doesn't mention them | |
| 466 in connection with XPM, but a pointer needs a hotspot.) | |
| 467 @item :color-symbols | |
| 468 An alist that maps the one- or two-character strings that specify | |
| 469 symbolic color names in the XPM file to the actual color to be used for | |
| 470 that symbolic color (in the form of a string acceptable as a color | |
| 471 instantiator, @ref{Color Specifiers}, or a color-specifier object). | |
| 472 If this is not specified, the contents of @code{xpm-color-symbols} are | |
| 473 used to generate the alist. | |
| 474 @end table | |
| 475 | |
| 476 @item xface | |
| 477 An X-Face bitmap, used to encode people's faces in e-mail messages; | |
| 478 only available if X-Face support was compiled into this XEmacs. | |
| 479 | |
| 2953 | 480 Will be instantiated as @code{mono-pixmap}, @code{color-pixmap}, or |
| 2182 | 481 @code{pointer}, depending on the target instance type and the presence |
| 482 of color keywords. | |
| 483 | |
| 484 The valid keywords and their values are | |
| 485 @table @code | |
| 486 @item :data | |
| 487 A list containing the height and width of the bitmap as integers, and | |
| 488 a string interpreted as a bit vector according to the X11 standard XBM | |
| 489 bitmap format, in that order. | |
| 490 @item :file | |
| 491 The name of a file containing standard XBM-format data. If it contains | |
| 492 a hotspot specification, it will be parsed and used if the hotspot is | |
| 493 not explicitly specified. | |
| 494 @item :mask-data | |
| 495 A list containing the height and width of the bitmap as integers, and | |
| 496 a string interpreted as a bit vector according to the X11 standard XBM | |
| 497 bitmap format, in that order. This bitmap is interpreted as the | |
| 498 clipping region for the bitmap contained in the @code{:data} property. | |
| 499 @item :mask-file | |
| 500 The name of a file containing standard XBM-format data. Interpreted as | |
| 501 the clipping region for the bitmap contained in the @code{:data} property. | |
| 502 @item :foreground | |
| 503 @itemx :background | |
| 504 These keywords allow you to explicitly specify foreground and background | |
| 505 colors. The values should be acceptable to @code{make-color-instance}. | |
| 506 @item :hotspot-x | |
| 507 @itemx :hotspot-y | |
| 508 Integers denoting the hotspot (mouse pointer position), with (0,0) at | |
| 509 the top left corner. If given, these override any specification in the | |
| 510 XBM file. | |
| 511 @end table | |
| 512 | |
| 513 @item gif | |
| 514 @itemx jpeg | |
| 515 @itemx png | |
| 516 @itemx tiff | |
| 517 These are GIF87- or GIF89-format, JPEG-format, PNG/GIF24-format, and | |
| 518 TIFF-format images, respectively. They are available only if | |
|
4708
1cecc3e9f0a0
Use giflib or libungif to provide GIF support, instead of using internal
Jerry James <james@xemacs.org>
parents:
2953
diff
changeset
|
519 appropriate decoding support was built into XEmacs. If you have |
|
1cecc3e9f0a0
Use giflib or libungif to provide GIF support, instead of using internal
Jerry James <james@xemacs.org>
parents:
2953
diff
changeset
|
520 development support (both the libraries and the relevant C header files) |
|
1cecc3e9f0a0
Use giflib or libungif to provide GIF support, instead of using internal
Jerry James <james@xemacs.org>
parents:
2953
diff
changeset
|
521 available when XEmacs is built, the JPEG, PNG, GIF, and TIFF libraries |
|
1cecc3e9f0a0
Use giflib or libungif to provide GIF support, instead of using internal
Jerry James <james@xemacs.org>
parents:
2953
diff
changeset
|
522 will automatically be detected (in the ``usual places'') and linked into |
|
1cecc3e9f0a0
Use giflib or libungif to provide GIF support, instead of using internal
Jerry James <james@xemacs.org>
parents:
2953
diff
changeset
|
523 the build. |
| 2182 | 524 |
| 525 Note that PNG is the standard format for images distributed with XEmacs, | |
| 526 so it is highly recommended that PNG support be built in. | |
| 527 | |
| 2953 | 528 All of these instantiators will be instantiated as @code{color-pixmap}. |
| 2182 | 529 |
| 530 The valid keywords and their values are | |
| 531 @table @code | |
| 532 @item :data | |
| 533 A string interpreted as the contents of a file containing data in the | |
| 534 appropriate standard format. | |
| 535 @item :file | |
| 536 The name of a file containing standard-format data. | |
| 537 @end table | |
| 538 | |
| 539 @item cursor-font | |
| 540 Most window systems provide a set of standard cursors, which in X11 is | |
| 2953 | 541 called a cursor font. Can only be instantiated as @code{pointer}. This |
| 2182 | 542 should probably be fixed. |
| 543 | |
| 544 The valid keyword is @code{:data}. Its value should be a string | |
| 545 containing one of the standard cursor-font names, such as @samp{watch} | |
| 546 or @samp{right_ptr} under X. More specifically, in the X Window System | |
| 547 it may be any of the standard cursor names from appendix B of the Xlib | |
| 548 manual, provided in the file @file{<X11/cursorfont.h>} by most | |
| 549 distributions, minus the @samp{XC_} prefix. For MS Windows, use | |
| 550 @code{mswindows-resource} instantiator format, not @code{cursor-font}. | |
| 551 Other window systems may have different lists. | |
| 552 | |
| 553 @item font | |
| 554 A glyph from a font; i.e. the name of a font, and glyph index into it | |
| 555 of the form @samp{@var{font} fontname index [[mask-font] mask-index]}. | |
| 556 Only if X support was compiled into this XEmacs. Currently can only be | |
| 2953 | 557 instantiated as @code{pointer}. This should probably be fixed. |
| 2182 | 558 @c #### The above description is not very helpful, so it's not obvious |
| 559 @c how to instantiate a font image. | |
| 560 | |
| 561 @item mswindows-resource | |
| 562 An MS Windows pointer resource. Specifies a resource to retrieve | |
| 563 directly from the system (an OEM resource) or from a file, particularly | |
| 2953 | 564 an executable file. Can be instantiated as @code{pointer} or |
| 2182 | 565 @code{color-pixmap}. |
| 566 | |
| 567 The valid keywords and their values are | |
| 568 | |
| 569 @table @code | |
| 570 @item :resource-type | |
| 571 A string naming the type (@code{cursor}, @code{bitmap}, or @code{icon}) | |
| 572 of the resource. Required. | |
| 573 @item :file | |
| 574 A string containing the name of the file containing the resource (often | |
| 575 an executable). If a system resource, @code{:file} should be omitted. | |
| 576 @item :resource-id | |
| 577 A string containing the name of a resource. Required if @code{:file} | |
| 578 is not specified. | |
| 579 | |
| 580 This must be either an integer (which directly specifies a resource | |
| 581 number) or a string. Valid strings are | |
| 582 | |
| 583 For bitmaps: | |
| 584 | |
| 585 "close", "uparrow", "dnarrow", "rgarrow", "lfarrow", | |
| 586 "reduce", "zoom", "restore", "reduced", "zoomd", | |
| 587 "restored", "uparrowd", "dnarrowd", "rgarrowd", "lfarrowd", | |
| 588 "mnarrow", "combo", "uparrowi", "dnarrowi", "rgarrowi", | |
| 589 "lfarrowi", "size", "btsize", "check", "checkboxes", and | |
| 590 "btncorners". | |
| 591 | |
| 592 For cursors: | |
| 593 | |
| 594 "normal", "ibeam", "wait", "cross", "up", "sizenwse", | |
| 595 "sizenesw", "sizewe", "sizens", "sizeall", and "no". | |
| 596 | |
| 597 For icons: | |
| 598 | |
| 599 "sample", "hand", "ques", "bang", "note", and "winlogo". | |
| 600 @end table | |
| 601 | |
| 602 @item subwindow | |
| 2953 | 603 An embedded windowing system window. Can only be instantiated as |
| 2182 | 604 @code{subwindow}. Not implemented. |
| 605 @c #### Check status of subwindows ... I thought Andy implemented them. | |
| 606 | |
| 607 @item button | |
| 608 A button widget; either a push button, radio button or toggle button. | |
| 2953 | 609 Can only be instantiated as @code{widget}. |
| 2182 | 610 |
| 611 @item combo-box | |
| 612 A drop list of selectable items in a widget, for editing text. | |
| 2953 | 613 Can only be instantiated as @code{widget}. |
| 2182 | 614 |
| 615 @item edit-field | |
| 2953 | 616 A text editing widget. Can only be instantiated as @code{widget}. |
| 2182 | 617 |
| 618 @item label | |
| 2953 | 619 A static, text-only, widget; for displaying text. Can only be instantiated |
| 2182 | 620 as @code{widget}. |
| 621 | |
| 622 @item layout | |
| 623 A widget for controlling the positioning of children underneath it. | |
| 624 Through the use of nested layouts, a widget hierarchy can be created | |
| 625 which can have the appearance of any standard dialog box or similar | |
| 626 arrangement; all of this is counted as one @dfn{glyph} and could appear | |
| 2953 | 627 in many of the places that expect a single glyph. Can only be instantiated |
| 2182 | 628 as @code{widget}. |
| 629 | |
| 630 @item native-layout | |
| 631 The native version of a layout widget. | |
| 2953 | 632 Can only be instantiated as @code{widget}. |
| 2182 | 633 |
| 634 @item progress-gauge | |
| 2953 | 635 A sliding widget, for showing progress. Can only be instantiated as |
| 2182 | 636 @code{widget}. |
| 637 | |
| 638 @item tab-control | |
| 2953 | 639 A tab widget; a series of user selectable tabs. Can only be instantiated |
| 2182 | 640 as @code{widget}. |
| 641 | |
| 2297 | 642 The required keyword is @code{:items}. Its value should be a list of |
| 643 vectors, whose first element is a string, the second element is a | |
| 644 callback (a Lisp expression to be eval'ed), and the remaining elements | |
| 645 are key-value pairs. The most important keyword is @code{:selected} (a | |
| 646 Boolean); exactly one of the elements should have a value of @code{t} | |
| 647 for the @code{:selected} property. Other keywords accepted include | |
| 648 @code{:descriptor} (a string), @code{:face} (a symbol naming a face), | |
| 649 @code{:orientation} (a symbol, one of @code{top}, @code{center}, | |
| 650 @code{bottom}, @code{left}, or @code{right}), and @code{:pixel-width} | |
| 651 and @code{:pixel-height} (positive integers). | |
| 652 | |
| 653 (The above is incomplete and may be inaccurate.) | |
| 654 | |
| 2182 | 655 @item tree-view |
| 2953 | 656 A folding widget. Can only be instantiated as @code{widget}. |
| 2182 | 657 |
| 658 @item scrollbar | |
| 2953 | 659 A scrollbar widget. Can only be instantiated as @code{widget}. |
| 2182 | 660 |
| 661 @item autodetect | |
| 662 XEmacs tries to guess what format the data is in. If X support exists, | |
| 663 the data string will be checked to see if it names a filename. If so, | |
| 664 and this filename contains XBM or XPM data, the appropriate sort of | |
| 665 pixmap or pointer will be created. [This includes picking up any | |
| 666 specified hotspot or associated mask file.] Otherwise, if @code{pointer} | |
| 667 is one of the allowable image-instance types and the string names a | |
| 668 valid cursor-font name, the image will be created as a pointer. | |
| 669 Otherwise, the image will be displayed as text. If no X support exists, | |
| 670 the image will always be displayed as text. | |
| 671 | |
| 672 @item inherit | |
| 673 Inherit from the background-pixmap property of a face. Can only be | |
| 2953 | 674 instantiated as @code{mono-pixmap}. |
| 2182 | 675 @end table |
| 676 | |
| 677 There are two convenience variables for use with the XBM and XPM image | |
| 678 formats. | |
| 679 | |
| 680 @defvar xpm-color-symbols | |
| 681 This variable holds definitions of logical color-names used when reading | |
| 682 XPM files. Elements of this list should be of the form | |
| 683 @code{(@var{color-name} @var{form-to-evaluate})}. The @var{color-name} | |
| 684 should be a string, which is the name of the color to define; the | |
| 685 @var{form-to-evaluate} should evaluate to a color specifier object, or a | |
| 686 string to be passed to @code{make-color-instance} (@pxref{Colors}). If | |
| 687 a loaded XPM file references a symbolic color called @var{color-name}, | |
| 688 it will display as the computed color instead. | |
| 689 | |
| 690 The default value of this variable defines the logical color names | |
| 691 @samp{"foreground"} and @samp{"background"} to be the colors of the | |
| 692 @code{default} face. | |
| 693 @end defvar | |
| 694 | |
| 695 @defvar x-bitmap-file-path | |
| 696 A list of the directories in which X bitmap files may be found. If @code{nil}, | |
| 697 this is initialized from the @samp{"*bitmapFilePath"} resource. This is | |
| 698 used by the @code{make-image-instance} function (however, note that if | |
| 699 the environment variable @samp{XBMLANGPATH} is set, it is consulted | |
| 700 first). | |
| 701 @end defvar | |
| 702 | |
| 703 | |
|
5791
9fae6227ede5
Silence texinfo 5.2 warnings, primarily by adding next, prev, and up
Jerry James <james@xemacs.org>
parents:
5715
diff
changeset
|
704 @node Image Instances, , Image Instantiator Formats, Images |
| 2182 | 705 @subsection Image Instances |
| 706 @cindex image instances | |
| 707 | |
| 708 Image-instance objects encapsulate the way a particular image (pixmap, | |
| 709 etc.) is displayed on a particular device. | |
| 710 | |
| 711 In most circumstances, you do not need to directly create image | |
| 712 instances; use a glyph instead. However, it may occasionally be useful | |
| 713 to explicitly create image instances, if you want more control over the | |
| 714 instantiation process. | |
| 715 | |
| 716 @defun image-instance-p object | |
| 717 This function returns non-@code{nil} if @var{object} is an image instance. | |
| 718 @end defun | |
| 719 | |
| 720 @menu | |
| 2953 | 721 * Image Instance Types:: Each image instance has a particular type. |
| 2182 | 722 * Image Instance Functions:: Functions for working with image instances. |
| 723 @end menu | |
| 724 | |
| 725 | |
|
5791
9fae6227ede5
Silence texinfo 5.2 warnings, primarily by adding next, prev, and up
Jerry James <james@xemacs.org>
parents:
5715
diff
changeset
|
726 @node Image Instance Types, Image Instance Functions, Image Instances, Image Instances |
| 2182 | 727 @subsubsection Image Instance Types |
| 728 @cindex image instance types | |
| 729 | |
| 730 Image instances come in a number of different types. The type | |
| 731 of an image instance specifies the nature of the image: Whether | |
| 732 it is a text string, a mono pixmap, a color pixmap, etc. | |
| 733 | |
| 734 The valid image instance types are | |
| 735 | |
| 736 @table @code | |
| 737 @item nothing | |
| 738 Nothing is displayed. | |
| 739 | |
| 740 @item text | |
| 741 Displayed as text. The foreground and background colors and the | |
| 742 font of the text are specified independent of the pixmap. Typically | |
| 743 these attributes will come from the face of the surrounding text, | |
| 744 unless a face is specified for the glyph in which the image appears. | |
| 745 | |
| 746 @item mono-pixmap | |
| 747 Displayed as a mono pixmap (a pixmap with only two colors where the | |
| 748 foreground and background can be specified independent of the pixmap; | |
| 749 typically the pixmap assumes the foreground and background colors of | |
| 750 the text around it, unless a face is specified for the glyph in which | |
| 751 the image appears). | |
| 752 @item color-pixmap | |
| 753 | |
| 754 Displayed as a color pixmap. | |
| 755 | |
| 756 @item pointer | |
| 757 Used as the mouse pointer for a window. | |
| 758 | |
| 759 @item subwindow | |
| 760 A child window that is treated as an image. This allows (e.g.) | |
| 761 another program to be responsible for drawing into the window. | |
| 762 Not currently implemented. | |
| 763 @c #### Check status of subwindows ... I thought Andy implemented them. | |
| 764 | |
| 765 @item widget | |
| 766 An active GUI element implemented as a ``widget'' or ``control'' of the | |
| 767 underlying window system. | |
| 768 @end table | |
| 769 | |
| 770 The following functions are used to check whether an image instance type | |
| 771 is valid in the running XEmacs. | |
| 772 | |
| 773 @defun valid-image-instance-type-p type | |
| 774 This function returns non-@code{nil} if @var{type} is a valid image | |
| 775 instance type. | |
| 776 @end defun | |
| 777 | |
| 778 @defun image-instance-type-list | |
| 779 This function returns a list of the valid image instance types. | |
| 780 @end defun | |
| 781 | |
| 782 The following functions are used to determine the type of an image | |
| 783 instance. | |
| 784 | |
| 785 @defun image-instance-type image-instance | |
| 786 Return the type of the given image instance. The return | |
| 787 value will be one of @code{nothing}, @code{text}, @code{mono-pixmap}, | |
| 788 @code{color-pixmap}, @code{pointer}, @code{subwindow}, or @code{widget}. | |
| 789 @c #### Check status of subwindows ... I thought Andy implemented them. | |
| 790 @end defun | |
| 791 | |
| 792 @defun text-image-instance-p object | |
| 793 Return non-@code{nil} if @var{object} is an image instance of type | |
| 794 @code{text}. | |
| 795 @end defun | |
| 796 | |
| 797 @defun mono-pixmap-image-instance-p object | |
| 798 Return non-@code{nil} if @var{object} is an image instance of type | |
| 799 @code{mono-pixmap}. | |
| 800 @end defun | |
| 801 | |
| 802 @defun color-pixmap-image-instance-p object | |
| 803 Return non-@code{nil} if @var{object} is an image instance of type | |
| 804 @code{color-pixmap}. | |
| 805 @end defun | |
| 806 | |
| 807 @defun pointer-image-instance-p object | |
| 808 Return non-@code{nil} if @var{object} is an image instance of type | |
| 809 @code{pointer}. | |
| 810 @end defun | |
| 811 | |
| 812 @defun subwindow-image-instance-p object | |
| 813 Return non-@code{nil} if @var{object} is an image instance of type | |
| 814 @code{subwindow}. | |
| 815 @c #### Check status of subwindows ... I thought Andy implemented them. | |
| 816 @end defun | |
| 817 | |
| 818 @defun nothing-image-instance-p object | |
| 819 Return non-@code{nil} if @var{object} is an image instance of type | |
| 820 @code{nothing}. | |
| 821 @end defun | |
| 822 | |
| 823 @defun widget-image-instance-p object | |
| 824 Return non-@code{nil} if @var{object} is an image instance of type | |
| 825 @code{widget}. | |
| 826 @end defun | |
| 827 | |
| 828 | |
|
5791
9fae6227ede5
Silence texinfo 5.2 warnings, primarily by adding next, prev, and up
Jerry James <james@xemacs.org>
parents:
5715
diff
changeset
|
829 @node Image Instance Functions, , Image Instance Types, Image Instances |
| 2182 | 830 @subsubsection Image Instance Functions |
| 831 | |
| 832 @defun make-image-instance data &optional domain dest-types noerror | |
| 833 This function creates a new image-instance object. | |
| 834 | |
| 835 @var{data} is an image instantiator, which describes the image | |
| 2953 | 836 (@pxref{Image Instantiators}). |
| 2182 | 837 |
| 838 @var{dest-types} should be a list of allowed image instance types that | |
| 839 can be generated. The @var{dest-types} list is unordered. If multiple | |
| 840 destination types are possible for a given instantiator, the ``most | |
| 841 natural'' type for the instantiator's format is chosen. These are | |
| 842 | |
| 843 @table @code | |
| 844 @item XBM | |
| 845 @c #### check xface | |
| 846 @itemx xface | |
| 847 @code{mono-pixmap}, then @code{color-pixmap}, then @code{pointer}. | |
| 848 | |
| 849 @item XPM | |
| 850 @itemx GIF | |
| 851 @itemx JPEG | |
| 852 @itemx PNG | |
| 853 @itemx TIFF | |
| 854 @code{color-pixmap}, then @code{mono-pixmap}, then @code{pointer}. | |
| 855 | |
| 856 @item string | |
| 857 @itemx formatted-string formats | |
| 858 @code{text}, then @code{mono-pixmap} (not currently implemented), then | |
| 859 @code{color-pixmap} (not currently implemented). | |
| 860 | |
| 861 @item mswindows-resource | |
| 862 For pointer resources, @code{pointer}. | |
| 863 | |
| 864 For the others, @code{color-pixmap}. | |
| 865 @end table | |
| 866 | |
| 867 @c #### So what? This is a reference manual, list them, you lazy bastard! | |
| 868 The other formats can only be instantiated as one type. | |
| 869 | |
| 870 If you want to control more specifically the order of the types into | |
| 871 which an image is instantiated, call @code{make-image-instance} | |
| 872 repeatedly until it succeeds, passing less and less preferred | |
| 873 destination types each time. | |
| 874 | |
| 875 If @var{dest-types} is omitted, all possible types are allowed. | |
| 876 | |
| 877 @var{domain} specifies the domain to which the image instance will be | |
| 878 attached. This domain is termed the @dfn{governing domain}. The type | |
| 879 of the governing domain depends on the image instantiator format. | |
| 880 (Although, more correctly, it should probably depend on the image | |
| 881 instance type.) For example, pixmap image instances are specific to a | |
| 882 device, but widget image instances are specific to a particular XEmacs | |
| 883 window because in order to display such a widget when two windows onto | |
| 884 the same buffer want to display the widget, two separate underlying | |
| 885 widgets must be created. (That's because a widget is actually a child | |
| 886 window-system window, and all window-system windows have a unique | |
| 887 existence on the screen.) This means that the governing domain for a | |
| 888 pixmap image instance will be some device (most likely, the only | |
| 889 existing device), whereas the governing domain for a widget image | |
| 890 instance will be some XEmacs window. | |
| 891 | |
| 892 If you specify an overly general @var{domain} (e.g. a frame when a | |
| 893 window was wanted), an error is signaled. If you specify an overly | |
| 894 specific @var{domain} (e.g. a window when a device was wanted), the | |
| 895 corresponding general domain is fetched and used instead. For | |
| 896 @code{make-image-instance}, it makes no difference whether you specify | |
| 897 an overly specific domain or the properly general domain derived from | |
| 898 it. However, it does matter when creating an image instance by | |
| 899 instantiating a specifier or glyph (e.g. with | |
| 900 @code{glyph-image-instance}), because the more specific domain causes | |
| 901 spec lookup to start there and proceed to more general domains. (It | |
| 902 would also matter when creating an image instance with an instantiator | |
| 903 format of @code{inherit}, but we currently disallow this.) | |
| 904 @c #### We should fix that. | |
| 905 | |
| 906 If omitted, @var{domain} defaults to the selected window. | |
| 907 | |
| 908 @var{noerror} controls what happens when the image cannot be generated. | |
| 909 If @code{nil}, an error message is generated. If @code{t}, no messages | |
| 910 are generated and this function returns @code{nil}. If anything else, a | |
| 911 warning message is generated and this function returns @code{nil}. | |
| 912 @end defun | |
| 913 | |
| 914 @defun colorize-image-instance image-instance foreground background | |
| 915 This function makes the image instance be displayed in the given | |
| 916 colors. Image instances come in two varieties: bitmaps, which are 1 | |
| 917 bit deep which are rendered in the prevailing foreground and background | |
| 918 colors; and pixmaps, which are of arbitrary depth (including 1) and | |
| 919 which have the colors explicitly specified. This function converts a | |
| 920 bitmap to a pixmap. If the image instance was a pixmap already, | |
| 921 nothing is done (and @code{nil} is returned). Otherwise @code{t} is | |
| 922 returned. | |
| 923 @end defun | |
| 924 | |
| 925 The following functions are | |
| 926 | |
| 927 @defun image-instance-name image-instance | |
| 928 This function returns the name of the given image instance. The name is | |
| 929 typically taken from the @code{:file} property of the instantiator if | |
| 930 present, otherwise from the @code{:data} property. | |
| 931 @end defun | |
| 932 | |
| 933 @defun image-instance-domain image-instance | |
| 934 Return the governing domain of the given @var{image-instance}. The | |
| 935 governing domain of an image instance is the domain that the image | |
| 936 instance is specific to. It is @emph{NOT} necessarily the domain that | |
| 937 was given to the call to @code{specifier-instance} that resulted in the | |
| 938 creation of this image instance. See @code{make-image-instance} for | |
| 939 more information on governing domains. | |
| 940 @end defun | |
| 941 | |
| 942 @defun image-instance-string image-instance | |
| 943 This function returns the string of the given image instance. This will | |
| 944 only be non-@code{nil} for text image instances. | |
| 945 @end defun | |
| 946 | |
| 947 @defun image-instance-file-name image-instance | |
| 948 This function returns the file name from which @var{image-instance} was | |
| 949 read, if known. | |
| 950 @end defun | |
| 951 | |
| 952 @defun image-instance-mask-file-name image-instance | |
| 953 This function returns the file name from which @var{image-instance}'s | |
| 954 mask was read, if known. | |
| 955 @end defun | |
| 956 | |
| 957 Pixmaps are considered to be three-dimensional. The height and width of | |
| 958 the pixel array that is displayed, and the color depth of its pixels, | |
| 959 are accessed with these functions. | |
| 960 | |
| 961 @defun image-instance-depth image-instance | |
| 962 This function returns the depth of the image instance. This is 0 for a | |
| 963 mono pixmap, or a positive integer for a color pixmap. | |
| 964 @end defun | |
| 965 | |
| 966 @defun image-instance-height image-instance | |
| 967 This function returns the height of the image instance, in pixels. | |
| 968 @end defun | |
| 969 | |
| 970 @defun image-instance-width image-instance | |
| 971 This function returns the width of the image instance, in pixels. | |
| 972 @end defun | |
| 973 | |
| 974 The hotspot is a point relative to the origin of the pixmap. When | |
| 975 an image is used as a mouse pointer, the hotspot is the point on the | |
| 976 image that sits over the location that the pointer points to. This is, | |
| 977 for example, the tip of the arrow or the center of the crosshairs. | |
| 978 | |
| 979 These functions access the coordinates of the hotspot. They simply | |
| 980 return @code{nil} for a non-pointer image instance. | |
| 981 | |
| 982 @defun image-instance-hotspot-x image-instance | |
| 983 This function returns the X coordinate of the image instance's hotspot, | |
| 984 if known. | |
| 985 @end defun | |
| 986 | |
| 987 @defun image-instance-hotspot-y image-instance | |
| 988 This function returns the Y coordinate of the image instance's hotspot, | |
| 989 if known. | |
| 990 @end defun | |
| 991 | |
| 992 Mono pixmaps and pointers may have their foreground and background | |
| 2953 | 993 colors set when instantiated. Use these functions to access color |
| 2182 | 994 information. |
| 995 | |
| 996 @defun image-instance-foreground image-instance | |
| 997 This function returns the foreground color of @var{image-instance}, if | |
| 998 applicable. This will be a color instance or @code{nil}. (It will only | |
| 999 be non-@code{nil} for colorized mono pixmaps and for pointers.) | |
| 1000 @end defun | |
| 1001 | |
| 1002 @defun image-instance-background image-instance | |
| 1003 This function returns the background color of @var{image-instance}, if | |
| 1004 applicable. This will be a color instance or @code{nil}. (It will only | |
| 1005 be non-@code{nil} for colorized mono pixmaps and for pointers.) | |
| 1006 @end defun | |
| 1007 | |
| 1008 | |
|
5791
9fae6227ede5
Silence texinfo 5.2 warnings, primarily by adding next, prev, and up
Jerry James <james@xemacs.org>
parents:
5715
diff
changeset
|
1009 @node Using Glyphs, Manipulating Glyphs, Images, Glyphs |
| 2182 | 1010 @section Using Glyphs |
| 1011 | |
| 1012 Glyph usage is unfortunately somewhat arcane. (For discussion of | |
| 1013 rationale, @ref{Glyphs,,,Internals}.) Because they are not ``text,'' | |
| 1014 they cannot be inserted directly into a buffer. Instead, they are | |
| 1015 values of properties of extents attached to buffers or strings, values | |
| 1016 of global variables such as mouse pointers, or as a component of a | |
| 1017 complex data structure such as a toolbar initializer. Although these | |
| 1018 uses could probably streamlined, each structure has its own | |
| 1019 requirements. Since glyphs are very flexible, it is possible to create | |
| 1020 applications like the @file{edit-toolbar} and @file{xpm-mode} libraries | |
| 1021 which display glyphs in a buffer (for reference while editing) that are | |
| 1022 normally used in a different context. | |
| 1023 | |
| 1024 Usage of glyphs can roughly be categorized as follows: | |
| 1025 | |
| 1026 @table @strong | |
| 1027 @item Buffer glyphs | |
| 1028 Glyphs that are inserted in a buffer may be used for their own sake (for | |
| 1029 example, image display in @file{w3}), as an accurate representation of | |
| 1030 text that can't be displayed in usual fonts (equation display in | |
| 1031 @file{preview-latex}), or as annotations (such as a marginal indication | |
| 1032 of a bookmark). Glyphs are attached to buffers via extents. | |
| 1033 | |
| 1034 @item Redisplay glyphs | |
| 1035 Glyphs can be used to create XEmacs-specific ``fonts''. For example, | |
| 1036 the character that indicates truncation of lines is implemented as the | |
| 1037 @code{truncation-glyph}. It is also possible to have XEmacs display a | |
| 1038 certain character using a custom glyph, via display tables. | |
| 1039 | |
| 1040 @item Frame glyphs | |
| 1041 Glyphs are used to control the appearance of various other components of | |
| 1042 the frame. They can be inserted in the modeline, the favicons are used | |
| 1043 in Web browsers. They are used to specify the labels on toolbar | |
| 1044 buttons. Finally, they can be inserted in the gutters. (The difference | |
| 1045 between a glyph inserted in a gutter and a marginal annotation is that | |
| 1046 the marginal annotation is tied to the text in the buffer. If the | |
| 1047 buffer line scrolls out of view, the marginal annotation will, as well. | |
| 1048 A gutter glyph does not move with the text.) | |
| 1049 | |
| 1050 Unfortunately, all these uses are special cases, and have their own | |
| 1051 APIs, in contrast to glyphs in a buffer. | |
| 1052 | |
| 1053 @item External glyphs | |
| 1054 External glyphs simply allow a consistent API for images. The images | |
| 1055 are then passed to external software such as the window system itself | |
| 1056 (mouse cursor shapes) and the window manager (icons to represent | |
| 1057 minimized windows). XEmacs has no role in managing their use. | |
| 1058 | |
| 1059 @item Subwindow and widget glyphs | |
| 1060 These do not constitute a context of use, but rather an important class of | |
| 1061 glyph types. The difference between these and other glyphs is that | |
| 1062 while their geometry is determined by XEmacs, their behavior is managed | |
| 1063 separately, by internal mechanisms in the case of widgets, and | |
| 1064 (possibly) by another process in the case of subwindows. | |
| 1065 @c #### Check status of subwindows ... I thought Andy implemented them. | |
| 1066 @end table | |
| 1067 | |
| 1068 Some simple concrete examples showing how to insert a glyph in a | |
| 1069 buffer are presented later. @ref{Glyph Examples}. | |
| 1070 | |
| 1071 ``Creating Glyphs'' explains how to create glyphs. Creating a glyph | |
| 1072 using @code{make-glyph} does not specify @emph{where} the glyph will be | |
| 1073 used, it only specifies @emph{what} the glyph will look like. The next | |
| 1074 four sections explain how to embed glyphs in different display | |
| 1075 contexts. Finally, the last two sections explain the special | |
| 1076 considerations of using glyphs whose behavior is not determined by the | |
| 1077 code creating them, but by the glyph itself (a ``widget'' in X11 or | |
| 1078 ``control'' in MS Windows or Aqua), or even by a separate process. | |
| 428 | 1079 |
| 1080 @menu | |
| 1081 * Creating Glyphs:: Creating new glyphs. | |
| 2182 | 1082 * Buffer Glyphs:: Annotations are glyphs that appear in a buffer. |
| 1083 * Redisplay Glyphs:: Glyphs controlling various redisplay functions. | |
| 1084 * Frame Glyphs:: Displaying glyphs in GUI components of the frame. | |
| 1085 * External Glyphs:: Icons and mouse pointers for the window system. | |
| 1086 * Native GUI Widgets:: Complex active elements treated as a single glyph. | |
| 1087 * Subwindows:: Externally-controlled subwindows in buffers. | |
| 1088 @c #### Check status of subwindows ... I thought Andy implemented them. | |
| 428 | 1089 @end menu |
| 1090 | |
|
5791
9fae6227ede5
Silence texinfo 5.2 warnings, primarily by adding next, prev, and up
Jerry James <james@xemacs.org>
parents:
5715
diff
changeset
|
1091 @node Creating Glyphs, Buffer Glyphs, Using Glyphs, Using Glyphs |
| 428 | 1092 @subsection Creating Glyphs |
| 1093 | |
| 1094 @defun make-glyph &optional spec-list type | |
| 1095 This function creates a new glyph object of type @var{type}. | |
| 1096 | |
| 2182 | 1097 The optional @var{spec-list} is used to initialize the glyph's image. |
| 1098 It can be any spec-list of @dfn{image instantiator} accepted by | |
| 1099 @code{canonicalize-spec-list}, @ref{Adding Specifications}. An | |
| 1100 individual image instantiator may be a string, which is converted to a | |
| 1101 vector according to @code{console-type-image-conversion-list}, or a | |
| 1102 vector. The vector's first element specifies the @emph{external} format | |
| 1103 of the data, such as a string, a PNG file, or an MS Windows resource. | |
| 1104 This is followed by properties (keyword-value pairs) specifying such | |
| 1105 information as the name of a file containing an image, or pixmap data | |
| 2953 | 1106 directly. @xref{Image Instantiators}. |
| 2182 | 1107 |
| 1108 The optional @var{type} specifies the type of the glyph. @var{type} | |
| 1109 should be one of @code{buffer} (used for glyphs in an extent, the | |
| 1110 modeline, the toolbar, or elsewhere in a frame), @code{pointer} (used | |
| 1111 for the mouse-pointer), or @code{icon} (used for a frame's icon), and | |
| 1112 defaults to @code{buffer}. | |
| 1113 @end defun | |
| 1114 | |
| 1115 @var{spec-list} is the initializer for the glyph's @code{image} | |
| 1116 property, which is an image specifier. (Note that @dfn{image} as used | |
| 1117 in the context of a glyph's @code{image} property or in the terms | |
| 1118 @dfn{image specifier}, @dfn{image instantiator}, or @dfn{image instance} | |
| 1119 does not refer to what people normally think of as an image (which in | |
| 1120 XEmacs is called a @dfn{pixmap}), but to any graphical element---a | |
| 1121 pixmap, a widget, or even a block of text, when used in the places that | |
| 1122 call for a glyph.) | |
| 1123 | |
| 1124 The most common form of @var{spec-list} is a single image instantiator. | |
| 1125 (@strong{Compatibility note:} in GNU Emacs 21, a string used to | |
| 1126 instantiate an image is interpreted as the name of an image file, which | |
| 1127 is searched for and instantiated.) The conversion controlled by | |
| 1128 @code{console-type-image-conversion-list} typically attempts to look up | |
| 1129 the string as a file name in XEmacs's data directory path, and if this | |
| 1130 fails, defaults to displaying the string as a text image instance | |
| 1131 (@emph{i.e.}. the string itself. | |
| 1132 | |
| 1133 Fine control of a particular specification is provided by using a vector | |
| 1134 as the image instantiator. More complicated instantiators allow lists | |
| 1135 of instantiators to be specified (which are tried in order), or mappings | |
| 1136 from locales to lists of instantiators, @emph{etc}. @xref{Specifiers}, | |
| 1137 for more information about specification formats. | |
| 1138 | |
| 1139 As well as using @var{spec-list} to initialize the glyph, you can set | |
| 1140 specifications using @code{set-glyph-image}. The glyph itself is not | |
| 1141 actually a specifier, but rather is an object containing an image | |
| 1142 specifier (as well as other properties seldom set by user code). | |
| 1143 Therefore, you cannot set or access specifications for the glyph's image | |
| 1144 by directly using @code{set-specifier}, @code{specifier-instance} or the | |
| 1145 like on the glyph; instead use them on @code{(glyph-image @var{glyph})} | |
| 1146 or use the convenience functions @code{set-glyph-image}, | |
| 1147 @code{glyph-image-instance}, and @code{glyph-image}. | |
| 428 | 1148 |
| 2182 | 1149 Glyph types reflect the fact that glyphs are used in contexts like |
| 1150 pointers and window manager icons, which are defined by external | |
| 1151 programs such as the window system or window manager. These require | |
| 1152 somewhat different @emph{internal} format, which is opaque to the user. | |
| 1153 | |
| 1154 It is extremely rare that you will ever have to specify a value for | |
| 1155 @var{type}, which should be one of @code{buffer} (used for glyphs in an | |
| 1156 extent, the modeline, the toolbar, or elsewhere in a buffer), | |
| 1157 @code{pointer} (used for the mouse-pointer), or @code{icon} (used for a | |
| 1158 frame's icon), and defaults to @code{buffer}. The only cases where it | |
| 1159 needs to be specified is when creating icon or pointer glyphs, and in | |
| 1160 both cases the necessary glyphs have already been created at startup and | |
| 1161 are accessed through the appropriate variables, | |
| 1162 e.g. @code{text-pointer-glyph} (or in general, any | |
| 1163 @samp{*-pointer-glyph}) and @code{frame-icon-glyph}. User code should | |
| 1164 never need to create @code{pointer} or @code{icon} glyphs. @xref{Glyph | |
| 1165 Types}. | |
| 1166 | |
| 1167 There are a few other glyph creation functions, normally used only | |
| 1168 internally or at XEmacs initialization. | |
| 1169 | |
| 1170 @defun make-glyph-internal &optional type | |
| 1171 This function creates a new, uninitialized glyph of type @var{type}. | |
| 1172 @end defun | |
| 1173 | |
| 1174 @defun make-pointer-glyph &optional spec-list | |
| 442 | 1175 |
| 2182 | 1176 Return a new @code{pointer-glyph} object with the specification list |
| 1177 @var{spec-list}. This function is equivalent to calling | |
| 1178 @code{make-glyph} with a @var{type} of @code{pointer}. | |
| 1179 @end defun | |
| 1180 | |
| 1181 @code{make-pointer-glyph} is normally used only by XEmacs initialization | |
| 1182 code. It is extremely unlikely that you will ever need to create a | |
| 1183 pointer glyph. Instead, you probably want to be calling | |
| 1184 @code{set-glyph-image} on an existing glyph, | |
| 1185 e.g. @code{text-pointer-glyph}. | |
| 1186 | |
| 1187 @defun make-icon-glyph &optional spec-list | |
| 1188 | |
| 1189 Return a new @code{icon-glyph} object with the specification list | |
| 1190 @var{spec-list}. This function is equivalent to calling | |
| 1191 @code{make-glyph} with a @var{type} of @code{icon}. | |
| 1192 @end defun | |
| 1193 | |
| 1194 @code{make-icon-glyph} is normally used only by XEmacs initialization | |
| 1195 code. It is extremely unlikely that you will ever need to create a icon | |
| 1196 glyph. Instead, you probably want to be calling @code{set-glyph-image} | |
| 1197 on the existing glyph, @code{frame-icon-glyph}. | |
| 1198 | |
| 1199 | |
|
5791
9fae6227ede5
Silence texinfo 5.2 warnings, primarily by adding next, prev, and up
Jerry James <james@xemacs.org>
parents:
5715
diff
changeset
|
1200 @node Buffer Glyphs, Redisplay Glyphs, Creating Glyphs, Using Glyphs |
| 2182 | 1201 @subsection Buffer Glyphs |
| 442 | 1202 |
| 1203 Creating a glyph using @code{make-glyph} does not specify @emph{where} | |
| 2182 | 1204 the glyph will be used, it only specifies @emph{what} the glyph will |
| 1205 look like. Once you have created a glyph, you specify where it will be | |
| 1206 used by attaching it to an extent as a @emph{begin-glyph} or | |
| 1207 @emph{end-glyph}. | |
| 442 | 1208 |
| 2182 | 1209 @table @code |
| 1210 @item buffer text | |
| 442 | 1211 To insert a glyph into a buffer, create an extent in the buffer and then |
| 1212 use @code{set-extent-begin-glyph} or @code{set-extent-end-glyph} to set | |
| 2182 | 1213 a glyph to be displayed at the corresponding edge of the extent. (It is |
| 442 | 1214 common to create zero-width extents for this purpose.) |
| 1215 | |
| 2182 | 1216 @item margins |
| 442 | 1217 To insert a glyph into the left or right margin of a buffer, first |
| 1218 make sure the margin is visible by setting a value for the specifiers | |
| 2182 | 1219 @code{left-margin-width} or @code{right-margin-width}. (Not strictly necessary |
| 1220 when using margin glyphs with layout policy @code{whitespace}.) Follow | |
| 1221 the same procedure above for inserting a glyph in a buffer, then | |
| 442 | 1222 set a non-default layout policy for the glyph using |
| 1223 @code{set-extent-begin-glyph-layout} or @code{set-extent-end-glyph-layout}. | |
| 1224 Alternatively, use the high-level annotations API (see | |
| 2182 | 1225 @code{make-annotation}). (In fact, you can also use the annotations |
| 442 | 1226 API for glyphs in a buffer, by setting a layout policy of @code{text}.) |
| 1227 | |
| 2182 | 1228 @end table |
| 1229 | |
| 1230 | |
|
5791
9fae6227ede5
Silence texinfo 5.2 warnings, primarily by adding next, prev, and up
Jerry James <james@xemacs.org>
parents:
5715
diff
changeset
|
1231 @node Redisplay Glyphs, Frame Glyphs, Buffer Glyphs, Using Glyphs |
| 2182 | 1232 @subsection Redisplay Glyphs |
| 1233 | |
| 1234 To use a glyph to control the shape of miscellaneous redisplay effects | |
| 1235 such as the truncation and continuation markers, set the appropriate | |
| 1236 existing glyph variables with @code{set-glyph-image}. See | |
| 1237 @code{continuation-glyph}, @code{control-arrow-glyph}, | |
| 1238 @code{hscroll-glyph}, @code{invisible-text-glyph}, | |
| 1239 @code{octal-escape-glyph}, and @code{truncation-glyph}. See also | |
| 1240 @code{overlay-arrow-string}, an odd redisplay leftover which can be set | |
| 1241 to a glyph you created, and will cause the glyph to be displayed on top | |
| 1242 of the text position specified in the marker stored in | |
| 1243 @code{overlay-arrow-position}. | |
| 1244 | |
| 1245 To use a glyph in a display table (i.e. to control the appearance of any | |
| 1246 individual character), create the appropriate character glyphs and then | |
| 1247 set a specification for the specifier @code{current-display-table}, | |
| 1248 which controls the appearance of characters. You can also set an | |
| 1249 overriding display table for use with text displayed in a particular | |
| 1250 face; see @code{set-face-display-table} and @code{make-display-table}. | |
| 1251 #### Note: Display tables do not currently support general Mule | |
| 1252 characters. They will be overhauled at some point to support this | |
| 1253 and to provide other features required under Mule. @ref{Display Tables}. | |
| 1254 | |
| 1255 Glyphs are not actually used as the background pixmaps of faces, but the | |
| 1256 API is similar. The | |
| 1257 background pixmap of a face is actually an image specifier -- probably | |
| 1258 the only place in XEmacs where an image specifier occurs outside of a | |
| 1259 glyph. If you would like to use a glyph's image as a background pixmap, | |
| 1260 you can extract it with @code{glyph-image}, and then add it to a face. | |
| 1261 @xref{Face Convenience Functions}. | |
| 1262 | |
| 1263 @defvr Glyph truncation-glyph | |
| 1264 This variable specifies what is displayed at the end of truncated lines. | |
| 1265 @end defvr | |
| 1266 | |
| 1267 @defvr Glyph continuation-glyph | |
| 1268 This variable specifies what is displayed at the end of wrapped lines. | |
| 1269 @end defvr | |
| 1270 | |
| 1271 @defvr Glyph octal-escape-glyph | |
| 1272 This variable specifies what to prefix character codes displayed in octal | |
| 1273 with. | |
| 1274 @end defvr | |
| 1275 | |
| 1276 @defvr Glyph hscroll-glyph | |
| 1277 This variable specifies what to display at the beginning of horizontally | |
| 1278 scrolled lines. | |
| 1279 @end defvr | |
| 1280 | |
| 1281 @defvr Glyph invisible-text-glyph | |
| 1282 This variable specifies what to use to indicate the presence of | |
| 1283 invisible text. This is the glyph that is displayed when an ellipsis is | |
| 1284 called for, according to @code{selective-display-ellipses} or | |
| 1285 @code{buffer-invisibility-spec}). Normally this is three dots (``...''). | |
| 1286 @end defvr | |
| 1287 | |
| 1288 @defvr Glyph control-arrow-glyph | |
| 1289 This variable specifies what to use as an arrow for control characters. | |
| 1290 @end defvr | |
| 1291 | |
| 1292 | |
|
5791
9fae6227ede5
Silence texinfo 5.2 warnings, primarily by adding next, prev, and up
Jerry James <james@xemacs.org>
parents:
5715
diff
changeset
|
1293 @node Frame Glyphs, External Glyphs, Redisplay Glyphs, Using Glyphs |
| 2182 | 1294 @subsection Frame Glyphs |
| 1295 | |
| 1296 There are also a number of special objects whose appearance is specified | |
| 1297 by a glyph. Most of these a global objects that you update with | |
| 1298 @code{set-glyph-image}, such as mouse pointers. Frame icons, toolbar | |
| 1299 button icons, and the modeline are the main non-text objects which | |
| 1300 accept glyphs as elements. | |
| 1301 | |
| 1302 @table @code | |
| 1303 @item modeline | |
| 2127 | 1304 A glyph may be displayed in the modeline by inserting the glyph as one |
| 1305 of the elements of the modeline format. (Unfortunately you can't | |
| 1306 currently put a begin glyph or end glyph on one of the modeline | |
| 1307 extents---they're ignored.) | |
| 442 | 1308 |
| 2182 | 1309 @item toolbar |
| 2127 | 1310 To insert a glyph into a toolbar, specify it as the icon part of a toolbar |
| 1311 button, which in turn must be part of a toolbar instantiator (typically | |
| 1312 set on the specifier @code{default-toolbar}). | |
| 1313 See @code{default-toolbar} for more information. (As a convenience, you | |
| 1314 may use a symbol in place of the glyph list in the toolbar button | |
| 1315 instantiator; the symbol is evalled to get the glyph list. This | |
| 442 | 1316 facilitates both creating the toolbar instantiator and modifying |
| 1317 individual glyphs in a toolbar later on. For example, you can change | |
| 1318 the way that the Mail toolbar button looks by modifying the value of the | |
| 1319 variable @code{toolbar-mail-icon} (in general, @code{toolbar-*-icon}) | |
| 1320 and then calling @code{(set-specifier-dirty-flag default-toolbar)}. | |
| 1321 (#### Unfortunately this doesn't quite work the way it should; the | |
| 2127 | 1322 change will appear in new frames, but not existing ones, because once an |
| 1323 image has been displayed the pixmap replaces the symbol for those domains.) | |
| 442 | 1324 |
| 2182 | 1325 @item gutter |
| 2127 | 1326 To insert a glyph into a gutter, use |
| 442 | 1327 @code{set-extent-begin-glyph} or @code{set-extent-end-glyph} to set a |
| 2127 | 1328 glyph to be displayed at the corresponding edge of extent in a string, |
| 1329 similar to the way you insert glyphs in a buffer. Then insert the | |
| 2182 | 1330 string into the gutter @ref{Specifying a Gutter}. Glyphs that are |
| 1331 frequently used in this way are @code{tab control} and @code{progress | |
| 1332 bar} glyphs. | |
| 1333 | |
| 1334 @end table | |
| 1335 | |
| 1336 | |
|
5791
9fae6227ede5
Silence texinfo 5.2 warnings, primarily by adding next, prev, and up
Jerry James <james@xemacs.org>
parents:
5715
diff
changeset
|
1337 @node External Glyphs, Native GUI Widgets, Frame Glyphs, Using Glyphs |
| 2182 | 1338 @subsection External Glyphs |
| 1339 @cindex frame icon | |
| 1340 @cindex icon, frame | |
| 1341 @cindex mouse cursor | |
| 1342 @cindex cursor (mouse) | |
| 1343 @cindex pointer (mouse) | |
| 1344 @cindex mouse pointer | |
| 442 | 1345 |
| 2182 | 1346 There are two special kinds of glyph that are not displayed by XEmacs. |
| 1347 Instead, they are used to set the appearance of iconified frames and the | |
| 1348 mouse pointer. Because these uses are constrained by the window system, | |
| 1349 icons and pointers have their own special types @xref{Glyph Types}. | |
| 442 | 1350 |
| 2182 | 1351 You may use a glyph as the icon for a frame. Do not create a new glyph; |
| 1352 instead, change the specifications for the existing glyph | |
| 1353 @code{frame-icon-glyph} with @code{set-glyph-image}. This is a unique, | |
| 1354 predefined object. Although the natural usage is to set specifications | |
| 1355 for the global locale or a frame locale, you can also arrange for a | |
| 1356 special icon when a frame's selected window displays a particular buffer | |
| 1357 by using a buffer locale. | |
| 1358 | |
| 1359 The shape of the mouse pointer when over a particular section of a frame | |
| 1360 is controlled using various glyph variables. Since the image of a glyph | |
| 1361 is a specifier, it can be controlled on a per-buffer, per-frame, per-window, | |
| 1362 or per-device basis. | |
| 1363 | |
| 442 | 1364 To use a glyph as the mouse pointer, in general you do not create a new |
| 1365 glyph, but rather you change the specifications of various existing | |
| 1366 glyphs, such as @code{text-pointer-glyph} for the pointer used over | |
| 1367 text, @code{modeline-pointer-glyph} for the pointer used over the | |
| 2127 | 1368 modeline, etc. Do an apropos over @samp{pointer-glyph} to find all of |
| 1369 them. (Note also that you can temporarily set the mouse pointer to some | |
| 442 | 1370 specific shape by using @code{set-frame-pointer}, which takes an image |
| 1371 instance, as obtained from calling @code{glyph-image-instance} on a glyph | |
| 1372 of type @code{pointer} -- either one of the above-mentioned variables or | |
| 1373 one you created yourself. (See below for what it means to create a | |
| 1374 glyph of type @code{pointer}.) This pointer will last only until the | |
| 1375 next mouse motion event is processed or certain other things happen, | |
| 1376 such as creating or deleting a window. (In fact, the above-mentioned | |
| 1377 pointer glyph variables are implemented as part of the default handler | |
| 1378 for mouse motion events. If you want to customize this behavior, take a | |
| 1379 look at @code{mode-motion-hook}, or @code{mouse-motion-handler} if you | |
| 1380 really want to get low-level.) | |
| 1381 | |
| 2182 | 1382 You should use @code{set-glyph-image} to set the following variables, |
| 1383 @emph{not} @code{setq}. | |
| 1384 | |
| 1385 @defvr Glyph text-pointer-glyph | |
| 1386 This variable specifies the shape of the mouse pointer when over text. | |
| 1387 @end defvr | |
| 1388 | |
| 1389 @defvr Glyph nontext-pointer-glyph | |
| 1390 This variable specifies the shape of the mouse pointer when over a | |
| 1391 buffer, but not over text. If unspecified in a particular domain, | |
| 1392 @code{text-pointer-glyph} is used. | |
| 1393 @end defvr | |
| 1394 | |
| 1395 @defvr Glyph modeline-pointer-glyph | |
| 1396 This variable specifies the shape of the mouse pointer when over the modeline. | |
| 1397 If unspecified in a particular domain, @code{nontext-pointer-glyph} is used. | |
| 1398 @end defvr | |
| 1399 | |
| 1400 @defvr Glyph selection-pointer-glyph | |
| 1401 This variable specifies the shape of the mouse pointer when over a | |
| 1402 selectable text region. If unspecified in a particular domain, | |
| 1403 @code{text-pointer-glyph} is used. | |
| 1404 @end defvr | |
| 1405 | |
| 1406 @defvr Glyph gc-pointer-glyph | |
| 1407 This variable specifies the shape of the mouse pointer when a garbage | |
| 1408 collection is in progress. If the selected window is on a window system | |
| 1409 and this glyph specifies a value (i.e. a pointer image instance) in the | |
| 1410 domain of the selected window, the pointer will be changed as specified | |
| 1411 during garbage collection. Otherwise, a message will be printed in the | |
| 1412 echo area, as controlled by @code{gc-message}. | |
| 1413 @end defvr | |
| 442 | 1414 |
| 2182 | 1415 @defvr Glyph busy-pointer-glyph |
| 1416 This variable specifies the shape of the mouse pointer when XEmacs is busy. | |
| 1417 If unspecified in a particular domain, the pointer is not changed | |
| 1418 when XEmacs is busy. | |
| 1419 @end defvr | |
| 1420 | |
| 1421 @defvr Glyph menubar-pointer-glyph | |
| 1422 This variable specifies the shape of the mouse pointer when over the | |
| 1423 menubar. If unspecified in a particular domain, the | |
| 1424 window-system-provided default pointer is used. | |
| 1425 @end defvr | |
| 442 | 1426 |
| 2182 | 1427 @defvr Glyph scrollbar-pointer-glyph |
| 1428 This variable specifies the shape of the mouse pointer when over a | |
| 1429 scrollbar. If unspecified in a particular domain, the | |
| 1430 window-system-provided default pointer is used. | |
| 1431 @end defvr | |
| 442 | 1432 |
| 2182 | 1433 @defvr Glyph toolbar-pointer-glyph |
| 1434 This variable specifies the shape of the mouse pointer when over a | |
| 1435 toolbar. If unspecified in a particular domain, | |
| 1436 @code{nontext-pointer-glyph} is used. | |
| 1437 @end defvr | |
| 1438 | |
| 1439 Internally, these variables are implemented in | |
| 1440 @code{default-mouse-motion-handler}, and thus only take effect when the | |
| 1441 mouse moves. That function calls @code{set-frame-pointer}, which sets | |
| 1442 the current mouse pointer for a frame. | |
| 1443 | |
| 1444 @defun set-frame-pointer frame image-instance | |
| 1445 This function sets the mouse pointer of @var{frame} to the given pointer | |
| 1446 image instance. You should not call this function directly. | |
| 1447 (If you do, the pointer will change again the next time the mouse moves.) | |
| 428 | 1448 @end defun |
| 1449 | |
| 2182 | 1450 |
|
5791
9fae6227ede5
Silence texinfo 5.2 warnings, primarily by adding next, prev, and up
Jerry James <james@xemacs.org>
parents:
5715
diff
changeset
|
1451 @node Native GUI Widgets, Subwindows, External Glyphs, Using Glyphs |
| 2182 | 1452 @subsection Native GUI Widgets |
| 1453 @cindex native widget | |
| 1454 | |
| 1455 A ``native widget'' is a primitive GUI object defined either by the host | |
| 1456 GUI platform or an external toolkit, and accessed from Lisp as a | |
| 1457 ``glyph.'' | |
| 1458 | |
| 1459 @menu | |
| 1460 * Introduction to Widgets:: Native widgets provide tight integration of | |
| 1461 GUI features with the platform GUI. | |
| 1462 * Lisp API to Native Widgets:: Native widgets are glyphs. | |
| 1463 * Layouts:: Specifying composite widgets from Lisp. | |
| 1464 * Primitive Widgets:: Catalogue of available native widgets. | |
| 1465 @end menu | |
| 1466 | |
|
5791
9fae6227ede5
Silence texinfo 5.2 warnings, primarily by adding next, prev, and up
Jerry James <james@xemacs.org>
parents:
5715
diff
changeset
|
1467 @node Introduction to Widgets, Lisp API to Native Widgets, Native GUI Widgets, Native GUI Widgets |
| 2182 | 1468 @subsubsection Introduction to Native Widgets and Subwindow Glyphs |
| 1469 | |
| 1470 Traditionally Emacsen have hidden the GUI apparatus from the Lisp | |
| 1471 programmer, but in XEmacs 21.4 the ability to embed autonomous GUI | |
| 1472 objects, called @dfn{native widgets}, in text was added to Lisp. They | |
| 1473 are handled as @emph{glyphs}. Unlike traditional XEmacs | |
| 1474 glyphs such images and strings, native widgets are opaque to XEmacs, and | |
| 1475 must be able to redraw themselves because they are implemented as | |
| 1476 subwindows, not as graphics drawn by XEmacs into the text window. | |
| 1477 | |
| 1478 Primitive widgets are coded in C using the underlying GUI toolkit, and | |
| 1479 thus are beyond the scope of the @emph{XEmacs Lisp Reference Manual}. | |
| 1480 However, composite widgets can be created in Lisp using ``layouts,'' | |
| 1481 which are horizontal or vertical arrays of subwidgets. For example, the | |
| 1482 search dialog is formatted using layouts. | |
| 1483 | |
|
5791
9fae6227ede5
Silence texinfo 5.2 warnings, primarily by adding next, prev, and up
Jerry James <james@xemacs.org>
parents:
5715
diff
changeset
|
1484 @node Lisp API to Native Widgets, Layouts, Introduction to Widgets, Native GUI Widgets |
| 2182 | 1485 @subsubsection Lisp API to Native Widgets |
| 1486 | |
| 1487 Native widgets are manipulated as @emph{glyphs} (@pxref{Glyphs}). Thus | |
| 1488 they are created using @code{make-glyph}, with a format of one of the | |
| 1489 widget types and a @code{:data} property specific to the widget being | |
| 2953 | 1490 instantiated. |
| 2182 | 1491 |
| 1492 However, there is a technical difference between widgets and other kinds | |
| 1493 of glyphs that is theoretically important. Because widgets | |
| 1494 are active (that is, they can respond to user input events themselves), | |
| 1495 it is possible for the user to become aware that two appearances of the | |
| 1496 ``same'' glyph are actually separate instances. For example, if a user | |
| 1497 changes an image glyph from red to blue, and the buffer containing the | |
| 1498 glyph appears in more than one window, the user will perceive all the | |
| 1499 appearances to change from red to blue simultaneously. However, suppose | |
| 1500 the glyph is a button glyph (@emph{e.g.}, as used in the Customize | |
| 1501 buffer for the Set, Save, and Done buttons). Then if the Customize | |
| 1502 buffer appears in several windows at the same time, and the user clicks | |
| 1503 on the button, she will only perceive the button to be depressed in the | |
| 1504 window where she clicked the button. | |
| 1505 | |
| 1506 It seems from this example that it is unlikely to be a problem in | |
| 1507 practice. When the user is faced with an active widget, it seems likely | |
| 1508 that attention will focus on the widget being manipulated, and having | |
| 1509 other instances of the widget respond simultaneously might be more | |
| 1510 disconcerting than the actual case. | |
| 1511 | |
|
5791
9fae6227ede5
Silence texinfo 5.2 warnings, primarily by adding next, prev, and up
Jerry James <james@xemacs.org>
parents:
5715
diff
changeset
|
1512 @node Layouts, Primitive Widgets, Lisp API to Native Widgets, Native GUI Widgets |
| 2182 | 1513 @subsubsection Layouts |
| 1514 | |
| 1515 An XEmacs @dfn{layout} is a one-dimensional array of glyphs. It is a | |
| 1516 widget for controlling the positioning of children underneath it. | |
| 1517 Through the use of nested layouts, a widget hierarchy can be created | |
| 1518 which can have the appearance of any standard dialog box or similar | |
| 1519 arrangement; all of this is counted as one "glyph" and could appear in | |
| 1520 many of the places that expect a single glyph. | |
| 1521 | |
| 1522 (There are also @dfn{native layouts}, but I don't know what these are or | |
| 1523 how they are used.) | |
| 1524 | |
| 1525 A layout descriptor is an image instantiator, @emph{i.e.}, a vector of | |
| 1526 the form @samp{[FORMAT KEY-1 VALUE-1 KEY-2 VALUE-2 ...]} with format | |
| 1527 @code{layout}, and properties | |
| 1528 | |
| 1529 @c #### need defaults for these | |
| 1530 @table @code | |
| 1531 @item :orientation | |
| 1532 Specifies the orientation of the contained array of glyphs. The value | |
| 1533 must be one of the symbols @code{horizontal} or @code{vertical}. | |
| 1534 | |
| 1535 @item :horizontally-justify | |
| 1536 Specifies the horizontal justification of the items in the array. The | |
| 1537 value must be one of the symbols @code{:right}, @code{:center}, or | |
| 1538 @code{:left}. | |
| 1539 | |
| 1540 @item :vertically-justify | |
| 1541 Specifies the vertical justification of the items in the array. The | |
| 1542 value must be one of the symbols @code{:top}, @code{:center}, or | |
| 1543 @code{:bottom}. | |
| 1544 | |
| 1545 @item :justify | |
| 1546 Specifies justification. #### not understood. | |
| 1547 | |
| 1548 @item :border | |
| 1549 A glyph to place in the border. The value must be an image | |
| 1550 instantiator. | |
| 1551 | |
| 1552 @item :items | |
| 1553 The glyphs controlled by the layout. The value must be a list of image | |
| 1554 instantiators. | |
| 1555 @end table | |
| 1556 | |
| 1557 Here is the specification of the search dialog widget created by | |
| 1558 @code{make-search-dialog} in the @file{dialog-items} library, which | |
| 1559 makes use of recursive layouts. | |
| 1560 | |
| 1561 @example | |
| 1562 (make-glyph | |
| 1563 `[layout | |
| 1564 :orientation horizontal | |
| 1565 :vertically-justify top | |
| 1566 :horizontally-justify center | |
| 1567 :border [string :data "Search"] | |
| 1568 :items | |
| 1569 ([layout :orientation vertical | |
| 1570 :justify top ; implies left also | |
| 1571 :items | |
| 1572 ([string :data "Search for:"] | |
| 1573 [button :descriptor "Match Case" | |
| 1574 :style toggle | |
| 1575 :selected (not case-fold-search) | |
| 1576 :callback (setq case-fold-search | |
| 1577 (not case-fold-search))] | |
| 1578 [button :descriptor "Regular Expression" | |
| 1579 :style toggle | |
| 1580 :selected search-dialog-regexp | |
| 1581 :callback (setq search-dialog-regexp | |
| 1582 (not search-dialog-regexp))] | |
| 1583 [button :descriptor "Forwards" | |
| 1584 :style radio | |
| 1585 :selected search-dialog-direction | |
| 1586 :callback (setq search-dialog-direction t)] | |
| 1587 [button :descriptor "Backwards" | |
| 1588 :style radio | |
| 1589 :selected (not search-dialog-direction) | |
| 1590 :callback (setq search-dialog-direction nil)] | |
| 1591 )] | |
| 1592 [layout :orientation vertical | |
| 1593 :vertically-justify top | |
| 1594 :horizontally-justify right | |
| 1595 :items | |
| 1596 ([edit-field :width 15 :descriptor "" :active t | |
| 1597 :initial-focus t] | |
| 1598 [button :width 10 :descriptor "Find Next" | |
| 1599 :callback-ex | |
| 1600 (lambda (image-instance event) | |
| 1601 (search-dialog-callback ,parent | |
| 1602 image-instance | |
| 1603 event))] | |
| 1604 [button :width 10 :descriptor "Cancel" | |
| 1605 :callback-ex | |
| 1606 (lambda (image-instance event) | |
| 1607 (isearch-dehighlight) | |
| 1608 (delete-frame | |
| 1609 (event-channel event)))])])]) | |
| 1610 @end example | |
| 1611 | |
|
5791
9fae6227ede5
Silence texinfo 5.2 warnings, primarily by adding next, prev, and up
Jerry James <james@xemacs.org>
parents:
5715
diff
changeset
|
1612 @node Primitive Widgets, , Layouts, Native GUI Widgets |
| 2182 | 1613 @subsubsection Primitive Widgets |
| 1614 | |
| 1615 @c #### the following table should be replaced with a menu of nodes | |
| 1616 @table @code | |
| 1617 @item button | |
| 1618 A button widget; either a push button, radio button or toggle | |
| 1619 button. | |
| 1620 | |
| 1621 @item combo-box | |
| 1622 A drop list of selectable items in a widget, for editing text. | |
| 1623 | |
| 1624 @item edit-field | |
| 1625 A text editing widget. | |
| 1626 | |
| 1627 @item label | |
| 1628 A static, text-only, widget; for displaying text. | |
| 1629 | |
| 1630 @item progress-gauge | |
| 1631 A sliding widget, for showing progress. | |
| 1632 | |
| 1633 @item tab-control | |
| 1634 A tab widget; a series of user selectable tabs. | |
| 1635 | |
| 1636 @item tree-view | |
| 1637 A folding widget. | |
| 1638 | |
| 1639 @item scrollbar | |
| 1640 A scrollbar widget. (#### Probably not the same as the scrollbar | |
| 1641 controlling an Emacs window.) | |
| 1642 @end table | |
| 1643 | |
| 1644 | |
|
5791
9fae6227ede5
Silence texinfo 5.2 warnings, primarily by adding next, prev, and up
Jerry James <james@xemacs.org>
parents:
5715
diff
changeset
|
1645 @node Subwindows, , Native GUI Widgets, Using Glyphs |
| 2182 | 1646 @subsection Subwindows |
| 1647 | |
| 1648 Subwindows are not currently implemented. | |
| 1649 @c #### Check status of subwindows ... I thought Andy implemented them. | |
| 1650 | |
| 1651 @defun subwindowp object | |
| 1652 This function returns non-@code{nil} if @var{object} is a subwindow. | |
| 428 | 1653 @end defun |
| 1654 | |
| 442 | 1655 |
|
5791
9fae6227ede5
Silence texinfo 5.2 warnings, primarily by adding next, prev, and up
Jerry James <james@xemacs.org>
parents:
5715
diff
changeset
|
1656 @node Manipulating Glyphs, Glyph Examples, Using Glyphs, Glyphs |
| 2182 | 1657 @section Manipulating Glyphs |
| 428 | 1658 |
| 2182 | 1659 Each glyphs has properties that may be accessed. Most of these can |
| 1660 also be set after the glyph is initialized, with the exception of the | |
| 1661 glyph's type. This is not a real restriction, as it is almost never | |
| 1662 useful to create glyphs of types other than @code{buffer}. | |
| 442 | 1663 |
| 2182 | 1664 @menu |
| 1665 * Glyph Properties:: Accessing and modifying a glyph's properties. | |
| 1666 * Glyph Convenience Functions:: Accessing particular properties of a glyph. | |
| 1667 * Glyph Dimensions:: Determining the height, width, etc. of a glyph. | |
| 1668 * Glyph Types:: Each glyph has a particular type. | |
| 1669 @end menu | |
| 442 | 1670 |
| 428 | 1671 |
|
5791
9fae6227ede5
Silence texinfo 5.2 warnings, primarily by adding next, prev, and up
Jerry James <james@xemacs.org>
parents:
5715
diff
changeset
|
1672 @node Glyph Properties, Glyph Convenience Functions, Manipulating Glyphs, Manipulating Glyphs |
| 428 | 1673 @subsection Glyph Properties |
| 1674 | |
| 1675 Each glyph has a list of properties, which control all of the aspects of | |
| 1676 the glyph's appearance. The following symbols have predefined meanings: | |
| 1677 | |
| 1678 @table @code | |
| 1679 @item image | |
| 1680 The image used to display the glyph. | |
| 1681 | |
| 1682 @item baseline | |
| 1683 Percent above baseline that glyph is to be displayed. Only for glyphs | |
| 1684 displayed inside of a buffer. | |
| 1685 | |
| 1686 @item contrib-p | |
| 1687 Whether the glyph contributes to the height of the line it's on. | |
| 1688 Only for glyphs displayed inside of a buffer. | |
| 1689 | |
| 1690 @item face | |
| 1691 Face of this glyph (@emph{not} a specifier). | |
| 1692 @end table | |
| 1693 | |
| 1694 @defun set-glyph-property glyph property value &optional locale tag-set how-to-add | |
| 1695 This function changes a property of a @var{glyph}. | |
| 1696 | |
| 1697 For built-in properties, the actual value of the property is a specifier | |
| 1698 and you cannot change this; but you can change the specifications within | |
| 2182 | 1699 the specifier, and that is what this function will do. The glyph face |
| 1700 is an exception; it is a face name (a symbol) or a face object, not a | |
| 1701 specifier. (The face properties themselves are typically specifiers.) | |
| 1702 For user-defined properties, you can use this function to either change | |
| 1703 the actual value of the property or, if this value is a specifier, | |
| 1704 change the specifications within it. | |
| 428 | 1705 |
| 1706 If @var{property} is a built-in property, the specifications to be added | |
| 1707 to this property can be supplied in many different ways: | |
| 1708 | |
| 1709 @itemize @bullet | |
| 1710 @item | |
| 1711 If @var{value} is a simple instantiator (e.g. a string naming a pixmap | |
| 1712 filename) or a list of instantiators, then the instantiator(s) will be | |
| 1713 added as a specification of the property for the given @var{locale} | |
| 1714 (which defaults to @code{global} if omitted). | |
| 1715 | |
| 1716 @item | |
| 1717 If @var{value} is a list of specifications (each of which is a cons of a | |
| 1718 locale and a list of instantiators), then @var{locale} must be | |
| 1719 @code{nil} (it does not make sense to explicitly specify a locale in | |
| 1720 this case), and specifications will be added as given. | |
| 1721 | |
| 1722 @item | |
| 1723 If @var{value} is a specifier (as would be returned by | |
| 1724 @code{glyph-property} if no @var{locale} argument is given), then some | |
| 1725 or all of the specifications in the specifier will be added to the | |
| 1726 property. In this case, the function is really equivalent to | |
| 1727 @code{copy-specifier} and @var{locale} has the same semantics (if it is | |
| 1728 a particular locale, the specification for the locale will be copied; if | |
| 1729 a locale type, specifications for all locales of that type will be | |
| 1730 copied; if @code{nil} or @code{all}, then all specifications will be | |
| 1731 copied). | |
| 1732 @end itemize | |
| 1733 | |
| 1734 @var{how-to-add} should be either @code{nil} or one of the symbols | |
| 1735 @code{prepend}, @code{append}, @code{remove-tag-set-prepend}, | |
| 1736 @code{remove-tag-set-append}, @code{remove-locale}, | |
| 1737 @code{remove-locale-type}, or @code{remove-all}. See | |
| 1738 @code{copy-specifier} and @code{add-spec-to-specifier} for a description | |
| 1739 of what each of these means. Most of the time, you do not need to worry | |
| 1740 about this argument; the default behavior usually is fine. | |
| 1741 | |
| 1742 In general, it is OK to pass an instance object (e.g. as returned by | |
| 1743 @code{glyph-property-instance}) as an instantiator in place of an actual | |
| 1744 instantiator. In such a case, the instantiator used to create that | |
| 1745 instance object will be used (for example, if you set a font-instance | |
| 1746 object as the value of the @code{font} property, then the font name used | |
| 2028 | 1747 to create that object will be used instead). In some cases, however, |
| 428 | 1748 doing this conversion does not make sense, and this will be noted in the |
| 1749 documentation for particular types of instance objects. | |
| 1750 | |
| 1751 If @var{property} is not a built-in property, then this function will | |
| 1752 simply set its value if @var{locale} is @code{nil}. However, if | |
| 1753 @var{locale} is given, then this function will attempt to add | |
| 1754 @var{value} as the instantiator for the given @var{locale}, using | |
| 1755 @code{add-spec-to-specifier}. If the value of the property is not a | |
| 1756 specifier, it will automatically be converted into a @code{generic} | |
| 1757 specifier. | |
| 1758 @end defun | |
| 1759 | |
| 1760 @defun glyph-property glyph property &optional locale | |
| 1761 This function returns @var{glyph}'s value of the given @var{property}. | |
| 1762 | |
| 1763 If @var{locale} is omitted, the @var{glyph}'s actual value for | |
| 1764 @var{property} will be returned. For built-in properties, this will be | |
| 1765 a specifier object of a type appropriate to the property (e.g. a font or | |
| 1766 color specifier). For other properties, this could be anything. | |
| 1767 | |
| 1768 If @var{locale} is supplied, then instead of returning the actual value, | |
| 1769 the specification(s) for the given locale or locale type will be | |
| 1770 returned. This will only work if the actual value of @var{property} is | |
| 1771 a specifier (this will always be the case for built-in properties, but | |
| 1772 may or may not apply to user-defined properties). If the actual value | |
| 1773 of @var{property} is not a specifier, this value will simply be returned | |
| 1774 regardless of @var{locale}. | |
| 1775 | |
| 1776 The return value will be a list of instantiators (e.g. vectors | |
| 1777 specifying pixmap data), or a list of specifications, each of which is a | |
| 1778 cons of a locale and a list of instantiators. Specifically, if | |
| 1779 @var{locale} is a particular locale (a buffer, window, frame, device, or | |
| 1780 @code{global}), a list of instantiators for that locale will be | |
| 1781 returned. Otherwise, if @var{locale} is a locale type (one of the | |
| 1782 symbols @code{buffer}, @code{window}, @code{frame}, or @code{device}), | |
| 1783 the specifications for all locales of that type will be returned. | |
| 1784 Finally, if @var{locale} is @code{all}, the specifications for all | |
| 1785 locales of all types will be returned. | |
| 1786 | |
| 1787 The specifications in a specifier determine what the value of | |
| 1788 @var{property} will be in a particular @dfn{domain} or set of | |
| 1789 circumstances, which is typically a particular Emacs window along with | |
| 1790 the buffer it contains and the frame and device it lies within. The | |
| 1791 value is derived from the instantiator associated with the most specific | |
| 1792 locale (in the order buffer, window, frame, device, and @code{global}) | |
| 1793 that matches the domain in question. In other words, given a domain | |
| 1794 (i.e. an Emacs window, usually), the specifier for @var{property} will | |
| 1795 first be searched for a specification whose locale is the buffer | |
| 1796 contained within that window; then for a specification whose locale is | |
| 1797 the window itself; then for a specification whose locale is the frame | |
| 1798 that the window is contained within; etc. The first instantiator that | |
| 1799 is valid for the domain (usually this means that the instantiator is | |
| 1800 recognized by the device [i.e. the X server or TTY device] that the | |
| 1801 domain is on). The function @code{glyph-property-instance} actually does | |
| 1802 all this, and is used to determine how to display the glyph. | |
| 1803 @end defun | |
| 1804 | |
| 1805 @defun glyph-property-instance glyph property &optional domain default no-fallback | |
| 1806 This function returns the instance of @var{glyph}'s @var{property} in the | |
| 1807 specified @var{domain}. | |
| 1808 | |
| 1809 Under most circumstances, @var{domain} will be a particular window, and | |
| 1810 the returned instance describes how the specified property actually is | |
| 1811 displayed for that window and the particular buffer in it. Note that | |
| 1812 this may not be the same as how the property appears when the buffer is | |
| 1813 displayed in a different window or frame, or how the property appears in | |
| 1814 the same window if you switch to another buffer in that window; and in | |
| 1815 those cases, the returned instance would be different. | |
| 1816 | |
| 1817 The returned instance is an image-instance object, and you can query it | |
| 1818 using the appropriate image instance functions. For example, you could use | |
| 1819 @code{image-instance-depth} to find out the depth (number of color | |
| 1820 planes) of a pixmap displayed in a particular window. The results might | |
| 1821 be different from the results you would get for another window (perhaps | |
| 1822 the user specified a different image for the frame that window is on; or | |
| 1823 perhaps the same image was specified but the window is on a different X | |
| 1824 server, and that X server has different color capabilities from this | |
| 1825 one). | |
| 1826 | |
| 1827 @var{domain} defaults to the selected window if omitted. | |
| 1828 | |
| 1829 @var{domain} can be a frame or device, instead of a window. The value | |
| 1830 returned for such a domain is used in special circumstances when a | |
| 1831 more specific domain does not apply; for example, a frame value might be | |
| 1832 used for coloring a toolbar, which is conceptually attached to a frame | |
| 1833 rather than a particular window. The value is also useful in | |
| 1834 determining what the value would be for a particular window within the | |
| 1835 frame or device, if it is not overridden by a more specific | |
| 1836 specification. | |
| 1837 | |
| 1838 If @var{property} does not name a built-in property, its value will | |
| 1839 simply be returned unless it is a specifier object, in which case it | |
| 2953 | 1840 will be instantiated using @code{specifier-instance}. |
| 428 | 1841 |
| 1842 Optional arguments @var{default} and @var{no-fallback} are the same as | |
| 1843 in @code{specifier-instance}. @xref{Specifiers}. | |
| 1844 @end defun | |
| 1845 | |
| 1846 @defun remove-glyph-property glyph property &optional locale tag-set exact-p | |
| 1847 This function removes a property from a glyph. For built-in properties, | |
| 1848 this is analogous to @code{remove-specifier}. @xref{Specifiers, | |
| 1849 remove-specifier-p}, for the meaning of the @var{locale}, @var{tag-set}, | |
| 1850 and @var{exact-p} arguments. | |
| 1851 @end defun | |
| 1852 | |
| 2182 | 1853 |
|
5791
9fae6227ede5
Silence texinfo 5.2 warnings, primarily by adding next, prev, and up
Jerry James <james@xemacs.org>
parents:
5715
diff
changeset
|
1854 @node Glyph Convenience Functions, Glyph Dimensions, Glyph Properties, Manipulating Glyphs |
| 428 | 1855 @subsection Glyph Convenience Functions |
| 1856 | |
| 1857 The following functions are provided for working with specific | |
| 1858 properties of a glyph. Note that these are exactly like calling | |
| 1859 the general functions described above and passing in the | |
| 1860 appropriate value for @var{property}. | |
| 1861 | |
| 1862 Remember that if you want to determine the ``value'' of a | |
| 1863 specific glyph property, you probably want to use the @code{*-instance} | |
| 1864 functions. For example, to determine whether a glyph contributes | |
| 1865 to its line height, use @code{glyph-contrib-p-instance}, not | |
| 1866 @code{glyph-contrib-p}. (The latter will return a boolean specifier | |
| 1867 or a list of specifications, and you probably aren't concerned with | |
| 1868 these.) | |
| 1869 | |
| 1870 @defun glyph-image glyph &optional locale | |
| 1871 This function is equivalent to calling @code{glyph-property} with | |
| 1872 a property of @code{image}. The return value will be an image | |
| 1873 specifier if @var{locale} is @code{nil} or omitted; otherwise, | |
| 1874 it will be a specification or list of specifications. | |
| 1875 @end defun | |
| 1876 | |
| 1877 @defun set-glyph-image glyph spec &optional locale tag-set how-to-add | |
| 1878 This function is equivalent to calling @code{set-glyph-property} with | |
| 1879 a property of @code{image}. | |
| 1880 @end defun | |
| 1881 | |
| 1882 @defun glyph-image-instance glyph &optional domain default no-fallback | |
| 1883 This function returns the instance of @var{glyph}'s image in the given | |
| 1884 @var{domain}, and is equivalent to calling | |
| 1885 @code{glyph-property-instance} with a property of @code{image}. The | |
| 1886 return value will be an image instance. | |
| 1887 | |
| 1888 Normally @var{domain} will be a window or @code{nil} (meaning the | |
| 1889 selected window), and an instance object describing how the image | |
| 1890 appears in that particular window and buffer will be returned. | |
| 1891 @end defun | |
| 1892 | |
| 1893 @defun glyph-contrib-p glyph &optional locale | |
| 1894 This function is equivalent to calling @code{glyph-property} with | |
| 1895 a property of @code{contrib-p}. The return value will be a boolean | |
| 1896 specifier if @var{locale} is @code{nil} or omitted; otherwise, | |
| 1897 it will be a specification or list of specifications. | |
| 1898 @end defun | |
| 1899 | |
| 1900 @defun set-glyph-contrib-p glyph spec &optional locale tag-set how-to-add | |
| 1901 This function is equivalent to calling @code{set-glyph-property} with | |
| 1902 a property of @code{contrib-p}. | |
| 1903 @end defun | |
| 1904 | |
| 1905 @defun glyph-contrib-p-instance glyph &optional domain default no-fallback | |
| 1906 This function returns whether the glyph contributes to its line height | |
| 1907 in the given @var{domain}, and is equivalent to calling | |
| 1908 @code{glyph-property-instance} with a property of @code{contrib-p}. The | |
| 1909 return value will be either @code{nil} or @code{t}. (Normally @var{domain} | |
| 1910 will be a window or @code{nil}, meaning the selected window.) | |
| 1911 @end defun | |
| 1912 | |
| 1913 @defun glyph-baseline glyph &optional locale | |
| 1914 This function is equivalent to calling @code{glyph-property} with a | |
| 1915 property of @code{baseline}. The return value will be a specifier if | |
| 1916 @var{locale} is @code{nil} or omitted; otherwise, it will be a | |
| 1917 specification or list of specifications. | |
| 1918 @end defun | |
| 1919 | |
| 1920 @defun set-glyph-baseline glyph spec &optional locale tag-set how-to-add | |
| 1921 This function is equivalent to calling @code{set-glyph-property} with | |
| 1922 a property of @code{baseline}. | |
| 1923 @end defun | |
| 1924 | |
| 1925 @defun glyph-baseline-instance glyph &optional domain default no-fallback | |
| 1926 This function returns the instance of @var{glyph}'s baseline value in | |
| 1927 the given @var{domain}, and is equivalent to calling | |
| 1928 @code{glyph-property-instance} with a property of @code{baseline}. The | |
| 1929 return value will be an integer or @code{nil}. | |
| 1930 | |
| 1931 Normally @var{domain} will be a window or @code{nil} (meaning the | |
| 1932 selected window), and an instance object describing the baseline value | |
| 1933 appears in that particular window and buffer will be returned. | |
| 1934 @end defun | |
| 1935 | |
| 1936 @defun glyph-face glyph | |
| 1937 This function returns the face of @var{glyph}. (Remember, this is | |
| 1938 not a specifier, but a simple property.) | |
| 1939 @end defun | |
| 1940 | |
| 1941 @defun set-glyph-face glyph face | |
| 1942 This function changes the face of @var{glyph} to @var{face}. | |
| 1943 @end defun | |
| 1944 | |
| 2182 | 1945 |
|
5791
9fae6227ede5
Silence texinfo 5.2 warnings, primarily by adding next, prev, and up
Jerry James <james@xemacs.org>
parents:
5715
diff
changeset
|
1946 @node Glyph Dimensions, Glyph Types, Glyph Convenience Functions, Manipulating Glyphs |
| 428 | 1947 @subsection Glyph Dimensions |
| 1948 | |
| 1949 @defun glyph-width glyph &optional window | |
| 1950 This function returns the width of @var{glyph} on @var{window}. This | |
| 1951 may not be exact as it does not take into account all of the context | |
| 1952 that redisplay will. | |
| 1953 @end defun | |
| 1954 | |
| 1955 @defun glyph-ascent glyph &optional window | |
| 1956 This function returns the ascent value of @var{glyph} on @var{window}. | |
| 1957 This may not be exact as it does not take into account all of the | |
| 1958 context that redisplay will. | |
| 1959 @end defun | |
| 1960 | |
| 1961 @defun glyph-descent glyph &optional window | |
| 1962 This function returns the descent value of @var{glyph} on @var{window}. | |
| 1963 This may not be exact as it does not take into account all of the | |
| 1964 context that redisplay will. | |
| 1965 @end defun | |
| 1966 | |
| 1967 @defun glyph-height glyph &optional window | |
| 1968 This function returns the height of @var{glyph} on @var{window}. (This | |
| 1969 is equivalent to the sum of the ascent and descent values.) This may | |
| 1970 not be exact as it does not take into account all of the context that | |
| 1971 redisplay will. | |
| 1972 @end defun | |
| 1973 | |
| 1974 | |
|
5791
9fae6227ede5
Silence texinfo 5.2 warnings, primarily by adding next, prev, and up
Jerry James <james@xemacs.org>
parents:
5715
diff
changeset
|
1975 @node Glyph Types, , Glyph Dimensions, Manipulating Glyphs |
| 2182 | 1976 @subsection Glyph Types |
| 428 | 1977 |
| 1978 Each glyph has a particular type, which controls how the glyph's image | |
| 1979 is generated. Each glyph type has a corresponding list of allowable | |
| 1980 image instance types that can be generated. When you call | |
| 1981 @code{glyph-image-instance} to retrieve the image instance of a glyph, | |
| 1982 XEmacs does the equivalent of calling @code{make-image-instance} and | |
| 1983 passing in @var{dest-types} the list of allowable image instance types | |
| 1984 for the glyph's type. | |
| 1985 | |
| 1986 @itemize @bullet | |
| 1987 @item | |
| 1988 @code{buffer} glyphs can be used as the begin-glyph or end-glyph of an | |
| 1989 extent, in the modeline, and in the toolbar. Their image can be | |
| 1990 instantiated as @code{nothing}, @code{mono-pixmap}, @code{color-pixmap}, | |
| 1991 @code{text}, and @code{subwindow}. | |
| 2182 | 1992 @c #### Check status of subwindows ... I thought Andy implemented them. |
| 428 | 1993 |
| 1994 @item | |
| 1995 @code{pointer} glyphs can be used to specify the mouse pointer. Their | |
| 1996 image can be instantiated as @code{pointer}. | |
| 1997 | |
| 1998 @item | |
| 1999 @code{icon} glyphs can be used to specify the icon used when a frame is | |
| 2000 iconified. Their image can be instantiated as @code{mono-pixmap} and | |
| 2001 @code{color-pixmap}. | |
| 2002 @end itemize | |
| 2003 | |
| 2004 @defun glyph-type glyph | |
| 2005 This function returns the type of the given glyph. The return value | |
| 2006 will be a symbol, one of @code{buffer}, @code{pointer}, or @code{icon}. | |
| 2007 @end defun | |
| 2008 | |
| 2009 @defun valid-glyph-type-p glyph-type | |
| 2010 Given a @var{glyph-type}, this function returns non-@code{nil} if it is | |
| 2011 valid. | |
| 2012 @end defun | |
| 2013 | |
| 2014 @defun glyph-type-list | |
| 2015 This function returns a list of valid glyph types. | |
| 2016 @end defun | |
| 2017 | |
| 2018 @defun buffer-glyph-p object | |
| 2019 This function returns non-@code{nil} if @var{object} is a glyph of type | |
| 2020 @code{buffer}. | |
| 2021 @end defun | |
| 2022 | |
| 2023 @defun icon-glyph-p object | |
| 2024 This function returns non-@code{nil} if @var{object} is a glyph of type | |
| 2025 @code{icon}. | |
| 2026 @end defun | |
| 2027 | |
| 2028 @defun pointer-glyph-p object | |
| 2029 This function returns non-@code{nil} if @var{object} is a glyph of type | |
| 2030 @code{pointer}. | |
| 2031 @end defun | |
| 2032 | |
| 707 | 2033 |
|
5791
9fae6227ede5
Silence texinfo 5.2 warnings, primarily by adding next, prev, and up
Jerry James <james@xemacs.org>
parents:
5715
diff
changeset
|
2034 @node Glyph Examples, , Manipulating Glyphs, Glyphs |
| 707 | 2035 @section Glyph Examples |
| 2036 | |
| 2037 For many applications, displaying graphics is a simple process: you | |
| 2038 create a glyph, and then you insert it into a buffer. | |
| 2039 | |
| 2040 The easiest way to create a glyph is to use a file that contains a | |
| 2041 graphical image, such as a JPEG, TIFF, or PNG file: | |
| 2042 | |
| 2043 @lisp | |
| 2044 ;; Create a glyph from a JPEG file: | |
| 2045 (setq foo (make-glyph [jpeg :file "/tmp/file1.jpg"])) | |
| 2046 @end lisp | |
| 2047 | |
| 2048 @lisp | |
| 2049 ;; Create a glyph from a XPM file: | |
| 2050 (setq foo (make-glyph [xpm :file "/tmp/file2.xpm"])) | |
| 2051 @end lisp | |
| 2052 | |
| 2053 @lisp | |
| 2054 ;; Create a glyph from a PNG file: | |
| 2055 (setq foo (make-glyph [png :file "/tmp/file3.png"])) | |
| 2056 @end lisp | |
| 2057 | |
| 2058 @lisp | |
| 2059 ;; Create a glyph from a TIFF file: | |
| 2060 (setq foo (make-glyph [tiff :file "/tmp/file4.tiff"])) | |
| 2061 @end lisp | |
| 2062 | |
| 2063 The parameters passed to @code{make-glyph} are called "Image | |
| 2064 Specifiers", and can handle more image types than those shown above. | |
| 2065 You can also put the raw image data into a string (e.g., if you put the | |
| 2066 contents of a JPEG file into a string), and use that to create a glyph. | |
| 2953 | 2067 @xref{Image Instantiators}, for more information. |
| 707 | 2068 |
| 2069 @quotation | |
| 2070 @strong{Caution}: In order for XEmacs to read a particular graphics file | |
| 2071 format, support for that format must have been compiled into XEmacs. | |
| 2072 It's possible, although somewhat unlikely, for XEmacs to have been | |
| 2073 compiled without support for any of the various graphics file formats. | |
| 2074 To see what graphics formats your particular version of XEmacs supports, | |
| 2075 use @kbd{M-x describe-installation}. | |
| 2076 | |
| 2077 To programmatically query whether or not a particular file format is | |
| 2078 supported, you can use the @code{featurep} function, with one of: | |
| 2079 @code{gif}, @code{tiff}, @code{jpeg}, @code{xpm}, @code{xbm}, | |
| 2080 @code{png}, or @code{xface}. For an up-to-date list, @ref{Image | |
| 2953 | 2081 Instantiators}. Example: |
| 707 | 2082 |
| 2083 @example | |
| 2084 ;; Returns `t' if TIFF is supported: | |
| 2085 (featurep 'tiff) | |
| 2086 @end example | |
| 2087 | |
| 2088 Another example is: | |
| 2089 | |
| 2090 @example | |
| 2091 ;; Returns a list of `t' or `nil', depending on whether or not the | |
| 2092 ;; corresponding feature is supported: | |
| 2093 (mapcar #'(lambda (format-symbol) (featurep format-symbol)) | |
| 2094 '(gif tiff jpeg xpm png)) | |
| 2095 @end example | |
| 2096 | |
| 2097 @end quotation | |
| 2098 | |
| 2099 Once you have a glyph, you can then insert it into a buffer. Example: | |
| 2100 | |
| 2101 @lisp | |
| 2102 ;; Use this function to insert a glyph at the left edge of point in the | |
| 2103 ;; current buffer. Any existing glyph at this location is replaced. | |
| 2104 (defun insert-glyph (gl) | |
| 2105 "Insert a glyph at the left edge of point." | |
| 1137 | 2106 (let ( (prop 'myimage) ;; myimage is an arbitrary name, chosen |
| 707 | 2107 ;; to (hopefully) not conflict with any |
| 2108 ;; other properties. Change it if | |
| 2109 ;; necessary. | |
| 2110 extent ) | |
| 2111 ;; First, check to see if one of our extents already exists at | |
| 2112 ;; point. For ease-of-programming, we are creating and using our | |
| 2113 ;; own extents (multiple extents are allowed to exist/overlap at the | |
| 2114 ;; same point, and it's quite possible for other applications to | |
| 2115 ;; embed extents in the current buffer without your knowledge). | |
| 2116 ;; Basically, if an extent, with the property stored in "prop", | |
| 2117 ;; exists at point, we assume that it is one of ours, and we re-use | |
| 2118 ;; it (this is why it is important for the property stored in "prop" | |
| 2119 ;; to be unique, and only used by us). | |
| 2120 (if (not (setq extent (extent-at (point) (current-buffer) prop))) | |
| 2121 (progn | |
| 2122 ;; If an extent does not already exist, create a zero-length | |
| 2123 ;; extent, and give it our special property. | |
| 2124 (setq extent (make-extent (point) (point) (current-buffer))) | |
| 2125 (set-extent-property extent prop t) | |
| 2126 )) | |
| 2127 ;; Display the glyph by storing it as the extent's "begin-glyph". | |
| 2128 (set-extent-property extent 'begin-glyph gl) | |
| 2129 )) | |
| 2130 | |
| 2131 ;; You can then use this function like: | |
| 2132 (insert-glyph (make-glyph [jpeg :file "/tmp/file1.jpg"])) | |
| 2133 ;; This will insert the glyph at point. | |
| 2134 | |
| 2135 ;; Here's an example of how to insert two glyphs side-by-side, at point | |
| 2136 ;; (using the above code): | |
| 2137 (progn | |
| 2138 (insert-glyph (make-glyph [jpeg :file "/tmp/file1.jpg"])) | |
| 2139 ;; Create a new extent at point. We can't simply call "insert-glyph", | |
| 2140 ;; as "insert-glyph" will simply replace the first glyph with the | |
| 2141 ;; second. | |
| 2142 (setq extent (make-extent (point) (point) (current-buffer))) | |
| 2143 ;; Here, we're only setting the 'myimage property in case we need | |
| 2144 ;; to later identify/locate/reuse this particular extent. | |
| 2145 (set-extent-property extent 'myimage t) | |
| 2146 (set-extent-property extent 'begin-glyph | |
| 2147 (make-glyph [jpeg :file "/tmp/file2.jpg"])) | |
| 2148 ) | |
| 2149 | |
| 2150 @end lisp | |
| 2151 | |
| 2152 Here are the gory details: | |
| 2153 | |
| 2154 @itemize @bullet | |
| 2155 | |
| 2156 @item | |
| 2157 Glyphs are displayed by attaching them to extents (see @ref{Extents}), | |
| 2158 either to the beginning or the end of extents. | |
| 2159 | |
| 2160 Note that extents can be used for many things, and not just for | |
| 2161 displaying images (although, in the above example, we are creating our | |
| 2162 own extent for the sole purpose of displaying an image). Also, note | |
| 2163 that multiple extents are allowed to exist at the same position, and | |
| 2164 they can overlap. | |
| 2165 | |
| 2166 @item | |
| 2167 Glyphs are often displayed inside the text area (alongside text). This | |
| 2168 is the default. | |
| 2169 | |
| 2170 Although glyphs can also be displayed in the margins, how to do this | |
| 2171 will not be described here. For more information on this, see | |
| 2172 @ref{Annotation Basics} (look for information on "layout types") and | |
| 2173 @ref{Extent Properties} (look for @code{begin-glyph-layout} and | |
| 2174 @code{end-glyph-layout}). | |
| 2175 | |
| 2176 @item | |
| 2177 The easiest way to insert a glyph into text is to create a zero-length | |
| 2178 extent at the point where you want the glyph to appear. | |
| 2179 | |
| 2180 Note that zero-length extents are attached to the character to the | |
| 2181 right of the extent; deleting this character will also delete the extent. | |
| 2182 | |
| 2183 @item | |
| 2184 It's often a good idea to assign a unique property to the newly-created | |
| 2185 extent, in case you later want to locate it, and replace any existing | |
| 2186 glyph with a different one (or just delete the existing one). In the | |
| 2187 above example, we are using "myimage" as our (hopefully) unique property | |
| 2188 name. | |
| 2189 | |
| 2190 If you need to locate all of the extents, you'll have to use functions | |
| 2191 like @code{extent-list} or @code{next-extent}, or provide additional | |
| 2192 parameters to the @code{extent-at} function. Assigning a unique | |
| 2193 property to the extent makes it easy to locate your extents; for | |
| 2194 example, @code{extent-list} can return only those extents with a | |
| 2195 particular property. @xref{Finding Extents}, and @ref{Mapping Over | |
| 2196 Extents}, for more information. | |
| 2197 | |
| 2198 @item | |
| 2199 Glyphs are displayed by assigning then to the @code{begin-glyph} or | |
| 2200 @code{end-glyph} property of the extent. For zero-length extents, it | |
| 2201 doesn't really matter if you assign the glyph to the @code{begin-glyph} | |
| 2202 or @code{end-glyph} property, as they are both at the same location; | |
| 2203 however, for non-zero-length extents (extents that cover one or more | |
| 2204 characters of text), it does matter which one you use. | |
| 2205 | |
| 2206 Assigning @code{nil} to the @code{begin-glyph} or @code{end-glyph} | |
| 2207 property will delete any existing glyph. In this case, you may also | |
| 2208 want to delete the extent, assuming that the extent is used for no other | |
| 2209 purpose. | |
| 2210 | |
| 2211 @item | |
| 2212 If you happen to insert two glyphs, side-by-side, note that the example | |
| 2213 @code{insert-glyph} function will have trouble, if it's again used at | |
| 2214 the same point (it can only locate one of the two extents). | |
| 2215 @xref{Finding Extents}, and @ref{Mapping Over Extents}, for more | |
| 2216 information on locating extents in a buffer. | |
| 2217 | |
| 2218 @item | |
| 2219 Among other things, glyphs provide a way of displaying graphics | |
| 2220 alongside text. Note, however, that glyphs only provide a way of | |
| 2221 displaying graphics; glyphs are not actually part of the text, and are | |
| 2222 only displayed alongside the text. If you save the text in the buffer, | |
| 2223 the graphics are not saved. The low-level glyph code does not provide a | |
| 2224 way of saving graphics with the text. If you need to save graphics and | |
| 2225 text, you have to write your own code to do this, and this topic is | |
| 2226 outside the scope of this discussion. | |
| 2227 | |
| 2228 @end itemize |