overlays vs text properties

overlays vs text properties

[Eric Abrahamsen]

Hi,

I'm learning about overlays and text properties, and am looking for some
pointers on which to use. I'm building a medium-sized package, and one
function I need is that as the user moves point through paragraphs of
text in a buffer, each paragraph should be given a certain
property/overlay. As point leaves a paragraph its properties are
deleted, and as it enters a different paragraph (either by typing or
simple movement), that new paragraph gets the properties.

I can't decide whether to use overlays or regular properties. The
advantages of using overlays seem to be:

1. I can make a single named overlay, and move it around the buffer with
   move-overlay. Nice and clean, no searching for boundaries of things
   and suchlike.
2. I can attach multiple properties to a single overlay -- saves time
   and effort, and seems like good programming.

The disadvantage seems to be the practical issue that overlays don't
come with point-entered/point-left special properties -- ie, there's no
good way of keeping track of when point is going in and out of a
paragraph with the overlay, and then moving the overlay to the
next/previous/other paragraph.

Does anyone have any experience they'd like to share on this point?
Should I just use fundamental text properties?

Thanks,
Eric

Re: overlays vs text properties

[Eli Zaretskii]

> From: Eric Abrahamsen <eric@ericabrahamsen.net>
> Date: Tue, 12 Jul 2011 23:12:20 -0700
> 
> I can't decide whether to use overlays or regular properties. The
> advantages of using overlays seem to be:
> 
> 1. I can make a single named overlay, and move it around the buffer with
>    move-overlay. Nice and clean, no searching for boundaries of things
>    and suchlike.
> 2. I can attach multiple properties to a single overlay -- saves time
>    and effort, and seems like good programming.
> 
> The disadvantage seems to be the practical issue that overlays don't
> come with point-entered/point-left special properties -- ie, there's no
> good way of keeping track of when point is going in and out of a
> paragraph with the overlay, and then moving the overlay to the
> next/previous/other paragraph.
> 
> Does anyone have any experience they'd like to share on this point?
> Should I just use fundamental text properties?

You didn't give enough information to help you with this issue.  For
example: how many properties/overlays will exist in a given buffer
simultaneously?  Text properties scale much better than overlays, so
this information is important.

Also, text properties by default are copied with text, while overlays
are not.  Will this be an issue in your application?

Overlays can overlap, while text properties cannot (for the same
property).  Is this a possible issue for you?

Etc. etc.  IOW, tell more about your application to get any advice
beyond a list of abstract cons and pros.

Re: overlays vs text properties

[Eric Abrahamsen]

On Tue, Jul 12 2011, Eli Zaretskii wrote:

>> From: Eric Abrahamsen <eric@ericabrahamsen.net>
>> Date: Tue, 12 Jul 2011 23:12:20 -0700
>> 
>> I can't decide whether to use overlays or regular properties. The
>> advantages of using overlays seem to be:
>> 
>> 1. I can make a single named overlay, and move it around the buffer with
>>    move-overlay. Nice and clean, no searching for boundaries of things
>>    and suchlike.
>> 2. I can attach multiple properties to a single overlay -- saves time
>>    and effort, and seems like good programming.
>> 
>> The disadvantage seems to be the practical issue that overlays don't
>> come with point-entered/point-left special properties -- ie, there's no
>> good way of keeping track of when point is going in and out of a
>> paragraph with the overlay, and then moving the overlay to the
>> next/previous/other paragraph.
>> 
>> Does anyone have any experience they'd like to share on this point?
>> Should I just use fundamental text properties?
>
> You didn't give enough information to help you with this issue.  For
> example: how many properties/overlays will exist in a given buffer
> simultaneously?  Text properties scale much better than overlays, so
> this information is important.
>
> Also, text properties by default are copied with text, while overlays
> are not.  Will this be an issue in your application?
>
> Overlays can overlap, while text properties cannot (for the same
> property).  Is this a possible issue for you?
>
> Etc. etc.  IOW, tell more about your application to get any advice
> beyond a list of abstract cons and pros.

Can do! So:

1. I'll have a buffer and an indirect buffer on the same file. Each
   buffer will have a single "active" paragraph at any one time, but
   only one. So I don't think scaling is too much of an issue. I'm
   trying to create a "follow" situation, where a paragraph in the
   source buffer is matched to a paragraph in the indirect buffer, and
   these two paragraphs have (different) properties. But only the two
   paragraphs at one time, moving in unison.
2. This is mostly a visual effect (hence my leaning towards overlays),
   and copying text properties is not necessary. In fact, it would be
   annoying.
3. Overlapping would not be an issue -- within the "active" paragraphs
   there might be other properties present, but they would be separate
   from the overall paragraph property.

I am trying to create a translation environment, by modifying an org-mode
file so that I can move through one subtree while the indirect buffer
displays mirror paragraphs in another subtree. I want to link
source-language paragraphs with target-language paragraphs, so it's
pretty crucial that movement be covered: wherever point goes in the main
buffer, it should be tracked and mirrored in the indirect buffer.

Having different keymaps available within the "active" paragraphs is
key!

Thanks a lot for considering this issue…

Eric

Re: overlays vs text properties

[Eli Zaretskii]

