GNU Info

(elisp)Image Descriptors

---

Next: XBM Images Up: Images

---

Enter node , (file) or (file)node

Image Descriptors
-----------------

   An image description is a list of the form `(image . PROPS)', where
PROPS is a property list containing alternating keyword symbols
(symbols whose names start with a colon) and their values.  You can use
any Lisp object as a property, but the only properties that have any
special meaning are certain symbols, all of them keywords.

   Every image descriptor must contain the property `:type TYPE' to
specify the format of the image.  The value of TYPE should be an image
type symbol; for example, `xpm' for an image in XPM format.

   Here is a list of other properties that are meaningful for all image
types:

`:file FILE'
     The `:file' property specifies to load the image from file FILE.
     If FILE is not an absolute file name, it is expanded in
     `data-directory'.

`:data DATA'
     The `:data' property specifies the actual contents of the image.
     Each image must use either `:data' or `:file', but not both.  For
     most image types, the value of the `:data' property should be a
     string containing the image data; we recommend using a unibyte
     string.

     Before using `:data', look for further information in the section
     below describing the specific image format.  For some image types,
     `:data' may not be supported; for some, it allows other data types;
     for some, `:data' alone is not enough, so you need to use other
     image properties along with `:data'.

`:margin MARGIN'
     The `:margin' property specifies how many pixels to add as an
     extra margin around the image.  The value, MARGIN, must be a a
     non-negative number, or a pair `(X . Y)' of such numbers.  If it
     is a pair, X specifies how many pixels to add horizontally, and Y
     specifies how many pixels to add vertically.  If `:margin' is not
     specified, the default is zero.

`:ascent ASCENT'
     The `:ascent' property specifies the amount of the image's height
     to use for its ascent--that is, the part above the baseline.  The
     value, ASCENT, must be a number in the range 0 to 100, or the
     symbol `center'.

     If ASCENT is a number, that percentage of the image's height is
     used for its ascent.

     If ASCENT is `center', the image is vertically centered around a
     centerline which would be the vertical centerline of text drawn at
     the position of the image, in the manner specified by the text
     properties and overlays that apply to the image.

     If this property is omitted, it defaults to 50.

`:relief RELIEF'
     The `:relief' property, if non-`nil', adds a shadow rectangle
     around the image.  The value, RELIEF, specifies the width of the
     shadow lines, in pixels.  If RELIEF is negative, shadows are drawn
     so that the image appears as a pressed button; otherwise, it
     appears as an unpressed button.

`:conversion ALGORITHM'
     The `:conversion' property, if non-`nil', specifies a conversion
     algorithm that should be applied to the image before it is
     displayed; the value, ALGORITHM, specifies which algorithm.

    `laplace'
    `emboss'
          Specifies the Laplace edge detection algorithm, which blurs
          out small differences in color while highlighting larger
          differences.  People sometimes consider this useful for
          displaying the image for a "disabled" button.

    `(edge-detection :matrix MATRIX :color-adjust ADJUST)'
          Specifies a general edge-detection algorithm.  MATRIX must be
          either a nine-element list or a nine-element vector of
          numbers.  A pixel at position x/y in the transformed image is
          computed from original pixels around that position.  MATRIX
          specifies, for each pixel in the neighborhood of x/y, a
          factor with which that pixel will influence the transformed
          pixel; element 0 specifies the factor for the pixel at
          x-1/y-1, element 1 the factor for the pixel at x/y-1 etc., as
          shown below:
                 (x-1/y-1  x/y-1  x+1/y-1
                  x-1/y    x/y    x+1/y
                  x-1/y+1  x/y+1  x+1/y+1)

          The resulting pixel is computed from the color intensity of
          the color resulting from summing up the RGB values of
          surrounding pixels, multiplied by the specified factors, and
          dividing that sum by the sum of the factors' absolute values.

          Laplace edge-detection currently uses a matrix of
                 (1  0  0
                  0  0  0
                  9  9 -1)

          Emboss edge-detection uses a matrix of
                 ( 2 -1  0
                  -1  0  1
                   0  1 -2)

    `disabled'
          Specifies transforming the image so that it looks "disabled".

`:mask MASK'
     If MASK is `heuristic' or `(heuristic BG)', build a clipping mask
     for the image, so that the background of a frame is visible behind
     the image.  If BG is not specified, or if BG is `t', determine the
     background color of the image by looking at the four corners of
     the image, assuming the most frequently occurring color from the
     corners is the background color of the image.  Otherwise, BG must
     be a list `(RED GREEN BLUE)' specifying the color to assume for
     the background of the image.

     If MASK is nil, remove a mask from the image, if it has one.
     Images in some formats include a mask which can be removed by
     specifying `:mask nil'.

 - Function: image-mask-p spec &optional frame
     This function returns `t' if image SPEC has a mask bitmap.  FRAME
     is the frame on which the image will be displayed.  FRAME `nil' or
     omitted means to use the selected frame (Note: Input Focus).