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.