text_widget.txt

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

true, LINE_PARAMS_ITERATE heap-allocates the LineParams and does not
free them.  Otherwise, no storage is permanently allocated.  ITER
should return TRUE when it wishes to continue no longer.

There are currently two uses of LINE_PARAMS_ITERATE:

* Compute the total buffer height for setting the parameters of the
  scroll bars.  This is done in SET_VERTICAL_SCROLL each time the
  window is resized.  When horizontal scrolling is added, depending on
  the policy chosen, the max line width can be computed here as well.

* Computing geometry of some pixel height worth of lines.  This is
  done in FETCH_LINES, FETCH_LINES_BACKWARD, FETCH_LINES_FORWARD, etc.

The GtkText structure contains a cache of the LineParams data for all
visible lines:

  GList *current_line;
  GList *line_start_cache;

  guint first_line_start_index;
  guint first_cut_pixels;
  guint first_onscreen_hor_pixel;
  guint first_onscreen_ver_pixel;

LINE_START_CACHE is a doubly linked list of LineParams.  CURRENT_LINE
is a transient piece of data which is set in varoius places such as
the mouse click code.  Generally, it is the line on which the cursor
property mark CURSOR_MARK is on.  LINE_START_CACHE points to the first
visible line and may contain PREV pointers if the cached data of
offscreen lines is kept around.  I haven't come up with a policy.  The
cache can keep more lines than are visible if desired, but the result
is that inserts and deletes will then become slower as the entire
cache has to be "corrected".  Right now it doesn't delete from the
cache (it should).  As a result, scrolling through the whole buffer
once will fill the cache with an entry for each line, and subsequent
modifications will be slower than they should
be. FIRST_LINE_START_INDEX is the index of the *REAL* line start of
the first line.  That is, if the first visible line is a continued
line, this is the index of the real line start (preceded by a
newline).  FIRST_CUT_PIXELS is the number of pixels which are not
drawn on the first visible line.  If FIRST_CUT_PIXELS is zero, the
whole line is visible.  FIRST_ONSCREEN_HOR_PIXEL is not used.
FIRST_ONSCREEN_VER_PIXEL is the absolute pixel which starts the
visible region.  This is used for setting the vertical scroll bar.

Other miscellaneous things in the GtkText structure:

Gtk specific things:

  GtkWidget widget;

  GdkWindow *text_area;

  GtkAdjustment *hadj;
  GtkAdjustment *vadj;

  GdkGC *gc;

  GdkPixmap* line_wrap_bitmap;
  GdkPixmap* line_arrow_bitmap;

These are pretty self explanatory, especially if you know Gtk.
LINE_WRAP_BITMAP and LINE_ARROW_BITMAP are two bitmaps used to
indicate that a line wraps and is continued offscreen, respectively.

Some flags:

  guint has_cursor : 1;
  guint is_editable : 1;
  guint line_wrap : 1;
  guint freeze : 1;
  guint has_selection : 1;
  guint own_selection : 1;

HAS_CURSOR is true iff the cursor is visible.  IS_EDITABLE is true iff
the user is allowed to modify the buffer.  If IS_EDITABLE is false,
HAS_CURSOR is guaranteed to be false.  If IS_EDITABLE is true,
HAS_CURSOR starts out false and is set to true the first time the user
clicks in the window.  LINE_WRAP is where the line-wrap policy is
set.  True means wrap lines, false means continue lines offscreen,
horizontally.

The text properties list:

  GList *text_properties;
  GList *text_properties_end;

A scratch area used for constructing a contiguous piece of the buffer
which may otherwise span the gap.  It is not strictly neccesary
but simplifies the drawing code because it does not need to deal with
the gap.

  guchar* scratch_buffer;
  guint   scratch_buffer_len;

The last vertical scrollbar position.  Currently this looks the same
as FIRST_ONSCREEN_VER_PIXEL.  I can't remember why I have two values.
Perhaps someone should clean this up.

  gint last_ver_value;

The cursor:

  gint            cursor_pos_x;
  gint            cursor_pos_y;
  GtkPropertyMark cursor_mark;
  gchar           cursor_char;
  gchar           cursor_char_offset;
  gint            cursor_virtual_x;
  gint            cursor_drawn_level;

CURSOR_POS_X and CURSOR_POS_Y are the screen coordinates of the
cursor.  CURSOR_MARK is the buffer position.  CURSOR_CHAR is
TEXT_INDEX (TEXT, CURSOR_MARK.INDEX) if a drawable character, or 0 if
it is whitespace, which is treated specially.  CURSOR_CHAR_OFFSET is
the pixel offset above the base of the line at which it should be
drawn.  Note that the base of the line is not the "baseline" in the
traditional font metric sense.  A line (LineParams) is
FONT_ASCENT+FONT_DESCENT high (use the macro LINE_HEIGHT).  The
"baseline" is FONT_DESCENT below the base of the line.  I think this
requires a drawing.

