Re: marks API

[Havoc Pennington <hp redhat com>]

Tim Janik <timj@gtk.org> writes:
> > void gtk_text_mark_set_visible (GtkTextMark *mark,
> >                                 gboolean setting);
> 
> what is this doing exactly? how is a mark being visualized?
> do i get multiple "cursors" if more than one mark is visible?
>

Yes. Example of a use for this is to display the drop point when you
are dragging text to be inserted in the buffer.
 
> > gboolean gtk_text_mark_is_visible (GtkTextMark *mark);
> > char *   gtk_text_mark_get_name   (GtkTextMark *mark);
> 
> can we finally use g* prefixed types? yes?
>

Yes, though that's the least of the style issues with this widget. ;-)
I want to fix them after merging these fixes back to HEAD, because
otherwise it will conceal the fixes in the diff.
 
> > GtkTextMark *gtk_text_mark_ref (GtkTextMark *mark);
> > void         gtk_text_mark_unref (GtkTextMark *mark);
> 
> how's that implemented?
> is a mark something like a pseudo-object?
> why could there be a need to reference marks?
> 

A mark is actually a GtkTextLineSegment, which is an internal data
structure (you do not want to know, trust me). It's pretty lightweight
and should remain so.

Reference counting and deleting here are very much like GtkObject; the
reference prevents finalization so you can keep the pointer valid, and
that's it. Deletion means removing the mark from the buffer. There is
a signal on the buffer which gets emitted on deletion. 

> what do i need marks for?
> (other than getting a name that i couldn't set through the
> gtk_text_mark_* API)
> 

Marks are like bookmarks for a spot in the buffer. You would use them
to hold a place during mutations that would invalidate an iterator.
A mark behaves like the cursor (though the cursor has right gravity,
and marks can also have left gravity). Like the cursor, the mark's
position after inserting or deleting text around it is predictable.

> > 
> > gboolean   gtk_text_mark_deleted (GtkTextMark *mark);
> 
> this simply returns whether a mark got deleted meanwhile?
> could i get "delete notification" of such an event occouring?
>

This could also be called gtk_text_mark_not_in_buffer()
or gtk_text_buffer_mark_in_buffer(). There's a signal on the buffer
you could use to get notification.
  
> i guess i need to deeply dive into your text widget implementation
> before i can provide you with reasonable comments on your TextMark
> API, unless you give a little more context.
> 
> [this is meant as general criticism on your "API-review" postals,
> for a large part, they mostly contain <code> and maybe a short blurb
> if the reader is lucky]
> 

Well, I try to explain them in the blurb. ;-) Ask questions if you
have them. tktext-port/README also has a longer overview of the widget
IIRC, though it may be outdated in some details now.

Havoc