info/lispref.info-35

   1 This is ../info/lispref.info, produced by makeinfo version 4.0 from
   2 lispref/lispref.texi.
   3
   4 INFO-DIR-SECTION XEmacs Editor
   5 START-INFO-DIR-ENTRY
   6 * Lispref: (lispref).           XEmacs Lisp Reference Manual.
   7 END-INFO-DIR-ENTRY
   8
   9    Edition History:
  10
  11    GNU Emacs Lisp Reference Manual Second Edition (v2.01), May 1993 GNU
  12 Emacs Lisp Reference Manual Further Revised (v2.02), August 1993 Lucid
  13 Emacs Lisp Reference Manual (for 19.10) First Edition, March 1994
  14 XEmacs Lisp Programmer's Manual (for 19.12) Second Edition, April 1995
  15 GNU Emacs Lisp Reference Manual v2.4, June 1995 XEmacs Lisp
  16 Programmer's Manual (for 19.13) Third Edition, July 1995 XEmacs Lisp
  17 Reference Manual (for 19.14 and 20.0) v3.1, March 1996 XEmacs Lisp
  18 Reference Manual (for 19.15 and 20.1, 20.2, 20.3) v3.2, April, May,
  19 November 1997 XEmacs Lisp Reference Manual (for 21.0) v3.3, April 1998
  20
  21    Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995 Free Software
  22 Foundation, Inc.  Copyright (C) 1994, 1995 Sun Microsystems, Inc.
  23 Copyright (C) 1995, 1996 Ben Wing.
  24
  25    Permission is granted to make and distribute verbatim copies of this
  26 manual provided the copyright notice and this permission notice are
  27 preserved on all copies.
  28
  29    Permission is granted to copy and distribute modified versions of
  30 this manual under the conditions for verbatim copying, provided that the
  31 entire resulting derived work is distributed under the terms of a
  32 permission notice identical to this one.
  33
  34    Permission is granted to copy and distribute translations of this
  35 manual into another language, under the above conditions for modified
  36 versions, except that this permission notice may be stated in a
  37 translation approved by the Foundation.
  38
  39    Permission is granted to copy and distribute modified versions of
  40 this manual under the conditions for verbatim copying, provided also
  41 that the section entitled "GNU General Public License" is included
  42 exactly as in the original, and provided that the entire resulting
  43 derived work is distributed under the terms of a permission notice
  44 identical to this one.
  45
  46    Permission is granted to copy and distribute translations of this
  47 manual into another language, under the above conditions for modified
  48 versions, except that the section entitled "GNU General Public License"
  49 may be included in a translation approved by the Free Software
  50 Foundation instead of in the original English.
  51
  52 \1f
  53 File: lispref.info,  Node: Face Properties,  Next: Face Convenience Functions,  Prev: Basic Face Functions,  Up: Faces
  54
  55 Face Properties
  56 ---------------
  57
  58    You can examine and modify the properties of an existing face with
  59 the following functions.
  60
  61    The following symbols have predefined meanings:
  62
  63 `foreground'
  64      The foreground color of the face.
  65
  66 `background'
  67      The background color of the face.
  68
  69 `font'
  70      The font used to display text covered by this face.
  71
  72 `display-table'
  73      The display table of the face.
  74
  75 `background-pixmap'
  76      The pixmap displayed in the background of the face.  Only used by
  77      faces on X devices.
  78
  79 `underline'
  80      Underline all text covered by this face.
  81
  82 `highlight'
  83      Highlight all text covered by this face.  Only used by faces on TTY
  84      devices.
  85
  86 `dim'
  87      Dim all text covered by this face.  Only used by faces on TTY
  88      devices.
  89
  90 `blinking'
  91      Blink all text covered by this face.  Only used by faces on TTY
  92      devices.
  93
  94 `reverse'
  95      Reverse the foreground and background colors.  Only used by faces
  96      on TTY devices.
  97
  98 `doc-string'
  99      Description of what the face's normal use is.  NOTE: This is not a
 100      specifier, unlike all the other built-in properties, and cannot
 101      contain locale-specific values.
 102
 103  - Function: set-face-property face property value &optional locale tag
 104           how-to-add
 105      This function changes a property of a FACE.
 106
 107      For built-in properties, the actual value of the property is a
 108      specifier and you cannot change this; but you can change the
 109      specifications within the specifier, and that is what this
 110      function will do.  For user-defined properties, you can use this
 111      function to either change the actual value of the property or, if
 112      this value is a specifier, change the specifications within it.
 113
 114      If PROPERTY is a built-in property, the specifications to be added
 115      to this property can be supplied in many different ways:
 116
 117           If VALUE is a simple instantiator (e.g. a string naming a
 118           font or color) or a list of instantiators, then the
 119           instantiator(s) will be added as a specification of the
 120           property for the given LOCALE (which defaults to `global' if
 121           omitted).
 122
 123           If VALUE is a list of specifications (each of which is a cons
 124           of a locale and a list of instantiators), then LOCALE must be
 125           `nil' (it does not make sense to explicitly specify a locale
 126           in this case), and specifications will be added as given.
 127
 128           If VALUE is a specifier (as would be returned by
 129           `face-property' if no LOCALE argument is given), then some or
 130           all of the specifications in the specifier will be added to
 131           the property.  In this case, the function is really
 132           equivalent to `copy-specifier' and LOCALE has the same
 133           semantics (if it is a particular locale, the specification
 134           for the locale will be copied; if a locale type,
 135           specifications for all locales of that type will be copied;
 136           if `nil' or `all', then all specifications will be copied).
 137
 138      HOW-TO-ADD should be either `nil' or one of the symbols `prepend',
 139      `append', `remove-tag-set-prepend', `remove-tag-set-append',
 140      `remove-locale', `remove-locale-type', or `remove-all'.  See
 141      `copy-specifier' and `add-spec-to-specifier' for a description of
 142      what each of these means.  Most of the time, you do not need to
 143      worry about this argument; the default behavior usually is fine.
 144
 145      In general, it is OK to pass an instance object (e.g. as returned
 146      by `face-property-instance') as an instantiator in place of an
 147      actual instantiator.  In such a case, the instantiator used to
 148      create that instance object will be used (for example, if you set
 149      a font-instance object as the value of the `font' property, then
 150      the font name used to create that object will be used instead).
 151      If some cases, however, doing this conversion does not make sense,
 152      and this will be noted in the documentation for particular types
 153      of instance objects.
 154
 155      If PROPERTY is not a built-in property, then this function will
 156      simply set its value if LOCALE is `nil'.  However, if LOCALE is
 157      given, then this function will attempt to add VALUE as the
 158      instantiator for the given LOCALE, using `add-spec-to-specifier'.
 159      If the value of the property is not a specifier, it will
 160      automatically be converted into a `generic' specifier.
 161
 162  - Function: remove-face-property face property &optional local tag-set
 163           exact-p
 164      This function removes a property of a FACE.
 165
 166      For built-in properties, this is analogous to `remove-specifier'.
 167      For more information, *Note Other Specification Functions::.
 168
 169      When PROPERTY is not a built-in property, this function will just
 170      remove its value if LOCALE is `nil' or `all'.  However, if LOCALE
 171      is other than that, this function will attempt to remove VALUE as
 172      the instantiator for the given LOCALE with `remove-specifier'.  If
 173      the value of the property is not a specifier, it will be converted
 174      into a `generic' specifier automatically.
 175
 176  - Function: face-property face property &optional locale
 177      This function returns FACE's value of the given PROPERTY.
 178
 179      If LOCALE is omitted, the FACE's actual value for PROPERTY will be
 180      returned.  For built-in properties, this will be a specifier
 181      object of a type appropriate to the property (e.g. a font or color
 182      specifier).  For other properties, this could be anything.
 183
 184      If LOCALE is supplied, then instead of returning the actual value,
 185      the specification(s) for the given locale or locale type will be
 186      returned.  This will only work if the actual value of PROPERTY is
 187      a specifier (this will always be the case for built-in properties,
 188      but not or not may apply to user-defined properties).  If the
 189      actual value of PROPERTY is not a specifier, this value will
 190      simply be returned regardless of LOCALE.
 191
 192      The return value will be a list of instantiators (e.g. strings
 193      specifying a font or color name), or a list of specifications,
 194      each of which is a cons of a locale and a list of instantiators.
 195      Specifically, if LOCALE is a particular locale (a buffer, window,
 196      frame, device, or `global'), a list of instantiators for that
 197      locale will be returned.  Otherwise, if LOCALE is a locale type
 198      (one of the symbols `buffer', `window', `frame', or `device'), the
 199      specifications for all locales of that type will be returned.
 200      Finally, if LOCALE is `all', the specifications for all locales of
 201      all types will be returned.
 202
 203      The specifications in a specifier determine what the value of
 204      PROPERTY will be in a particular "domain" or set of circumstances,
 205      which is typically a particular Emacs window along with the buffer
 206      it contains and the frame and device it lies within.  The value is
 207      derived from the instantiator associated with the most specific
 208      locale (in the order buffer, window, frame, device, and `global')
 209      that matches the domain in question.  In other words, given a
 210      domain (i.e. an Emacs window, usually), the specifier for PROPERTY
 211      will first be searched for a specification whose locale is the
 212      buffer contained within that window; then for a specification
 213      whose locale is the window itself; then for a specification whose
 214      locale is the frame that the window is contained within; etc.  The
 215      first instantiator that is valid for the domain (usually this
 216      means that the instantiator is recognized by the device [i.e. the
 217      X server or TTY device] that the domain is on).  The function
 218      `face-property-instance' actually does all this, and is used to
 219      determine how to display the face.
 220
 221  - Function: face-property-instance face property &optional domain
 222           default no-fallback
 223      This function returns the instance of FACE's PROPERTY in the
 224      specified DOMAIN.
 225
 226      Under most circumstances, DOMAIN will be a particular window, and
 227      the returned instance describes how the specified property
 228      actually is displayed for that window and the particular buffer in
 229      it.  Note that this may not be the same as how the property
 230      appears when the buffer is displayed in a different window or
 231      frame, or how the property appears in the same window if you
 232      switch to another buffer in that window; and in those cases, the
 233      returned instance would be different.
 234
 235      The returned instance will typically be a color-instance,
 236      font-instance, or pixmap-instance object, and you can query it
 237      using the appropriate object-specific functions.  For example, you
 238      could use `color-instance-rgb-components' to find out the RGB
 239      (red, green, and blue) components of how the `background' property
 240      of the `highlight' face is displayed in a particular window.  The
 241      results might be different from the results you would get for
 242      another window (perhaps the user specified a different color for
 243      the frame that window is on; or perhaps the same color was
 244      specified but the window is on a different X server, and that X
 245      server has different RGB values for the color from this one).
 246
 247      DOMAIN defaults to the selected window if omitted.
 248
 249      DOMAIN can be a frame or device, instead of a window.  The value
 250      returned for a such a domain is used in special circumstances when
 251      a more specific domain does not apply; for example, a frame value
 252      might be used for coloring a toolbar, which is conceptually
 253      attached to a frame rather than a particular window.  The value is
 254      also useful in determining what the value would be for a
 255      particular window within the frame or device, if it is not
 256      overridden by a more specific specification.
 257
 258      If PROPERTY does not name a built-in property, its value will
 259      simply be returned unless it is a specifier object, in which case
 260      it will be instanced using `specifier-instance'.
 261
 262      Optional arguments DEFAULT and NO-FALLBACK are the same as in
 263      `specifier-instance'.  *Note Specifiers::.
 264
 265 \1f
 266 File: lispref.info,  Node: Face Convenience Functions,  Next: Other Face Display Functions,  Prev: Face Properties,  Up: Faces
 267
 268 Face Convenience Functions
 269 --------------------------
 270
 271  - Function: set-face-foreground face color &optional locale tag
 272           how-to-add
 273  - Function: set-face-background face color &optional locale tag
 274           how-to-add
 275      These functions set the foreground (respectively, background)
 276      color of face FACE to COLOR.  The argument COLOR should be a
 277      string (the name of a color) or a color object as returned by
 278      `make-color' (*note Colors::).
 279
 280  - Function: set-face-background-pixmap face pixmap &optional locale
 281           tag how-to-add
 282      This function sets the background pixmap of face FACE to PIXMAP.
 283      The argument PIXMAP should be a string (the name of a bitmap or
 284      pixmap file; the directories listed in the variable
 285      `x-bitmap-file-path' will be searched) or a glyph object as
 286      returned by `make-glyph' (*note Glyphs::).  The argument may also
 287      be a list of the form `(WIDTH HEIGHT DATA)' where WIDTH and HEIGHT
 288      are the size in pixels, and DATA is a string, containing the raw
 289      bits of the bitmap.
 290
 291  - Function: set-face-font face font &optional locale tag how-to-add
 292      This function sets the font of face FACE.  The argument FONT
 293      should be a string or a font object as returned by `make-font'
 294      (*note Fonts::).
 295
 296  - Function: set-face-underline-p face underline-p &optional locale tag
 297           how-to-add
 298      This function sets the underline property of face FACE.
 299
 300  - Function: face-foreground face &optional locale
 301  - Function: face-background face &optional locale
 302      These functions return the foreground (respectively, background)
 303      color specifier of face FACE.  *Note Colors::.
 304
 305  - Function: face-background-pixmap face &optional locale
 306      This function return the background-pixmap glyph object of face
 307      FACE.
 308
 309  - Function: face-font face &optional locale
 310      This function returns the font specifier of face FACE.  (Note:
 311      This is not the same as the function `face-font' in FSF Emacs.)
 312      *Note Fonts::.
 313
 314  - Function: face-font-name face &optional domain
 315      This function returns the name of the font of face FACE, or `nil'
 316      if it is unspecified.  This is basically equivalent to `(font-name
 317      (face-font FACE) DOMAIN)' except that it does not cause an error
 318      if FACE's font is `nil'. (This function is named `face-font' in
 319      FSF Emacs.)
 320
 321  - Function: face-underline-p face &optional locale
 322      This function returns the underline property of face FACE.
 323
 324  - Function: face-foreground-instance face &optional domain
 325  - Function: face-background-instance face &optional domain
 326      These functions return the foreground (respectively, background)
 327      color specifier of face FACE.  *Note Colors::.
 328
 329  - Function: face-background-pixmap-instance face &optional domain
 330      This function return the background-pixmap glyph object of face
 331      FACE.
 332
 333  - Function: face-font-instance face &optional domain
 334      This function returns the font specifier of face FACE.  *Note
 335      Fonts::.
 336
 337 \1f
 338 File: lispref.info,  Node: Other Face Display Functions,  Prev: Face Convenience Functions,  Up: Faces
 339
 340 Other Face Display Functions
 341 ----------------------------
 342
 343  - Function: invert-face face &optional locale
 344      Swap the foreground and background colors of face FACE.  If the
 345      face doesn't specify both foreground and background, then its
 346      foreground and background are set to the default background and
 347      foreground.
 348
 349  - Function: face-equal face1 face2 &optional domain
 350      This returns `t' if the faces FACE1 and FACE2 will display in the
 351      same way.  DOMAIN is as in `face-property-instance'.
 352
 353  - Function: face-differs-from-default-p face &optional domain
 354      This returns `t' if the face FACE displays differently from the
 355      default face.  DOMAIN is as in `face-property-instance'.
 356
 357 \1f
 358 File: lispref.info,  Node: Fonts,  Next: Colors,  Prev: Faces,  Up: Faces and Window-System Objects
 359
 360 Fonts
 361 =====
 362
 363    This section describes how to work with font specifier and font
 364 instance objects, which encapsulate fonts in the window system.
 365
 366 * Menu:
 367
 368 * Font Specifiers::             Specifying how a font will appear.
 369 * Font Instances::              What a font specifier gets instanced as.
 370 * Font Instance Names::         The name of a font instance.
 371 * Font Instance Size::          The size of a font instance.
 372 * Font Instance Characteristics:: Display characteristics of font instances.
 373 * Font Convenience Functions::  Convenience functions that automatically
 374                                   instance and retrieve the properties
 375                                   of a font specifier.
 376
 377 \1f
 378 File: lispref.info,  Node: Font Specifiers,  Next: Font Instances,  Up: Fonts
 379
 380 Font Specifiers
 381 ---------------
 382
 383  - Function: font-specifier-p object
 384      This predicate returns `t' if OBJECT is a font specifier, and
 385      `nil' otherwise.
 386
 387 \1f
 388 File: lispref.info,  Node: Font Instances,  Next: Font Instance Names,  Prev: Font Specifiers,  Up: Fonts
 389
 390 Font Instances
 391 --------------
 392
 393  - Function: font-instance-p object
 394      This predicate returns `t' if OBJECT is a font instance, and `nil'
 395      otherwise.
 396
 397  - Function: make-font-instance name &optional device noerror
 398      This function creates a new font-instance object of the specified
 399      name.  DEVICE specifies the device this object applies to and
 400      defaults to the selected device.  An error is signalled if the
 401      font is unknown or cannot be allocated; however, if NOERROR is
 402      non-`nil', `nil' is simply returned in this case.
 403
 404      The returned object is a normal, first-class lisp object.  The way
 405      you "deallocate" the font is the way you deallocate any other lisp
 406      object: you drop all pointers to it and allow it to be garbage
 407      collected.  When these objects are GCed, the underlying X data is
 408      deallocated as well.
 409
 410 \1f
 411 File: lispref.info,  Node: Font Instance Names,  Next: Font Instance Size,  Prev: Font Instances,  Up: Fonts
 412
 413 Font Instance Names
 414 -------------------
 415
 416  - Function: list-fonts pattern &optional device
 417      This function returns a list of font names matching the given
 418      pattern.  DEVICE specifies which device to search for names, and
 419      defaults to the currently selected device.
 420
 421  - Function: font-instance-name font-instance
 422      This function returns the name used to allocate FONT-INSTANCE.
 423
 424  - Function: font-instance-truename font-instance
 425      This function returns the canonical name of the given font
 426      instance.  Font names are patterns which may match any number of
 427      fonts, of which the first found is used.  This returns an
 428      unambiguous name for that font (but not necessarily its only
 429      unambiguous name).
 430
 431 \1f
 432 File: lispref.info,  Node: Font Instance Size,  Next: Font Instance Characteristics,  Prev: Font Instance Names,  Up: Fonts
 433
 434 Font Instance Size
 435 ------------------
 436
 437  - Function: x-font-size font
 438      This function returns the nominal size of the given font.  This is
 439      done by parsing its name, so it's likely to lose.  X fonts can be
 440      specified (by the user) in either pixels or 10ths of points, and
 441      this returns the first one it finds, so you have to decide which
 442      units the returned value is measured in yourself ...
 443
 444  - Function: x-find-larger-font font &optional device
 445      This function loads a new, slightly larger version of the given
 446      font (or font name).  Returns the font if it succeeds, `nil'
 447      otherwise.  If scalable fonts are available, this returns a font
 448      which is 1 point larger.  Otherwise, it returns the next larger
 449      version of this font that is defined.
 450
 451  - Function: x-find-smaller-font font &optional device
 452      This function loads a new, slightly smaller version of the given
 453      font (or font name).  Returns the font if it succeeds, `nil'
 454      otherwise.  If scalable fonts are available, this returns a font
 455      which is 1 point smaller.  Otherwise, it returns the next smaller
 456      version of this font that is defined.
 457
 458 \1f
 459 File: lispref.info,  Node: Font Instance Characteristics,  Next: Font Convenience Functions,  Prev: Font Instance Size,  Up: Fonts
 460
 461 Font Instance Characteristics
 462 -----------------------------
 463
 464  - Function: font-instance-properties font
 465      This function returns the properties (an alist or `nil') of
 466      FONT-INSTANCE.
 467
 468  - Function: x-make-font-bold font &optional device
 469      Given an X font specification, this attempts to make a "bold" font.
 470      If it fails, it returns `nil'.
 471
 472  - Function: x-make-font-unbold font &optional device
 473      Given an X font specification, this attempts to make a non-bold
 474      font.  If it fails, it returns `nil'.
 475
 476  - Function: x-make-font-italic font &optional device
 477      Given an X font specification, this attempts to make an "italic"
 478      font.  If it fails, it returns `nil'.
 479
 480  - Function: x-make-font-unitalic font &optional device
 481      Given an X font specification, this attempts to make a non-italic
 482      font.  If it fails, it returns `nil'.
 483
 484  - Function: x-make-font-bold-italic font &optional device
 485      Given an X font specification, this attempts to make a
 486      "bold-italic" font.  If it fails, it returns `nil'.
 487
 488 \1f
 489 File: lispref.info,  Node: Font Convenience Functions,  Prev: Font Instance Characteristics,  Up: Fonts
 490
 491 Font Convenience Functions
 492 --------------------------
 493
 494  - Function: font-name font &optional domain
 495      This function returns the name of the FONT in the specified
 496      DOMAIN, if any.  FONT should be a font specifier object and DOMAIN
 497      is normally a window and defaults to the selected window if
 498      omitted.  This is equivalent to using `specifier-instance' and
 499      applying `font-instance-name' to the result.
 500
 501  - Function: font-truename font &optional domain
 502      This function returns the truename of the FONT in the specified
 503      DOMAIN, if any.  FONT should be a font specifier object and DOMAIN
 504      is normally a window and defaults to the selected window if
 505      omitted.  This is equivalent to using `specifier-instance' and
 506      applying `font-instance-truename' to the result.
 507
 508  - Function: font-properties font &optional domain
 509      This function returns the properties of the FONT in the specified
 510      DOMAIN, if any.  FONT should be a font specifier object and DOMAIN
 511      is normally a window and defaults to the selected window if
 512      omitted.  This is equivalent to using `specifier-instance' and
 513      applying `font-instance-properties' to the result.
 514
 515 \1f
 516 File: lispref.info,  Node: Colors,  Prev: Fonts,  Up: Faces and Window-System Objects
 517
 518 Colors
 519 ======
 520
 521 * Menu:
 522
 523 * Color Specifiers::            Specifying how a color will appear.
 524 * Color Instances::             What a color specifier gets instanced as.
 525 * Color Instance Properties::   Properties of color instances.
 526 * Color Convenience Functions:: Convenience functions that automatically
 527                                   instance and retrieve the properties
 528                                   of a color specifier.
 529
 530 \1f
 531 File: lispref.info,  Node: Color Specifiers,  Next: Color Instances,  Up: Colors
 532
 533 Color Specifiers
 534 ----------------
 535
 536  - Function: color-specifier-p object
 537      This function returns non-`nil' if OBJECT is a color specifier.
 538
 539 \1f
 540 File: lispref.info,  Node: Color Instances,  Next: Color Instance Properties,  Prev: Color Specifiers,  Up: Colors
 541
 542 Color Instances
 543 ---------------
 544
 545    A "color-instance object" is an object describing the way a color
 546 specifier is instanced in a particular domain.  Functions such as
 547 `face-background-instance' return a color-instance object.  For example,
 548
 549      (face-background-instance 'default (next-window))
 550          => #<color-instance moccasin 47=(FFFF,E4E4,B5B5) 0x678d>
 551
 552    The color-instance object returned describes the way the background
 553 color of the `default' face is displayed in the next window after the
 554 selected one.
 555
 556  - Function: color-instance-p object
 557      This function returns non-`nil' if OBJECT is a color-instance.
 558
 559 \1f
 560 File: lispref.info,  Node: Color Instance Properties,  Next: Color Convenience Functions,  Prev: Color Instances,  Up: Colors
 561
 562 Color Instance Properties
 563 -------------------------
 564
 565  - Function: color-instance-name color-instance
 566      This function returns the name used to allocate COLOR-INSTANCE.
 567
 568  - Function: color-instance-rgb-components color-instance
 569      This function returns a three element list containing the red,
 570      green, and blue color components of COLOR-INSTANCE.
 571
 572           (color-instance-rgb-components
 573             (face-background-instance 'default (next-window)))
 574               => (65535 58596 46517)
 575
 576 \1f
 577 File: lispref.info,  Node: Color Convenience Functions,  Prev: Color Instance Properties,  Up: Colors
 578
 579 Color Convenience Functions
 580 ---------------------------
 581
 582  - Function: color-name color &optional domain
 583      This function returns the name of the COLOR in the specified
 584      DOMAIN, if any.  COLOR should be a color specifier object and
 585      DOMAIN is normally a window and defaults to the selected window if
 586      omitted.  This is equivalent to using `specifier-instance' and
 587      applying `color-instance-name' to the result.
 588
 589  - Function: color-rgb-components color &optional domain
 590      This function returns the RGB components of the COLOR in the
 591      specified DOMAIN, if any.  COLOR should be a color specifier
 592      object and DOMAIN is normally a window and defaults to the
 593      selected window if omitted.  This is equivalent to using
 594      `specifier-instance' and applying `color-instance-rgb-components'
 595      to the result.
 596
 597           (color-rgb-components (face-background 'default (next-window)))
 598               => (65535 58596 46517)
 599
 600 \1f
 601 File: lispref.info,  Node: Glyphs,  Next: Annotations,  Prev: Faces and Window-System Objects,  Up: Top
 602
 603 Glyphs
 604 ******
 605
 606    A "glyph" is an object that is used for pixmaps and images of all
 607 sorts, as well as for things that "act" like pixmaps, such as
 608 non-textual strings ("annotations") displayed in a buffer or in the
 609 margins.  It is used in begin-glyphs and end-glyphs attached to extents,
 610 marginal and textual annotations, overlay arrows (`overlay-arrow-*'
 611 variables), toolbar buttons, mouse pointers, frame icons, truncation and
 612 continuation markers, and the like. (Basically, any place there is an
 613 image or something that acts like an image, there will be a glyph object
 614 representing it.)
 615
 616    The actual image that is displayed (as opposed to its position or
 617 clipping) is defined by an "image specifier" object contained within
 618 the glyph.  The separation between an image specifier object and a
 619 glyph object is made because the glyph includes other properties than
 620 just the actual image: e.g. the face it is displayed in (for text
 621 images), the alignment of the image (when it is in a buffer), etc.
 622
 623  - Function: glyphp object
 624      This function returns `t' if OBJECT is a glyph.
 625
 626 * Menu:
 627
 628 * Glyph Functions::     Functions for working with glyphs.
 629 * Images::              Graphical images displayed in a frame.
 630 * Glyph Types::         Each glyph has a particular type.
 631 * Mouse Pointer::       Controlling the mouse pointer.
 632 * Redisplay Glyphs::    Glyphs controlling various redisplay functions.
 633 * Subwindows::          Inserting an externally-controlled subwindow
 634                           into a buffer.
 635
 636 \1f
 637 File: lispref.info,  Node: Glyph Functions,  Next: Images,  Up: Glyphs
 638
 639 Glyph Functions
 640 ===============
 641
 642 * Menu:
 643
 644 * Creating Glyphs::     Creating new glyphs.
 645 * Glyph Properties::    Accessing and modifying a glyph's properties.
 646 * Glyph Convenience Functions::
 647                         Convenience functions for accessing particular
 648                           properties of a glyph.
 649 * Glyph Dimensions::    Determining the height, width, etc. of a glyph.
 650
 651 \1f
 652 File: lispref.info,  Node: Creating Glyphs,  Next: Glyph Properties,  Up: Glyph Functions
 653
 654 Creating Glyphs
 655 ---------------
 656
 657  - Function: make-glyph &optional spec-list type
 658      This function creates a new glyph object of type TYPE.
 659
 660      SPEC-LIST is used to initialize the glyph's image.  It is
 661      typically an image instantiator (a string or a vector; *Note Image
 662      Specifiers::), but can also be a list of such instantiators (each
 663      one in turn is tried until an image is successfully produced), a
 664      cons of a locale (frame, buffer, etc.) and an instantiator, a list
 665      of such conses, or any other form accepted by
 666      `canonicalize-spec-list'.  *Note Specifiers::, for more
 667      information about specifiers.
 668
 669      TYPE specifies the type of the glyph, which specifies in which
 670      contexts the glyph can be used, and controls the allowable image
 671      types into which the glyph's image can be instantiated.  TYPE
 672      should be one of `buffer' (used for glyphs in an extent, the
 673      modeline, the toolbar, or elsewhere in a buffer), `pointer' (used
 674      for the mouse-pointer), or `icon' (used for a frame's icon), and
 675      defaults to `buffer'.  *Note Glyph Types::.
 676
 677  - Function: make-glyph-internal &optional type
 678      This function creates a new, uninitialized glyph of type TYPE.
 679
 680  - Function: make-pointer-glyph &optional spec-list
 681      This function is equivalent to calling `make-glyph' with a TYPE of
 682      `pointer'.
 683
 684  - Function: make-icon-glyph &optional spec-list
 685      This function is equivalent to calling `make-glyph' with a TYPE of
 686      `icon'.
 687
 688 \1f
 689 File: lispref.info,  Node: Glyph Properties,  Next: Glyph Convenience Functions,  Prev: Creating Glyphs,  Up: Glyph Functions
 690
 691 Glyph Properties
 692 ----------------
 693
 694    Each glyph has a list of properties, which control all of the
 695 aspects of the glyph's appearance.  The following symbols have
 696 predefined meanings:
 697
 698 `image'
 699      The image used to display the glyph.
 700
 701 `baseline'
 702      Percent above baseline that glyph is to be displayed.  Only for
 703      glyphs displayed inside of a buffer.
 704
 705 `contrib-p'
 706      Whether the glyph contributes to the height of the line it's on.
 707      Only for glyphs displayed inside of a buffer.
 708
 709 `face'
 710      Face of this glyph (_not_ a specifier).
 711
 712  - Function: set-glyph-property glyph property value &optional locale
 713           tag-set how-to-add
 714      This function changes a property of a GLYPH.
 715
 716      For built-in properties, the actual value of the property is a
 717      specifier and you cannot change this; but you can change the
 718      specifications within the specifier, and that is what this
 719      function will do.  For user-defined properties, you can use this
 720      function to either change the actual value of the property or, if
 721      this value is a specifier, change the specifications within it.
 722
 723      If PROPERTY is a built-in property, the specifications to be added
 724      to this property can be supplied in many different ways:
 725
 726         * If VALUE is a simple instantiator (e.g. a string naming a
 727           pixmap filename) or a list of instantiators, then the
 728           instantiator(s) will be added as a specification of the
 729           property for the given LOCALE (which defaults to `global' if
 730           omitted).
 731
 732         * If VALUE is a list of specifications (each of which is a cons
 733           of a locale and a list of instantiators), then LOCALE must be
 734           `nil' (it does not make sense to explicitly specify a locale
 735           in this case), and specifications will be added as given.
 736
 737         * If VALUE is a specifier (as would be returned by
 738           `glyph-property' if no LOCALE argument is given), then some
 739           or all of the specifications in the specifier will be added
 740           to the property.  In this case, the function is really
 741           equivalent to `copy-specifier' and LOCALE has the same
 742           semantics (if it is a particular locale, the specification
 743           for the locale will be copied; if a locale type,
 744           specifications for all locales of that type will be copied;
 745           if `nil' or `all', then all specifications will be copied).
 746
 747      HOW-TO-ADD should be either `nil' or one of the symbols `prepend',
 748      `append', `remove-tag-set-prepend', `remove-tag-set-append',
 749      `remove-locale', `remove-locale-type', or `remove-all'.  See
 750      `copy-specifier' and `add-spec-to-specifier' for a description of
 751      what each of these means.  Most of the time, you do not need to
 752      worry about this argument; the default behavior usually is fine.
 753
 754      In general, it is OK to pass an instance object (e.g. as returned
 755      by `glyph-property-instance') as an instantiator in place of an
 756      actual instantiator.  In such a case, the instantiator used to
 757      create that instance object will be used (for example, if you set
 758      a font-instance object as the value of the `font' property, then
 759      the font name used to create that object will be used instead).
 760      If some cases, however, doing this conversion does not make sense,
 761      and this will be noted in the documentation for particular types
 762      of instance objects.
 763
 764      If PROPERTY is not a built-in property, then this function will
 765      simply set its value if LOCALE is `nil'.  However, if LOCALE is
 766      given, then this function will attempt to add VALUE as the
 767      instantiator for the given LOCALE, using `add-spec-to-specifier'.
 768      If the value of the property is not a specifier, it will
 769      automatically be converted into a `generic' specifier.
 770
 771  - Function: glyph-property glyph property &optional locale
 772      This function returns GLYPH's value of the given PROPERTY.
 773
 774      If LOCALE is omitted, the GLYPH's actual value for PROPERTY will
 775      be returned.  For built-in properties, this will be a specifier
 776      object of a type appropriate to the property (e.g. a font or color
 777      specifier).  For other properties, this could be anything.
 778
 779      If LOCALE is supplied, then instead of returning the actual value,
 780      the specification(s) for the given locale or locale type will be
 781      returned.  This will only work if the actual value of PROPERTY is
 782      a specifier (this will always be the case for built-in properties,
 783      but may or may not apply to user-defined properties).  If the
 784      actual value of PROPERTY is not a specifier, this value will
 785      simply be returned regardless of LOCALE.
 786
 787      The return value will be a list of instantiators (e.g. vectors
 788      specifying pixmap data), or a list of specifications, each of
 789      which is a cons of a locale and a list of instantiators.
 790      Specifically, if LOCALE is a particular locale (a buffer, window,
 791      frame, device, or `global'), a list of instantiators for that
 792      locale will be returned.  Otherwise, if LOCALE is a locale type
 793      (one of the symbols `buffer', `window', `frame', or `device'), the
 794      specifications for all locales of that type will be returned.
 795      Finally, if LOCALE is `all', the specifications for all locales of
 796      all types will be returned.
 797
 798      The specifications in a specifier determine what the value of
 799      PROPERTY will be in a particular "domain" or set of circumstances,
 800      which is typically a particular Emacs window along with the buffer
 801      it contains and the frame and device it lies within.  The value is
 802      derived from the instantiator associated with the most specific
 803      locale (in the order buffer, window, frame, device, and `global')
 804      that matches the domain in question.  In other words, given a
 805      domain (i.e. an Emacs window, usually), the specifier for PROPERTY
 806      will first be searched for a specification whose locale is the
 807      buffer contained within that window; then for a specification
 808      whose locale is the window itself; then for a specification whose
 809      locale is the frame that the window is contained within; etc.  The
 810      first instantiator that is valid for the domain (usually this
 811      means that the instantiator is recognized by the device [i.e. the
 812      X server or TTY device] that the domain is on).  The function
 813      `glyph-property-instance' actually does all this, and is used to
 814      determine how to display the glyph.
 815
 816  - Function: glyph-property-instance glyph property &optional domain
 817           default no-fallback
 818      This function returns the instance of GLYPH's PROPERTY in the
 819      specified DOMAIN.
 820
 821      Under most circumstances, DOMAIN will be a particular window, and
 822      the returned instance describes how the specified property
 823      actually is displayed for that window and the particular buffer in
 824      it.  Note that this may not be the same as how the property
 825      appears when the buffer is displayed in a different window or
 826      frame, or how the property appears in the same window if you
 827      switch to another buffer in that window; and in those cases, the
 828      returned instance would be different.
 829
 830      The returned instance is an image-instance object, and you can
 831      query it using the appropriate image instance functions.  For
 832      example, you could use `image-instance-depth' to find out the
 833      depth (number of color planes) of a pixmap displayed in a
 834      particular window.  The results might be different from the
 835      results you would get for another window (perhaps the user
 836      specified a different image for the frame that window is on; or
 837      perhaps the same image was specified but the window is on a
 838      different X server, and that X server has different color
 839      capabilities from this one).
 840
 841      DOMAIN defaults to the selected window if omitted.
 842
 843      DOMAIN can be a frame or device, instead of a window.  The value
 844      returned for such a domain is used in special circumstances when a
 845      more specific domain does not apply; for example, a frame value
 846      might be used for coloring a toolbar, which is conceptually
 847      attached to a frame rather than a particular window.  The value is
 848      also useful in determining what the value would be for a
 849      particular window within the frame or device, if it is not
 850      overridden by a more specific specification.
 851
 852      If PROPERTY does not name a built-in property, its value will
 853      simply be returned unless it is a specifier object, in which case
 854      it will be instanced using `specifier-instance'.
 855
 856      Optional arguments DEFAULT and NO-FALLBACK are the same as in
 857      `specifier-instance'.  *Note Specifiers::.
 858
 859  - Function: remove-glyph-property glyph property &optional locale
 860           tag-set exact-p
 861      This function removes a property from a glyph.  For built-in
 862      properties, this is analogous to `remove-specifier'.  *Note
 863      remove-specifier-p: Specifiers, for the meaning of the LOCALE,
 864      TAG-SET, and EXACT-P arguments.
 865
 866 \1f
 867 File: lispref.info,  Node: Glyph Convenience Functions,  Next: Glyph Dimensions,  Prev: Glyph Properties,  Up: Glyph Functions
 868
 869 Glyph Convenience Functions
 870 ---------------------------
 871
 872    The following functions are provided for working with specific
 873 properties of a glyph.  Note that these are exactly like calling the
 874 general functions described above and passing in the appropriate value
 875 for PROPERTY.
 876
 877    Remember that if you want to determine the "value" of a specific
 878 glyph property, you probably want to use the `*-instance' functions.
 879 For example, to determine whether a glyph contributes to its line
 880 height, use `glyph-contrib-p-instance', not `glyph-contrib-p'. (The
 881 latter will return a boolean specifier or a list of specifications, and
 882 you probably aren't concerned with these.)
 883
 884  - Function: glyph-image glyph &optional locale
 885      This function is equivalent to calling `glyph-property' with a
 886      property of `image'.  The return value will be an image specifier
 887      if LOCALE is `nil' or omitted; otherwise, it will be a
 888      specification or list of specifications.
 889
 890  - Function: set-glyph-image glyph spec &optional locale tag-set
 891           how-to-add
 892      This function is equivalent to calling `set-glyph-property' with a
 893      property of `image'.
 894
 895  - Function: glyph-image-instance glyph &optional domain default
 896           no-fallback
 897      This function returns the instance of GLYPH's image in the given
 898      DOMAIN, and is equivalent to calling `glyph-property-instance'
 899      with a property of `image'.  The return value will be an image
 900      instance.
 901
 902      Normally DOMAIN will be a window or `nil' (meaning the selected
 903      window), and an instance object describing how the image appears
 904      in that particular window and buffer will be returned.
 905
 906  - Function: glyph-contrib-p glyph &optional locale
 907      This function is equivalent to calling `glyph-property' with a
 908      property of `contrib-p'.  The return value will be a boolean
 909      specifier if LOCALE is `nil' or omitted; otherwise, it will be a
 910      specification or list of specifications.
 911
 912  - Function: set-glyph-contrib-p glyph spec &optional locale tag-set
 913           how-to-add
 914      This function is equivalent to calling `set-glyph-property' with a
 915      property of `contrib-p'.
 916
 917  - Function: glyph-contrib-p-instance glyph &optional domain default
 918           no-fallback
 919      This function returns whether the glyph contributes to its line
 920      height in the given DOMAIN, and is equivalent to calling
 921      `glyph-property-instance' with a property of `contrib-p'.  The
 922      return value will be either `nil' or `t'. (Normally DOMAIN will be
 923      a window or `nil', meaning the selected window.)
 924
 925  - Function: glyph-baseline glyph &optional locale
 926      This function is equivalent to calling `glyph-property' with a
 927      property of `baseline'.  The return value will be a specifier if
 928      LOCALE is `nil' or omitted; otherwise, it will be a specification
 929      or list of specifications.
 930
 931  - Function: set-glyph-baseline glyph spec &optional locale tag-set
 932           how-to-add
 933      This function is equivalent to calling `set-glyph-property' with a
 934      property of `baseline'.
 935
 936  - Function: glyph-baseline-instance glyph &optional domain default
 937           no-fallback
 938      This function returns the instance of GLYPH's baseline value in
 939      the given DOMAIN, and is equivalent to calling
 940      `glyph-property-instance' with a property of `baseline'.  The
 941      return value will be an integer or `nil'.
 942
 943      Normally DOMAIN will be a window or `nil' (meaning the selected
 944      window), and an instance object describing the baseline value
 945      appears in that particular window and buffer will be returned.
 946
 947  - Function: glyph-face glyph
 948      This function returns the face of GLYPH. (Remember, this is not a
 949      specifier, but a simple property.)
 950
 951  - Function: set-glyph-face glyph face
 952      This function changes the face of GLYPH to FACE.
 953
 954 \1f
 955 File: lispref.info,  Node: Glyph Dimensions,  Prev: Glyph Convenience Functions,  Up: Glyph Functions
 956
 957 Glyph Dimensions
 958 ----------------
 959
 960  - Function: glyph-width glyph &optional window
 961      This function returns the width of GLYPH on WINDOW.  This may not
 962      be exact as it does not take into account all of the context that
 963      redisplay will.
 964
 965  - Function: glyph-ascent glyph &optional window
 966      This function returns the ascent value of GLYPH on WINDOW.  This
 967      may not be exact as it does not take into account all of the
 968      context that redisplay will.
 969
 970  - Function: glyph-descent glyph &optional window
 971      This function returns the descent value of GLYPH on WINDOW.  This
 972      may not be exact as it does not take into account all of the
 973      context that redisplay will.
 974
 975  - Function: glyph-height glyph &optional window
 976      This function returns the height of GLYPH on WINDOW.  (This is
 977      equivalent to the sum of the ascent and descent values.)  This may
 978      not be exact as it does not take into account all of the context
 979      that redisplay will.
 980
 981 \1f
 982 File: lispref.info,  Node: Images,  Next: Glyph Types,  Prev: Glyph Functions,  Up: Glyphs
 983
 984 Images
 985 ======
 986
 987 * Menu:
 988
 989 * Image Specifiers::            Specifying how an image will appear.
 990 * Image Instantiator Conversion::
 991                                 Conversion is applied to image instantiators
 992                                   at the time they are added to an
 993                                   image specifier or at the time they
 994                                   are passed to `make-image-instance'.
 995 * Image Instances::             What an image specifier gets instanced as.
 996