Info Catalog elisp: Defining Images elisp: Images elisp: Multi-Frame Images

elisp: Showing Images

 
 37.17.9 Showing Images
 ----------------------
 
 You can use an image descriptor by setting up the ‘display’ property
 yourself, but it is easier to use the functions in this section.
 
  -- Function: insert-image image &optional string area slice
      This function inserts IMAGE in the current buffer at point.  The
      value IMAGE should be an image descriptor; it could be a value
      returned by ‘create-image’, or the value of a symbol defined with
      ‘defimage’.  The argument STRING specifies the text to put in the
      buffer to hold the image.  If it is omitted or ‘nil’,
      ‘insert-image’ uses ‘" "’ by default.
 
      The argument AREA specifies whether to put the image in a margin.
      If it is ‘left-margin’, the image appears in the left margin;
      ‘right-margin’ specifies the right margin.  If AREA is ‘nil’ or
      omitted, the image is displayed at point within the buffer’s text.
 
      The argument SLICE specifies a slice of the image to insert.  If
      SLICE is ‘nil’ or omitted the whole image is inserted.  Otherwise,
      SLICE is a list ‘(X Y WIDTH HEIGHT)’ which specifies the X and Y
      positions and WIDTH and HEIGHT of the image area to insert.
      Integer values are in units of pixels.  A floating-point number in
      the range 0.0–1.0 stands for that fraction of the width or height
      of the entire image.
 
      Internally, this function inserts STRING in the buffer, and gives
      it a ‘display’ property which specifies IMAGE.  Display
      Property.
 
  -- Function: insert-sliced-image image &optional string area rows cols
      This function inserts IMAGE in the current buffer at point, like
      ‘insert-image’, but splits the image into ROWSxCOLS equally sized
      slices.
 
      Emacs displays each slice as a separate image, and allows more
      intuitive scrolling up/down, instead of jumping up/down the entire
      image when paging through a buffer that displays (large) images.
 
  -- Function: put-image image pos &optional string area
      This function puts image IMAGE in front of POS in the current
      buffer.  The argument POS should be an integer or a marker.  It
      specifies the buffer position where the image should appear.  The
      argument STRING specifies the text that should hold the image as an
      alternative to the default.
 
      The argument IMAGE must be an image descriptor, perhaps returned by
      ‘create-image’ or stored by ‘defimage’.
 
      The argument AREA specifies whether to put the image in a margin.
      If it is ‘left-margin’, the image appears in the left margin;
      ‘right-margin’ specifies the right margin.  If AREA is ‘nil’ or
      omitted, the image is displayed at point within the buffer’s text.
 
      Internally, this function creates an overlay, and gives it a
      ‘before-string’ property containing text that has a ‘display’
      property whose value is the image.  (Whew!)
 
  -- Function: remove-images start end &optional buffer
      This function removes images in BUFFER between positions START and
      END.  If BUFFER is omitted or ‘nil’, images are removed from the
      current buffer.
 
      This removes only images that were put into BUFFER the way
      ‘put-image’ does it, not images that were inserted with
      ‘insert-image’ or in other ways.
 
  -- Function: image-size spec &optional pixels frame
      This function returns the size of an image as a pair
      ‘(WIDTH . HEIGHT)’.  SPEC is an image specification.  PIXELS
      non-‘nil’ means return sizes measured in pixels, otherwise return
      sizes measured in the default character size of FRAME (Frame
      Font).  FRAME is the frame on which the image will be displayed.
      FRAME null or omitted means use the selected frame (Input
      Focus).
 
  -- Variable: max-image-size
      This variable is used to define the maximum size of image that
      Emacs will load.  Emacs will refuse to load (and display) any image
      that is larger than this limit.
 
      If the value is an integer, it directly specifies the maximum image
      height and width, measured in pixels.  If it is floating point, it
      specifies the maximum image height and width as a ratio to the
      frame height and width.  If the value is non-numeric, there is no
      explicit limit on the size of images.
 
      The purpose of this variable is to prevent unreasonably large
      images from accidentally being loaded into Emacs.  It only takes
      effect the first time an image is loaded.  Once an image is placed
      in the image cache, it can always be displayed, even if the value
      of ‘max-image-size’ is subsequently changed (Image Cache).
 

Info Catalog elisp: Defining Images elisp: Images elisp: Multi-Frame Images