text_widget.txt

gtk是linux一款强大的夸平台的图形化开发工具

Date: Sun, 14 Sep 1997 20:17:06 -0700 (PDT)
From: Josh MacDonald <[e-mail]>
To: [e-mail], [e-mail]
Subject: [gtk-list] gtktext widget internal documentation


Pete convinced me to just write up the text widget and let someone else
finish it.  I'm pretty busy and have other commitments now.  Sorry.  I think
I'm not the most qualified for some of the remaining work anyway, because I
don't really know Gtk and it's event model very well.  Most of the work so 
far was possible without knowing Gtk all that well, it was simply a data 
structure exercise (though after reading this you might say it was a fairly
complicated data structure exercise).  I'm happy to answer questions.

-josh


High level description:

There are several layers of data structure to the widget.  They are
seperated from each other as much as possible.  The first is a gapped
text segment similar to the data structure Emacs uses for representing
text.  Then there is a property list, which stores text properties for
various ranges of text.  There is no direct relation between the text
property list and the gapped text segment.  Finally there is a drawn
line parameter cache to speed calculations when drawing and redrawing
lines on screen.  In addition to these data structures, there are
structures to help iterate over text in the buffer.

The gapped text segment is quite simple.  It's parameters are (all
parameters I mention here are in the structure GtkText):

  guchar* text;
  guint text_len;
  guint gap_position;
  guint gap_size;
  guint text_end;

TEXT is the buffer, TEXT_LEN is its allocated length.  TEXT_END is the
length of the text, including the gap.  GAP_POSITION is the start of
the gap, and GAP_SIZE is the gap's length.  Therefore, TEXT_END -
GAP_SIZE is the length of the text in the buffer.  The macro
TEXT_LENGTH returns this value.  To get the value of a character in
the buffer, use the macro TEXT_INDEX(TEXT,INDEX).  This macro tests
whether the index is less than the GAP_POSITION and returns
TEXT[INDEX] or returns TEXT[GAP_SIZE+INDEX].  The function
MOVE_GAP_TO_POINT positions the gap to a particular index.  The
function MAKE_FORWARD_SPACE lengthens the gap to provide room for a
certain number of characters.

The property list is a doubly linked list (GList) of text property
data for each contiguous set of characters with similar properties.
The data field of the GList points to a TextProperty structure, which
contains:

  TextFont* font;
  GdkColor* back_color;
  GdkColor* fore_color;
  guint length;

Currently, only font and color data are contained in the property
list, but it can be extended by modifying the INSERT_TEXT_PROPERTY,
TEXT_PROPERTIES_EQUAL, and a few other procedures.  The text property
structure does not contain an absolute offset, only a length.  As a
result, inserting a character into the buffer simply requires moving
the gap to the correct position, making room in the buffer, and either
inserting a new property or extending the old one.  This logic is done
by INSERT_TEXT_PROPERTY.  A similar procedure exists to delete from
the text property list, DELETE_TEXT_PROPERTY.  Since the property
structure doesn't contain an offset, insertion into the list is an
O(1) operation.  All such operations act on the insertion point, which
is the POINT field of the GtkText structure.

The GtkPropertyMark structure is used for keeping track of the mapping
between absolute buffer offsets and positions in the property list.
These will be referred to as property marks.  Generally, there are
four property marks the system keeps track of.  Two are trivial, the
beginning and the end of the buffer are easy to find.  The other two
are the insertion point (POINT) and the cursor point (CURSOR_MARK).
All operations on the text buffer are done using a property mark as a
sort of cursor to keep track of the alignment of the property list and
the absolute buffer offset.  The GtkPropertyMark structure contains:

  GList* property;
  guint offset;
  guint index;

PROPERTY is a pointer at the current property list element.  INDEX is
the absolute buffer index, and OFFSET is the offset of INDEX from the
beginning of PROPERTY.  It is essential to keep property marks valid,
or else you will have the wrong text properties at each property mark
transition.  An important point is that all property marks are invalid
after a buffer modification unless care is taken to keep them
accurate.  That is the difficulty of the insert and delete operations,
because as the next section describes, line data is cached and by
neccesity contains text property marks.  The functions for operating
and computing property marks are:

 void advance_mark     (GtkPropertyMark* mark);
 void decrement_mark   (GtkPropertyMark* mark);
 void advance_mark_n   (GtkPropertyMark* mark, gint n);
 void decrement_mark_n (GtkPropertyMark* mark, gint n);
 void move_mark_n      (GtkPropertyMark* mark, gint n);

 GtkPropertyMark find_mark      (GtkText* text, guint mark_position);
 GtkPropertyMark find_mark_near (GtkText* text, guint mark_position,
                                 const GtkPropertyMark* near);

ADVANCE_MARK and DECREMENT_MARK modify the mark by plus or minus one
buffer index.  ADVANCE_MARK_N and DECREMENT_MARK_N modify the mark by
plus or minus N indices.  MOVE_MARK_N accepts a positive or negative
argument.  FIND_MARK returns a mark at MARK_POSITION using a linear
search from the nearest known property mark (the beginning, the end,
the point, etc).  FIND_MARK_NEAR also does a linear search, but
searches from the NEAR argument.  A number of macros exist at the top
of the file for doing things like getting the current text property,
or some component of the current property.  See the MARK_* macros.

