Re: FYI: GtkText design progress

[Tim Janik <timj gtk org>]

On Mon, 27 Dec 1999, Derek Simkowiak wrote:

>      All,
> 	I am one of the people working on a replacement GtkText widget.  

hi derek,

just read over your document and have some comments.
most notably, one of the hardest problems of the
current GtkText widget is maintenance of the line
start cache, you didn't indicate that you want to
simply take over the current pile of hacks that
build up around it, but you didn't solve the problem
of knowing about line offsets either, so i'm
wondering: how do you know where in the gaped text
buffer do distinct lines start?

> Thanks,
> Derek
> ---------------------------------------------------------------------------
> 
> New textwidget API and design:
> ------------------------------
> 
> 	There will be two modules (i.e., components) to the text
> widget.
> 
> 	Normally, these would be modules in their own .h and .c files, but
> since this is a GTK+ widget, everything goes into the same .h and .c
> files.  The APIs are treated separately, so don't add any functions that
> access private members of structs that should be opaque.  If you need
> access to something that can't be obtained via that module's API, write a
> new function for it.  Clarity and maintainability are paramount.

hm, if you want to use something like
gtktext.h	- widget related headers
gtktext.c	- widget related implementation
gtktextbuffer.h	- gaped text buffer API
gtktextbuffer.c	- gaped text buffer implementation
gtktextprops.h	- text property API
gtktextprops.c	- text property implementation

no one is going to stop you from that (not implying that this would
be the sort of split up you should/want to make).

> 	Instead, we use a "property list".  The property list is a
> doubly-linked list of TextProperty structs.  A TextProperty struct is
> defined as:

if you're expecting to have huge numbers of text properties around and
need to maintain the property list on your own anyways, don't allocate
extra GList nodes for this, but put TextProperty *prev, *next; pointers
at the begining of your structure right away (the necessary bits for
list and tail cache maintenance are already waiting in glist.c and
queue.c to be cut'n pasted ;).

> 
> struct _TextProperty
> {
>   /* Font. */
>   GtkSCTextFont* font;
> 
>   /* Background Color. */
>   GdkColor back_color;
>   
>   /* Foreground Color. */
>   GdkColor fore_color;
> 
>   /* Show which properties are set */
>   TextPropertyFlags flags;
> 
>   /* Length of this property. */
>   guint length;
> 
>   /* user data */
>   gpointer user_data;
> };
> 
> 	[...and just FYI:]
> 
> typedef enum {
>   PROPERTY_FONT =       1 << 0,
>   PROPERTY_FOREGROUND = 1 << 1,
>   PROPERTY_BACKGROUND = 1 << 2,
>   PROPERTY_DATA =       1 << 3
> } TextPropertyFlags;
> 
> 
> 
> FIXME: Should some of those members be labelled as 'private'?

if this is going to be part of the public API (which should be
prefered, so syntax highlighting code can inspect what is already
marked up) you need to prefix your enum values and the structure name.

> 	The user_data struct member is there for extensibility.  With it,
> you could specify things like whether or not the text should be blinking,
> or translucent, or saved with <emphasis> tags, or who-knows-what.  
> (FIXME: Need to describe the API for that here).  The TextProperty also
> has its own API, in order to maintain clarity of code, but it is
> definately a sub-componenent of the data buffer.

this is one important thing you need to have specified in the forefield.
one user_data pointer is seldomly sufficient, there will always be multiple
domains wanting to set specific properties on text portions. while in gtk
we can usually just use g_datalist_*() for such things, that is not the case
for text properties, as you need to be able to arbitrarily copy, delete,
merge and compare text properties (and therefore the user data portions
as well). so to avoid a revised text widget to fall short on this again,
you'll have to solve this now ;)

> 	Be aware that there is much code in the GtkText widget which is
> not part of either the data buffer or the renderer.  The GtkText is built
> on top of those componenents, but some code (such as handling the
> GtkBindings, clipboard stuff, the GTK+ signals, etc.) is purely widget
> code which does not belong in either the buffer or the renderer.

which strongly suggests to split its implementation up into arbitrary
header and .c files.

---
ciaoTJ