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