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
442
+ − 10 A @dfn{glyph} is an object that is used for pixmaps, widgets and
+ − 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
+ − 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 The actual image that is displayed (as opposed to its position or
+ − 21 clipping) is defined by an @dfn{image specifier} object contained
+ − 22 within the glyph. The separation between an image specifier object
+ − 23 and a glyph object is made because the glyph includes other properties
+ − 24 than just the actual image: e.g. the face it is displayed in (for text
+ − 25 images), the alignment of the image (when it is in a buffer), etc.
+ − 26
+ − 27 @defun glyphp object
+ − 28 This function returns @code{t} if @var{object} is a glyph.
+ − 29 @end defun
+ − 30
+ − 31 @menu
+ − 32 * Glyph Functions:: Functions for working with glyphs.
+ − 33 * Images:: Graphical images displayed in a frame.
+ − 34 * Glyph Types:: Each glyph has a particular type.
+ − 35 * Mouse Pointer:: Controlling the mouse pointer.
+ − 36 * Redisplay Glyphs:: Glyphs controlling various redisplay functions.
+ − 37 * Subwindows:: Inserting an externally-controlled subwindow
+ − 38 into a buffer.
707
+ − 39 * Glyph Examples:: Examples of how to work with glyphs.
428
+ − 40 @end menu
+ − 41
+ − 42 @node Glyph Functions
+ − 43 @section Glyph Functions
+ − 44
+ − 45 @menu
+ − 46 * Creating Glyphs:: Creating new glyphs.
+ − 47 * Glyph Properties:: Accessing and modifying a glyph's properties.
+ − 48 * Glyph Convenience Functions::
+ − 49 Convenience functions for accessing particular
+ − 50 properties of a glyph.
+ − 51 * Glyph Dimensions:: Determining the height, width, etc. of a glyph.
+ − 52 @end menu
+ − 53
+ − 54 @node Creating Glyphs
+ − 55 @subsection Creating Glyphs
+ − 56
+ − 57 @defun make-glyph &optional spec-list type
+ − 58 This function creates a new glyph object of type @var{type}.
+ − 59
+ − 60 @var{spec-list} is used to initialize the glyph's image. It is
+ − 61 typically an image instantiator (a string or a vector; @ref{Image
+ − 62 Specifiers}), but can also be a list of such instantiators (each one in
+ − 63 turn is tried until an image is successfully produced), a cons of a
+ − 64 locale (frame, buffer, etc.) and an instantiator, a list of such conses,
+ − 65 or any other form accepted by @code{canonicalize-spec-list}.
+ − 66 @xref{Specifiers}, for more information about specifiers.
+ − 67
+ − 68 @var{type} specifies the type of the glyph, which specifies in which
+ − 69 contexts the glyph can be used, and controls the allowable image types
+ − 70 into which the glyph's image can be instantiated. @var{type} should be
+ − 71 one of @code{buffer} (used for glyphs in an extent, the modeline, the
+ − 72 toolbar, or elsewhere in a buffer), @code{pointer} (used for the
+ − 73 mouse-pointer), or @code{icon} (used for a frame's icon), and defaults
+ − 74 to @code{buffer}. @xref{Glyph Types}.
442
+ − 75
+ − 76 A glyph in XEmacs does @strong{NOT} refer to a single unit of textual
+ − 77 display (the XEmacs term for this is @dfn{rune}), but rather is an
+ − 78 object encapsulating a graphical element, such as an image or widget (an
+ − 79 element such as a button or text field; @dfn{widget} is the term for
+ − 80 this under X Windows, and it's called a @dfn{control} under MS Windows).
+ − 81 This graphical element could appear in a buffer, a margin, a gutter, or
+ − 82 a toolbar, or as a mouse pointer or an icon, for example.
+ − 83
+ − 84 Creating a glyph using @code{make-glyph} does not specify @emph{where}
+ − 85 the glyph will be used, but it does specify @emph{what} the glyph will
444
+ − 86 look like. In particular, @var{spec-list} is used to specify this, and it's
442
+ − 87 used to initialize the glyph's @code{image} property, which is an image
+ − 88 specifier. (Note that @dfn{image} as used in the context of a glyph's
+ − 89 @code{image} property or in the terms @dfn{image specifier}, @dfn{image
+ − 90 instantiator}, or @dfn{image instance} does not refer to what people
+ − 91 normally think of as an image (which in XEmacs is called a
+ − 92 @dfn{pixmap}), but to any graphical element---a pixmap, a widget, or
+ − 93 even a block of text, when used in the places that call for a glyph.)
444
+ − 94 The format of the @var{spec-list} is typically an image instantiator (a string
442
+ − 95 or a vector; @ref{Image Specifiers}), but can also be a list of such
+ − 96 instantiators (each one in turn is tried until an image is successfully
+ − 97 produced), a cons of a locale (frame, buffer, etc.) and an
+ − 98 instantiator, a list of such conses, or any other form accepted by
+ − 99 @code{canonicalize-spec-list}. @xref{Specifiers}, for more information
+ − 100 about specifiers.
+ − 101
+ − 102 If you're not familiar with specifiers, you should be in order to
+ − 103 understand how glyphs work. The clearest introduction to specifiers
+ − 104 is in the Lispref manual, available under Info. (Choose
+ − 105 Help->Info->Info Contents on the menubar or type C-h i.) You can
+ − 106 also see @code{make-specifier} for a capsule summary. What's important to
+ − 107 keep in mind is that a specifier lets you set a different value for
+ − 108 any particular buffer, window, frame, device, or console. This allows
+ − 109 for a great deal of flexibility; in particular, only one global glyph
+ − 110 needs to exist for a particular purpose (e.g. the icon used to represent
+ − 111 an iconified frame, the mouse pointer used over particular areas of a
+ − 112 frame, etc.), and in these cases you do not create your own glyph, but
+ − 113 rather modify the existing one.
+ − 114
+ − 115 As well as using @var{spec-list} to initialize the glyph, you can set
+ − 116 specifications using @code{set-glyph-image}. Note that, due to a
+ − 117 possibly questionable historical design decision, a glyph itself is not
+ − 118 actually a specifier, but rather is an object containing an image
+ − 119 specifier (as well as other, seldom-used properties). Therefore, you
+ − 120 cannot set or access specifications for the glyph's image by directly
+ − 121 using @code{set-specifier}, @code{specifier-instance} or the like on the
+ − 122 glyph; instead use them on @code{(glyph-image @var{glyph})} or use the
+ − 123 convenience functions @code{set-glyph-image},
+ − 124 @code{glyph-image-instance}, and @code{glyph-image}.
+ − 125
+ − 126 Once you have created a glyph, you specify where it will be used as
+ − 127 follows:
+ − 128
+ − 129 @itemize @bullet
+ − 130 @item
+ − 131 To insert a glyph into a buffer, create an extent in the buffer and then
+ − 132 use @code{set-extent-begin-glyph} or @code{set-extent-end-glyph} to set
+ − 133 a glyph to be displayed at the corresponding edge of the extent. (It is
+ − 134 common to create zero-width extents for this purpose.)
+ − 135
+ − 136 @item
+ − 137 To insert a glyph into the left or right margin of a buffer, first
+ − 138 make sure the margin is visible by setting a value for the specifiers
+ − 139 @code{left-margin-width} or @code{right-margin-width}. (Not strictly necessary
+ − 140 when using margin glyphs with layout policy @code{whitespace}.) Then follow
+ − 141 the same procedure above for inserting a glyph in a buffer, and then
+ − 142 set a non-default layout policy for the glyph using
+ − 143 @code{set-extent-begin-glyph-layout} or @code{set-extent-end-glyph-layout}.
+ − 144 Alternatively, use the high-level annotations API (see
+ − 145 @code{make-annotation}). (In point of fact, you can also use the annotations
+ − 146 API for glyphs in a buffer, by setting a layout policy of @code{text}.)
+ − 147
+ − 148 @item
+ − 149 To insert a glyph into the modeline, just put the glyph directly as one
+ − 150 of the modeline elements. (Unfortunately you can't currently put a begin
+ − 151 glyph or end glyph on one of the modeline extents---they're ignored.)
+ − 152
+ − 153 @item
+ − 154 To insert a glyph into a toolbar, specify it as part of a toolbar
+ − 155 instantiator (typically set on the specifier @code{default-toolbar}).
+ − 156 See @code{default-toolbar} for more information. (Note that it is
+ − 157 standard practice to use a symbol in place of the glyph list in the
+ − 158 toolbar instantiator; the symbol is evalled to get the glyph list. This
+ − 159 facilitates both creating the toolbar instantiator and modifying
+ − 160 individual glyphs in a toolbar later on. For example, you can change
+ − 161 the way that the Mail toolbar button looks by modifying the value of the
+ − 162 variable @code{toolbar-mail-icon} (in general, @code{toolbar-*-icon})
+ − 163 and then calling @code{(set-specifier-dirty-flag default-toolbar)}.
+ − 164 (#### Unfortunately this doesn't quite work the way it should; the
+ − 165 change will appear in new frames, but not existing ones.
+ − 166
+ − 167 @item
+ − 168 To insert a glyph into a gutter, create or modify a gutter instantiator
+ − 169 (typically set on the specifier @code{default-gutter}). Gutter
+ − 170 instantiators consist of strings or lists of strings, so to insert a
+ − 171 glyph, create an extent over the string, and use
+ − 172 @code{set-extent-begin-glyph} or @code{set-extent-end-glyph} to set a
+ − 173 glyph to be displayed at the corresponding edge of the extent, just like
+ − 174 for glyphs in a buffer.
+ − 175
+ − 176 @item
+ − 177 To use a glyph as the icon for a frame, you do not actually create a new
+ − 178 glyph; rather, you change the specifications for the existing glyph
+ − 179 @code{frame-icon-glyph}. (Remember that, because of the specifier nature
+ − 180 of glyphs, you can set different values for any particular buffer or
+ − 181 frame.)
+ − 182
+ − 183 @item
+ − 184 To use a glyph as the mouse pointer, in general you do not create a new
+ − 185 glyph, but rather you change the specifications of various existing
+ − 186 glyphs, such as @code{text-pointer-glyph} for the pointer used over
+ − 187 text, @code{modeline-pointer-glyph} for the pointer used over the
+ − 188 modeline, etc. Do an apropos over @code{*-pointer-glyph} to find all of
+ − 189 them. (Note also that you can temporarily set the mouse pointer to some
+ − 190 specific shape by using @code{set-frame-pointer}, which takes an image
+ − 191 instance, as obtained from calling @code{glyph-image-instance} on a glyph
+ − 192 of type @code{pointer} -- either one of the above-mentioned variables or
+ − 193 one you created yourself. (See below for what it means to create a
+ − 194 glyph of type @code{pointer}.) This pointer will last only until the
+ − 195 next mouse motion event is processed or certain other things happen,
+ − 196 such as creating or deleting a window. (In fact, the above-mentioned
+ − 197 pointer glyph variables are implemented as part of the default handler
+ − 198 for mouse motion events. If you want to customize this behavior, take a
+ − 199 look at @code{mode-motion-hook}, or @code{mouse-motion-handler} if you
+ − 200 really want to get low-level.)
+ − 201
+ − 202 @item
+ − 203 To use a glyph to control the shape of miscellaneous redisplay effects
+ − 204 such as the truncation and continuation markers, set the appropriate
+ − 205 existing glyph variables, as for icons and pointers above. See
+ − 206 @code{continuation-glyph}, @code{control-arrow-glyph},
+ − 207 @code{hscroll-glyph}, @code{invisible-text-glyph},
+ − 208 @code{octal-escape-glyph}, and @code{truncation-glyph}. See also
+ − 209 @code{overlay-arrow-string}, an odd redisplay leftover which can be set
+ − 210 to a glyph you created, and will cause the glyph to be displayed on top
+ − 211 of the text position specified in the marker stored in
+ − 212 @code{overlay-arrow-position}.
+ − 213
+ − 214 @item
+ − 215 To use a glyph in a display table (i.e. to control the appearance of any
+ − 216 individual character), create the appropriate character glyphs and then
+ − 217 set a specification for the specifier @code{current-display-table},
+ − 218 which controls the appearance of characters. You can also set an
+ − 219 overriding display table for use with text displayed in a particular
+ − 220 face; see @code{set-face-display-table} and @code{make-display-table}.
+ − 221 #### Note: Display tables do not currently support general Mule
+ − 222 characters. They will be overhauled at some point to support this
+ − 223 and to provide other features required under Mule.
+ − 224
+ − 225 @item
+ − 226 To use a glyph as the background pixmap of a face: Note that the
+ − 227 background pixmap of a face is actually an image specifier -- probably
+ − 228 the only place in XEmacs where an image specifier occurs outside of a
+ − 229 glyph. Similarly to how the glyph's image specifier works, you don't
+ − 230 create your own image specifier, but rather add specifications to the
+ − 231 existing one (using @code{set-face-background-pixmap}). Note that the
+ − 232 image instance that is generated in order to actually display the
+ − 233 background pixmap is of type @code{mono-pixmap}, meaning that it's a
+ − 234 two-color image and the foreground and background of the image get
+ − 235 filled in with the corresponding colors from the face.
+ − 236 @end itemize
+ − 237
+ − 238 It is extremely rare that you will ever have to specify a value for
444
+ − 239 @var{type}, which should be one of @code{buffer} (used for glyphs in an
442
+ − 240 extent, the modeline, the toolbar, or elsewhere in a buffer),
+ − 241 @code{pointer} (used for the mouse-pointer), or @code{icon} (used for a
+ − 242 frame's icon), and defaults to @code{buffer}. The only cases where it
+ − 243 needs to be specified is when creating icon or pointer glyphs, and in
+ − 244 both cases the necessary glyphs have already been created at startup and
+ − 245 are accessed through the appropriate variables,
+ − 246 e.g. @code{text-pointer-glyph} (or in general, @code{*-pointer-glyph})
+ − 247 and @code{frame-icon-glyph}. @xref{Glyph Types}.
428
+ − 248 @end defun
+ − 249
+ − 250 @defun make-glyph-internal &optional type
+ − 251 This function creates a new, uninitialized glyph of type @var{type}.
+ − 252 @end defun
+ − 253
+ − 254 @defun make-pointer-glyph &optional spec-list
442
+ − 255
+ − 256 Return a new @code{pointer-glyph} object with the specification list
+ − 257 @var{spec-list}. This function is equivalent to calling
+ − 258 @code{make-glyph} with a @var{type} of @code{pointer}.
+ − 259
+ − 260 It is extremely unlikely that you will ever need to create a pointer
+ − 261 glyph. Instead, you probably want to be calling @code{set-glyph-image}
+ − 262 on an existing glyph, e.g. @code{text-pointer-glyph}.
428
+ − 263 @end defun
+ − 264
+ − 265 @defun make-icon-glyph &optional spec-list
442
+ − 266
+ − 267 Return a new @code{pointer-glyph} object with the specification list
+ − 268 @var{spec-list}. This function is equivalent to calling
+ − 269 @code{make-glyph} with a @var{type} of @code{icon}.
+ − 270
+ − 271 It is extremely unlikely that you will ever need to create a pointer
+ − 272 glyph. Instead, you probably want to be calling @code{set-glyph-image}
+ − 273 on an existing glyph, e.g. @code{text-pointer-glyph}.
428
+ − 274 @end defun
+ − 275
+ − 276 @node Glyph Properties
+ − 277 @subsection Glyph Properties
+ − 278
+ − 279 Each glyph has a list of properties, which control all of the aspects of
+ − 280 the glyph's appearance. The following symbols have predefined meanings:
+ − 281
+ − 282 @table @code
+ − 283 @item image
+ − 284 The image used to display the glyph.
+ − 285
+ − 286 @item baseline
+ − 287 Percent above baseline that glyph is to be displayed. Only for glyphs
+ − 288 displayed inside of a buffer.
+ − 289
+ − 290 @item contrib-p
+ − 291 Whether the glyph contributes to the height of the line it's on.
+ − 292 Only for glyphs displayed inside of a buffer.
+ − 293
+ − 294 @item face
+ − 295 Face of this glyph (@emph{not} a specifier).
+ − 296 @end table
+ − 297
+ − 298 @defun set-glyph-property glyph property value &optional locale tag-set how-to-add
+ − 299 This function changes a property of a @var{glyph}.
+ − 300
+ − 301 For built-in properties, the actual value of the property is a specifier
+ − 302 and you cannot change this; but you can change the specifications within
+ − 303 the specifier, and that is what this function will do. For user-defined
+ − 304 properties, you can use this function to either change the actual value
+ − 305 of the property or, if this value is a specifier, change the
+ − 306 specifications within it.
+ − 307
+ − 308 If @var{property} is a built-in property, the specifications to be added
+ − 309 to this property can be supplied in many different ways:
+ − 310
+ − 311 @itemize @bullet
+ − 312 @item
+ − 313 If @var{value} is a simple instantiator (e.g. a string naming a pixmap
+ − 314 filename) or a list of instantiators, then the instantiator(s) will be
+ − 315 added as a specification of the property for the given @var{locale}
+ − 316 (which defaults to @code{global} if omitted).
+ − 317
+ − 318 @item
+ − 319 If @var{value} is a list of specifications (each of which is a cons of a
+ − 320 locale and a list of instantiators), then @var{locale} must be
+ − 321 @code{nil} (it does not make sense to explicitly specify a locale in
+ − 322 this case), and specifications will be added as given.
+ − 323
+ − 324 @item
+ − 325 If @var{value} is a specifier (as would be returned by
+ − 326 @code{glyph-property} if no @var{locale} argument is given), then some
+ − 327 or all of the specifications in the specifier will be added to the
+ − 328 property. In this case, the function is really equivalent to
+ − 329 @code{copy-specifier} and @var{locale} has the same semantics (if it is
+ − 330 a particular locale, the specification for the locale will be copied; if
+ − 331 a locale type, specifications for all locales of that type will be
+ − 332 copied; if @code{nil} or @code{all}, then all specifications will be
+ − 333 copied).
+ − 334 @end itemize
+ − 335
+ − 336 @var{how-to-add} should be either @code{nil} or one of the symbols
+ − 337 @code{prepend}, @code{append}, @code{remove-tag-set-prepend},
+ − 338 @code{remove-tag-set-append}, @code{remove-locale},
+ − 339 @code{remove-locale-type}, or @code{remove-all}. See
+ − 340 @code{copy-specifier} and @code{add-spec-to-specifier} for a description
+ − 341 of what each of these means. Most of the time, you do not need to worry
+ − 342 about this argument; the default behavior usually is fine.
+ − 343
+ − 344 In general, it is OK to pass an instance object (e.g. as returned by
+ − 345 @code{glyph-property-instance}) as an instantiator in place of an actual
+ − 346 instantiator. In such a case, the instantiator used to create that
+ − 347 instance object will be used (for example, if you set a font-instance
+ − 348 object as the value of the @code{font} property, then the font name used
+ − 349 to create that object will be used instead). If some cases, however,
+ − 350 doing this conversion does not make sense, and this will be noted in the
+ − 351 documentation for particular types of instance objects.
+ − 352
+ − 353 If @var{property} is not a built-in property, then this function will
+ − 354 simply set its value if @var{locale} is @code{nil}. However, if
+ − 355 @var{locale} is given, then this function will attempt to add
+ − 356 @var{value} as the instantiator for the given @var{locale}, using
+ − 357 @code{add-spec-to-specifier}. If the value of the property is not a
+ − 358 specifier, it will automatically be converted into a @code{generic}
+ − 359 specifier.
+ − 360 @end defun
+ − 361
+ − 362 @defun glyph-property glyph property &optional locale
+ − 363 This function returns @var{glyph}'s value of the given @var{property}.
+ − 364
+ − 365 If @var{locale} is omitted, the @var{glyph}'s actual value for
+ − 366 @var{property} will be returned. For built-in properties, this will be
+ − 367 a specifier object of a type appropriate to the property (e.g. a font or
+ − 368 color specifier). For other properties, this could be anything.
+ − 369
+ − 370 If @var{locale} is supplied, then instead of returning the actual value,
+ − 371 the specification(s) for the given locale or locale type will be
+ − 372 returned. This will only work if the actual value of @var{property} is
+ − 373 a specifier (this will always be the case for built-in properties, but
+ − 374 may or may not apply to user-defined properties). If the actual value
+ − 375 of @var{property} is not a specifier, this value will simply be returned
+ − 376 regardless of @var{locale}.
+ − 377
+ − 378 The return value will be a list of instantiators (e.g. vectors
+ − 379 specifying pixmap data), or a list of specifications, each of which is a
+ − 380 cons of a locale and a list of instantiators. Specifically, if
+ − 381 @var{locale} is a particular locale (a buffer, window, frame, device, or
+ − 382 @code{global}), a list of instantiators for that locale will be
+ − 383 returned. Otherwise, if @var{locale} is a locale type (one of the
+ − 384 symbols @code{buffer}, @code{window}, @code{frame}, or @code{device}),
+ − 385 the specifications for all locales of that type will be returned.
+ − 386 Finally, if @var{locale} is @code{all}, the specifications for all
+ − 387 locales of all types will be returned.
+ − 388
+ − 389 The specifications in a specifier determine what the value of
+ − 390 @var{property} will be in a particular @dfn{domain} or set of
+ − 391 circumstances, which is typically a particular Emacs window along with
+ − 392 the buffer it contains and the frame and device it lies within. The
+ − 393 value is derived from the instantiator associated with the most specific
+ − 394 locale (in the order buffer, window, frame, device, and @code{global})
+ − 395 that matches the domain in question. In other words, given a domain
+ − 396 (i.e. an Emacs window, usually), the specifier for @var{property} will
+ − 397 first be searched for a specification whose locale is the buffer
+ − 398 contained within that window; then for a specification whose locale is
+ − 399 the window itself; then for a specification whose locale is the frame
+ − 400 that the window is contained within; etc. The first instantiator that
+ − 401 is valid for the domain (usually this means that the instantiator is
+ − 402 recognized by the device [i.e. the X server or TTY device] that the
+ − 403 domain is on). The function @code{glyph-property-instance} actually does
+ − 404 all this, and is used to determine how to display the glyph.
+ − 405 @end defun
+ − 406
+ − 407 @defun glyph-property-instance glyph property &optional domain default no-fallback
+ − 408 This function returns the instance of @var{glyph}'s @var{property} in the
+ − 409 specified @var{domain}.
+ − 410
+ − 411 Under most circumstances, @var{domain} will be a particular window, and
+ − 412 the returned instance describes how the specified property actually is
+ − 413 displayed for that window and the particular buffer in it. Note that
+ − 414 this may not be the same as how the property appears when the buffer is
+ − 415 displayed in a different window or frame, or how the property appears in
+ − 416 the same window if you switch to another buffer in that window; and in
+ − 417 those cases, the returned instance would be different.
+ − 418
+ − 419 The returned instance is an image-instance object, and you can query it
+ − 420 using the appropriate image instance functions. For example, you could use
+ − 421 @code{image-instance-depth} to find out the depth (number of color
+ − 422 planes) of a pixmap displayed in a particular window. The results might
+ − 423 be different from the results you would get for another window (perhaps
+ − 424 the user specified a different image for the frame that window is on; or
+ − 425 perhaps the same image was specified but the window is on a different X
+ − 426 server, and that X server has different color capabilities from this
+ − 427 one).
+ − 428
+ − 429 @var{domain} defaults to the selected window if omitted.
+ − 430
+ − 431 @var{domain} can be a frame or device, instead of a window. The value
+ − 432 returned for such a domain is used in special circumstances when a
+ − 433 more specific domain does not apply; for example, a frame value might be
+ − 434 used for coloring a toolbar, which is conceptually attached to a frame
+ − 435 rather than a particular window. The value is also useful in
+ − 436 determining what the value would be for a particular window within the
+ − 437 frame or device, if it is not overridden by a more specific
+ − 438 specification.
+ − 439
+ − 440 If @var{property} does not name a built-in property, its value will
+ − 441 simply be returned unless it is a specifier object, in which case it
+ − 442 will be instanced using @code{specifier-instance}.
+ − 443
+ − 444 Optional arguments @var{default} and @var{no-fallback} are the same as
+ − 445 in @code{specifier-instance}. @xref{Specifiers}.
+ − 446 @end defun
+ − 447
+ − 448 @defun remove-glyph-property glyph property &optional locale tag-set exact-p
+ − 449 This function removes a property from a glyph. For built-in properties,
+ − 450 this is analogous to @code{remove-specifier}. @xref{Specifiers,
+ − 451 remove-specifier-p}, for the meaning of the @var{locale}, @var{tag-set},
+ − 452 and @var{exact-p} arguments.
+ − 453 @end defun
+ − 454
+ − 455 @node Glyph Convenience Functions
+ − 456 @subsection Glyph Convenience Functions
+ − 457
+ − 458 The following functions are provided for working with specific
+ − 459 properties of a glyph. Note that these are exactly like calling
+ − 460 the general functions described above and passing in the
+ − 461 appropriate value for @var{property}.
+ − 462
+ − 463 Remember that if you want to determine the ``value'' of a
+ − 464 specific glyph property, you probably want to use the @code{*-instance}
+ − 465 functions. For example, to determine whether a glyph contributes
+ − 466 to its line height, use @code{glyph-contrib-p-instance}, not
+ − 467 @code{glyph-contrib-p}. (The latter will return a boolean specifier
+ − 468 or a list of specifications, and you probably aren't concerned with
+ − 469 these.)
+ − 470
+ − 471 @defun glyph-image glyph &optional locale
+ − 472 This function is equivalent to calling @code{glyph-property} with
+ − 473 a property of @code{image}. The return value will be an image
+ − 474 specifier if @var{locale} is @code{nil} or omitted; otherwise,
+ − 475 it will be a specification or list of specifications.
+ − 476 @end defun
+ − 477
+ − 478 @defun set-glyph-image glyph spec &optional locale tag-set how-to-add
+ − 479 This function is equivalent to calling @code{set-glyph-property} with
+ − 480 a property of @code{image}.
+ − 481 @end defun
+ − 482
+ − 483 @defun glyph-image-instance glyph &optional domain default no-fallback
+ − 484 This function returns the instance of @var{glyph}'s image in the given
+ − 485 @var{domain}, and is equivalent to calling
+ − 486 @code{glyph-property-instance} with a property of @code{image}. The
+ − 487 return value will be an image instance.
+ − 488
+ − 489 Normally @var{domain} will be a window or @code{nil} (meaning the
+ − 490 selected window), and an instance object describing how the image
+ − 491 appears in that particular window and buffer will be returned.
+ − 492 @end defun
+ − 493
+ − 494 @defun glyph-contrib-p glyph &optional locale
+ − 495 This function is equivalent to calling @code{glyph-property} with
+ − 496 a property of @code{contrib-p}. The return value will be a boolean
+ − 497 specifier if @var{locale} is @code{nil} or omitted; otherwise,
+ − 498 it will be a specification or list of specifications.
+ − 499 @end defun
+ − 500
+ − 501 @defun set-glyph-contrib-p glyph spec &optional locale tag-set how-to-add
+ − 502 This function is equivalent to calling @code{set-glyph-property} with
+ − 503 a property of @code{contrib-p}.
+ − 504 @end defun
+ − 505
+ − 506 @defun glyph-contrib-p-instance glyph &optional domain default no-fallback
+ − 507 This function returns whether the glyph contributes to its line height
+ − 508 in the given @var{domain}, and is equivalent to calling
+ − 509 @code{glyph-property-instance} with a property of @code{contrib-p}. The
+ − 510 return value will be either @code{nil} or @code{t}. (Normally @var{domain}
+ − 511 will be a window or @code{nil}, meaning the selected window.)
+ − 512 @end defun
+ − 513
+ − 514 @defun glyph-baseline glyph &optional locale
+ − 515 This function is equivalent to calling @code{glyph-property} with a
+ − 516 property of @code{baseline}. The return value will be a specifier if
+ − 517 @var{locale} is @code{nil} or omitted; otherwise, it will be a
+ − 518 specification or list of specifications.
+ − 519 @end defun
+ − 520
+ − 521 @defun set-glyph-baseline glyph spec &optional locale tag-set how-to-add
+ − 522 This function is equivalent to calling @code{set-glyph-property} with
+ − 523 a property of @code{baseline}.
+ − 524 @end defun
+ − 525
+ − 526 @defun glyph-baseline-instance glyph &optional domain default no-fallback
+ − 527 This function returns the instance of @var{glyph}'s baseline value in
+ − 528 the given @var{domain}, and is equivalent to calling
+ − 529 @code{glyph-property-instance} with a property of @code{baseline}. The
+ − 530 return value will be an integer or @code{nil}.
+ − 531
+ − 532 Normally @var{domain} will be a window or @code{nil} (meaning the
+ − 533 selected window), and an instance object describing the baseline value
+ − 534 appears in that particular window and buffer will be returned.
+ − 535 @end defun
+ − 536
+ − 537 @defun glyph-face glyph
+ − 538 This function returns the face of @var{glyph}. (Remember, this is
+ − 539 not a specifier, but a simple property.)
+ − 540 @end defun
+ − 541
+ − 542 @defun set-glyph-face glyph face
+ − 543 This function changes the face of @var{glyph} to @var{face}.
+ − 544 @end defun
+ − 545
+ − 546 @node Glyph Dimensions
+ − 547 @subsection Glyph Dimensions
+ − 548
+ − 549 @defun glyph-width glyph &optional window
+ − 550 This function returns the width of @var{glyph} on @var{window}. This
+ − 551 may not be exact as it does not take into account all of the context
+ − 552 that redisplay will.
+ − 553 @end defun
+ − 554
+ − 555 @defun glyph-ascent glyph &optional window
+ − 556 This function returns the ascent value of @var{glyph} on @var{window}.
+ − 557 This may not be exact as it does not take into account all of the
+ − 558 context that redisplay will.
+ − 559 @end defun
+ − 560
+ − 561 @defun glyph-descent glyph &optional window
+ − 562 This function returns the descent value of @var{glyph} on @var{window}.
+ − 563 This may not be exact as it does not take into account all of the
+ − 564 context that redisplay will.
+ − 565 @end defun
+ − 566
+ − 567 @defun glyph-height glyph &optional window
+ − 568 This function returns the height of @var{glyph} on @var{window}. (This
+ − 569 is equivalent to the sum of the ascent and descent values.) This may
+ − 570 not be exact as it does not take into account all of the context that
+ − 571 redisplay will.
+ − 572 @end defun
+ − 573
+ − 574 @node Images
+ − 575 @section Images
+ − 576
+ − 577 @menu
+ − 578 * Image Specifiers:: Specifying how an image will appear.
+ − 579 * Image Instantiator Conversion::
+ − 580 Conversion is applied to image instantiators
+ − 581 at the time they are added to an
+ − 582 image specifier or at the time they
+ − 583 are passed to @code{make-image-instance}.
+ − 584 * Image Instances:: What an image specifier gets instanced as.
+ − 585 @end menu
+ − 586
+ − 587 @node Image Specifiers
+ − 588 @subsection Image Specifiers
+ − 589 @cindex image specifiers
+ − 590
+ − 591 An image specifier is used to describe the actual image of a glyph.
+ − 592 It works like other specifiers (@pxref{Specifiers}), in that it contains
+ − 593 a number of specifications describing how the image should appear in a
+ − 594 variety of circumstances. These specifications are called @dfn{image
+ − 595 instantiators}. When XEmacs wants to display the image, it instantiates
+ − 596 the image into an @dfn{image instance}. Image instances are their own
+ − 597 primitive object type (similar to font instances and color instances),
+ − 598 describing how the image appears in a particular domain. (On the other
+ − 599 hand, image instantiators, which are just descriptions of how the image
+ − 600 should appear, are represented using strings or vectors.)
+ − 601
+ − 602 @defun image-specifier-p object
+ − 603 This function returns non-@code{nil} if @var{object} is an image specifier.
+ − 604 Usually, an image specifier results from calling @code{glyph-image} on
+ − 605 a glyph.
+ − 606 @end defun
+ − 607
+ − 608 @defun make-image-specifier spec-list
442
+ − 609 This function creates a new image specifier object and initializes it
+ − 610 according to @var{spec-list}. @xref{Specifiers}.
+ − 611
+ − 612 Note that, in practice, you rarely, if ever, need to actually create an
+ − 613 image specifier! (This function exists mainly for completeness.) Pretty
+ − 614 much the only use for image specifiers is to control how glyphs are
+ − 615 displayed, and the image specifier associated with a glyph (the
+ − 616 @code{image} property of a glyph) is created automatically when a glyph
+ − 617 is created and need not (and cannot, for that matter) ever be changed
+ − 618 (@pxref{Glyphs}). In fact, the design decision to create a separate
+ − 619 image specifier type, rather than make glyphs themselves be specifiers,
+ − 620 is debatable---the other properties of glyphs are rarely used and could
+ − 621 conceivably have been incorporated into the glyph's instantiator. The
+ − 622 rarely used glyph types (buffer, pointer, icon) could also have been
+ − 623 incorporated into the instantiator.
428
+ − 624 @end defun
+ − 625
+ − 626 Image instantiators come in many formats: @code{xbm}, @code{xpm},
+ − 627 @code{gif}, @code{jpeg}, etc. This describes the format of the data
+ − 628 describing the image. The resulting image instances also come in many
440
+ − 629 types---@code{mono-pixmap}, @code{color-pixmap}, @code{text},
428
+ − 630 @code{pointer}, etc. This refers to the behavior of the image and the
+ − 631 sorts of places it can appear. (For example, a color-pixmap image has
+ − 632 fixed colors specified for it, while a mono-pixmap image comes in two
+ − 633 unspecified shades ``foreground'' and ``background'' that are determined
+ − 634 from the face of the glyph or surrounding text; a text image appears as
+ − 635 a string of text and has an unspecified foreground, background, and
+ − 636 font; a pointer image behaves like a mono-pixmap image but can only be
+ − 637 used as a mouse pointer [mono-pixmap images cannot be used as mouse
+ − 638 pointers]; etc.) It is important to keep the distinction between image
+ − 639 instantiator format and image instance type in mind. Typically, a given
+ − 640 image instantiator format can result in many different image instance
+ − 641 types (for example, @code{xpm} can be instanced as @code{color-pixmap},
+ − 642 @code{mono-pixmap}, or @code{pointer}; whereas @code{cursor-font} can be
+ − 643 instanced only as @code{pointer}), and a particular image instance type
+ − 644 can be generated by many different image instantiator formats (e.g.
+ − 645 @code{color-pixmap} can be generated by @code{xpm}, @code{gif},
+ − 646 @code{jpeg}, etc.).
+ − 647
+ − 648 @xref{Image Instances}, for a more detailed discussion of image
+ − 649 instance types.
+ − 650
+ − 651 An image instantiator should be a string or a vector of the form
+ − 652
+ − 653 @example
+ − 654 @code{[@var{format} @var{:keyword} @var{value} ...]}
+ − 655 @end example
+ − 656
+ − 657 i.e. a format symbol followed by zero or more alternating keyword-value
+ − 658 pairs. The @dfn{format} field should be a symbol, one of
+ − 659
+ − 660 @table @code
+ − 661 @item nothing
442
+ − 662 Don't display anything; no keywords are valid for this. Can only be
+ − 663 instanced as @code{nothing}.
428
+ − 664 @item string
442
+ − 665 Display this image as a text string. Can only be instanced
428
+ − 666 as @code{text}, although support for instancing as @code{mono-pixmap}
442
+ − 667 should be added.
428
+ − 668 @item formatted-string
442
+ − 669 Display this image as a text string with replaceable fields,
+ − 670 similar to a modeline format string; not currently implemented.
428
+ − 671 @item xbm
442
+ − 672 An X bitmap; only if X support was compiled into this XEmacs. Can be
428
+ − 673 instanced as @code{mono-pixmap}, @code{color-pixmap}, or
442
+ − 674 @code{pointer}.
428
+ − 675 @item xpm
442
+ − 676 An XPM pixmap; only if XPM support was compiled into this XEmacs. Can
428
+ − 677 be instanced as @code{color-pixmap}, @code{mono-pixmap}, or
+ − 678 @code{pointer}. XPM is an add-on library for X that was designed to
+ − 679 rectify the shortcomings of the XBM format. Most implementations of X
+ − 680 include the XPM library as a standard part. If your vendor does not, it
+ − 681 is highly recommended that you download it and install it. You can get
442
+ − 682 it from the standard XEmacs FTP site, among other places.
428
+ − 683 @item xface
442
+ − 684 An X-Face bitmap, used to encode people's faces in e-mail messages;
428
+ − 685 only if X-Face support was compiled into this XEmacs. Can be instanced
442
+ − 686 as @code{mono-pixmap}, @code{color-pixmap}, or @code{pointer}.
428
+ − 687 @item gif
442
+ − 688 A GIF87 or GIF89 image; only if GIF support was compiled into this
428
+ − 689 XEmacs. Can be instanced as @code{color-pixmap}. Note that XEmacs
+ − 690 includes GIF decoding functions as a standard part of it, so if you have
+ − 691 X support, you will normally have GIF support, unless you explicitly
442
+ − 692 disable it at configure time.
428
+ − 693 @item jpeg
442
+ − 694 A JPEG-format image; only if JPEG support was compiled into this
428
+ − 695 XEmacs. Can be instanced as @code{color-pixmap}. If you have the JPEG
+ − 696 libraries present on your system when XEmacs is built, XEmacs will
+ − 697 automatically detect this and use them, unless you explicitly disable it
442
+ − 698 at configure time.
428
+ − 699 @item png
442
+ − 700 A PNG/GIF24 image; only if PNG support was compiled into this XEmacs.
+ − 701 Can be instanced as @code{color-pixmap}.
428
+ − 702 @item tiff
442
+ − 703 A TIFF-format image; only if TIFF support was compiled into this XEmacs.
428
+ − 704 @item cursor-font
442
+ − 705 One of the standard cursor-font names, such as @samp{watch} or
428
+ − 706 @samp{right_ptr} under X. Under X, this is, more specifically, any of
+ − 707 the standard cursor names from appendix B of the Xlib manual [also known
+ − 708 as the file @file{<X11/cursorfont.h>}] minus the @samp{XC_} prefix. On
+ − 709 other window systems, the valid names will be specific to the type of
442
+ − 710 window system. Can only be instanced as @code{pointer}.
428
+ − 711 @item font
442
+ − 712 A glyph from a font; i.e. the name of a font, and glyph index into it
428
+ − 713 of the form @samp{@var{font} fontname index [[mask-font] mask-index]}.
+ − 714 Only if X support was compiled into this XEmacs. Currently can only be
442
+ − 715 instanced as @code{pointer}, although this should probably be fixed.
+ − 716 @item mswindows-resource
+ − 717 An MS Windows pointer resource. Specifies a resource to retrieve
+ − 718 directly from the system (an OEM resource) or from a file, particularly
+ − 719 an executable file. If the resource is to be retrieved from a file, use
+ − 720 :file and optionally :resource-id. Otherwise use :resource-id. Always
+ − 721 specify :resource-type to specify the type (cursor, bitmap or icon) of
+ − 722 the resource. Possible values for :resource-id are listed below. Can
+ − 723 be instanced as @code{pointer} or @code{color-pixmap}.
428
+ − 724 @item subwindow
442
+ − 725 An embedded windowing system window. Can only be instanced as
+ − 726 @code{subwindow}.
+ − 727 @item button
+ − 728 A button widget; either a push button, radio button or toggle button.
+ − 729 Can only be instanced as @code{widget}.
+ − 730 @item combo-box
+ − 731 A drop list of selectable items in a widget, for editing text.
+ − 732 Can only be instanced as @code{widget}.
+ − 733 @item edit-field
+ − 734 A text editing widget. Can only be instanced as @code{widget}.
+ − 735 @item label
+ − 736 A static, text-only, widget; for displaying text. Can only be instanced
+ − 737 as @code{widget}.
+ − 738 @item layout
+ − 739 A widget for controlling the positioning of children underneath it.
+ − 740 Through the use of nested layouts, a widget hierarchy can be created
+ − 741 which can have the appearance of any standard dialog box or similar
+ − 742 arrangement; all of this is counted as one @dfn{glyph} and could appear
+ − 743 in many of the places that expect a single glyph. Can only be instanced
+ − 744 as @code{widget}.
+ − 745 @item native-layout
+ − 746 @c #### Document me better!
+ − 747 The native version of a layout widget.
+ − 748 Can only be instanced as @code{widget}.
+ − 749 @item progress-gauge
+ − 750 A sliding widget, for showing progress. Can only be instanced as
+ − 751 @code{widget}.
+ − 752 @item tab-control
+ − 753 A tab widget; a series of user selectable tabs. Can only be instanced
+ − 754 as @code{widget}.
+ − 755 @item tree-view
+ − 756 A folding widget. Can only be instanced as @code{widget}.
+ − 757 @item scrollbar
+ − 758 A scrollbar widget. Can only be instanced as @code{widget}.
428
+ − 759 @item autodetect
442
+ − 760 XEmacs tries to guess what format the data is in. If X support exists,
428
+ − 761 the data string will be checked to see if it names a filename. If so,
+ − 762 and this filename contains XBM or XPM data, the appropriate sort of
+ − 763 pixmap or pointer will be created. [This includes picking up any
+ − 764 specified hotspot or associated mask file.] Otherwise, if @code{pointer}
+ − 765 is one of the allowable image-instance types and the string names a
+ − 766 valid cursor-font name, the image will be created as a pointer.
+ − 767 Otherwise, the image will be displayed as text. If no X support exists,
442
+ − 768 the image will always be displayed as text.
+ − 769 @item inherit
+ − 770 Inherit from the background-pixmap property of a face. Can only be
+ − 771 instanced as @code{mono-pixmap}.
428
+ − 772 @end table
+ − 773
+ − 774 The valid keywords are:
+ − 775
+ − 776 @table @code
+ − 777 @item :data
442
+ − 778 Inline data. For most formats above, this should be a string. For
428
+ − 779 XBM images, this should be a list of three elements: width, height, and
+ − 780 a string of bit data. This keyword is not valid for instantiator
442
+ − 781 format @code{nothing}.
428
+ − 782
+ − 783 @item :file
442
+ − 784 Data is contained in a file. The value is the name of this file. If
428
+ − 785 both @code{:data} and @code{:file} are specified, the image is created
+ − 786 from what is specified in @code{:data} and the string in @code{:file}
+ − 787 becomes the value of the @code{image-instance-file-name} function when
+ − 788 applied to the resulting image-instance. This keyword is not valid for
+ − 789 instantiator formats @code{nothing}, @code{string},
+ − 790 @code{formatted-string}, @code{cursor-font}, @code{font}, and
442
+ − 791 @code{autodetect}.
428
+ − 792
+ − 793 @item :foreground
+ − 794 @itemx :background
442
+ − 795 For @code{xbm}, @code{xface}, @code{cursor-font}, and @code{font}.
428
+ − 796 These keywords allow you to explicitly specify foreground and background
+ − 797 colors. The argument should be anything acceptable to
+ − 798 @code{make-color-instance}. This will cause what would be a
+ − 799 @code{mono-pixmap} to instead be colorized as a two-color color-pixmap,
+ − 800 and specifies the foreground and/or background colors for a pointer
442
+ − 801 instead of black and white.
428
+ − 802
+ − 803 @item :mask-data
442
+ − 804 For @code{xbm} and @code{xface}. This specifies a mask to be used with the
428
+ − 805 bitmap. The format is a list of width, height, and bits, like for
442
+ − 806 @code{:data}.
428
+ − 807
+ − 808 @item :mask-file
442
+ − 809 For @code{xbm} and @code{xface}. This specifies a file containing the
428
+ − 810 mask data. If neither a mask file nor inline mask data is given for an
+ − 811 XBM image, and the XBM image comes from a file, XEmacs will look for a
+ − 812 mask file with the same name as the image file but with @samp{Mask} or
+ − 813 @samp{msk} appended. For example, if you specify the XBM file
+ − 814 @file{left_ptr} [usually located in @file{/usr/include/X11/bitmaps}],
+ − 815 the associated mask file @file{left_ptrmsk} will automatically be picked
442
+ − 816 up.
428
+ − 817
+ − 818 @item :hotspot-x
+ − 819 @itemx :hotspot-y
442
+ − 820 For @code{xbm} and @code{xface}. These keywords specify a hotspot if
428
+ − 821 the image is instantiated as a @code{pointer}. Note that if the XBM
+ − 822 image file specifies a hotspot, it will automatically be picked up if no
442
+ − 823 explicit hotspot is given.
428
+ − 824
+ − 825 @item :color-symbols
442
+ − 826 Only for @code{xpm}. This specifies an alist that maps strings that
428
+ − 827 specify symbolic color names to the actual color to be used for that
+ − 828 symbolic color (in the form of a string or a color-specifier object).
+ − 829 If this is not specified, the contents of @code{xpm-color-symbols} are
442
+ − 830 used to generate the alist.
+ − 831 @item :resource-id
+ − 832 Only for @code{mswindows-resource}. This must be either an integer
+ − 833 (which directly specifies a resource number) or a string. Valid strings
+ − 834 are
+ − 835
+ − 836 For bitmaps:
+ − 837
+ − 838 "close", "uparrow", "dnarrow", "rgarrow", "lfarrow",
+ − 839 "reduce", "zoom", "restore", "reduced", "zoomd",
+ − 840 "restored", "uparrowd", "dnarrowd", "rgarrowd", "lfarrowd",
+ − 841 "mnarrow", "combo", "uparrowi", "dnarrowi", "rgarrowi",
+ − 842 "lfarrowi", "size", "btsize", "check", "checkboxes", and
+ − 843 "btncorners".
+ − 844
+ − 845 For cursors:
+ − 846
+ − 847 "normal", "ibeam", "wait", "cross", "up", "sizenwse",
+ − 848 "sizenesw", "sizewe", "sizens", "sizeall", and "no".
+ − 849
+ − 850 For icons:
+ − 851
+ − 852 "sample", "hand", "ques", "bang", "note", and "winlogo".
+ − 853 @item :resource-type
+ − 854 Only for @code{mswindows-resource}. This must be a symbol, either
+ − 855 @code{cursor}, @code{icon}, or @code{bitmap}, specifying the type of
+ − 856 resource to be retrieved.
+ − 857 @item :face
+ − 858 Only for @code{inherit}. This specifies the face to inherit from. For
+ − 859 widgets this also specifies the face to use for display. It defaults to
+ − 860 gui-element-face.
428
+ − 861 @end table
+ − 862
442
+ − 863 Keywords accepted as menu item specs are also accepted by widgets.
+ − 864 These are @code{:selected}, @code{:active}, @code{:suffix},
+ − 865 @code{:keys}, @code{:style}, @code{:filter}, @code{:config},
+ − 866 @code{:included}, @code{:key-sequence}, @code{:accelerator},
+ − 867 @code{:label} and @code{:callback}.
+ − 868
428
+ − 869 If instead of a vector, the instantiator is a string, it will be
+ − 870 converted into a vector by looking it up according to the specs in the
+ − 871 @code{console-type-image-conversion-list} for the console type of
+ − 872 the domain (usually a window; sometimes a frame or device) over which
+ − 873 the image is being instantiated.
+ − 874
+ − 875 If the instantiator specifies data from a file, the data will be read in
+ − 876 at the time that the instantiator is added to the image specifier (which
+ − 877 may be well before the image is actually displayed), and the
+ − 878 instantiator will be converted into one of the inline-data forms, with
+ − 879 the filename retained using a @code{:file} keyword. This implies that
+ − 880 the file must exist when the instantiator is added to the image, but
+ − 881 does not need to exist at any other time (e.g. it may safely be a
+ − 882 temporary file).
+ − 883
444
+ − 884 @defun valid-image-instantiator-format-p format &optional locale
428
+ − 885 This function returns non-@code{nil} if @var{format} is a valid image
444
+ − 886 instantiator format.
+ − 887
+ − 888 If @var{locale} is non-@code{nil} then the format is checked in that locale.
+ − 889 If @var{locale} is @code{nil} the current console is used.
+ − 890
+ − 891 Note that the return value for many formats listed above depends on
+ − 892 whether XEmacs was compiled with support for that format.
428
+ − 893 @end defun
+ − 894
+ − 895 @defun image-instantiator-format-list
+ − 896 This function return a list of valid image-instantiator formats.
+ − 897 @end defun
+ − 898
+ − 899 @defvar xpm-color-symbols
+ − 900 This variable holds definitions of logical color-names used when reading
+ − 901 XPM files. Elements of this list should be of the form
+ − 902 @code{(@var{color-name} @var{form-to-evaluate})}. The @var{color-name}
+ − 903 should be a string, which is the name of the color to define; the
+ − 904 @var{form-to-evaluate} should evaluate to a color specifier object, or a
+ − 905 string to be passed to @code{make-color-instance} (@pxref{Colors}). If
+ − 906 a loaded XPM file references a symbolic color called @var{color-name},
+ − 907 it will display as the computed color instead.
+ − 908
+ − 909 The default value of this variable defines the logical color names
+ − 910 @samp{"foreground"} and @samp{"background"} to be the colors of the
+ − 911 @code{default} face.
+ − 912 @end defvar
+ − 913
+ − 914 @defvar x-bitmap-file-path
444
+ − 915 A list of the directories in which X bitmap files may be found. If @code{nil},
428
+ − 916 this is initialized from the @samp{"*bitmapFilePath"} resource. This is
+ − 917 used by the @code{make-image-instance} function (however, note that if
+ − 918 the environment variable @samp{XBMLANGPATH} is set, it is consulted
+ − 919 first).
+ − 920 @end defvar
+ − 921
+ − 922 @node Image Instantiator Conversion
+ − 923 @subsection Image Instantiator Conversion
+ − 924 @cindex image instantiator conversion
+ − 925 @cindex conversion of image instantiators
+ − 926
+ − 927 @defun set-console-type-image-conversion-list console-type list
+ − 928 This function sets the image-conversion-list for consoles of the given
+ − 929 @var{console-type}. The image-conversion-list specifies how image
+ − 930 instantiators that are strings should be interpreted. Each element of
+ − 931 the list should be a list of two elements (a regular expression string
+ − 932 and a vector) or a list of three elements (the preceding two plus an
+ − 933 integer index into the vector). The string is converted to the vector
+ − 934 associated with the first matching regular expression. If a vector
+ − 935 index is specified, the string itself is substituted into that position
+ − 936 in the vector.
+ − 937
+ − 938 Note: The conversion above is applied when the image instantiator is
+ − 939 added to an image specifier, not when the specifier is actually
+ − 940 instantiated. Therefore, changing the image-conversion-list only affects
+ − 941 newly-added instantiators. Existing instantiators in glyphs and image
+ − 942 specifiers will not be affected.
+ − 943 @end defun
+ − 944
+ − 945 @defun console-type-image-conversion-list console-type
+ − 946 This function returns the image-conversion-list for consoles of the given
+ − 947 @var{console-type}.
+ − 948 @end defun
+ − 949
+ − 950 @node Image Instances
+ − 951 @subsection Image Instances
+ − 952 @cindex image instances
+ − 953
+ − 954 Image-instance objects encapsulate the way a particular image (pixmap,
+ − 955 etc.) is displayed on a particular device.
+ − 956
+ − 957 In most circumstances, you do not need to directly create image
+ − 958 instances; use a glyph instead. However, it may occasionally be useful
+ − 959 to explicitly create image instances, if you want more control over the
+ − 960 instantiation process.
+ − 961
+ − 962 @defun image-instance-p object
+ − 963 This function returns non-@code{nil} if @var{object} is an image instance.
+ − 964 @end defun
+ − 965
+ − 966 @menu
+ − 967 * Image Instance Types:: Each image instances has a particular type.
+ − 968 * Image Instance Functions:: Functions for working with image instances.
+ − 969 @end menu
+ − 970
+ − 971 @node Image Instance Types
+ − 972 @subsubsection Image Instance Types
+ − 973 @cindex image instance types
+ − 974
+ − 975 Image instances come in a number of different types. The type
+ − 976 of an image instance specifies the nature of the image: Whether
+ − 977 it is a text string, a mono pixmap, a color pixmap, etc.
+ − 978
+ − 979 The valid image instance types are
+ − 980
+ − 981 @table @code
+ − 982 @item nothing
+ − 983 Nothing is displayed.
+ − 984
+ − 985 @item text
+ − 986 Displayed as text. The foreground and background colors and the
+ − 987 font of the text are specified independent of the pixmap. Typically
+ − 988 these attributes will come from the face of the surrounding text,
+ − 989 unless a face is specified for the glyph in which the image appears.
+ − 990
+ − 991 @item mono-pixmap
+ − 992 Displayed as a mono pixmap (a pixmap with only two colors where the
+ − 993 foreground and background can be specified independent of the pixmap;
+ − 994 typically the pixmap assumes the foreground and background colors of
+ − 995 the text around it, unless a face is specified for the glyph in which
+ − 996 the image appears).
+ − 997 @item color-pixmap
+ − 998
+ − 999 Displayed as a color pixmap.
+ − 1000
+ − 1001 @item pointer
+ − 1002 Used as the mouse pointer for a window.
+ − 1003
+ − 1004 @item subwindow
+ − 1005 A child window that is treated as an image. This allows (e.g.)
+ − 1006 another program to be responsible for drawing into the window.
+ − 1007 Not currently implemented.
+ − 1008 @end table
+ − 1009
+ − 1010 @defun valid-image-instance-type-p type
+ − 1011 This function returns non-@code{nil} if @var{type} is a valid image
+ − 1012 instance type.
+ − 1013 @end defun
+ − 1014
+ − 1015 @defun image-instance-type-list
+ − 1016 This function returns a list of the valid image instance types.
+ − 1017 @end defun
+ − 1018
+ − 1019 @defun image-instance-type image-instance
+ − 1020 This function returns the type of the given image instance. The return
+ − 1021 value will be one of @code{nothing}, @code{text}, @code{mono-pixmap},
+ − 1022 @code{color-pixmap}, @code{pointer}, or @code{subwindow}.
+ − 1023 @end defun
+ − 1024
+ − 1025 @defun text-image-instance-p object
+ − 1026 This function returns non-@code{nil} if @var{object} is an image
+ − 1027 instance of type @code{text}.
+ − 1028 @end defun
+ − 1029
+ − 1030 @defun mono-pixmap-image-instance-p object
+ − 1031 This function returns non-@code{nil} if @var{object} is an image
+ − 1032 instance of type @code{mono-pixmap}.
+ − 1033 @end defun
+ − 1034
+ − 1035 @defun color-pixmap-image-instance-p object
+ − 1036 This function returns non-@code{nil} if @var{object} is an image
+ − 1037 instance of type @code{color-pixmap}.
+ − 1038 @end defun
+ − 1039
+ − 1040 @defun pointer-image-instance-p object
+ − 1041 This function returns non-@code{nil} if @var{object} is an image
+ − 1042 instance of type @code{pointer}.
+ − 1043 @end defun
+ − 1044
+ − 1045 @defun subwindow-image-instance-p object
+ − 1046 This function returns non-@code{nil} if @var{object} is an image
+ − 1047 instance of type @code{subwindow}.
+ − 1048 @end defun
+ − 1049
+ − 1050 @defun nothing-image-instance-p object
+ − 1051 This function returns non-@code{nil} if @var{object} is an image
+ − 1052 instance of type @code{nothing}.
+ − 1053 @end defun
+ − 1054
442
+ − 1055 @defun widget-image-instance-p object
444
+ − 1056 Return @code{t} if @var{object} is an image instance of type @code{widget}.
442
+ − 1057 @end defun
+ − 1058
428
+ − 1059 @node Image Instance Functions
+ − 1060 @subsubsection Image Instance Functions
+ − 1061
444
+ − 1062 @defun make-image-instance data &optional domain dest-types noerror
428
+ − 1063 This function creates a new image-instance object.
+ − 1064
+ − 1065 @var{data} is an image instantiator, which describes the image
+ − 1066 (@pxref{Image Specifiers}).
+ − 1067
+ − 1068 @var{dest-types} should be a list of allowed image instance types that
+ − 1069 can be generated. The @var{dest-types} list is unordered. If multiple
+ − 1070 destination types are possible for a given instantiator, the ``most
+ − 1071 natural'' type for the instantiator's format is chosen. (For XBM, the
+ − 1072 most natural types are @code{mono-pixmap}, followed by
+ − 1073 @code{color-pixmap}, followed by @code{pointer}. For the other normal
+ − 1074 image formats, the most natural types are @code{color-pixmap}, followed
+ − 1075 by @code{mono-pixmap}, followed by @code{pointer}. For the string and
+ − 1076 formatted-string formats, the most natural types are @code{text},
+ − 1077 followed by @code{mono-pixmap} (not currently implemented), followed by
442
+ − 1078 @code{color-pixmap} (not currently implemented). For MS Windows
+ − 1079 resources, the most natural type for pointer resources is
+ − 1080 @code{pointer}, and for the others it's @code{color-pixmap}. The other
+ − 1081 formats can only be instantiated as one type. (If you want to control
+ − 1082 more specifically the order of the types into which an image is
+ − 1083 instantiated, just call @code{make-image-instance} repeatedly until it
+ − 1084 succeeds, passing less and less preferred destination types each time.
428
+ − 1085
+ − 1086 If @var{dest-types} is omitted, all possible types are allowed.
+ − 1087
442
+ − 1088 @var{domain} specifies the domain to which the image instance will be
+ − 1089 attached. This domain is termed the @dfn{governing domain}. The type
+ − 1090 of the governing domain depends on the image instantiator
+ − 1091 format. (Although, more correctly, it should probably depend on the
+ − 1092 image instance type.) For example, pixmap image instances are specific
+ − 1093 to a device, but widget image instances are specific to a particular
+ − 1094 XEmacs window because in order to display such a widget when two windows
+ − 1095 onto the same buffer want to display the widget, two separate underlying
+ − 1096 widgets must be created. (That's because a widget is actually a child
+ − 1097 window-system window, and all window-system windows have a unique
+ − 1098 existence on the screen.) This means that the governing domain for a
+ − 1099 pixmap image instance will be some device (most likely, the only
+ − 1100 existing device), whereas the governing domain for a widget image
+ − 1101 instance will be some XEmacs window.
+ − 1102
+ − 1103 If you specify an overly general @var{domain} (e.g. a frame when a
+ − 1104 window was wanted), an error is signaled. If you specify an overly
+ − 1105 specific @var{domain} (e.g. a window when a device was wanted), the
+ − 1106 corresponding general domain is fetched and used instead. For
+ − 1107 @code{make-image-instance}, it makes no difference whether you specify
+ − 1108 an overly specific domain or the properly general domain derived from
+ − 1109 it. However, it does matter when creating an image instance by
+ − 1110 instantiating a specifier or glyph (e.g. with
+ − 1111 @code{glyph-image-instance}), because the more specific domain causes
+ − 1112 spec lookup to start there and proceed to more general domains. (It
+ − 1113 would also matter when creating an image instance with an instantiator
+ − 1114 format of @code{inherit}, but we currently disallow this. #### We should
+ − 1115 fix this.)
+ − 1116 n
+ − 1117 If omitted, @var{domain} defaults to the selected window.
+ − 1118
444
+ − 1119 @var{noerror} controls what happens when the image cannot be generated.
+ − 1120 If @code{nil}, an error message is generated. If @code{t}, no messages
+ − 1121 are generated and this function returns @code{nil}. If anything else, a
+ − 1122 warning message is generated and this function returns @code{nil}.
428
+ − 1123 @end defun
+ − 1124
+ − 1125 @defun colorize-image-instance image-instance foreground background
+ − 1126 This function makes the image instance be displayed in the given
+ − 1127 colors. Image instances come in two varieties: bitmaps, which are 1
+ − 1128 bit deep which are rendered in the prevailing foreground and background
+ − 1129 colors; and pixmaps, which are of arbitrary depth (including 1) and
+ − 1130 which have the colors explicitly specified. This function converts a
+ − 1131 bitmap to a pixmap. If the image instance was a pixmap already,
+ − 1132 nothing is done (and @code{nil} is returned). Otherwise @code{t} is
+ − 1133 returned.
+ − 1134 @end defun
+ − 1135
+ − 1136 @defun image-instance-name image-instance
+ − 1137 This function returns the name of the given image instance.
+ − 1138 @end defun
+ − 1139
442
+ − 1140 @defun image-instance-domain image-instance
+ − 1141
+ − 1142 Return the governing domain of the given @var{image-instance}. The
+ − 1143 governing domain of an image instance is the domain that the image
+ − 1144 instance is specific to. It is @emph{NOT} necessarily the domain that
+ − 1145 was given to the call to @code{specifier-instance} that resulted in the
+ − 1146 creation of this image instance. See @code{make-image-instance} for
+ − 1147 more information on governing domains.
+ − 1148 @end defun
+ − 1149
+ − 1150
428
+ − 1151 @defun image-instance-string image-instance
+ − 1152 This function returns the string of the given image instance. This will
+ − 1153 only be non-@code{nil} for text image instances.
+ − 1154 @end defun
+ − 1155
+ − 1156 @defun image-instance-file-name image-instance
+ − 1157 This function returns the file name from which @var{image-instance} was
+ − 1158 read, if known.
+ − 1159 @end defun
+ − 1160
+ − 1161 @defun image-instance-mask-file-name image-instance
+ − 1162 This function returns the file name from which @var{image-instance}'s
+ − 1163 mask was read, if known.
+ − 1164 @end defun
+ − 1165
+ − 1166 @defun image-instance-depth image-instance
+ − 1167 This function returns the depth of the image instance. This is 0 for a
+ − 1168 mono pixmap, or a positive integer for a color pixmap.
+ − 1169 @end defun
+ − 1170
+ − 1171 @defun image-instance-height image-instance
+ − 1172 This function returns the height of the image instance, in pixels.
+ − 1173 @end defun
+ − 1174
+ − 1175 @defun image-instance-width image-instance
+ − 1176 This function returns the width of the image instance, in pixels.
+ − 1177 @end defun
+ − 1178
+ − 1179 @defun image-instance-hotspot-x image-instance
+ − 1180 This function returns the X coordinate of the image instance's hotspot,
+ − 1181 if known. This is a point relative to the origin of the pixmap. When
+ − 1182 an image is used as a mouse pointer, the hotspot is the point on the
+ − 1183 image that sits over the location that the pointer points to. This is,
+ − 1184 for example, the tip of the arrow or the center of the crosshairs.
+ − 1185
+ − 1186 This will always be @code{nil} for a non-pointer image instance.
+ − 1187 @end defun
+ − 1188
+ − 1189 @defun image-instance-hotspot-y image-instance
+ − 1190 This function returns the Y coordinate of the image instance's hotspot,
+ − 1191 if known.
+ − 1192 @end defun
+ − 1193
+ − 1194 @defun image-instance-foreground image-instance
+ − 1195 This function returns the foreground color of @var{image-instance}, if
+ − 1196 applicable. This will be a color instance or @code{nil}. (It will only
+ − 1197 be non-@code{nil} for colorized mono pixmaps and for pointers.)
+ − 1198 @end defun
+ − 1199
+ − 1200 @defun image-instance-background image-instance
+ − 1201 This function returns the background color of @var{image-instance}, if
+ − 1202 applicable. This will be a color instance or @code{nil}. (It will only
+ − 1203 be non-@code{nil} for colorized mono pixmaps and for pointers.)
+ − 1204 @end defun
+ − 1205
+ − 1206
+ − 1207 @node Glyph Types
+ − 1208 @section Glyph Types
+ − 1209
+ − 1210 Each glyph has a particular type, which controls how the glyph's image
+ − 1211 is generated. Each glyph type has a corresponding list of allowable
+ − 1212 image instance types that can be generated. When you call
+ − 1213 @code{glyph-image-instance} to retrieve the image instance of a glyph,
+ − 1214 XEmacs does the equivalent of calling @code{make-image-instance} and
+ − 1215 passing in @var{dest-types} the list of allowable image instance types
+ − 1216 for the glyph's type.
+ − 1217
+ − 1218 @itemize @bullet
+ − 1219 @item
+ − 1220 @code{buffer} glyphs can be used as the begin-glyph or end-glyph of an
+ − 1221 extent, in the modeline, and in the toolbar. Their image can be
+ − 1222 instantiated as @code{nothing}, @code{mono-pixmap}, @code{color-pixmap},
+ − 1223 @code{text}, and @code{subwindow}.
+ − 1224
+ − 1225 @item
+ − 1226 @code{pointer} glyphs can be used to specify the mouse pointer. Their
+ − 1227 image can be instantiated as @code{pointer}.
+ − 1228
+ − 1229 @item
+ − 1230 @code{icon} glyphs can be used to specify the icon used when a frame is
+ − 1231 iconified. Their image can be instantiated as @code{mono-pixmap} and
+ − 1232 @code{color-pixmap}.
+ − 1233 @end itemize
+ − 1234
+ − 1235 @defun glyph-type glyph
+ − 1236 This function returns the type of the given glyph. The return value
+ − 1237 will be a symbol, one of @code{buffer}, @code{pointer}, or @code{icon}.
+ − 1238 @end defun
+ − 1239
+ − 1240 @defun valid-glyph-type-p glyph-type
+ − 1241 Given a @var{glyph-type}, this function returns non-@code{nil} if it is
+ − 1242 valid.
+ − 1243 @end defun
+ − 1244
+ − 1245 @defun glyph-type-list
+ − 1246 This function returns a list of valid glyph types.
+ − 1247 @end defun
+ − 1248
+ − 1249 @defun buffer-glyph-p object
+ − 1250 This function returns non-@code{nil} if @var{object} is a glyph of type
+ − 1251 @code{buffer}.
+ − 1252 @end defun
+ − 1253
+ − 1254 @defun icon-glyph-p object
+ − 1255 This function returns non-@code{nil} if @var{object} is a glyph of type
+ − 1256 @code{icon}.
+ − 1257 @end defun
+ − 1258
+ − 1259 @defun pointer-glyph-p object
+ − 1260 This function returns non-@code{nil} if @var{object} is a glyph of type
+ − 1261 @code{pointer}.
+ − 1262 @end defun
+ − 1263
+ − 1264 @node Mouse Pointer
+ − 1265 @section Mouse Pointer
+ − 1266 @cindex mouse cursor
+ − 1267 @cindex cursor (mouse)
+ − 1268 @cindex pointer (mouse)
+ − 1269 @cindex mouse pointer
+ − 1270
+ − 1271 The shape of the mouse pointer when over a particular section of a frame
+ − 1272 is controlled using various glyph variables. Since the image of a glyph
+ − 1273 is a specifier, it can be controlled on a per-buffer, per-frame, per-window,
+ − 1274 or per-device basis.
+ − 1275
+ − 1276 You should use @code{set-glyph-image} to set the following variables,
+ − 1277 @emph{not} @code{setq}.
+ − 1278
+ − 1279 @defvr Glyph text-pointer-glyph
+ − 1280 This variable specifies the shape of the mouse pointer when over text.
+ − 1281 @end defvr
+ − 1282
+ − 1283 @defvr Glyph nontext-pointer-glyph
+ − 1284 This variable specifies the shape of the mouse pointer when over a
+ − 1285 buffer, but not over text. If unspecified in a particular domain,
+ − 1286 @code{text-pointer-glyph} is used.
+ − 1287 @end defvr
+ − 1288
+ − 1289 @defvr Glyph modeline-pointer-glyph
+ − 1290 This variable specifies the shape of the mouse pointer when over the modeline.
+ − 1291 If unspecified in a particular domain, @code{nontext-pointer-glyph} is used.
+ − 1292 @end defvr
+ − 1293
+ − 1294 @defvr Glyph selection-pointer-glyph
+ − 1295 This variable specifies the shape of the mouse pointer when over a
+ − 1296 selectable text region. If unspecified in a particular domain,
+ − 1297 @code{text-pointer-glyph} is used.
+ − 1298 @end defvr
+ − 1299
+ − 1300 @defvr Glyph gc-pointer-glyph
+ − 1301 This variable specifies the shape of the mouse pointer when a garbage
+ − 1302 collection is in progress. If the selected window is on a window system
+ − 1303 and this glyph specifies a value (i.e. a pointer image instance) in the
+ − 1304 domain of the selected window, the pointer will be changed as specified
+ − 1305 during garbage collection. Otherwise, a message will be printed in the
+ − 1306 echo area, as controlled by @code{gc-message}.
+ − 1307 @end defvr
+ − 1308
+ − 1309 @defvr Glyph busy-pointer-glyph
+ − 1310 This variable specifies the shape of the mouse pointer when XEmacs is busy.
+ − 1311 If unspecified in a particular domain, the pointer is not changed
+ − 1312 when XEmacs is busy.
+ − 1313 @end defvr
+ − 1314
+ − 1315 @defvr Glyph menubar-pointer-glyph
+ − 1316 This variable specifies the shape of the mouse pointer when over the
+ − 1317 menubar. If unspecified in a particular domain, the
+ − 1318 window-system-provided default pointer is used.
+ − 1319 @end defvr
+ − 1320
+ − 1321 @defvr Glyph scrollbar-pointer-glyph
+ − 1322 This variable specifies the shape of the mouse pointer when over a
+ − 1323 scrollbar. If unspecified in a particular domain, the
+ − 1324 window-system-provided default pointer is used.
+ − 1325 @end defvr
+ − 1326
+ − 1327 @defvr Glyph toolbar-pointer-glyph
+ − 1328 This variable specifies the shape of the mouse pointer when over a
+ − 1329 toolbar. If unspecified in a particular domain,
+ − 1330 @code{nontext-pointer-glyph} is used.
+ − 1331 @end defvr
+ − 1332
+ − 1333 Internally, these variables are implemented in
+ − 1334 @code{default-mouse-motion-handler}, and thus only take effect when the
+ − 1335 mouse moves. That function calls @code{set-frame-pointer}, which sets
+ − 1336 the current mouse pointer for a frame.
+ − 1337
+ − 1338 @defun set-frame-pointer frame image-instance
+ − 1339 This function sets the mouse pointer of @var{frame} to the given pointer
+ − 1340 image instance. You should not call this function directly.
+ − 1341 (If you do, the pointer will change again the next time the mouse moves.)
+ − 1342 @end defun
+ − 1343
+ − 1344 @node Redisplay Glyphs
+ − 1345 @section Redisplay Glyphs
+ − 1346
+ − 1347 @defvr Glyph truncation-glyph
+ − 1348 This variable specifies what is displayed at the end of truncated lines.
+ − 1349 @end defvr
+ − 1350
+ − 1351 @defvr Glyph continuation-glyph
+ − 1352 This variable specifies what is displayed at the end of wrapped lines.
+ − 1353 @end defvr
+ − 1354
+ − 1355 @defvr Glyph octal-escape-glyph
+ − 1356 This variable specifies what to prefix character codes displayed in octal
+ − 1357 with.
+ − 1358 @end defvr
+ − 1359
+ − 1360 @defvr Glyph hscroll-glyph
+ − 1361 This variable specifies what to display at the beginning of horizontally
+ − 1362 scrolled lines.
+ − 1363 @end defvr
+ − 1364
+ − 1365 @defvr Glyph invisible-text-glyph
+ − 1366 This variable specifies what to use to indicate the presence of
+ − 1367 invisible text. This is the glyph that is displayed when an ellipsis is
+ − 1368 called for, according to @code{selective-display-ellipses} or
+ − 1369 @code{buffer-invisibility-spec}). Normally this is three dots (``...'').
+ − 1370 @end defvr
+ − 1371
+ − 1372 @defvr Glyph control-arrow-glyph
+ − 1373 This variable specifies what to use as an arrow for control characters.
+ − 1374 @end defvr
+ − 1375
+ − 1376 @node Subwindows
+ − 1377 @section Subwindows
+ − 1378
+ − 1379 Subwindows are not currently implemented.
+ − 1380
+ − 1381 @defun subwindowp object
+ − 1382 This function returns non-@code{nil} if @var{object} is a subwindow.
+ − 1383 @end defun
707
+ − 1384
+ − 1385 @node Glyph Examples
+ − 1386 @section Glyph Examples
+ − 1387
+ − 1388 For many applications, displaying graphics is a simple process: you
+ − 1389 create a glyph, and then you insert it into a buffer.
+ − 1390
+ − 1391 The easiest way to create a glyph is to use a file that contains a
+ − 1392 graphical image, such as a JPEG, TIFF, or PNG file:
+ − 1393
+ − 1394 @lisp
+ − 1395 ;; Create a glyph from a JPEG file:
+ − 1396 (setq foo (make-glyph [jpeg :file "/tmp/file1.jpg"]))
+ − 1397 @end lisp
+ − 1398
+ − 1399 @lisp
+ − 1400 ;; Create a glyph from a XPM file:
+ − 1401 (setq foo (make-glyph [xpm :file "/tmp/file2.xpm"]))
+ − 1402 @end lisp
+ − 1403
+ − 1404 @lisp
+ − 1405 ;; Create a glyph from a PNG file:
+ − 1406 (setq foo (make-glyph [png :file "/tmp/file3.png"]))
+ − 1407 @end lisp
+ − 1408
+ − 1409 @lisp
+ − 1410 ;; Create a glyph from a TIFF file:
+ − 1411 (setq foo (make-glyph [tiff :file "/tmp/file4.tiff"]))
+ − 1412 @end lisp
+ − 1413
+ − 1414 The parameters passed to @code{make-glyph} are called "Image
+ − 1415 Specifiers", and can handle more image types than those shown above.
+ − 1416 You can also put the raw image data into a string (e.g., if you put the
+ − 1417 contents of a JPEG file into a string), and use that to create a glyph.
+ − 1418 @xref{Image Specifiers}, for more information.
+ − 1419
+ − 1420 @quotation
+ − 1421 @strong{Caution}: In order for XEmacs to read a particular graphics file
+ − 1422 format, support for that format must have been compiled into XEmacs.
+ − 1423 It's possible, although somewhat unlikely, for XEmacs to have been
+ − 1424 compiled without support for any of the various graphics file formats.
+ − 1425 To see what graphics formats your particular version of XEmacs supports,
+ − 1426 use @kbd{M-x describe-installation}.
+ − 1427
+ − 1428 To programmatically query whether or not a particular file format is
+ − 1429 supported, you can use the @code{featurep} function, with one of:
+ − 1430 @code{gif}, @code{tiff}, @code{jpeg}, @code{xpm}, @code{xbm},
+ − 1431 @code{png}, or @code{xface}. For an up-to-date list, @ref{Image
+ − 1432 Specifiers}. Example:
+ − 1433
+ − 1434 @example
+ − 1435 ;; Returns `t' if TIFF is supported:
+ − 1436 (featurep 'tiff)
+ − 1437 @end example
+ − 1438
+ − 1439 Another example is:
+ − 1440
+ − 1441 @example
+ − 1442 ;; Returns a list of `t' or `nil', depending on whether or not the
+ − 1443 ;; corresponding feature is supported:
+ − 1444 (mapcar #'(lambda (format-symbol) (featurep format-symbol))
+ − 1445 '(gif tiff jpeg xpm png))
+ − 1446 @end example
+ − 1447
+ − 1448 @end quotation
+ − 1449
+ − 1450 Once you have a glyph, you can then insert it into a buffer. Example:
+ − 1451
+ − 1452 @lisp
+ − 1453 ;; Use this function to insert a glyph at the left edge of point in the
+ − 1454 ;; current buffer. Any existing glyph at this location is replaced.
+ − 1455 (defun insert-glyph (gl)
+ − 1456 "Insert a glyph at the left edge of point."
+ − 1457 (let ( (prop 'myimage) ;; myimage is an arbitrary name, chosen
+ − 1458 ;; to (hopefully) not conflict with any
+ − 1459 ;; other properties. Change it if
+ − 1460 ;; necessary.
+ − 1461 extent )
+ − 1462 ;; First, check to see if one of our extents already exists at
+ − 1463 ;; point. For ease-of-programming, we are creating and using our
+ − 1464 ;; own extents (multiple extents are allowed to exist/overlap at the
+ − 1465 ;; same point, and it's quite possible for other applications to
+ − 1466 ;; embed extents in the current buffer without your knowledge).
+ − 1467 ;; Basically, if an extent, with the property stored in "prop",
+ − 1468 ;; exists at point, we assume that it is one of ours, and we re-use
+ − 1469 ;; it (this is why it is important for the property stored in "prop"
+ − 1470 ;; to be unique, and only used by us).
+ − 1471 (if (not (setq extent (extent-at (point) (current-buffer) prop)))
+ − 1472 (progn
+ − 1473 ;; If an extent does not already exist, create a zero-length
+ − 1474 ;; extent, and give it our special property.
+ − 1475 (setq extent (make-extent (point) (point) (current-buffer)))
+ − 1476 (set-extent-property extent prop t)
+ − 1477 ))
+ − 1478 ;; Display the glyph by storing it as the extent's "begin-glyph".
+ − 1479 (set-extent-property extent 'begin-glyph gl)
+ − 1480 ))
+ − 1481
+ − 1482 ;; You can then use this function like:
+ − 1483 (insert-glyph (make-glyph [jpeg :file "/tmp/file1.jpg"]))
+ − 1484 ;; This will insert the glyph at point.
+ − 1485
+ − 1486 ;; Here's an example of how to insert two glyphs side-by-side, at point
+ − 1487 ;; (using the above code):
+ − 1488 (progn
+ − 1489 (insert-glyph (make-glyph [jpeg :file "/tmp/file1.jpg"]))
+ − 1490 ;; Create a new extent at point. We can't simply call "insert-glyph",
+ − 1491 ;; as "insert-glyph" will simply replace the first glyph with the
+ − 1492 ;; second.
+ − 1493 (setq extent (make-extent (point) (point) (current-buffer)))
+ − 1494 ;; Here, we're only setting the 'myimage property in case we need
+ − 1495 ;; to later identify/locate/reuse this particular extent.
+ − 1496 (set-extent-property extent 'myimage t)
+ − 1497 (set-extent-property extent 'begin-glyph
+ − 1498 (make-glyph [jpeg :file "/tmp/file2.jpg"]))
+ − 1499 )
+ − 1500
+ − 1501 @end lisp
+ − 1502
+ − 1503 Here are the gory details:
+ − 1504
+ − 1505 @itemize @bullet
+ − 1506
+ − 1507 @item
+ − 1508 Glyphs are displayed by attaching them to extents (see @ref{Extents}),
+ − 1509 either to the beginning or the end of extents.
+ − 1510
+ − 1511 Note that extents can be used for many things, and not just for
+ − 1512 displaying images (although, in the above example, we are creating our
+ − 1513 own extent for the sole purpose of displaying an image). Also, note
+ − 1514 that multiple extents are allowed to exist at the same position, and
+ − 1515 they can overlap.
+ − 1516
+ − 1517 @item
+ − 1518 Glyphs are often displayed inside the text area (alongside text). This
+ − 1519 is the default.
+ − 1520
+ − 1521 Although glyphs can also be displayed in the margins, how to do this
+ − 1522 will not be described here. For more information on this, see
+ − 1523 @ref{Annotation Basics} (look for information on "layout types") and
+ − 1524 @ref{Extent Properties} (look for @code{begin-glyph-layout} and
+ − 1525 @code{end-glyph-layout}).
+ − 1526
+ − 1527 @item
+ − 1528 The easiest way to insert a glyph into text is to create a zero-length
+ − 1529 extent at the point where you want the glyph to appear.
+ − 1530
+ − 1531 Note that zero-length extents are attached to the character to the
+ − 1532 right of the extent; deleting this character will also delete the extent.
+ − 1533
+ − 1534 @item
+ − 1535 It's often a good idea to assign a unique property to the newly-created
+ − 1536 extent, in case you later want to locate it, and replace any existing
+ − 1537 glyph with a different one (or just delete the existing one). In the
+ − 1538 above example, we are using "myimage" as our (hopefully) unique property
+ − 1539 name.
+ − 1540
+ − 1541 If you need to locate all of the extents, you'll have to use functions
+ − 1542 like @code{extent-list} or @code{next-extent}, or provide additional
+ − 1543 parameters to the @code{extent-at} function. Assigning a unique
+ − 1544 property to the extent makes it easy to locate your extents; for
+ − 1545 example, @code{extent-list} can return only those extents with a
+ − 1546 particular property. @xref{Finding Extents}, and @ref{Mapping Over
+ − 1547 Extents}, for more information.
+ − 1548
+ − 1549 @item
+ − 1550 Glyphs are displayed by assigning then to the @code{begin-glyph} or
+ − 1551 @code{end-glyph} property of the extent. For zero-length extents, it
+ − 1552 doesn't really matter if you assign the glyph to the @code{begin-glyph}
+ − 1553 or @code{end-glyph} property, as they are both at the same location;
+ − 1554 however, for non-zero-length extents (extents that cover one or more
+ − 1555 characters of text), it does matter which one you use.
+ − 1556
+ − 1557 Assigning @code{nil} to the @code{begin-glyph} or @code{end-glyph}
+ − 1558 property will delete any existing glyph. In this case, you may also
+ − 1559 want to delete the extent, assuming that the extent is used for no other
+ − 1560 purpose.
+ − 1561
+ − 1562 @item
+ − 1563 If you happen to insert two glyphs, side-by-side, note that the example
+ − 1564 @code{insert-glyph} function will have trouble, if it's again used at
+ − 1565 the same point (it can only locate one of the two extents).
+ − 1566 @xref{Finding Extents}, and @ref{Mapping Over Extents}, for more
+ − 1567 information on locating extents in a buffer.
+ − 1568
+ − 1569 @item
+ − 1570 Among other things, glyphs provide a way of displaying graphics
+ − 1571 alongside text. Note, however, that glyphs only provide a way of
+ − 1572 displaying graphics; glyphs are not actually part of the text, and are
+ − 1573 only displayed alongside the text. If you save the text in the buffer,
+ − 1574 the graphics are not saved. The low-level glyph code does not provide a
+ − 1575 way of saving graphics with the text. If you need to save graphics and
+ − 1576 text, you have to write your own code to do this, and this topic is
+ − 1577 outside the scope of this discussion.
+ − 1578
+ − 1579 @end itemize