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
This commit is contained in:
Havoc Pennington 2002-01-06 21:09:26 +00:00 committed by Havoc Pennington
parent ec81d4a8af
commit 824e8e2d9d
7 changed files with 243 additions and 56 deletions

View File

@ -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.

View File

@ -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>

View File

@ -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

View File

@ -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 gtk-GtkTextMark SYSTEM "sgml/gtktextmark.sgml">
<!entity GtkTextIter SYSTEM "sgml/gtktextiter.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 gtk-GtkTreeSortable SYSTEM "sgml/gtktreesortable.sgml">
<!entity gtk-GtkTreeModelSort SYSTEM "sgml/gtktreemodelsort.sgml">
<!entity gtk-GtkTreeSelection SYSTEM "sgml/gtktreeselection.sgml">
<!entity gtk-GtkTreeStore SYSTEM "sgml/gtktreestore.sgml">
<!entity gtk-GtkTreeViewColumn SYSTEM "sgml/gtktreeviewcolumn.sgml">
<!entity gtk-GtkTreeView SYSTEM "sgml/gtktreeview.sgml">
<!entity gtk-GtkCellRenderer SYSTEM "sgml/gtkcellrenderer.sgml">
<!entity gtk-GtkCellEditable SYSTEM "sgml/gtkcelleditable.sgml">
<!entity gtk-GtkCellRendererPixbuf SYSTEM "sgml/gtkcellrendererpixbuf.sgml">
<!entity gtk-GtkCellRendererText SYSTEM "sgml/gtkcellrenderertext.sgml">
<!entity gtk-GtkCellRendererToggle SYSTEM "sgml/gtkcellrenderertoggle.sgml">
<!entity gtk-GtkListStore SYSTEM "sgml/gtkliststore.sgml">
<!entity gtk-GtkTreeDND SYSTEM "sgml/gtktreednd.sgml">
<!entity GtkTreeModel SYSTEM "sgml/gtktreemodel.sgml">
<!entity GtkTreeSortable SYSTEM "sgml/gtktreesortable.sgml">
<!entity GtkTreeModelSort SYSTEM "sgml/gtktreemodelsort.sgml">
<!entity GtkTreeSelection SYSTEM "sgml/gtktreeselection.sgml">
<!entity GtkTreeStore SYSTEM "sgml/gtktreestore.sgml">
<!entity GtkTreeViewColumn SYSTEM "sgml/gtktreeviewcolumn.sgml">
<!entity GtkTreeView SYSTEM "sgml/gtktreeview.sgml">
<!entity GtkCellRenderer SYSTEM "sgml/gtkcellrenderer.sgml">
<!entity GtkCellEditable SYSTEM "sgml/gtkcelleditable.sgml">
<!entity GtkCellRendererPixbuf SYSTEM "sgml/gtkcellrendererpixbuf.sgml">
<!entity GtkCellRendererText SYSTEM "sgml/gtkcellrenderertext.sgml">
<!entity GtkCellRendererToggle SYSTEM "sgml/gtkcellrenderertoggle.sgml">
<!entity GtkListStore SYSTEM "sgml/gtkliststore.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;
&gtk-GtkTextMark;
&GtkTextIter;
&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;
&gtk-GtkTreeSelection;
&gtk-GtkTreeViewColumn;
&gtk-GtkTreeView;
&gtk-GtkTreeDND;
&gtk-GtkTreeSortable;
&gtk-GtkTreeModelSort;
&gtk-GtkCellRenderer;
&gtk-GtkCellEditable;
&gtk-GtkCellRendererPixbuf;
&gtk-GtkCellRendererText;
&gtk-GtkCellRendererToggle;
&gtk-GtkListStore;
&gtk-GtkTreeStore;
&GtkTreeModel;
&GtkTreeSelection;
&GtkTreeViewColumn;
&GtkTreeView;
&GtkTreeDND;
&GtkTreeSortable;
&GtkTreeModelSort;
&GtkCellRenderer;
&GtkCellEditable;
&GtkCellRendererPixbuf;
&GtkCellRendererText;
&GtkCellRendererToggle;
&GtkListStore;
&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;

View File

@ -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>

View File

@ -120,7 +120,7 @@ Tells about the state of the object.
</para>
@GTK_IN_DESTRUCTION: the object is currently being destroyed. This is used
internally by GTK+ to prevent reinvokations during destruction.
internally by GTK+ to prevent reinvokations during destruction.
@GTK_FLOATING: the object is orphaned. Objects that take strong hold of an
object may gtk_object_sink() it, after obtaining their own references, if
they believe they are nearly primary ownership of the object.

View File

@ -75,7 +75,7 @@ Tells about certain properties of the widget.
defined through the rc mechanism.
@GTK_COMPOSITE_CHILD:
Indicates that the widget is a composite child of its parent; see
gtk_widget_push_composite_child(), gtk_widget_pop_composite_child().
gtk_widget_push_composite_child(), gtk_widget_pop_composite_child().
@GTK_NO_REPARENT:
@GTK_APP_PAINTABLE:
Set and unset by gtk_widget_set_app_paintable().
@ -112,7 +112,7 @@ again, after it has been made insensitive with gtk_widget_set_state()
or gtk_widget_set_sensitive().
</para>
@wid: a #GtkWidget.
@wid: a #GtkWidget.
<!-- ##### MACRO GTK_WIDGET_FLAGS ##### -->
@ -120,7 +120,7 @@ or gtk_widget_set_sensitive().
Returns the widget flags from @wid.
</para>
@wid: a #GtkWidget.
@wid: a #GtkWidget.
<!-- ##### MACRO GTK_WIDGET_TOPLEVEL ##### -->
@ -128,7 +128,7 @@ Returns the widget flags from @wid.
Evaluates to %TRUE if the widget is a toplevel widget.
</para>
@wid: a #GtkWidget.
@wid: a #GtkWidget.
<!-- ##### MACRO GTK_WIDGET_NO_WINDOW ##### -->
@ -168,7 +168,7 @@ Evaluates to %TRUE if the widget is visible.
Evaluates to %TRUE if the widget is mapped and visible.
</para>
@wid: a #GtkWidget.
@wid: a #GtkWidget.
<!-- ##### MACRO GTK_WIDGET_SENSITIVE ##### -->
@ -285,7 +285,7 @@ Evaluates to %TRUE if the #GTK_DOUBLE_BUFFERED flag has been set on the widget.
Turns on certain widget flags.
</para>
@wid: a #GtkWidget.
@wid: a #GtkWidget.
@flag: the flags to set.
@ -294,7 +294,7 @@ Turns on certain widget flags.
Turns off certain widget flags.
</para>
@wid: a #GtkWidget.
@wid: a #GtkWidget.
@flag: the flags to unset.
@ -919,7 +919,7 @@ Equivalent to <literal>gtk_widget_set_style (widget, NULL)</literal>.
Calls gtk_widget_set_rc_style() recursively on all descendants.
</para>
@widget: a #GtkWidget.
@widget: a #GtkWidget.
<!-- ##### FUNCTION gtk_widget_push_colormap ##### -->