Mercurial > hg > xemacs-beta

comparison man/lispref/extents.texi @ 70:131b0175ea99 r20-0b30

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Import from CVS: tag r20-0b30
author cvs
date Mon, 13 Aug 2007 09:02:59 +0200
parents 8fc7fe29b841
children dbb370e3c29e
comparison
equal deleted inserted replaced
69:804d1389bcd6 70:131b0175ea99
82 the extent. An extent's @code{keymap} property controls the effect of 82 the extent. An extent's @code{keymap} property controls the effect of
83 key and mouse strokes within the extent's text, and the @code{mouse-face} 83 key and mouse strokes within the extent's text, and the @code{mouse-face}
84 property controls whether the extent is highlighted when the mouse moves 84 property controls whether the extent is highlighted when the mouse moves
85 over it. @xref{Extents and Events}. 85 over it. @xref{Extents and Events}.
86 86
87 An extent can optionally have a @dfn{begin-glyph} or @dfn{end-glyph} 87 An extent can optionally have a @dfn{start-glyph} or @dfn{end-glyph}
88 (but not both at one time) associated with it. A begin-glyph or 88 (but not both at one time) associated with it. A start-glyph or
89 end-glyph is a pixmap or string that will be displayed either at the 89 end-glyph is a pixmap or string that will be displayed either at the
90 start or end of an extent or in the margin of the line that the start 90 start or end of an extent or in the margin of the line that the start
91 or end of the extent lies in, depending on the extent's layout policy. 91 or end of the extent lies in, depending on the extent's layout policy.
92 Begin-glyphs and end-glyphs are used to implement annotations, and you 92 Start-glyphs and end-glyphs are used to implement annotations, and you
93 should use the annotation API functions in preference to the 93 should use the annotation API functions in preference to the
94 lower-level extent functions. For more information, @xref{Annotations}. 94 lower-level extent functions. For more information, @xref{Annotations}.
95 95
96 If an extent has its @code{detachable} property set, it will become 96 If an extent has its @code{detachable} property set, it will become
97 @dfn{detached} (i.e. no longer in the buffer) when all its text its 97 @dfn{detached} (i.e. no longer in the buffer) when all its text its
551 @item duplicable 551 @item duplicable
552 (Boolean) Whether this extent should be copied into strings, so that 552 (Boolean) Whether this extent should be copied into strings, so that
553 kill, yank, and undo commands will restore or copy it. @xref{Duplicable 553 kill, yank, and undo commands will restore or copy it. @xref{Duplicable
554 Extents}. 554 Extents}.
555 555
556 @item replicating
557 (Boolean) Meaningful only in conjunction with @code{duplicable}. If
558 set, actions that cause an extent to be copied from a buffer to a string
559 cause the original extent to be recorded in the copy (as the copied
560 extent's parent), so that when the extent is copied back into the
561 buffer, @code{eq}ness between the original extent and the re-inserted
562 extent is maintained whenever possible. @xref{Duplicable Extents}.
563
556 @item unique 564 @item unique
557 (Boolean) Meaningful only in conjunction with @code{duplicable}. 565 (Boolean) Meaningful only in conjunction with @code{duplicable} and
558 When this is set, there may be only one instance of 566 @code{replicating}. When this is set, there may be only one instance of
559 this extent attached at a time. @xref{Duplicable Extents}. 567 this extent attached at a time. @xref{Duplicable Extents}.
560 568
561 @item invisible 569 @item invisible
562 (Boolean) If @code{t}, text under this extent will not be displayed -- 570 (Boolean) If @code{t}, text under this extent will not be displayed --
563 it will look as if the text is not there at all. 571 it will look as if the text is not there at all.
755 and so on. Through this, a whole tree of extents can be created, 763 and so on. Through this, a whole tree of extents can be created,
756 all deriving their properties from one root extent. Note, however, 764 all deriving their properties from one root extent. Note, however,
757 that you cannot create an inheritance loop -- this is explicitly 765 that you cannot create an inheritance loop -- this is explicitly
758 disallowed. 766 disallowed.
759 767
760 Parent extents are used to implement the extents over the modeline. 768 Parent extents are used to implement the ``replicating'' property
769 (@pxref{Duplicable Extents}) and extents over the modeline.
761 770
762 @defun set-extent-parent extent parent 771 @defun set-extent-parent extent parent
763 This function sets the parent of @var{extent} to @var{parent}. 772 This function sets the parent of @var{extent} to @var{parent}.
764 If @var{parent} is @code{nil}, the extent is set to have no parent. 773 If @var{parent} is @code{nil}, the extent is set to have no parent.
765 @end defun 774 @end defun
782 @end defun 791 @end defun
783 792
784 @node Duplicable Extents 793 @node Duplicable Extents
785 @section Duplicable Extents 794 @section Duplicable Extents
786 @cindex duplicable extent 795 @cindex duplicable extent
796 @cindex replicating extents
787 @cindex unique extents 797 @cindex unique extents
788 @cindex extent replica 798 @cindex extent replica
789 @cindex extent, duplicable 799 @cindex extent, duplicable
800 @cindex extent, replicating
790 @cindex extent, unique 801 @cindex extent, unique
791 802
792 If an extent has the @code{duplicable} property, it will be copied into 803 If an extent has the @code{duplicable} property, it will be copied into
793 strings, so that kill, yank, and undo commands will restore or copy it. 804 strings, so that kill, yank, and undo commands will restore or copy it.
805
806 If a duplicable extent also has the @code{replicating} property, the
807 extent itself is not actually copied; rather, a pointer to it is
808 stored, along with the start and end positions of the extent. (This
809 is done by making the copied extent a child of the original extent.
810 Formerly, this was done by creating a special object called an
811 @dfn{extent replica}. Extent replicas no longer exist, but all the
812 functionality is available in a cleaner and more general fashion
813 using the @code{replicating} property.) This means that, e.g.,
814 if you copy a replacting extent into the kill ring, then change the
815 properties of the extent, then paste the kill-ring text back into the
816 buffer, the newly-inserted extent will have the property changes you
817 just made to the original extent, and not the property values at the
818 time the text was copied into the kill ring.
794 819
795 Specifically: 820 Specifically:
796 821
797 @itemize @bullet 822 @itemize @bullet
798 @item 823 @item
810 Similarly, when text is copied or cut into the kill ring, any duplicable 835 Similarly, when text is copied or cut into the kill ring, any duplicable
811 extents will be remembered and reinserted later when the text is pasted 836 extents will be remembered and reinserted later when the text is pasted
812 back into a buffer. 837 back into a buffer.
813 838
814 @item 839 @item
840 If a duplicable extent has the @code{replicating} property, then when
841 it is copied into a string, the parent of the new extent is set to the
842 extent it was copied from.
843
844 @item
845 When an extent with the @code{replicating} property is copied from
846 a string back into a buffer:
847
848 @itemize @minus
849 @item
850 If the extent's parent was detached from this buffer, it is reattached
851 at the new range.
852
853 @item
854 If the extent's parent is attached to this buffer and is contiguous with
855 or overlaps the new range, it is simply extended to include that range.
856 Note that in this case the extent's @code{paste-function} is not called
857 (see below).
858
859 @item
860 If the extent's parent was detached from another buffer, it is copied
861 as if by @code{copy-extent} and attached at the new range.
862
863 @item
864 If the extent's parent is attached to another buffer, or is attached to
865 this buffer and does not overlap the new range, it is copied as if by
866 @code{copy-extent} and attached at the new range. However, if the
867 extent's parent has the @code{unique} property, this action is inhibited
868 and nothing happens.
869 @end itemize
870
871 @item
815 When @code{concat} is called on strings, the extents in the strings are 872 When @code{concat} is called on strings, the extents in the strings are
816 copied into the resulting string. 873 copied into the resulting string. If two or more replicating extents
874 with the same parent end up overlapping or abutting in the resulting
875 string, they are merged into a single extent.
817 876
818 @item 877 @item
819 When @code{substring} is called on a string, the relevant extents 878 When @code{substring} is called on a string, the relevant extents
820 are copied into the resulting string. 879 are copied into the resulting string.
821 880
822 @item 881 @item
823 When a duplicable extent is detached by @code{detach-extent} or string 882 When a duplicable extent is detached by @code{detach-extent} or string
824 deletion, or inserted by @code{insert-extent} or string insertion, the 883 deletion, or inserted by @code{insert-extent} or string insertion, the
825 action is recorded by the undo mechanism so that it can be undone later. 884 action is recorded by the undo mechanism so that it can be undone later.
826 Note that if an extent gets detached and then a later undo causes the 885 Note that if an extent gets detached and then a later undo causes the
827 extent to get reinserted, the new extent will not be `eq' to the original 886 extent to get reinserted, the new extent will be `eq' to the original
828 extent. 887 extent if and only if the extent has the @code{replicating} property
888 set. This is the same as what happens when a string is cut and then
889 pasted back in.
829 890
830 @item 891 @item
831 Extent motion, face changes, and attachment via @code{make-extent} are 892 Extent motion, face changes, and attachment via @code{make-extent} are
832 not recorded by the undo mechanism. This means that extent changes 893 not recorded by the undo mechanism. This means that extent changes
833 which are to be undo-able must be performed by character editing, or by 894 which are to be undo-able must be performed by character editing, or by