Mercurial > hg > xemacs-beta
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 |