> From: Eric Abrahamsen <eric@ericabrahamsen.net>
> Cc: help-gnu-emacs@gnu.org
> Date: Wed, 13 Jul 2011 00:23:23 -0700
> 
> 1. I'll have a buffer and an indirect buffer on the same file. Each
>    buffer will have a single "active" paragraph at any one time, but
>    only one. So I don't think scaling is too much of an issue. I'm
>    trying to create a "follow" situation, where a paragraph in the
>    source buffer is matched to a paragraph in the indirect buffer, and
>    these two paragraphs have (different) properties. But only the two
>    paragraphs at one time, moving in unison.
> 2. This is mostly a visual effect (hence my leaning towards overlays),
>    and copying text properties is not necessary. In fact, it would be
>    annoying.
> 3. Overlapping would not be an issue -- within the "active" paragraphs
>    there might be other properties present, but they would be separate
>    from the overall paragraph property.
> 
> I am trying to create a translation environment, by modifying an org-mode
> file so that I can move through one subtree while the indirect buffer
> displays mirror paragraphs in another subtree. I want to link
> source-language paragraphs with target-language paragraphs, so it's
> pretty crucial that movement be covered: wherever point goes in the main
> buffer, it should be tracked and mirrored in the indirect buffer.

Sounds like overlays are better suited for this job, unless I'm
missing something.

Re: overlays vs text properties

[Eric Abrahamsen]

On Wed, Jul 13 2011, Eli Zaretskii wrote:

>> From: Eric Abrahamsen <eric@ericabrahamsen.net>
>> Cc: help-gnu-emacs@gnu.org
>> Date: Wed, 13 Jul 2011 00:23:23 -0700
>> 
>> 1. I'll have a buffer and an indirect buffer on the same file. Each
>>    buffer will have a single "active" paragraph at any one time, but
>>    only one. So I don't think scaling is too much of an issue. I'm
>>    trying to create a "follow" situation, where a paragraph in the
>>    source buffer is matched to a paragraph in the indirect buffer, and
>>    these two paragraphs have (different) properties. But only the two
>>    paragraphs at one time, moving in unison.
>> 2. This is mostly a visual effect (hence my leaning towards overlays),
>>    and copying text properties is not necessary. In fact, it would be
>>    annoying.
>> 3. Overlapping would not be an issue -- within the "active" paragraphs
>>    there might be other properties present, but they would be separate
>>    from the overall paragraph property.
>> 
>> I am trying to create a translation environment, by modifying an org-mode
>> file so that I can move through one subtree while the indirect buffer
>> displays mirror paragraphs in another subtree. I want to link
>> source-language paragraphs with target-language paragraphs, so it's
>> pretty crucial that movement be covered: wherever point goes in the main
>> buffer, it should be tracked and mirrored in the indirect buffer.
>
> Sounds like overlays are better suited for this job, unless I'm
> missing something.

Only that there's no good way of moving overlays based on the movement
of point!

Re: overlays vs text properties

[PJ Weisberg]

On Wednesday, July 13, 2011, Eric Abrahamsen <eric@ericabrahamsen.net> wrote:
> On Wed, Jul 13 2011, Eli Zaretskii wrote:
>> Sounds like overlays are better suited for this job, unless I'm
>> missing something.
>
> Only that there's no good way of moving overlays based on the movement
> of point!

I don't know if there's a good way of "moving" text properties at all. ;-)

I know of one library (Magit) that moves its "highlight" overlay to
the current section in a post-command-hook.

-- 

-PJ

Re: overlays vs text properties

[Eric Abrahamsen]

On Wed, Jul 13 2011, PJ Weisberg wrote:

> On Wednesday, July 13, 2011, Eric Abrahamsen <eric@ericabrahamsen.net> wrote:
>> On Wed, Jul 13 2011, Eli Zaretskii wrote:
>>> Sounds like overlays are better suited for this job, unless I'm
>>> missing something.
>>
>> Only that there's no good way of moving overlays based on the movement
>> of point!
>
> I don't know if there's a good way of "moving" text properties at all. ;-)
>
> I know of one library (Magit) that moves its "highlight" overlay to
> the current section in a post-command-hook.

Thanks for everyone's responses, it sounds like post-command-hook is the
way to go, though that had originally seemed like overkill. I should
have thought of Magit as a good example to copy…

Thanks again,
Eric

Re: overlays vs text properties

[Eli Zaretskii]

> From: Eric Abrahamsen <eric@ericabrahamsen.net>
> Date: Wed, 13 Jul 2011 00:32:24 -0700
> 
> > Sounds like overlays are better suited for this job, unless I'm
> > missing something.
> 
> Only that there's no good way of moving overlays based on the movement
> of point!

Not sure what that means.  What would you like to do for which you
think you have no good way?

RE: overlays vs text properties

[Drew Adams]

I don't have much to offer here that hasn't been said already.

FWIW - It sounds to me like overlays are best suited for what you want to do.

Checking for point movements in/out of the overlay: How often and when do you
need to do it?

If you need to do it after each user interaction, then maybe do it in
`post-command-hook'.  If you can avoid using that hook, great (it tends to be
overused, in general).  But if that's when you need to check, then that's
probably the best approach I can think of.

(To check, just see whether point is inside the overlay.  To know whether that
state represents a change you will likely need to save the last in/out state and
compare.)