comparison man/lispref/extents.texi @ 96:dbb370e3c29e r20-0final

Import from CVS: tag r20-0final
author cvs
date Mon, 13 Aug 2007 09:12:40 +0200
parents 131b0175ea99
children 0d2f883870bc
comparison
equal deleted inserted replaced
95:e8c07a565f9c 96:dbb370e3c29e
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
564 @item unique 556 @item unique
565 (Boolean) Meaningful only in conjunction with @code{duplicable} and 557 (Boolean) Meaningful only in conjunction with @code{duplicable}.
566 @code{replicating}. When this is set, there may be only one instance of 558 When this is set, there may be only one instance of
567 this extent attached at a time. @xref{Duplicable Extents}. 559 this extent attached at a time. @xref{Duplicable Extents}.
568 560
569 @item invisible 561 @item invisible
570 (Boolean) If @code{t}, text under this extent will not be displayed -- 562 (Boolean) If @code{t}, text under this extent will not be displayed --
571 it will look as if the text is not there at all. 563 it will look as if the text is not there at all.
763 and so on. Through this, a whole tree of extents can be created, 755 and so on. Through this, a whole tree of extents can be created,
764 all deriving their properties from one root extent. Note, however, 756 all deriving their properties from one root extent. Note, however,
765 that you cannot create an inheritance loop -- this is explicitly 757 that you cannot create an inheritance loop -- this is explicitly
766 disallowed. 758 disallowed.
767 759
768 Parent extents are used to implement the ``replicating'' property 760 Parent extents are used to implement the extents over the modeline.
769 (@pxref{Duplicable Extents}) and extents over the modeline.
770 761
771 @defun set-extent-parent extent parent 762 @defun set-extent-parent extent parent
772 This function sets the parent of @var{extent} to @var{parent}. 763 This function sets the parent of @var{extent} to @var{parent}.
773 If @var{parent} is @code{nil}, the extent is set to have no parent. 764 If @var{parent} is @code{nil}, the extent is set to have no parent.
774 @end defun 765 @end defun
791 @end defun 782 @end defun
792 783
793 @node Duplicable Extents 784 @node Duplicable Extents
794 @section Duplicable Extents 785 @section Duplicable Extents
795 @cindex duplicable extent 786 @cindex duplicable extent
796 @cindex replicating extents
797 @cindex unique extents 787 @cindex unique extents
798 @cindex extent replica 788 @cindex extent replica
799 @cindex extent, duplicable 789 @cindex extent, duplicable
800 @cindex extent, replicating
801 @cindex extent, unique 790 @cindex extent, unique
802 791
803 If an extent has the @code{duplicable} property, it will be copied into 792 If an extent has the @code{duplicable} property, it will be copied into
804 strings, so that kill, yank, and undo commands will restore or copy it. 793 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.
819 794
820 Specifically: 795 Specifically:
821 796
822 @itemize @bullet 797 @itemize @bullet
823 @item 798 @item
835 Similarly, when text is copied or cut into the kill ring, any duplicable 810 Similarly, when text is copied or cut into the kill ring, any duplicable
836 extents will be remembered and reinserted later when the text is pasted 811 extents will be remembered and reinserted later when the text is pasted
837 back into a buffer. 812 back into a buffer.
838 813
839 @item 814 @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
872 When @code{concat} is called on strings, the extents in the strings are 815 When @code{concat} is called on strings, the extents in the strings are
873 copied into the resulting string. If two or more replicating extents 816 copied into the resulting string.
874 with the same parent end up overlapping or abutting in the resulting
875 string, they are merged into a single extent.
876 817
877 @item 818 @item
878 When @code{substring} is called on a string, the relevant extents 819 When @code{substring} is called on a string, the relevant extents
879 are copied into the resulting string. 820 are copied into the resulting string.
880 821
881 @item 822 @item
882 When a duplicable extent is detached by @code{detach-extent} or string 823 When a duplicable extent is detached by @code{detach-extent} or string
883 deletion, or inserted by @code{insert-extent} or string insertion, the 824 deletion, or inserted by @code{insert-extent} or string insertion, the
884 action is recorded by the undo mechanism so that it can be undone later. 825 action is recorded by the undo mechanism so that it can be undone later.
885 Note that if an extent gets detached and then a later undo causes the 826 Note that if an extent gets detached and then a later undo causes the
886 extent to get reinserted, the new extent will be `eq' to the original 827 extent to get reinserted, the new extent will not be `eq' to the original
887 extent if and only if the extent has the @code{replicating} property 828 extent.
888 set. This is the same as what happens when a string is cut and then
889 pasted back in.
890 829
891 @item 830 @item
892 Extent motion, face changes, and attachment via @code{make-extent} are 831 Extent motion, face changes, and attachment via @code{make-extent} are
893 not recorded by the undo mechanism. This means that extent changes 832 not recorded by the undo mechanism. This means that extent changes
894 which are to be undo-able must be performed by character editing, or by 833 which are to be undo-able must be performed by character editing, or by