Mercurial > hg > xemacs-beta
annotate man/lispref/glyphs.texi @ 5142:f965e31a35f0
reduce lcrecord headers to 2 words, rename printing_unreadable_object
-------------------- ChangeLog entries follow: --------------------
man/ChangeLog addition:
2010-03-13 Ben Wing <ben@xemacs.org>
* internals/internals.texi (Working with Lisp Objects):
* internals/internals.texi (Writing Macros):
* internals/internals.texi (lrecords):
More rewriting to correspond with changes from
*LRECORD* to *LISP_OBJECT*.
modules/ChangeLog addition:
2010-03-13 Ben Wing <ben@xemacs.org>
* postgresql/postgresql.c (print_pgconn):
* postgresql/postgresql.c (print_pgresult):
printing_unreadable_object -> printing_unreadable_object_fmt.
2010-03-13 Ben Wing <ben@xemacs.org>
* ldap/eldap.c (print_ldap):
printing_unreadable_object -> printing_unreadable_object_fmt.
src/ChangeLog addition:
2010-03-13 Ben Wing <ben@xemacs.org>
* alloc.c (alloc_sized_lrecord_1):
* alloc.c (alloc_sized_lrecord_array):
* alloc.c (old_alloc_sized_lcrecord):
* alloc.c (disksave_object_finalization_1):
* alloc.c (mark_lcrecord_list):
* alloc.c (alloc_managed_lcrecord):
* alloc.c (free_managed_lcrecord):
* alloc.c (tick_lcrecord_stats):
* alloc.c (sweep_lcrecords_1):
* buffer.c (print_buffer):
* buffer.c (DEFVAR_BUFFER_LOCAL_1):
* casetab.c:
* casetab.c (print_case_table):
* console.c (print_console):
* console.c (DEFVAR_CONSOLE_LOCAL_1):
* data.c (print_weak_list):
* data.c (print_weak_box):
* data.c (print_ephemeron):
* data.c (ephemeron_equal):
* database.c (print_database):
* database.c (finalize_database):
* device-msw.c (sync_printer_with_devmode):
* device-msw.c (print_devmode):
* device-msw.c (finalize_devmode):
* device.c:
* device.c (print_device):
* elhash.c:
* elhash.c (print_hash_table):
* eval.c (print_subr):
* eval.c (print_multiple_value):
* event-stream.c (event_stream_resignal_wakeup):
* events.c (clear_event_resource):
* events.c (zero_event):
* events.c (print_event):
* extents.c:
* extents.c (print_extent):
* file-coding.c (print_coding_system):
* font-mgr.c:
* font-mgr.c (Ffc_init):
* frame.c:
* frame.c (print_frame):
* gc.c:
* gc.c (GC_CHECK_NOT_FREE):
* glyphs.c:
* glyphs.c (print_image_instance):
* glyphs.c (print_glyph):
* gui.c (print_gui_item):
* gui.c (copy_gui_item):
* keymap.c (print_keymap):
* keymap.c (MARKED_SLOT):
* lisp.h:
* lisp.h (struct Lisp_String):
* lisp.h (DEFUN):
* lisp.h (DEFUN_NORETURN):
* lrecord.h:
* lrecord.h (NORMAL_LISP_OBJECT_UID):
* lrecord.h (struct lrecord_header):
* lrecord.h (set_lheader_implementation):
* lrecord.h (struct old_lcrecord_header):
* lrecord.h (struct free_lcrecord_header):
* marker.c (print_marker):
* mule-charset.c:
* mule-charset.c (print_charset):
* objects.c (print_color_instance):
* objects.c (print_font_instance):
* objects.c (finalize_font_instance):
* print.c (print_cons):
* print.c (printing_unreadable_object_fmt):
* print.c (printing_unreadable_lisp_object):
* print.c (external_object_printer):
* print.c (internal_object_printer):
* print.c (debug_p4):
* print.c (ext_print_begin):
* process.c (print_process):
* rangetab.c (print_range_table):
* rangetab.c (range_table_equal):
* scrollbar.c (free_scrollbar_instance):
* specifier.c (print_specifier):
* specifier.c (finalize_specifier):
* symbols.c (guts_of_unbound_marker):
* symeval.h:
* symeval.h (DEFVAR_SYMVAL_FWD):
* tooltalk.c:
* tooltalk.c (print_tooltalk_message):
* tooltalk.c (print_tooltalk_pattern):
* ui-gtk.c (ffi_object_printer):
* ui-gtk.c (emacs_gtk_object_printer):
* ui-gtk.c (emacs_gtk_boxed_printer):
* window.c (print_window):
* window.c (free_window_mirror):
* window.c (debug_print_window):
* xemacs.def.in.in:
(1) printing_unreadable_object -> printing_unreadable_object_fmt.
(2) printing_unreadable_lcrecord -> printing_unreadable_lisp_object
and fix up so it no longer requires an lcrecord.
These previous changes eliminate most of the remaining places where
the terms `lcrecord' and `lrecord' occurred outside of specialized
code.
(3) Fairly major change: Reduce the number of words in an lcrecord
from 3 to 2. The third word consisted of a uid that duplicated the
lrecord uid, and a single free bit, which was moved into the lrecord
structure. This reduces the size of the `uid' slot from 21 bits to
20 bits. Arguably this isn't enough -- we could easily have more than
1,000,000 or so objects created in a session. The answer is
(a) It doesn't really matter if we overflow the uid field because
it's only used for debugging, to identify an object uniquely
(or pretty much so).
(b) If we cared about it overflowing and wanted to reduce this,
we could make it so that cons, string, float and certain other
frob-block types that never print out the uid simply don't
store a uid in them and don't increment the lrecord_uid_counter.
(4) In conjunction with (3), create new macro NORMAL_LISP_OBJECT_UID()
and use it to abstract out the differences between NEWGC and old-GC
in accessing the `uid' value from a "normal Lisp Object pointer".
(5) In events.c, use zero_nonsized_lisp_object() in place of custom-
written equivalent. In font-mgr.c use external_object_printer()
in place of custom-written equivalents.
| author | Ben Wing <ben@xemacs.org> |
|---|---|
| date | Sat, 13 Mar 2010 05:38:08 -0600 |
| 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 |