Re-enable the "find" dialog

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

1 files changed, 127 insertions, 0 deletions

diff --git a/docs/reference/gtk/text_widget.sgml b/docs/reference/gtk/text_widget.sgml
new file mode 100644
index 0000000000..776f079533
--- /dev/null
+++ b/docs/reference/gtk/text_widget.sgml
@@ -0,0 +1,127 @@
+<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>