Next there is a LineParams structure which contains all the
information neccesary to draw one line of text on screen.  When I say
"line" here, I do not mean one line of text seperated by newlines,
rather I mean one row of text on screen.  It is a matter of policy how
visible lines are chosen and there are currently two policies,
line-wrap and no-line-wrap.  I suspect it would not be difficult to
implement new policies for doing such things as justification.  The
LineParams structure includes the following fields:

  guint font_ascent;
  guint font_descent;
  guint pixel_width;
  guint displayable_chars;
  guint wraps : 1;

  PrevTabCont tab_cont;
  PrevTabCont tab_cont_next;

  GtkPropertyMark start;
  GtkPropertyMark end;

FONT_ASCENT and FONT_DESCENT are the maximum ascent and descent of any
character in the line.  PIXEL_WIDTH is the number of pixels wide the
drawn region is, though I don't think it's actually being used
currently.  You may wish to remove this field, eventually, though I
suspect it will come in handy implementing horizontal scrolling.
DISPLAYABLE_CHARS is the number of characters in the line actually
drawn.  This may be less than the number of characters in the line
when line wrapping is off (see below).  The bitflag WRAPS tells
whether the next line is a continuation of this line.  START and END
are the marks at the beginning and end of the line.  Note that END is
the actual last character, not one past it, so the smallest line
(containing, for example, one newline) has START == END.  TAB_CONT and
TAB_CONT_NEXT are for computation of tab positions.  I will discuss
them later.

A point about the end of the buffer.  You may be tempted to consider
working with the buffer as an array of length TEXT_LENGTH(TEXT), but
you have to be careful that the editor allows you to position your
cursor at the last index of the buffer, one past the last character.
The macro LAST_INDEX(TEXT, MARK) returns true if MARK is positioned at
this index.  If you see or add a special case in the code for this
end-of-buffer case, make sure to use LAST_INDEX if you can.  Very
often, the last index is treated as a newline.

[ One way the last index is special is that, although it is always
  part of some property, it will never be part of a property of
  length 1 unless there are no other characters in the text. That
  is, its properties are always that of the preceding character,
  if any.
  
  There is a fair bit of special case code to mantain this condition -
  which is needed so that user has control over the properties of
  characters inserted at the last position. OWT 2/9/98 ]

Tab stops are variable width.  A list of tab stops is contained in the
GtkText structure:

  GList *tab_stops;
  gint default_tab_width;

The elements of tab_stops are integers casted to gpointer.  This is a
little bogus, but works.  For example:

  text->default_tab_width = 4;
  text->tab_stops = NULL;
  text->tab_stops = g_list_prepend (text->tab_stops, (void*)8);
  text->tab_stops = g_list_prepend (text->tab_stops, (void*)8);

is how these fields are initialized, currently.  This means that the
first two tabs occur at 8 and 16, and every 4 characters thereafter.
Tab stops are used in the computation of line geometry (to fill in a
LineParams structure), and the width of the space character in the
current font is used.  The PrevTabCont structure, of which two are
stored per line, is used to compute the geometry of lines which may
have wrapped and carried part of a tab with them:

  guint pixel_offset;
  TabStopMark tab_start;

PIXEL_OFFSET is the number of pixels at which the line should start,
and tab_start is a tab stop mark, which is similar to a property mark,
only it keeps track of the mapping between line position (column) and
the next tab stop.  A TabStopMark contains:

  GList* tab_stops;
  gint to_next_tab;

TAB_STOPS is a pointer into the TAB_STOPS field of the GtkText
structure.  TO_NEXT_TAB is the number of characters before the next
tab.  The functions ADVANCE_TAB_MARK and ADVANCE_TAB_MARK_N advance
these marks.  The LineParams structure contains two PrevTabCont
structures, which each contain a tab stop.  The first (TAB_CONT) is
for computing the beginning pixel offset, as mentioned above.  The
second (TAB_CONT_NEXT) is used to initialize the TAB_CONT field of the
next line if it wraps.

Since computing the parameters of a line are fairly complicated, I
have one interface that should be all you ever need to figure out
something about a line.  The function FIND_LINE_PARAMS computes the
parameters of a single line.  The function LINE_PARAMS_ITERATE is used
for computing the properties of some number (> 0) of sequential lines.

void
line_params_iterate (GtkText* text,
		     const GtkPropertyMark* mark0,
		     const PrevTabCont* tab_mark0,
		     gboolean alloc,
		     gpointer data,
		     LineIteratorFunction iter);

where LineIteratorFunction is:

typedef gint (*LineIteratorFunction) (GtkText* text,
                                      LineParams* lp,
                                      gpointer data);

The arguments are a text widget (TEXT), the property mark at the
beginning of the first line (MARK0), the tab stop mark at the
beginning of that line (TAB_MARK0), whether to heap-allocate the
LineParams structure (ALLOC), some client data (DATA), and a function
to call with the parameters of each line.  TAB_MARK0 may be NULL, but
if so MARK0 MUST BE A REAL LINE START (not a continued line start; it
is preceded by a newline).  If TAB_MARK0 is not NULL, MARK0 may be any
line start (continued or not).  See the code for examples.  The
function ITER is called with each LineParams computed.  If ALLOC was