From 824e8e2d9d8d89ac8d7cfe044036825d5cd58278 Mon Sep 17 00:00:00 2001 From: Havoc Pennington Date: Sun, 6 Jan 2002 21:09:26 +0000 Subject: [PATCH] remove gtk- prefix from TreeView and a few other entities, more consistent 2002-01-06 Havoc Pennington * 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 | 14 ++ docs/reference/gtk/changes-1.2.sgml | 5 +- docs/reference/gtk/changes-2.0.sgml | 20 +-- docs/reference/gtk/gtk-docs.sgml | 68 +++++----- docs/reference/gtk/question_index.sgml | 174 +++++++++++++++++++++++++ docs/reference/gtk/tmpl/gtkobject.sgml | 2 +- docs/reference/gtk/tmpl/gtkwidget.sgml | 16 +-- 7 files changed, 243 insertions(+), 56 deletions(-) diff --git a/docs/reference/ChangeLog b/docs/reference/ChangeLog index 398ad79748..f9a818c01a 100644 --- a/docs/reference/ChangeLog +++ b/docs/reference/ChangeLog @@ -1,3 +1,17 @@ +2002-01-06 Havoc Pennington + + * 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 * gtk/tmpl/gtkwidget.sgml: Additions. diff --git a/docs/reference/gtk/changes-1.2.sgml b/docs/reference/gtk/changes-1.2.sgml index 1f013ba53f..abde840c2c 100644 --- a/docs/reference/gtk/changes-1.2.sgml +++ b/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: - + OldReplacement @@ -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: - + RemovedReplacement @@ -149,7 +149,6 @@ During the development phase of the 1.1.x line of GTK+ certain functions Note that gtk_entry_adjust_scroll() is no longer needed as GtkEntry should automatically keep the scroll adjusted properly. - diff --git a/docs/reference/gtk/changes-2.0.sgml b/docs/reference/gtk/changes-2.0.sgml index 6e5750e930..ce05ceed41 100644 --- a/docs/reference/gtk/changes-2.0.sgml +++ b/docs/reference/gtk/changes-2.0.sgml @@ -164,7 +164,7 @@ The type macros GTK_TYPE_MAKE() and GTK_TYPE_SEQN The following type functions vanished/were replaced: - + Old FunctionReplacement @@ -181,7 +181,7 @@ The following type functions vanished/were replaced: gtk_type_set_chunk_alloc()GTypeInfo.n_preallocs gtk_type_register_enum()g_enum_register_static() gtk_type_register_flags()g_flags_register_static() -gtk_type_parent_class()g_type_parent()/g_type_class_peek_parent() +gtk_type_parent_class()g_type_parent()/g_type_class_peek_parent() @@ -285,7 +285,7 @@ Signal system changes: GSignal API is recommended, this avoids significant performance hits where GtkArg structures have to be converted into GValues. For - language bindings, GSignal+GClosure + language bindings, GSignal+GClosure provide a much more flexible and convenient mechanism to hook into signal emissions or install class default handlers, so the old GtkSignal 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 GDK_DISABLE_DEPRECATED. - + Old functionDefined As @@ -683,7 +683,7 @@ In GTK+ 1.2, if an event handler returned TRUE it prevented -GtkRange/GtkScrollbar/GtkScale were rewritten; this means that most +GtkRange/GtkScrollbar/GtkScale 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 GtkRange, you @@ -748,7 +748,7 @@ The set_child_arg() and get_child_arg()GtkContainer functions with the replacements: - + Old functionReplacement @@ -851,7 +851,7 @@ If a container depended on its children not being mapped For !NO_WINDOW widgets, if you create children of widget->window and don't map them in realize() then you must map them - in map()map(). [ In almost all cases, you can simply map the windows in realize(). ] @@ -909,7 +909,7 @@ The following variables are no longer exported from GDK. (Other variables externally in a large sample of GTK+ code.) - + VariableReplacement @@ -919,7 +919,7 @@ The following variables are no longer exported from GDK. (Other variables gdk_screengdk_x11_get_default_screen () gdk_root_windowgdk_x11_get_default_root_xwindow () gdk_root_parentgdk_get_default_root_window () -gdk_error_codegdk_error_trap_push ()/pop ()/entry> +gdk_error_codegdk_error_trap_push ()/pop () gdk_error_warningsgdk_error_trap_push ()/pop () gdk_display_namegdk_get_display () gdk_wm_delete_windowgdk_atom_intern ("WM_DELETE_WINDOW", FALSE) @@ -990,7 +990,7 @@ GDK is no longer put into threaded mode automatically when The GtkPreviewInfo struct has had its visual and colormap fields removed. Also, gtk_preview_get_cmap() - and gtk_preview_get_visual() are deprecated, as + and gtk_preview_get_visual() are deprecated, as GdkRGB works on any colormap and visual. You no longer need to gtk_widget_push_cmap (gtk_preview_get_cmap ()) in diff --git a/docs/reference/gtk/gtk-docs.sgml b/docs/reference/gtk/gtk-docs.sgml index bf777fa529..a0c4101508 100644 --- a/docs/reference/gtk/gtk-docs.sgml +++ b/docs/reference/gtk/gtk-docs.sgml @@ -24,7 +24,7 @@ - + @@ -87,8 +87,8 @@ - - + + @@ -98,20 +98,20 @@ - - - - - - - - - - - - - - + + + + + + + + + + + + + + @@ -325,8 +325,8 @@ that is, GUI components such as #GtkButton or #GtkTextView. Multiline Text Editor >k-TextWidget; - >k-GtkTextIter; - >k-GtkTextMark; + &GtkTextIter; + &GtkTextMark; &GtkTextBuffer; &GtkTextTag; &GtkTextTagTable; @@ -336,20 +336,20 @@ that is, GUI components such as #GtkButton or #GtkTextView. Tree and List Widget >k-TreeWidget; - >k-GtkTreeModel; - >k-GtkTreeSelection; - >k-GtkTreeViewColumn; - >k-GtkTreeView; - >k-GtkTreeDND; - >k-GtkTreeSortable; - >k-GtkTreeModelSort; - >k-GtkCellRenderer; - >k-GtkCellEditable; - >k-GtkCellRendererPixbuf; - >k-GtkCellRendererText; - >k-GtkCellRendererToggle; - >k-GtkListStore; - >k-GtkTreeStore; + &GtkTreeModel; + &GtkTreeSelection; + &GtkTreeViewColumn; + &GtkTreeView; + &GtkTreeDND; + &GtkTreeSortable; + &GtkTreeModelSort; + &GtkCellRenderer; + &GtkCellEditable; + &GtkCellRendererPixbuf; + &GtkCellRendererText; + &GtkCellRendererToggle; + &GtkListStore; + &GtkTreeStore; Menus, Combo Box, Toolbar @@ -430,7 +430,7 @@ that is, GUI components such as #GtkButton or #GtkTextView. &GtkBox; &GtkButtonBox; &GtkContainer; - >k-GtkEditable; + &GtkEditable; &GtkOldEditable; &GtkItem; &GtkMisc; diff --git a/docs/reference/gtk/question_index.sgml b/docs/reference/gtk/question_index.sgml index bec841025d..ee85179f11 100644 --- a/docs/reference/gtk/question_index.sgml +++ b/docs/reference/gtk/question_index.sgml @@ -122,8 +122,138 @@ threading primitives. + + + +How do I load an image or animation from a file? + + + + + +To load an image file straight into a display widget, use gtk_image_new_from_file() + If the file load fails, gtk_image_new_from_file() +will display a "broken image" graphic &mdash to detect a failed load +yourself, use gdk_pixbuf_new_from_file() +directly then gtk_image_new_from_pixbuf(). +. To load an image for another purpose, use gdk_pixbuf_new_from_file(). +To load an animation, use gdk_pixbuf_animation_new_from_file(). +gdk_pixbuf_animation_new_from_file() +can also load non-animated images, so use it in combination with +gdk_pixbuf_animation_is_static_image() to load a file of unknown type. + + +To load an image or animation file asynchronously (without blocking), use +GdkPixbufLoader. + + + + + + +Which widget should I use... + + + +...for lists and trees? + + + + +See tree widget overview &mdash you +should use the GtkTreeView 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 GtkTree or GtkCList/GtkCTree in newly-written code, they are +less flexible and result in an inferior user interface. + + + + + + +...for multi-line text display or editing? + + + + +See text widget overview &mdash you +should use the GtkTextView widget. +Do not use the deprecated widget GtkText in newly-written code, it has a +number of problems that are best avoided. + + +If you only have a small amount of text, GtkLabel may also be appropriate of course. +It can be made selectable with +gtk_label_set_selectable(). For a single-line text entry, +see GtkEntry. + + + + + + + +...to display an image or animation? + + + + +GtkImage can display images +in just about any format GTK+ understands. You can also +use GtkDrawingArea if you need +to do something more complex, such as draw text or graphics over the +top of the image. + + + + + + +...for presenting a set of mutually-exclusive choices, where Windows +would use a combo box? + + + + +With GTK+, a GtkOptionMenu 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. GtkOptionMenu is +much easier to use than GtkCombo +as well. Use GtkCombo only when you +need the editable text entry. + + +(As a future enhancement to GTK+, a new widget to replace GtkOptionMenu and GtkCombo 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 GtkCombo API. Bug +50554 tracks this issue, if you want to check status or post +comments.) + + + + + <link linkend="GtkWidget">GtkWidget</link> @@ -201,6 +331,50 @@ or + +<link linkend="GtkTreeView">GtkTreeView</link> + + + +How do I associate some data with a row in the tree? + + + + +Remember that the GtkTreeModel +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 gtk_tree_model_get(). +See the tree widget overview. + + + + + + +How do I put an image and some text in the same column? + + + + +You can pack more than one GtkCellRenderer into a single +GtkTreeViewColumn using +gtk_tree_view_column_pack_start() or gtk_tree_view_column_pack_end(). So pack both a GtkCellRendererPixbuf +and a GtkCellRendererText into the +column. + + + + + + + + diff --git a/docs/reference/gtk/tmpl/gtkobject.sgml b/docs/reference/gtk/tmpl/gtkobject.sgml index 0cc15ca13d..4496a5d449 100644 --- a/docs/reference/gtk/tmpl/gtkobject.sgml +++ b/docs/reference/gtk/tmpl/gtkobject.sgml @@ -120,7 +120,7 @@ Tells about the state of the object. @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. diff --git a/docs/reference/gtk/tmpl/gtkwidget.sgml b/docs/reference/gtk/tmpl/gtkwidget.sgml index 06617d5e95..cb107cfd43 100644 --- a/docs/reference/gtk/tmpl/gtkwidget.sgml +++ b/docs/reference/gtk/tmpl/gtkwidget.sgml @@ -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(). -@wid: a #GtkWidget. +@wid: a #GtkWidget. @@ -120,7 +120,7 @@ or gtk_widget_set_sensitive(). Returns the widget flags from @wid. -@wid: a #GtkWidget. +@wid: a #GtkWidget. @@ -128,7 +128,7 @@ Returns the widget flags from @wid. Evaluates to %TRUE if the widget is a toplevel widget. -@wid: a #GtkWidget. +@wid: a #GtkWidget. @@ -168,7 +168,7 @@ Evaluates to %TRUE if the widget is visible. Evaluates to %TRUE if the widget is mapped and visible. -@wid: a #GtkWidget. +@wid: a #GtkWidget. @@ -285,7 +285,7 @@ Evaluates to %TRUE if the #GTK_DOUBLE_BUFFERED flag has been set on the widget. Turns on certain widget flags. -@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. -@wid: a #GtkWidget. +@wid: a #GtkWidget. @flag: the flags to unset. @@ -919,7 +919,7 @@ Equivalent to gtk_widget_set_style (widget, NULL). Calls gtk_widget_set_rc_style() recursively on all descendants. -@widget: a #GtkWidget. +@widget: a #GtkWidget.