0                      AAAAAAA
1                      AAAAAAA
2                     AAAAAAAAA
3                     AAAAAAAAA
4                    AAAAA AAAAA
5                    AAAAA AAAAA
6                   AAAAA   AAAAA
7                  AAAAA     AAAAA
8                  AAAAA     AAAAA
9                 AAAAAAAAAAAAAAAAA
10                AAAAAAAAAAAAAAAAA
11               AAAAA         AAAAA
12               AAAAA         AAAAA
13              AAAAAA         AAAAAA
14______________AAAAA___________AAAAA__________________________________
15
16
17
18
19
20

This line is 20 pixels high, has FONT_ASCENT=14, FONT_DESCENT=6.  It's
"base" is at y=20.  Characters are drawn at y=14.  The LINE_START
macro returns the pixel height.  The LINE_CONTAINS macro is true if
the line contains a certain buffer index.  The LINE_STARTS_AT macro is
true if the line starts at a certain buffer index.  The
LINE_START_PIXEL is the pixel offset the line should be drawn at,
according the the tab continuation of the previous line.

Exposure and drawing:

Exposure is handled from the EXPOSE_TEXT function.  It assumes that
the LINE_START_CACHE and all it's parameters are accurate and simply
exposes any line which is in the exposure region.  It calls the
CLEAR_AREA function to clear the background and/or lay down a pixmap
background.  The text widget has a scrollable pixmap background, which
is implemented in CLEAR_AREA.  CLEAR_AREA does the math to figure out
how to tile the pixmap itself so that it can scroll the text with a
copy area call.  If the CURSOR argument to EXPOSE_TEXT is true, it
also draws the cursor.

The function DRAW_LINE draws a single line, doing all the tab and
color computations neccesary.  The function DRAW_LINE_WRAP draws the
line wrap bitmap at the end of the line if it wraps.  TEXT_EXPOSE will
expand the cached line data list if it has to by calling
FETCH_LINES_FORWARD.  The functions DRAW_CURSOR and UNDRAW_CURSOR draw
and undraw the cursor.  They count the number of draws and undraws so
that the cursor may be undrawn even if the cursor is already undrawn
and the re-draw will not occur too early.  This is useful in handling
scrolling.

Handling of the cursor is a little messed up, I should add.  It has to
be undrawn and drawn at various places.  Something better needs to be
done about this, because it currently doesn't do the right thing in
certain places.  I can't remember where very well.  Look for the calls
to DRAW_CURSOR and UNDRAW_CURSOR.

RECOMPUTE_GEOMETRY is called when the geometry of the window changes
or when it is first drawn.  This is probably not done right.  My
biggest weakness in writing this code is that I've never written a
widget before so I got most of the event handling stuff wrong as far
as Gtk is concerned.  Fortunatly, most of the code is unrelated and
simply an exercise in data structure manipulation.

Scrolling:

Scrolling is fairly straighforward.  It looks at the top line, and
advances it pixel by pixel until the FIRST_CUT_PIXELS equals the line
height and then advances the LINE_START_CACHE.  When it runs out of
lines it fetches more.  The function SCROLL_INT is used to scroll from
inside the code, it calls the appropriate functions and handles
updating the scroll bars.  It dispatches a change event which causes
Gtk to call the correct scroll action, which then enters SCROLL_UP or
SCROLL_DOWN.  Careful with the cursor during these changes.

Insertion, deletion:

There's some confusion right now over what to do with the cursor when
it's offscreen due to scrolling.  This is a policy decision.  I don't
know what's best.  Spencer criticized me for forcing it to stay
onscreen.  It shouldn't be hard to make stuff work with the cursor
offscreen.

Currently I've got functions to do insertion and deletion of a single
character.  It's fairly complicated.  In order to do efficient pasting
into the buffer, or write code that modifies the buffer while the
buffer is drawn, it needs to do multiple characters at at time.  This
is the hardest part of what remains.  Currently, gtk_text_insert does
not reexpose the modified lines.  It needs to.  Pete did this wrong at
one point and I disabled modification completely, I don't know what
the current state of things are.  The functions
INSERT_CHAR_LINE_EXPOSE and DELETE_CHAR_LINE_EXPOSE do the work.
Here's pseudo code for insert.  Delete is quite similar.

  insert character into the buffer
  update the text property list
  move the point
  undraw the cursor
  correct all LineParams cache entries after the insertion point
  compute the new height of the modified line
  compare with the old height of the modified line
  remove the old LineParams from the cache
  insert the new LineParams into the cache
  if the lines are of different height, do a copy area to move the
    area below the insertion down
  expose the current line
  update the cursor mark
  redraw the cursor

What needs to be done:

Horizintal scrolling, robustness, testing, selection handling.  If you
want to work in the text widget pay attention to the debugging
facilities I've written at the end of gtktext.c.  I'm sorry I waited
so long to try and pass this off.  I'm super busy with school and
work, and when I have free time my highest priority is another version
of PRCS.

Feel free to ask me questions.