GNU Info

(elisp)Managing Overlays

---

Next: Finding Overlays Prev: Overlay Properties Up: Overlays

---

Enter node , (file) or (file)node

Managing Overlays
-----------------

   This section describes the functions to create, delete and move
overlays, and to examine their contents.

 - Function: make-overlay start end &optional buffer front-advance
          rear-advance
     This function creates and returns an overlay that belongs to
     BUFFER and ranges from START to END.  Both START and END must
     specify buffer positions; they may be integers or markers.  If
     BUFFER is omitted, the overlay is created in the current buffer.

     The arguments FRONT-ADVANCE and REAR-ADVANCE specify the insertion
     type for the start of the overlay and for the end of the overlay,
     respectively.  Note: Marker Insertion Types.

 - Function: overlay-start overlay
     This function returns the position at which OVERLAY starts, as an
     integer.

 - Function: overlay-end overlay
     This function returns the position at which OVERLAY ends, as an
     integer.

 - Function: overlay-buffer overlay
     This function returns the buffer that OVERLAY belongs to.

 - Function: delete-overlay overlay
     This function deletes OVERLAY.  The overlay continues to exist as
     a Lisp object, and its property list is unchanged, but it ceases
     to be attached to the buffer it belonged to, and ceases to have
     any effect on display.

     A deleted overlay is not permanently disconnected.  You can give
     it a position in a buffer again by calling `move-overlay'.

 - Function: move-overlay overlay start end &optional buffer
     This function moves OVERLAY to BUFFER, and places its bounds at
     START and END.  Both arguments START and END must specify buffer
     positions; they may be integers or markers.

     If BUFFER is omitted, OVERLAY stays in the same buffer it was
     already associated with; if OVERLAY was deleted, it goes into the
     current buffer.

     The return value is OVERLAY.

     This is the only valid way to change the endpoints of an overlay.
     Do not try modifying the markers in the overlay by hand, as that
     fails to update other vital data structures and can cause some
     overlays to be "lost".

   Here are some examples:

     ;; Create an overlay.
     (setq foo (make-overlay 1 10))
          => #<overlay from 1 to 10 in display.texi>
     (overlay-start foo)
          => 1
     (overlay-end foo)
          => 10
     (overlay-buffer foo)
          => #<buffer display.texi>
     ;; Give it a property we can check later.
     (overlay-put foo 'happy t)
          => t
     ;; Verify the property is present.
     (overlay-get foo 'happy)
          => t
     ;; Move the overlay.
     (move-overlay foo 5 20)
          => #<overlay from 5 to 20 in display.texi>
     (overlay-start foo)
          => 5
     (overlay-end foo)
          => 20
     ;; Delete the overlay.
     (delete-overlay foo)
          => nil
     ;; Verify it is deleted.
     foo
          => #<overlay in no buffer>
     ;; A deleted overlay has no position.
     (overlay-start foo)
          => nil
     (overlay-end foo)
          => nil
     (overlay-buffer foo)
          => nil
     ;; Undelete the overlay.
     (move-overlay foo 1 20)
          => #<overlay from 1 to 20 in display.texi>
     ;; Verify the results.
     (overlay-start foo)
          => 1
     (overlay-end foo)
          => 20
     (overlay-buffer foo)
          => #<buffer display.texi>
     ;; Moving and deleting the overlay does not change its properties.
     (overlay-get foo 'happy)
          => t