forked from AuroraMiddleware/gtk
86b5c82a97
2000-10-23 Havoc Pennington <hp@redhat.com>
* gtk/testtext.c: Re-enable the "find" dialog
* gtk/testgtk.c: Add test for gdk_drawable_get_image
* gdk/gdkwindow.c (gdk_window_begin_paint_region): Fix bug where
the arguments to gdk_draw_drawable were in the wrong order
(gdk_window_paint_init_bg): This function was ignoring the
init_region, instead of clipping to it, so the entire backing
pixmap was cleared on every begin_paint()
(gdk_window_begin_paint_region): Hmm, the same list-walking bug
was in here again, the loop kept using the same GtkWindowPaint
over and over.
(gdk_window_begin_paint_region): Fix a bug where we had two
x_offset instead of x_offset and y_offset
* gdk/gdkdraw.c (gdk_drawable_get_image): get composite drawable
before we get the image.
(gdk_draw_drawable): get the composite before we draw the drawable.
(gdk_drawable_real_get_composite_drawable): default
get_composite_drawable implementation that returns the drawable
itself
* gdk/gdkdrawable.h (struct _GdkDrawableClass ): Add
get_composite_drawable virtual function
* gdk/gdkwindow.c (gdk_window_begin_paint_region): Fix a cheesy
list-walking bug
* gdk/x11/gdkdrawable-x11.c (gdk_x11_draw_drawable): Add a hack to
make this work if the source drawable is a GdkDrawableImplX11
instead of a public drawable type. This is really broken; the
problem is that GdkDrawable needs a virtual method get_xid(), but
of course that doesn't work in practice. Enter RTTI.
Also, improve mismatched depth message.
* gdk/gdkpixmap.c (gdk_pixmap_get_image): Implement get_image for
GdkPixmap
* gdk/x11/gdkdrawable-x11.c (gdk_drawable_impl_x11_class_init):
install _gdk_x11_get_image as our implementation of get_image
* gdk/x11/gdkimage-x11.c (gdk_image_get): Rename to
_gdk_x11_get_image and export for use in gdkdrawable-x11.c
* gdk/gdkimage.c (gdk_image_get): Make this just a wrapper around
gdk_drawable_get_image
* gdk/gdkdraw.c (gdk_drawable_get_image): call virtual get_image
* gdk/gdkdrawable.h (struct _GdkDrawableClass ): Virtualize
get_image
* gtk/gtktreestore.c (gtk_tree_store_get_node): remove weird
trailing semicolon after for loop
128 lines
5.0 KiB
Plaintext
128 lines
5.0 KiB
Plaintext
<refentry id="TextWidget" revision="18 Oct 2000">
|
|
<refmeta>
|
|
<refentrytitle>Text Widget Overview</refentrytitle>
|
|
<manvolnum>3</manvolnum>
|
|
<refmiscinfo>GTK Library</refmiscinfo>
|
|
</refmeta>
|
|
|
|
<refnamediv>
|
|
<refname>Text Widget Overview</refname><refpurpose>Overview of <link linkend="GtkTextBuffer">GtkTextBuffer</link>, <link linkend="GtkTextView">GtkTextView</link>, and friends</refpurpose>
|
|
</refnamediv>
|
|
|
|
<refsect1>
|
|
<title>Conceptual Overview</title>
|
|
|
|
<para>
|
|
GTK+ has an extremely powerful framework for multiline text editing. The
|
|
primary objects involved in the process are <link
|
|
linkend="GtkTextBuffer">GtkTextBuffer</link>, which represents the text being
|
|
edited, and <link linkend="GtkTextView">GtkTextView</link>, a widget which can
|
|
display a <link linkend="GtkTextBuffer">GtkTextBuffer</link>. Each buffer can be
|
|
displayed by any number of views.
|
|
</para>
|
|
|
|
<para>
|
|
Text in a buffer can be marked with <firstterm>tags</firstterm>. A tag is an
|
|
attribute that can be applied to some range of text. For example, a tag might be
|
|
called "bold" and make the text inside the tag bold. However, the tag concept is
|
|
more general than that; tags don't have to affect appearance. They can instead
|
|
affect change the behavior of mouse and key presses, "lock" a range of text so
|
|
the user can't edit it, or countless other things. A tag is represented by a
|
|
<link linkend="GtkTextTag">GtkTextTag</link> object. One <link
|
|
linkend="GtkTextTag">GtkTextTag</link> can be applied to any number of text
|
|
ranges in any number of buffers.
|
|
</para>
|
|
|
|
<para>
|
|
Each tag is stored in a <link
|
|
linkend="GtkTextTagTable">GtkTextTagTable</link>. A tag table defines a set of
|
|
tags that can be used together. Each buffer has one tag table associated with
|
|
it; only tags from that tag table can be used with the buffer. A single tag
|
|
table can be shared between multiple buffers, however.
|
|
</para>
|
|
|
|
<para>
|
|
Tags can have names, which is convenient sometimes (for example, you can name
|
|
your tag that makes things bold "bold"), but they can also be anonymous (which
|
|
is convenient if you're creating tags on-the-fly).
|
|
</para>
|
|
|
|
<para>
|
|
Most text manipulation is accomplished with <firstterm>iterators</firstterm>,
|
|
represented by a <link linkend="GtkTextIter">GtkTextIter</link>. An iterator
|
|
represents a position in the text buffer. <link
|
|
linkend="GtkTextIter">GtkTextIter</link> is a struct designed to be allocated on
|
|
the stack; it's guaranteed to be copiable by value and never contain any
|
|
heap-allocated data. Iterators are not valid indefinitely; whenever the buffer
|
|
is modified in a way that affects the number of characters in the buffer, all
|
|
outstanding iterators become invalid. (Note that deleting 5 characters and then
|
|
reinserting 5 still invalidates iterators, though you end up with the same
|
|
number of characters).
|
|
</para>
|
|
|
|
<para>
|
|
Because of this, iterators can't be used to preserve positions across buffer
|
|
modifications. To preserve a position, the <link
|
|
linkend="GtkTextMark">GtkTextMark</link> object is ideal. You can think of a
|
|
mark as an invisible cursor or insertion point; it floats in the buffer, saving
|
|
a position. If the text surrounding the mark is deleted, the mark remains in the
|
|
position the text once occupied; if text is inserted at the mark, the mark ends
|
|
up either to the left or to the right of the new text, depending on its
|
|
<firstterm>gravity</firstterm>. The standard text cursor in left-to-right
|
|
languages is a mark with right gravity, because it stays to the right of
|
|
inserted text.
|
|
</para>
|
|
|
|
<para>
|
|
Like tags, marks can be either named or anonymous. There are two marks built-in
|
|
to <link linkend="GtkTextBuffer">GtkTextBuffer</link>; these are named
|
|
<literal>"insert"</literal> and <literal>"selection_bound"</literal> and refer
|
|
to the insertion point and the boundary of the selection which is not the
|
|
insertion point, respectively. If no text is selected, these two marks will be
|
|
in the same position. You can manipulate what is selected and where the cursor
|
|
appears by moving these marks around.
|
|
|
|
<footnote>
|
|
<para>
|
|
If you want to place the cursor in response to a user action, be sure to use
|
|
gtk_text_buffer_place_cursor(), which moves both at once without causing a
|
|
temporary selection (moving one then the other temporarily selects the range in
|
|
between the old and new positions).
|
|
</para>
|
|
</footnote>
|
|
</para>
|
|
|
|
</refsect1>
|
|
|
|
|
|
<refsect1>
|
|
<title>Simple Example</title>
|
|
|
|
<para>
|
|
The simplest usage of <link linkend="GtkTextView">GtkTextView</link>
|
|
might look like this:
|
|
<programlisting>
|
|
|
|
/* Get a buffer (it's a GObject, not a GtkObject, so we own a reference
|
|
* after this). Passing NULL as argument causes an empty tag table to be
|
|
* automatically created.
|
|
*/
|
|
|
|
buffer = gtk_text_buffer_new (NULL);
|
|
|
|
view = gtk_text_view_new_with_buffer (buffer);
|
|
|
|
/* view holds a reference now */
|
|
g_object_unref (G_OBJECT (buffer));
|
|
|
|
/* Now you might put the view in a container and display it on the
|
|
* screen; when the user edits the text, signals on the buffer
|
|
* will be emitted, such as "changed", "insert_text", and so on.
|
|
*/
|
|
</programlisting>
|
|
</para>
|
|
|
|
</refsect1>
|
|
|
|
</refentry>
|