remove gtk- prefix from TreeView and a few other entities, more consistent

2002-01-06  Havoc Pennington  <hp@pobox.com>

	* gtk/gtk-docs.sgml: remove gtk- prefix from TreeView and a few
	other entities, more consistent anyway (I thought this would make
	links to "GtkTreeView" etc. go to the ref page, not the struct,
	but it wasn't the problem, the issue is the way gtkdoc-mkdb
	decides what's an object, see CheckIsObject() routine)

	* gtk/changes-1.2.sgml: sgml fixes to get rid of warnings

	* gtk/changes-2.0.sgml: ditto

	* gtk/question_index.sgml: add some questions

docs/reference/ChangeLog

@@ -1,3 +1,17 @@
+2002-01-06  Havoc Pennington  <hp@pobox.com>
+
+	* gtk/gtk-docs.sgml: remove gtk- prefix from TreeView and a few
+	other entities, more consistent anyway (I thought this would make
+	links to "GtkTreeView" etc. go to the ref page, not the struct,
+	but it wasn't the problem, the issue is the way gtkdoc-mkdb
+	decides what's an object, see CheckIsObject() routine)
+
+	* gtk/changes-1.2.sgml: sgml fixes to get rid of warnings
+
+	* gtk/changes-2.0.sgml: ditto
+	
+	* gtk/question_index.sgml: add some questions
+
 2002-01-04  Matthias Clasen  <matthiasc@poet.de>
 
 	* gtk/tmpl/gtkwidget.sgml: Additions.

docs/reference/gtk/changes-1.2.sgml

@@ -89,7 +89,7 @@ A number of GTK+ functions were renamed. For compatibility,
   Here is the list of the old names and replacements:
 
 <informaltable>
-<tgroup>
+<tgroup cols="2">
 <thead>
 <row><entry>Old</entry><entry>Replacement</entry></row>
 </thead>
@@ -122,7 +122,7 @@ During the development phase of the 1.1.x line of GTK+ certain functions
   were deprecated and later removed. Functions affected are:
 
 <informaltable>
-<tgroup>
+<tgroup cols="2">
 <thead>
 <row><entry>Removed</entry><entry>Replacement</entry></row>
 </thead>
@@ -149,7 +149,6 @@ During the development phase of the 1.1.x line of GTK+ certain functions
 Note that <function>gtk_entry_adjust_scroll()</function> is no longer needed 
     as <structname>GtkEntry</structname> should automatically keep the scroll 
     adjusted properly.
-</programlisting>
 </para>
 </listitem>
 

docs/reference/gtk/changes-2.0.sgml

@@ -164,7 +164,7 @@ The type macros <function>GTK_TYPE_MAKE()</function> and <function>GTK_TYPE_SEQN
 <para>
 The following type functions vanished/were replaced:
 <informaltable>
-<tgroup>
+<tgroup cols="2">
 <thead>
 <row><entry>Old Function</entry><entry>Replacement</entry></row>
 </thead>
@@ -181,7 +181,7 @@ The following type functions vanished/were replaced:
 <row><entry><function>gtk_type_set_chunk_alloc()</function></entry><entry><structfield>GTypeInfo.n_preallocs</structfield></entry></row>
 <row><entry><function>gtk_type_register_enum()</function></entry><entry><function>g_enum_register_static()</function></entry></row>
 <row><entry><function>gtk_type_register_flags()</function></entry><entry><function>g_flags_register_static()</function></entry></row>
-<row><entry><function>gtk_type_parent_class()</function></entry><entry><functiono>g_type_parent()</function>/<function>g_type_class_peek_parent()</function></entry></row>
+<row><entry><function>gtk_type_parent_class()</function></entry><entry><function>g_type_parent()</function>/<function>g_type_class_peek_parent()</function></entry></row>
 </tbody>
 </tgroup>
 </informaltable>
@@ -285,7 +285,7 @@ Signal system changes:
   <structname>GSignal</structname> API is recommended,
   this avoids significant performance hits where <structname>GtkArg</structname>
   structures have to be converted into <structname>GValue</structname>s. For 
-  language bindings, <structname>GSignal</structname>+</structname>GClosure</structname>
+  language bindings, <structname>GSignal</structname>+<structname>GClosure</structname>
   provide a much more flexible and convenient mechanism to hook into signal 
   emissions or install class default handlers, so the old 
   <structname>GtkSignal</structname> API for language bindings is not
@@ -424,7 +424,7 @@ A number of functions in GDK have been renamed for consistency and
   included, but can be disabled by defining <literal>GDK_DISABLE_DEPRECATED</literal>.
 
 <informaltable>
-<tgroup>
+<tgroup cols="2">
 <thead>
 <row><entry>Old function</entry><entry>Defined As</entry></row>
 </thead>
@@ -683,7 +683,7 @@ In GTK+ 1.2, if an event handler returned <literal>TRUE</literal> it prevented
 
 <listitem>
 <para>
-<structname>GtkRange</structname>/</structname>GtkScrollbar</structname>/<structname>GtkScale</structname> were rewritten; this means that most
+<structname>GtkRange</structname>/<structname>GtkScrollbar</structname>/<structname>GtkScale</structname> were rewritten; this means that most
   theme engines won't draw them properly, and any custom subclasses of
   these widgets will need a rewrite (though if you could figure out
   how to subclass the old version of <structname>GtkRange</structname>, you 
@@ -748,7 +748,7 @@ The <function>set_child_arg()</function> and <function>get_child_arg()</function
 Other removed <structname>GtkContainer</structname> functions with the replacements:
 
 <informaltable>
-<tgroup>
+<tgroup cols="2">
 <thead>
 <row><entry>Old function</entry><entry>Replacement</entry></row>
 </thead>
@@ -851,7 +851,7 @@ If a container depended on its children not being mapped
 For <literal>!NO_WINDOW</literal> widgets, if you create children of 
      <literal>widget-&gt;window</literal>
      and don't map them in <function>realize()</function> then you must map them
-     in <function>map()</function. [ In almost all cases, you can simply map the
+     in <function>map()</function>. [ In almost all cases, you can simply map the
      windows in <function>realize()</function>. ]
 </para>
 </listitem>
@@ -909,7 +909,7 @@ The following variables are no longer exported from GDK. (Other variables
   externally in a large sample of GTK+ code.)
 
 <informaltable>
-<tgroup>
+<tgroup cols="2">
 <thead>
 <row><entry>Variable</entry><entry>Replacement</entry></row>
 </thead>
@@ -919,7 +919,7 @@ The following variables are no longer exported from GDK. (Other variables
 <row><entry><literal>gdk_screen</literal></entry><entry><function>gdk_x11_get_default_screen ()</function></entry></row>
 <row><entry><literal>gdk_root_window</literal></entry><entry><function>gdk_x11_get_default_root_xwindow ()</function></entry></row>
 <row><entry><literal>gdk_root_parent</literal></entry><entry><function>gdk_get_default_root_window ()</function></entry></row>
-<row><entry><literal>gdk_error_code</literal></entry><entry><function>gdk_error_trap_push ()/pop ()</function>/entry></row>
+<row><entry><literal>gdk_error_code</literal></entry><entry><function>gdk_error_trap_push ()/pop ()</function></entry></row>
 <row><entry><literal>gdk_error_warnings</literal></entry><entry><function>gdk_error_trap_push ()/pop ()</function></entry></row>
 <row><entry><literal>gdk_display_name</literal></entry><entry><function>gdk_get_display ()</function></entry></row>
 <row><entry><literal>gdk_wm_delete_window</literal></entry><entry><literal>gdk_atom_intern ("WM_DELETE_WINDOW", FALSE)</literal></entry></row>
@@ -990,7 +990,7 @@ GDK is no longer put into threaded mode automatically when
 <para>
 The <structname>GtkPreviewInfo</structname> struct has had its visual and 
   colormap fields removed.  Also, <function>gtk_preview_get_cmap()</function> 
-  and <function>gtk_preview_get_visual()<function> are deprecated, as 
+  and <function>gtk_preview_get_visual()</function> are deprecated, as 
   <structname>GdkRGB</structname> works on any colormap and visual.  You no
   longer need to 
   <literal>gtk_widget_push_cmap (gtk_preview_get_cmap ())</literal> in

docs/reference/gtk/gtk-docs.sgml

@@ -24,7 +24,7 @@
 <!entity GtkCurve SYSTEM "sgml/gtkcurve.sgml">
 <!entity GtkDialog SYSTEM "sgml/gtkdialog.sgml">
 <!entity GtkDrawingArea SYSTEM "sgml/gtkdrawingarea.sgml">
-<!entity gtk-GtkEditable SYSTEM "sgml/gtkeditable.sgml">
+<!entity GtkEditable SYSTEM "sgml/gtkeditable.sgml">
 <!entity GtkOldEditable SYSTEM "sgml/gtkoldeditable.sgml">
 <!entity GtkEntry SYSTEM "sgml/gtkentry.sgml">
 <!entity GtkEventBox SYSTEM "sgml/gtkeventbox.sgml">
@@ -87,8 +87,8 @@
 <!entity GtkTearoffMenuItem SYSTEM "sgml/gtktearoffmenuitem.sgml">
 <!entity GtkText SYSTEM "sgml/gtktext.sgml">
 <!entity GtkTextBuffer SYSTEM "sgml/gtktextbuffer.sgml">
-<!entity gtk-GtkTextIter SYSTEM "sgml/gtktextiter.sgml">
+<!entity GtkTextIter SYSTEM "sgml/gtktextiter.sgml">
-<!entity gtk-GtkTextMark SYSTEM "sgml/gtktextmark.sgml">
+<!entity GtkTextMark SYSTEM "sgml/gtktextmark.sgml">
 <!entity GtkTextTag SYSTEM "sgml/gtktexttag.sgml">
 <!entity GtkTextTagTable SYSTEM "sgml/gtktexttagtable.sgml">
 <!entity GtkTextView SYSTEM "sgml/gtktextview.sgml">
@@ -98,20 +98,20 @@
 <!entity GtkTooltips SYSTEM "sgml/gtktooltips.sgml">
 <!entity GtkTree SYSTEM "sgml/gtktree.sgml">
 <!entity GtkTreeItem SYSTEM "sgml/gtktreeitem.sgml">
-<!entity gtk-GtkTreeModel SYSTEM "sgml/gtktreemodel.sgml">
+<!entity GtkTreeModel SYSTEM "sgml/gtktreemodel.sgml">
-<!entity gtk-GtkTreeSortable SYSTEM "sgml/gtktreesortable.sgml">
+<!entity GtkTreeSortable SYSTEM "sgml/gtktreesortable.sgml">
-<!entity gtk-GtkTreeModelSort SYSTEM "sgml/gtktreemodelsort.sgml">
+<!entity GtkTreeModelSort SYSTEM "sgml/gtktreemodelsort.sgml">
-<!entity gtk-GtkTreeSelection SYSTEM "sgml/gtktreeselection.sgml">
+<!entity GtkTreeSelection SYSTEM "sgml/gtktreeselection.sgml">
-<!entity gtk-GtkTreeStore SYSTEM "sgml/gtktreestore.sgml">
+<!entity GtkTreeStore SYSTEM "sgml/gtktreestore.sgml">
-<!entity gtk-GtkTreeViewColumn SYSTEM "sgml/gtktreeviewcolumn.sgml">
+<!entity GtkTreeViewColumn SYSTEM "sgml/gtktreeviewcolumn.sgml">
-<!entity gtk-GtkTreeView SYSTEM "sgml/gtktreeview.sgml">
+<!entity GtkTreeView SYSTEM "sgml/gtktreeview.sgml">
-<!entity gtk-GtkCellRenderer SYSTEM "sgml/gtkcellrenderer.sgml">
+<!entity GtkCellRenderer SYSTEM "sgml/gtkcellrenderer.sgml">
-<!entity gtk-GtkCellEditable SYSTEM "sgml/gtkcelleditable.sgml">
+<!entity GtkCellEditable SYSTEM "sgml/gtkcelleditable.sgml">
-<!entity gtk-GtkCellRendererPixbuf SYSTEM "sgml/gtkcellrendererpixbuf.sgml">
+<!entity GtkCellRendererPixbuf SYSTEM "sgml/gtkcellrendererpixbuf.sgml">
-<!entity gtk-GtkCellRendererText SYSTEM "sgml/gtkcellrenderertext.sgml">
+<!entity GtkCellRendererText SYSTEM "sgml/gtkcellrenderertext.sgml">
-<!entity gtk-GtkCellRendererToggle SYSTEM "sgml/gtkcellrenderertoggle.sgml">
+<!entity GtkCellRendererToggle SYSTEM "sgml/gtkcellrenderertoggle.sgml">
-<!entity gtk-GtkListStore SYSTEM "sgml/gtkliststore.sgml">
+<!entity GtkListStore SYSTEM "sgml/gtkliststore.sgml">
-<!entity gtk-GtkTreeDND SYSTEM "sgml/gtktreednd.sgml">
+<!entity GtkTreeDND SYSTEM "sgml/gtktreednd.sgml">
 <!entity GtkVButtonBox SYSTEM "sgml/gtkvbbox.sgml">
 <!entity GtkVBox SYSTEM "sgml/gtkvbox.sgml">
 <!entity GtkViewport SYSTEM "sgml/gtkviewport.sgml">
@@ -325,8 +325,8 @@ that is, GUI components such as #GtkButton or #GtkTextView.
     <sect1 id="TextWidgetObjects">
       <title>Multiline Text Editor</title>
         &gtk-TextWidget;
-        &gtk-GtkTextIter;
+        &GtkTextIter;
-        &gtk-GtkTextMark;
+        &GtkTextMark;
         &GtkTextBuffer;
         &GtkTextTag;
         &GtkTextTagTable;
@@ -336,20 +336,20 @@ that is, GUI components such as #GtkButton or #GtkTextView.
     <sect1 id="TreeWidgetObjects">
       <title>Tree and List Widget</title>
         &gtk-TreeWidget;
-        &gtk-GtkTreeModel;
+        &GtkTreeModel;
-        &gtk-GtkTreeSelection;
+        &GtkTreeSelection;
-        &gtk-GtkTreeViewColumn;
+        &GtkTreeViewColumn;
-        &gtk-GtkTreeView;
+        &GtkTreeView;
-        &gtk-GtkTreeDND;
+        &GtkTreeDND;
-	&gtk-GtkTreeSortable;
+	&GtkTreeSortable;
-        &gtk-GtkTreeModelSort;
+        &GtkTreeModelSort;
-        &gtk-GtkCellRenderer;
+        &GtkCellRenderer;
-        &gtk-GtkCellEditable;
+        &GtkCellEditable;
-        &gtk-GtkCellRendererPixbuf;
+        &GtkCellRendererPixbuf;
-        &gtk-GtkCellRendererText;
+        &GtkCellRendererText;
-        &gtk-GtkCellRendererToggle;
+        &GtkCellRendererToggle;
-        &gtk-GtkListStore;
+        &GtkListStore;
-        &gtk-GtkTreeStore;
+        &GtkTreeStore;
     </sect1>
     <sect1 id="MenusAndCombos">
       <title>Menus, Combo Box, Toolbar</title>
@@ -430,7 +430,7 @@ that is, GUI components such as #GtkButton or #GtkTextView.
         &GtkBox;
         &GtkButtonBox;
         &GtkContainer;
-        &gtk-GtkEditable;
+        &GtkEditable;
         &GtkOldEditable;
         &GtkItem;
         &GtkMisc;

docs/reference/gtk/question_index.sgml

@@ -122,8 +122,138 @@ threading primitives.
 
 </qandaentry>
 
+
+<qandaentry>
+<question><para>
+How do I load an image or animation from a file?
+</para></question>
+
+<answer>
+
+<para>
+To load an image file straight into a display widget, use <link
+linkend="gtk-image-new-from-file">gtk_image_new_from_file()</link>
+<footnote><para> If the file load fails, <link
+linkend="gtk-image-new-from-file">gtk_image_new_from_file()</link>
+will display a "broken image" graphic &mdash to detect a failed load
+yourself, use <link
+linkend="gdk-pixbuf-new-from-file">gdk_pixbuf_new_from_file()</link>
+directly then <link
+linkend="gtk-image-new-from-pixbuf">gtk_image_new_from_pixbuf()</link>.
+</para></footnote>. To load an image for another purpose, use <link
+linkend="gdk-pixbuf-new-from-file">gdk_pixbuf_new_from_file()</link>.
+To load an animation, use <link
+linkend="gdk-pixbuf-animation-new-from-file">gdk_pixbuf_animation_new_from_file()</link>.
+<link
+linkend="gdk-pixbuf-animation-new-from-file">gdk_pixbuf_animation_new_from_file()</link>
+can also load non-animated images, so use it in combination with 
+<link
+      linkend="gdk-pixbuf-animation-is-static-image">gdk_pixbuf_animation_is_static_image()</link> to load a file of unknown type. 
+</para>
+<para>
+To load an image or animation file asynchronously (without blocking), use 
+<link linkend="GdkPixbufLoader">GdkPixbufLoader</link>.
+</para>
+</answer>
+
+</qandaentry>
+
+
 </qandadiv>
 
+<qandadiv><title>Which widget should I use...</title>
+
+<qandaentry>
+<question><para>
+...for lists and trees?
+</para></question>
+
+<answer>
+<para>
+See <link linkend="TreeWidget">tree widget overview</link> &mdash you
+should use the <link linkend="GtkTreeView">GtkTreeView</link> widget.
+(A list is just a tree with no branches, so the tree widget is used
+for lists as well.) Do not use the deprecated widgets <link
+linkend="GtkTree">GtkTree</link> or <link
+linkend="GtkCList">GtkCList</link>/<link
+linkend="GtkCTree">GtkCTree</link> in newly-written code, they are
+less flexible and result in an inferior user interface.
+</para>
+</answer>
+</qandaentry>
+
+<qandaentry>
+<question><para>
+...for multi-line text display or editing?
+</para></question>
+
+<answer>
+<para>
+See <link linkend="TextWidget">text widget overview</link> &mdash you
+should use the <link linkend="GtkTextView">GtkTextView</link> widget.
+Do not use the deprecated widget <link
+linkend="GtkText">GtkText</link> in newly-written code, it has a
+number of problems that are best avoided.
+</para>
+<para>
+If you only have a small amount of text, <link
+linkend="GtkLabel">GtkLabel</link> may also be appropriate of course.
+It can be made selectable with <link
+                                     linkend="gtk-label-set-selectable">
+gtk_label_set_selectable()</link>. For a single-line text entry, 
+see <link linkend="GtkEntry">GtkEntry</link>.
+</para>
+</answer>
+</qandaentry>
+
+
+<qandaentry>
+<question><para>
+...to display an image or animation?
+</para></question>
+
+<answer>
+<para>
+<link linkend="GtkImage">GtkImage</link> can display images
+in just about any format GTK+ understands. You can also 
+use <link linkend="GtkDrawingArea">GtkDrawingArea</link> if you need 
+to do something more complex, such as draw text or graphics over the
+top of the image.
+</para>
+</answer>
+</qandaentry>
+
+<qandaentry>
+<question><para>
+...for presenting a set of mutually-exclusive choices, where Windows
+would use a combo box?
+</para></question>
+
+<answer>
+<para>
+With GTK+, a <link linkend="GtkOptionMenu">GtkOptionMenu</link> is
+recommended instead of a combo box, if the user is selecting from a
+fixed set of options. That is, non-editable combo boxes are not
+encouraged. <link linkend="GtkOptionMenu">GtkOptionMenu</link> is
+much easier to use than <link linkend="GtkCombo">GtkCombo</link>
+as well. Use <link linkend="GtkCombo">GtkCombo</link> only when you 
+need the editable text entry.
+</para>
+<para>
+(As a future enhancement to GTK+, a new widget to replace <link
+linkend="GtkOptionMenu">GtkOptionMenu</link> and <link
+linkend="GtkCombo">GtkCombo</link> is planned.  This widget will be
+themeable to look like either a combo box or the current option menu,
+and will address some shortcomings in the <link
+linkend="GtkCombo">GtkCombo</link> API.  <ulink
+url="http://bugzilla.gnome.org/show_bug.cgi?id=50554">Bug
+50554</ulink> tracks this issue, if you want to check status or post
+comments.)
+</para>
+</answer>
+</qandaentry>
+
+</qandadiv>
 
 <qandadiv><title><link linkend="GtkWidget">GtkWidget</link></title>
 
@@ -201,6 +331,50 @@ or <link
 </qandadiv>
 
 
+
+<qandadiv><title><link linkend="GtkTreeView">GtkTreeView</link></title>
+
+<qandaentry>
+<question><para>
+How do I associate some data with a row in the tree?
+</para></question>
+
+<answer>
+<para>
+Remember that the <link linkend="GtkTreeModel">GtkTreeModel</link>
+columns don't necessarily have to be displayed. So you can put
+non-user-visible data in your model just like any other data, and
+retrieve it with <link
+linkend="gtk-tree-model-get">gtk_tree_model_get()</link>.
+See the <link linkend="TreeWidget">tree widget overview</link>.
+</para>
+</answer>
+</qandaentry>
+
+<qandaentry>
+<question><para>
+How do I put an image and some text in the same column?
+</para></question>
+
+<answer>
+<para>
+You can pack more than one <link
+linkend="GtkCellRenderer">GtkCellRenderer</link> into a single
+<link linkend="GtkTreeViewColumn">GtkTreeViewColumn</link> using
+<link
+      linkend="gtk-tree-view-column-pack-start">gtk_tree_view_column_pack_start()</link> or <link linkend="gtk-tree-view-column-pack-end">gtk_tree_view_column_pack_end()</link>. So pack both a <link
+linkend="GtkCellRendererPixbuf">GtkCellRendererPixbuf</link>
+and a <link
+linkend="GtkCellRendererText">GtkCellRendererText</link> into the
+column.
+</para>
+</answer>
+</qandaentry>
+
+</qandadiv>
+
+
+
 </qandaset>
 
 </refsect1>