diff options
74 files changed, 2325 insertions, 324 deletions
diff --git a/demos/Makefile.am b/demos/Makefile.am index f6c8b4ae93..8a43035b55 100644 --- a/demos/Makefile.am +++ b/demos/Makefile.am @@ -6,6 +6,7 @@ INCLUDES = @STRIP_BEGIN@ \ -I$(top_srcdir) \ -I$(top_builddir)/gdk \ -DGTK_DISABLE_COMPAT_H \ + -DGTK_DISABLE_DEPRECATED \ @GTK_DEBUG_FLAGS@ \ @GTK_XIM_FLAGS@ \ @GTK_LOCALE_FLAGS@ \ diff --git a/demos/gtk-demo/Makefile.am b/demos/gtk-demo/Makefile.am index d3548fb5a7..2327c53e9b 100644 --- a/demos/gtk-demo/Makefile.am +++ b/demos/gtk-demo/Makefile.am @@ -15,6 +15,7 @@ INCLUDES = @STRIP_BEGIN@ \ -I$(top_srcdir) \ -I$(top_builddir)/gdk \ -DGTK_DISABLE_COMPAT_H \ + -DGTK_DISABLE_DEPRECATED \ @GTK_DEBUG_FLAGS@ \ @GTK_XIM_FLAGS@ \ @GTK_LOCALE_FLAGS@ \ diff --git a/demos/testpixbuf-drawable.c b/demos/testpixbuf-drawable.c index 7b3170520c..aee537459b 100644 --- a/demos/testpixbuf-drawable.c +++ b/demos/testpixbuf-drawable.c @@ -98,9 +98,9 @@ int main(int argc, char **argv) gtk_container_add(GTK_CONTAINER(window), vbox); drawing_area = gtk_drawing_area_new(); - gtk_drawing_area_size(GTK_DRAWING_AREA(drawing_area), - gdk_pixbuf_get_width (pixbuf), - gdk_pixbuf_get_height (pixbuf)); + gtk_widget_set_usize(GTK_WIDGET(drawing_area), + gdk_pixbuf_get_width (pixbuf), + gdk_pixbuf_get_height (pixbuf)); gtk_signal_connect(GTK_OBJECT(drawing_area), "expose_event", GTK_SIGNAL_FUNC(expose_cb), NULL); diff --git a/demos/testpixbuf.c b/demos/testpixbuf.c index 8a5d8f2ddc..0af6d368e9 100644 --- a/demos/testpixbuf.c +++ b/demos/testpixbuf.c @@ -393,7 +393,7 @@ new_testrgb_window (GdkPixbuf *pixbuf, gchar *title) drawing_area = gtk_drawing_area_new (); temp_box = gtk_hbox_new (FALSE, 0); - gtk_drawing_area_size (GTK_DRAWING_AREA(drawing_area), w, h); + gtk_widget_set_usize (GTK_WIDGET(drawing_area), w, h); gtk_box_pack_start (GTK_BOX (temp_box), drawing_area, FALSE, FALSE, 0); gtk_box_pack_start (GTK_BOX (vbox), temp_box, FALSE, FALSE, 0); diff --git a/docs/reference/ChangeLog b/docs/reference/ChangeLog index 89b57955c7..e327fbb904 100644 --- a/docs/reference/ChangeLog +++ b/docs/reference/ChangeLog @@ -1,3 +1,25 @@ +2001-02-01 Havoc Pennington <hp@redhat.com> + + * gtk/gtk-sections.txt: updated + + * gtk/gtk-docs.sgml: Move the below from "Deprecated" section to + "special-purpose" section; move GtkItem out of deprecated section, + since GtkMenuItem uses it, though probably the GtkItem signals + should just migrate down to GtkMenuItem someday it won't happen + for 2.0 + + * gtk/tmpl/gtkgamma.sgml: add note about eventual removal + + * gtk/tmpl/gtkcurve.sgml: add note about eventual removal + + * gtk/tmpl/gtkruler.sgml: add note about eventual removal + + * gtk/tmpl/gtkhruler.sgml: add note about eventual removal + + * gtk/tmpl/gtkvruler.sgml: add note about eventual removal + + * gtk/tmpl/gtkinputdialog.sgml: add note about eventual removal + 2001-01-30 Havoc Pennington <hp@pobox.com> Also committed a bunch of automatic changes made by gtk-doc, diff --git a/docs/reference/gtk/gtk-docs.sgml b/docs/reference/gtk/gtk-docs.sgml index 4792e3d616..7f4bc58b41 100644 --- a/docs/reference/gtk/gtk-docs.sgml +++ b/docs/reference/gtk/gtk-docs.sgml @@ -357,10 +357,11 @@ An advanced widget set. <title>Abstract Base Classes</title> &GtkBin; &GtkBox; + &GtkButtonBox; &GtkContainer; >k-GtkEditable; &GtkOldEditable; - &GtkButtonBox; + &GtkItem; &GtkMisc; &GtkObject; &GtkPaned; @@ -376,27 +377,30 @@ An advanced widget set. &GtkSocket; </sect1> + <sect1 id="SpecialObjects"> + <title>Special-purpose features</title> + &GtkCurve; + &GtkGammaCurve; + &GtkHRuler; + &GtkRuler; + &GtkVRuler; + </sect1> + <sect1 id="DeprecatedObjects"> <title>Deprecated</title> &GtkCList; &GtkCTree; - &GtkCurve; &GtkData; - &GtkGammaCurve; - &GtkHRuler; - &GtkItem; &GtkList; &GtkListItem; &GtkPacker; &GtkPixmap; - &GtkPreview; &GtkProgress; - &GtkRuler; + &GtkPreview; &GtkText; &GtkTipsQuery; &GtkTree; &GtkTreeItem; - &GtkVRuler; </sect1> </chapter> diff --git a/docs/reference/gtk/gtk-sections.txt b/docs/reference/gtk/gtk-sections.txt index 8206ca5d98..02d47762a7 100644 --- a/docs/reference/gtk/gtk-sections.txt +++ b/docs/reference/gtk/gtk-sections.txt @@ -1143,7 +1143,6 @@ GTK_ITEM_FACTORY_GET_CLASS <FILE>gtklabel</FILE> <TITLE>GtkLabel</TITLE> GtkLabel -GtkLabelWord gtk_label_new gtk_label_set_text gtk_label_set_attributes @@ -1893,7 +1892,6 @@ GTK_SPIN_BUTTON_GET_CLASS <FILE>gtkstatusbar</FILE> <TITLE>GtkStatusbar</TITLE> GtkStatusbar -GtkStatusbarMsg gtk_statusbar_new gtk_statusbar_get_context_id gtk_statusbar_push @@ -2525,16 +2523,13 @@ gtk_tree_store_set_n_columns gtk_tree_store_set_column_type gtk_tree_store_set_cell gtk_tree_store_set -gtk_tree_store_setv gtk_tree_store_get -gtk_tree_store_getv gtk_tree_store_remove gtk_tree_store_insert gtk_tree_store_insert_before gtk_tree_store_insert_after gtk_tree_store_prepend gtk_tree_store_append -gtk_tree_store_get_root_iter gtk_tree_store_is_ancestor gtk_tree_store_iter_depth <SUBSECTION Standard> @@ -2562,8 +2557,8 @@ gtk_tree_view_column_set_cell_data gtk_tree_view_column_set_visible gtk_tree_view_column_get_visible gtk_tree_view_column_set_sizing -gtk_tree_view_column_get_col_type -gtk_tree_view_column_get_size +gtk_tree_view_column_get_sizing +gtk_tree_view_column_get_width gtk_tree_view_column_set_width gtk_tree_view_column_set_min_width gtk_tree_view_column_get_min_width @@ -2571,7 +2566,7 @@ gtk_tree_view_column_set_max_width gtk_tree_view_column_get_max_width gtk_tree_view_column_set_title gtk_tree_view_column_get_title -gtk_tree_view_column_set_header_clickable +gtk_tree_view_column_set_clickable gtk_tree_view_column_set_widget gtk_tree_view_column_get_widget gtk_tree_view_column_set_justification @@ -2608,7 +2603,7 @@ gtk_tree_view_append_column gtk_tree_view_remove_column gtk_tree_view_insert_column gtk_tree_view_get_column -gtk_tree_view_move_to +gtk_tree_view_scroll_to_cell gtk_tree_view_get_path_at_pos gtk_tree_view_expand_all gtk_tree_view_collapse_all @@ -2637,7 +2632,7 @@ gtk_tree_model_simple_deleted <SUBSECTION Standard> GTK_TREE_MODEL_SIMPLE GTK_IS_TREE_MODEL_SIMPLE -GTK_TYPE_MODEL_SIMPLE +GTK_TYPE_TREE_MODEL_SIMPLE gtk_tree_model_simple_get_type GTK_TREE_MODEL_SIMPLE_CLASS GTK_IS_TREE_MODEL_SIMPLE_CLASS @@ -3002,7 +2997,7 @@ gtk_widget_modify_font gtk_widget_create_pango_context gtk_widget_get_pango_context gtk_widget_create_pango_layout -gtk_widget_render_stock_icon +gtk_widget_render_icon gtk_widget_pop_composite_child gtk_widget_push_composite_child gtk_widget_queue_clear diff --git a/docs/reference/gtk/tmpl/gtk-unused.sgml b/docs/reference/gtk/tmpl/gtk-unused.sgml index 25cbfa812d..7f37ff2cab 100644 --- a/docs/reference/gtk/tmpl/gtk-unused.sgml +++ b/docs/reference/gtk/tmpl/gtk-unused.sgml @@ -1626,6 +1626,26 @@ Given the type of an object and a pointer to it, the object is freed. </para> +<!-- ##### STRUCT GtkStatusbarMsg ##### --> +<para> +Holds the data for a statusbar message. <structfield>text</structfield> holds the actual text string. <structfield>context_id</structfield> is the context that this message is associated with, and <structfield>message_id</structfield> is this particular message's identifier. However, these fields should not be modified directly. +</para> + +@text: +@context_id: +@message_id: + +<!-- ##### FUNCTION gtk_widget_render_stock_icon ##### --> +<para> + +</para> + +@widget: +@stock_id: +@size: +@detail: +@Returns: + <!-- ##### SECTION ./tmpl/gtkprivate.sgml:Title ##### --> Private Information @@ -1943,6 +1963,12 @@ be used to bypass it. </para> +<!-- ##### STRUCT GtkLabelWord ##### --> +<para>
+Internal to #GtkLabel.
+</para> + + <!-- ##### FUNCTION gtk_text_buffer_spew ##### --> <para> diff --git a/docs/reference/gtk/tmpl/gtkcurve.sgml b/docs/reference/gtk/tmpl/gtkcurve.sgml index 919f6295f5..8701b8517d 100644 --- a/docs/reference/gtk/tmpl/gtkcurve.sgml +++ b/docs/reference/gtk/tmpl/gtkcurve.sgml @@ -6,6 +6,15 @@ allows direct editing of a curve. <!-- ##### SECTION Long_Description ##### --> <para> + NOTE this widget is considered too specialized/little-used for + GTK+, and will in the future be moved to some other package. If + your application needs this widget, feel free to use it, as the + widget does work and is useful in some applications; it's just not + of general interest. However, we are not accepting new features for + the widget, and it will eventually move out of the GTK+ + distribution. +</para> +<para> The #GtkCurve widget allows the user to edit a curve covering a range of values. It is typically used to fine-tune color balances in graphics applications like the Gimp. diff --git a/docs/reference/gtk/tmpl/gtkgamma.sgml b/docs/reference/gtk/tmpl/gtkgamma.sgml index 28f392d5c1..a3326cee5f 100644 --- a/docs/reference/gtk/tmpl/gtkgamma.sgml +++ b/docs/reference/gtk/tmpl/gtkgamma.sgml @@ -6,6 +6,15 @@ a subclass of #GtkCurve for editing gamma curves. <!-- ##### SECTION Long_Description ##### --> <para> + NOTE this widget is considered too specialized/little-used for + GTK+, and will in the future be moved to some other package. If + your application needs this widget, feel free to use it, as the + widget does work and is useful in some applications; it's just not + of general interest. However, we are not accepting new features for + the widget, and it will eventually move out of the GTK+ + distribution. +</para> +<para> The #GtkGammaCurve widget is a subclass of #GtkCurve specifically for editing gamma curves, which are used in graphics applications such as the Gimp. diff --git a/docs/reference/gtk/tmpl/gtkhruler.sgml b/docs/reference/gtk/tmpl/gtkhruler.sgml index e6ceadc291..ef99f9b00b 100644 --- a/docs/reference/gtk/tmpl/gtkhruler.sgml +++ b/docs/reference/gtk/tmpl/gtkhruler.sgml @@ -6,6 +6,15 @@ A horizontal ruler. <!-- ##### SECTION Long_Description ##### --> <para> + NOTE this widget is considered too specialized/little-used for + GTK+, and will in the future be moved to some other package. If + your application needs this widget, feel free to use it, as the + widget does work and is useful in some applications; it's just not + of general interest. However, we are not accepting new features for + the widget, and it will eventually move out of the GTK+ + distribution. +</para> +<para> The HRuler widget is a widget arranged horizontally creating a ruler that is utilized around other widgets such as a text widget. The ruler is used to show the location of the mouse on the window and to show the size of the window in diff --git a/docs/reference/gtk/tmpl/gtkiconfactory.sgml b/docs/reference/gtk/tmpl/gtkiconfactory.sgml index 933586279b..d617f266bb 100644 --- a/docs/reference/gtk/tmpl/gtkiconfactory.sgml +++ b/docs/reference/gtk/tmpl/gtkiconfactory.sgml @@ -3,10 +3,28 @@ Themeable Stock Images <!-- ##### SECTION Short_Description ##### --> +Manipulating stock icons <!-- ##### SECTION Long_Description ##### --> <para> + An icon factory manages a collection of #GtkIconSet; a #GtkIconSet manages a + set of variants of a particular icon (i.e. a #GtkIconSet contains variants for + different sizes and widget states). Icons in an icon factory are named by a + stock ID, which is a simple string identifying the icon. Each #GtkStyle has a + list of #GtkIconFactory derived from the current theme; those icon factories + are consulted first when searching for an icon. If the theme doesn't set a + particular icon, GTK+ looks for the icon in a list of default icon factories, + maintained by gtk_icon_factory_add_default() and + gtk_icon_factory_remove_default(). Applications with icons should add a default + icon factory with their icons, which will allow themes to override the icons + for the application. +</para> +<para> +To display an icon, always use gtk_style_lookup_icon_set() on the widget that +will display the icon, or the convenience function +gtk_widget_render_icon(). These functions take the theme into account when +looking up the icon to use for a given stock ID. </para> <!-- ##### SECTION See_Also ##### --> diff --git a/docs/reference/gtk/tmpl/gtkinputdialog.sgml b/docs/reference/gtk/tmpl/gtkinputdialog.sgml index 2abb5bc1a6..436f014e0f 100644 --- a/docs/reference/gtk/tmpl/gtkinputdialog.sgml +++ b/docs/reference/gtk/tmpl/gtkinputdialog.sgml @@ -6,6 +6,16 @@ Configure devices for the XInput extension. <!-- ##### SECTION Long_Description ##### --> <para> + NOTE this widget is considered too specialized/little-used for + GTK+, and will in the future be moved to some other package. If + your application needs this widget, feel free to use it, as the + widget does work and is useful in some applications; it's just not + of general interest. However, we are not accepting new features for + the widget, and it will eventually move out of the GTK+ + distribution. +</para> + +<para> #GtkInputDialog displays a dialog which allows the user to configure XInput extension devices. For each device, they can control the mode of the device diff --git a/docs/reference/gtk/tmpl/gtklabel.sgml b/docs/reference/gtk/tmpl/gtklabel.sgml index f26cf204ca..921328c1fc 100644 --- a/docs/reference/gtk/tmpl/gtklabel.sgml +++ b/docs/reference/gtk/tmpl/gtklabel.sgml @@ -24,12 +24,6 @@ described below. </para> -<!-- ##### STRUCT GtkLabelWord ##### --> -<para>
-Internal to #GtkLabel.
-</para> - - <!-- ##### FUNCTION gtk_label_new ##### --> <para>
Creates a new label with the given string of text inside it. You can
diff --git a/docs/reference/gtk/tmpl/gtkruler.sgml b/docs/reference/gtk/tmpl/gtkruler.sgml index 679d284306..ab4af18d3d 100644 --- a/docs/reference/gtk/tmpl/gtkruler.sgml +++ b/docs/reference/gtk/tmpl/gtkruler.sgml @@ -6,6 +6,15 @@ Base class for horizontal or vertical rulers <!-- ##### SECTION Long_Description ##### --> <para> + NOTE this widget is considered too specialized/little-used for + GTK+, and will in the future be moved to some other package. If + your application needs this widget, feel free to use it, as the + widget does work and is useful in some applications; it's just not + of general interest. However, we are not accepting new features for + the widget, and it will eventually move out of the GTK+ + distribution. +</para> +<para> The GTKRuler widget is a base class for horizontal and vertical rulers. Rulers are used to show the mouse pointer's location in a window. The ruler can either be horizontal or vertical on the window. Within the ruler a small triangle diff --git a/docs/reference/gtk/tmpl/gtkstatusbar.sgml b/docs/reference/gtk/tmpl/gtkstatusbar.sgml index 09e7b1dd2e..c4b37a46eb 100644 --- a/docs/reference/gtk/tmpl/gtkstatusbar.sgml +++ b/docs/reference/gtk/tmpl/gtkstatusbar.sgml @@ -50,15 +50,6 @@ Contains private data that should be modified with the functions described below </para> -<!-- ##### STRUCT GtkStatusbarMsg ##### --> -<para> -Holds the data for a statusbar message. <structfield>text</structfield> holds the actual text string. <structfield>context_id</structfield> is the context that this message is associated with, and <structfield>message_id</structfield> is this particular message's identifier. However, these fields should not be modified directly. -</para> - -@text: -@context_id: -@message_id: - <!-- ##### FUNCTION gtk_statusbar_new ##### --> <para> Creates a new #GtkStatusbar ready for messages. diff --git a/docs/reference/gtk/tmpl/gtkstock.sgml b/docs/reference/gtk/tmpl/gtkstock.sgml index 24280e4b5c..0345dc380e 100644 --- a/docs/reference/gtk/tmpl/gtkstock.sgml +++ b/docs/reference/gtk/tmpl/gtkstock.sgml @@ -30,8 +30,10 @@ Stock Items </para> -@item: +@items: @n_items: +<!-- # Unused Parameters # --> +@item: <!-- ##### FUNCTION gtk_stock_add_static ##### --> @@ -39,8 +41,10 @@ Stock Items </para> -@item: +@items: @n_items: +<!-- # Unused Parameters # --> +@item: <!-- ##### FUNCTION gtk_stock_item_copy ##### --> diff --git a/docs/reference/gtk/tmpl/gtktextbuffer.sgml b/docs/reference/gtk/tmpl/gtktextbuffer.sgml index 64ad8b4001..980fb9c0fa 100644 --- a/docs/reference/gtk/tmpl/gtktextbuffer.sgml +++ b/docs/reference/gtk/tmpl/gtktextbuffer.sgml @@ -334,6 +334,9 @@ types related to the text widget and how they work together. @buffer: @tag: +@start: +@end: +<!-- # Unused Parameters # --> @start_index: @end_index: @@ -345,6 +348,9 @@ types related to the text widget and how they work together. @buffer: @tag: +@start: +@end: +<!-- # Unused Parameters # --> @start_index: @end_index: @@ -356,6 +362,9 @@ types related to the text widget and how they work together. @buffer: @name: +@start: +@end: +<!-- # Unused Parameters # --> @start_index: @end_index: @@ -367,6 +376,9 @@ types related to the text widget and how they work together. @buffer: @name: +@start: +@end: +<!-- # Unused Parameters # --> @start_index: @end_index: diff --git a/docs/reference/gtk/tmpl/gtktreeview.sgml b/docs/reference/gtk/tmpl/gtktreeview.sgml index aaf95374b1..83b41ba5ab 100644 --- a/docs/reference/gtk/tmpl/gtktreeview.sgml +++ b/docs/reference/gtk/tmpl/gtktreeview.sgml @@ -203,6 +203,18 @@ GtkTreeView @Returns: +<!-- ##### FUNCTION gtk_tree_view_scroll_to_cell ##### --> +<para> + +</para> + +@tree_view: +@path: +@column: +@row_align: +@col_align: + + <!-- ##### FUNCTION gtk_tree_view_get_path_at_pos ##### --> <para> diff --git a/docs/reference/gtk/tmpl/gtktreeviewcolumn.sgml b/docs/reference/gtk/tmpl/gtktreeviewcolumn.sgml index ff4911e87f..11ebd19021 100644 --- a/docs/reference/gtk/tmpl/gtktreeviewcolumn.sgml +++ b/docs/reference/gtk/tmpl/gtktreeviewcolumn.sgml @@ -151,6 +151,24 @@ GtkTreeViewColumn @type: +<!-- ##### FUNCTION gtk_tree_view_column_get_sizing ##### --> +<para> + +</para> + +@tree_column: +@Returns: + + +<!-- ##### FUNCTION gtk_tree_view_column_get_width ##### --> +<para> + +</para> + +@tree_column: +@Returns: + + <!-- ##### FUNCTION gtk_tree_view_column_set_width ##### --> <para> @@ -214,6 +232,15 @@ GtkTreeViewColumn @Returns: +<!-- ##### FUNCTION gtk_tree_view_column_set_clickable ##### --> +<para> + +</para> + +@tree_column: +@active: + + <!-- ##### FUNCTION gtk_tree_view_column_set_widget ##### --> <para> diff --git a/docs/reference/gtk/tmpl/gtkvruler.sgml b/docs/reference/gtk/tmpl/gtkvruler.sgml index aad5d12e25..15f4980121 100644 --- a/docs/reference/gtk/tmpl/gtkvruler.sgml +++ b/docs/reference/gtk/tmpl/gtkvruler.sgml @@ -6,6 +6,15 @@ A vertical ruler. <!-- ##### SECTION Long_Description ##### --> <para> + NOTE this widget is considered too specialized/little-used for + GTK+, and will in the future be moved to some other package. If + your application needs this widget, feel free to use it, as the + widget does work and is useful in some applications; it's just not + of general interest. However, we are not accepting new features for + the widget, and it will eventually move out of the GTK+ + distribution. +</para> +<para> The VRuler widget is a widget arranged vertically creating a ruler that is utilized around other widgets such as a text widget. The ruler is used to show the location of the mouse on the window and to show the size of the window in diff --git a/docs/reference/gtk/tmpl/gtkwidget.sgml b/docs/reference/gtk/tmpl/gtkwidget.sgml index 2790ec369f..9180b2ede4 100644 --- a/docs/reference/gtk/tmpl/gtkwidget.sgml +++ b/docs/reference/gtk/tmpl/gtkwidget.sgml @@ -1142,7 +1142,7 @@ GtkWidget @Returns: -<!-- ##### FUNCTION gtk_widget_render_stock_icon ##### --> +<!-- ##### FUNCTION gtk_widget_render_icon ##### --> <para> </para> diff --git a/gtk/gtkcellrenderer.c b/gtk/gtkcellrenderer.c index d7724f49ab..0b69d98bcd 100644 --- a/gtk/gtkcellrenderer.c +++ b/gtk/gtkcellrenderer.c @@ -198,17 +198,23 @@ gtk_cell_renderer_set_property (GObject *object, } } +/** + * gtk_cell_renderer_get_size: + * @cell: a #GtkCellRenderer + * @widget: the widget the renderer is rendering to + * @width: location to return width needed to render a cell, or %NULL + * @height: location to return height needed to render a cell, or %NULL + * + * Obtains the width and height needed to render the cell. Used by + * view widgets to determine the appropriate size for the cell_area + * passed to gtk_cell_renderer_render(). + **/ void gtk_cell_renderer_get_size (GtkCellRenderer *cell, GtkWidget *widget, gint *width, gint *height) { - /* It's actually okay to pass in a NULL cell, as we run into that - * a lot - */ - if (cell == NULL) - return; g_return_if_fail (GTK_IS_CELL_RENDERER (cell)); g_return_if_fail (GTK_CELL_RENDERER_GET_CLASS (cell)->get_size != NULL); @@ -262,6 +268,22 @@ gtk_cell_renderer_render (GtkCellRenderer *cell, flags); } +/** + * gtk_cell_renderer_event: + * @cell: a #GtkCellRenderer + * @event: a #GdkEvent + * @widget: widget that received the event + * @path: widget-dependent string representation of the event location; e.g. for #GtkTreeView, a string representation of #GtkTreePath + * @background_area: background area as passed to gtk_cell_renderer_render() + * @cell_area: cell area as passed to gtk_cell_renderer_render() + * @flags: render flags + * + * Passes an event to the cell renderer for possible processing. Some + * cell renderers may use events; for example, #GtkCellRendererToggle + * toggles when it gets a mouse click. + * + * Return value: %TRUE if the event was consumed/handled + **/ gint gtk_cell_renderer_event (GtkCellRenderer *cell, GdkEvent *event, diff --git a/gtk/gtkcellrendererpixbuf.c b/gtk/gtkcellrendererpixbuf.c index 61a5572370..f3a434e37b 100644 --- a/gtk/gtkcellrendererpixbuf.c +++ b/gtk/gtkcellrendererpixbuf.c @@ -153,6 +153,19 @@ gtk_cell_renderer_pixbuf_set_property (GObject *object, } } +/** + * gtk_cell_renderer_pixbuf_new: + * + * Creates a new #GtkCellRendererPixbuf. Adjust rendering + * parameters using object properties. Object properties can be set + * globally (with g_object_set()). Also, with #GtkTreeViewColumn, you + * can bind a property to a value in a #GtkTreeModel. For example, you + * can bind the "pixbuf" property on the cell renderer to a pixbuf value + * in the model, thus rendering a different image in each row of the + * #GtkTreeView. + * + * Return value: the new cell renderer + **/ GtkCellRenderer * gtk_cell_renderer_pixbuf_new (void) { diff --git a/gtk/gtkcellrenderertext.c b/gtk/gtkcellrenderertext.c index e98e6fd098..751659fc5c 100644 --- a/gtk/gtkcellrenderertext.c +++ b/gtk/gtkcellrenderertext.c @@ -331,6 +331,19 @@ gtk_cell_renderer_text_set_property (GObject *object, } } +/** + * gtk_cell_renderer_text_new: + * + * Creates a new #GtkCellRendererText. Adjust how text is drawn using + * object properties. Object properties can be + * set globally (with g_object_set()). Also, with #GtkTreeViewColumn, + * you can bind a property to a value in a #GtkTreeModel. For example, + * you can bind the "text" property on the cell renderer to a string + * value in the model, thus rendering a different string in each row + * of the #GtkTreeView + * + * Return value: the new cell renderer + **/ GtkCellRenderer * gtk_cell_renderer_text_new (void) { diff --git a/gtk/gtkcellrenderertextpixbuf.c b/gtk/gtkcellrenderertextpixbuf.c index 8d8fe804bb..2f007dcc42 100644 --- a/gtk/gtkcellrenderertextpixbuf.c +++ b/gtk/gtkcellrenderertextpixbuf.c @@ -217,7 +217,6 @@ gtk_cell_renderer_text_pixbuf_get_property (GObject *object, } } - static void gtk_cell_renderer_text_pixbuf_set_property (GObject *object, guint param_id, @@ -263,6 +262,19 @@ gtk_cell_renderer_text_pixbuf_set_property (GObject *object, } } +/** + * gtk_cell_renderer_text_pixbuf_new: + * + * Creates a new #GtkCellRendererTextPixbuf. Adjust rendering + * parameters using object properties. Object properties can be set + * globally (with g_object_set()). Also, with #GtkTreeViewColumn, you + * can bind a property to a value in a #GtkTreeModel. For example, you + * can bind the "text" property on the cell renderer to a string value + * in the model, thus rendering a different string in each row of the + * #GtkTreeView + * + * Return value: the new cell renderer + **/ GtkCellRenderer * gtk_cell_renderer_text_pixbuf_new (void) { diff --git a/gtk/gtkcellrenderertoggle.c b/gtk/gtkcellrenderertoggle.c index 4ff6c7e520..2213f3c16b 100644 --- a/gtk/gtkcellrenderertoggle.c +++ b/gtk/gtkcellrenderertoggle.c @@ -184,7 +184,7 @@ gtk_cell_renderer_toggle_set_property (GObject *object, switch (param_id) { case PROP_ACTIVE: - gtk_cell_renderer_toggle_set_active (celltoggle, g_value_get_boolean (value)); + celltoggle->active = g_value_get_boolean (value); break; case PROP_RADIO: celltoggle->radio = g_value_get_boolean (value); @@ -195,6 +195,19 @@ gtk_cell_renderer_toggle_set_property (GObject *object, } } +/** + * gtk_cell_renderer_toggle_new: + * + * Creates a new #GtkCellRendererToggle. Adjust rendering + * parameters using object properties. Object properties can be set + * globally (with g_object_set()). Also, with #GtkTreeViewColumn, you + * can bind a property to a value in a #GtkTreeModel. For example, you + * can bind the "active" property on the cell renderer to a boolean value + * in the model, thus causing the check button to reflect the state of + * the model. + * + * Return value: the new cell renderer + **/ GtkCellRenderer * gtk_cell_renderer_toggle_new (void) { @@ -299,35 +312,38 @@ gtk_cell_renderer_toggle_event (GtkCellRenderer *cell, return retval; } +/** + * gtk_cell_renderer_toggle_set_radio: + * @toggle: a #GtkCellRendererToggle + * @radio: %TRUE to make the toggle look like a radio button + * + * If @radio is %TRUE, the cell renderer renders a radio toggle + * (i.e. a toggle in a group of mutually-exclusive toggles). + * If %FALSE, it renders a check toggle (a standalone boolean option). + * This can be set globally for the cell renderer, or changed just + * before rendering each cell in the model (for #GtkTreeView, you set + * up a per-row setting using #GtkTreeViewColumn to associate model + * columns with cell renderer properties). + **/ void gtk_cell_renderer_toggle_set_radio (GtkCellRendererToggle *toggle, gboolean radio) { - g_return_if_fail (toggle != NULL); g_return_if_fail (GTK_IS_CELL_RENDERER_TOGGLE (toggle)); toggle->radio = radio; } +/** + * gtk_cell_renderer_toggle_get_radio: + * @toggle: a #GtkCellRendererToggle + * + * Return value: %TRUE if we're rendering radio toggles rather than checkboxes + **/ gboolean -gtk_cell_renderer_toggle_get_active (GtkCellRendererToggle *toggle) +gtk_cell_renderer_toggle_get_radio (GtkCellRendererToggle *toggle) { g_return_val_if_fail (GTK_IS_CELL_RENDERER_TOGGLE (toggle), FALSE); - return toggle->active; -} - -void -gtk_cell_renderer_toggle_set_active (GtkCellRendererToggle *toggle, - gboolean setting) -{ - g_return_if_fail (GTK_IS_CELL_RENDERER_TOGGLE (toggle)); - - setting = !! setting; - - if (toggle->active != setting) - { - toggle->active = setting; - g_object_notify (G_OBJECT (toggle), "active"); - } + return toggle->radio; } diff --git a/gtk/gtkclist.h b/gtk/gtkclist.h index 3c41ed98ea..568c31f32f 100644 --- a/gtk/gtkclist.h +++ b/gtk/gtkclist.h @@ -25,6 +25,8 @@ * GTK+ at ftp://ftp.gtk.org/pub/gtk/. */ +#ifndef GTK_DISABLE_DEPRECATED + #ifndef __GTK_CLIST_H__ #define __GTK_CLIST_H__ @@ -785,3 +787,5 @@ PangoLayout *_gtk_clist_create_cell_layout (GtkCList *clist, #endif /* __cplusplus */ #endif /* __GTK_CLIST_H__ */ + +#endif /* GTK_DISABLE_DEPRECATED */ diff --git a/gtk/gtkcontainer.c b/gtk/gtkcontainer.c index 5f04910f95..d32eb52978 100644 --- a/gtk/gtkcontainer.c +++ b/gtk/gtkcontainer.c @@ -684,6 +684,20 @@ gtk_container_get_arg (GtkObject *object, } } +/** + * gtk_container_set_border_width: + * @container: a #GtkContainer + * @border_width: amount of blank space to leave <emphasis>outside</emphasis> the container + * + * The border width of a container is the amount of space to leave + * around the outside of the container. The only exception to this is + * #GtkWindow; because toplevel windows can't leave space outside, + * they leave the space inside. The border is added on all sides of + * the container. To add space to only one side, one approach is to + * create a #GtkAlignment widget, call gtk_widget_set_usize() to give + * it a size, and place it on the side of the container as a spacer. + * + **/ void gtk_container_set_border_width (GtkContainer *container, guint border_width) @@ -700,6 +714,20 @@ gtk_container_set_border_width (GtkContainer *container, } } +/** + * gtk_container_add: + * @container: a #GtkContainer + * @widget: a widget to be placed inside @container + * + * Adds @widget to @container. Typically used for simple containers + * such as #GtkWindow, #GtkFrame, or #GtkButton; for more complicated + * layout containers such as #GtkBox or #GtkTable, this function will + * pick default packing parameters that may not be correct. So + * consider functions such as gtk_box_pack_start() and + * gtk_table_attach() as an alternative to gtk_container_add() in + * those cases. A widget may be added to only one container at a time; + * you can't place the same widget inside two different containers. + **/ void gtk_container_add (GtkContainer *container, GtkWidget *widget) @@ -708,11 +736,32 @@ gtk_container_add (GtkContainer *container, g_return_if_fail (GTK_IS_CONTAINER (container)); g_return_if_fail (widget != NULL); g_return_if_fail (GTK_IS_WIDGET (widget)); - g_return_if_fail (widget->parent == NULL); + + if (widget->parent != NULL) + { + g_warning ("Attempting to add a widget with type %s to a container of " + "type %s, but the widget is already inside a container of type %s", + g_type_name (G_TYPE_FROM_INSTANCE (widget)), + g_type_name (G_TYPE_FROM_INSTANCE (container)), + g_type_name (G_TYPE_FROM_INSTANCE (widget->parent))); + return; + } gtk_signal_emit (GTK_OBJECT (container), container_signals[ADD], widget); } +/** + * gtk_container_remove: + * @container: a #GtkContainer + * @widget: a current child of @container + * + * Removes @widget from @container. @widget must be inside @container. + * Note that @container will own a reference to @widget, and that this + * may be the last reference held; so removing a widget from its + * container can destroy that widget. If you want to use @widget + * again, you need to add a reference to it while it's not inside + * a container, using g_object_ref(). + **/ void gtk_container_remove (GtkContainer *container, GtkWidget *widget) @@ -1087,6 +1136,19 @@ gtk_container_resize_children (GtkContainer *container) g_slist_free (resize_containers); } +/** + * gtk_container_forall: + * @container: a #GtkContainer + * @callback: a callback + * @callback_data: callback user data + * + * Invokes @callback on each child of @container, including children + * that are considered "internal" (implementation details of the + * container). "Internal" children generally weren't added by the user + * of the container, but were added by the container implementation + * itself. Most applications should use gtk_container_foreach(), + * rather than gtk_container_forall(). + **/ void gtk_container_forall (GtkContainer *container, GtkCallback callback, @@ -1104,6 +1166,17 @@ gtk_container_forall (GtkContainer *container, class->forall (container, TRUE, callback, callback_data); } +/** + * gtk_container_foreach: + * @container: a #GtkContainer + * @callback: a callback + * @callback_data: callback user data + * + * Invokes @callback on each non-internal child of @container. See + * gtk_container_forall() for details on what constitutes an + * "internal" child. Most applications should use + * gtk_container_foreach(), rather than gtk_container_forall(). + **/ void gtk_container_foreach (GtkContainer *container, GtkCallback callback, diff --git a/gtk/gtkctree.h b/gtk/gtkctree.h index b2dd4f39aa..69cc0b9821 100644 --- a/gtk/gtkctree.h +++ b/gtk/gtkctree.h @@ -28,6 +28,8 @@ * GTK+ at ftp://ftp.gtk.org/pub/gtk/. */ +#ifndef GTK_DISABLE_DEPRECATED + #ifndef __GTK_CTREE_H__ #define __GTK_CTREE_H__ @@ -434,3 +436,5 @@ void gtk_ctree_sort_recursive (GtkCTree *ctree, #endif /* __cplusplus */ #endif /* __GTK_CTREE_H__ */ + +#endif /* GTK_DISABLE_DEPRECATED */ diff --git a/gtk/gtkcurve.h b/gtk/gtkcurve.h index ba0235156e..027a86c5e3 100644 --- a/gtk/gtkcurve.h +++ b/gtk/gtkcurve.h @@ -24,6 +24,16 @@ * GTK+ at ftp://ftp.gtk.org/pub/gtk/. */ +/* + * NOTE this widget is considered too specialized/little-used for + * GTK+, and will in the future be moved to some other package. If + * your application needs this widget, feel free to use it, as the + * widget does work and is useful in some applications; it's just not + * of general interest. However, we are not accepting new features for + * the widget, and it will eventually move out of the GTK+ + * distribution. + */ + #ifndef __GTK_CURVE_H__ #define __GTK_CURVE_H__ diff --git a/gtk/gtkdrawingarea.h b/gtk/gtkdrawingarea.h index 8ba240f451..72e713b4bb 100644 --- a/gtk/gtkdrawingarea.h +++ b/gtk/gtkdrawingarea.h @@ -63,9 +63,12 @@ struct _GtkDrawingAreaClass GtkType gtk_drawing_area_get_type (void) G_GNUC_CONST; GtkWidget* gtk_drawing_area_new (void); + +#ifndef GTK_DISABLE_DEPRECATED void gtk_drawing_area_size (GtkDrawingArea *darea, gint width, gint height); +#endif /* GTK_DISABLE_DEPRECATED */ #ifdef __cplusplus diff --git a/gtk/gtkentry.c b/gtk/gtkentry.c index a74589936b..dfc9a81665 100644 --- a/gtk/gtkentry.c +++ b/gtk/gtkentry.c @@ -2578,6 +2578,20 @@ gtk_entry_set_visibility (GtkEntry *entry, gtk_entry_recompute (entry); } +/** + * gtk_entry_set_invisible_char: + * @entry: a #GtkEntry + * @ch: a Unicode character + * + * Sets the character to use in place of the actual text when + * gtk_entry_set_visibility() has been called to set text visibility + * to %FALSE. i.e. this is the character used in "password mode" to + * show the user how many characters have been typed. The default + * invisible char is an asterisk ('*'). If you set the invisible char + * to 0, then the user will get no feedback at all; there will be + * no text on the screen as they type. + * + **/ void gtk_entry_set_invisible_char (GtkEntry *entry, gunichar ch) diff --git a/gtk/gtkgamma.h b/gtk/gtkgamma.h index 4875df82a9..931860e6eb 100644 --- a/gtk/gtkgamma.h +++ b/gtk/gtkgamma.h @@ -24,6 +24,16 @@ * GTK+ at ftp://ftp.gtk.org/pub/gtk/. */ +/* + * NOTE this widget is considered too specialized/little-used for + * GTK+, and will in the future be moved to some other package. If + * your application needs this widget, feel free to use it, as the + * widget does work and is useful in some applications; it's just not + * of general interest. However, we are not accepting new features for + * the widget, and it will eventually move out of the GTK+ + * distribution. + */ + #ifndef __GTK_GAMMA_CURVE_H__ #define __GTK_GAMMA_CURVE_H__ diff --git a/gtk/gtkhruler.h b/gtk/gtkhruler.h index 1c482331b6..829665c626 100644 --- a/gtk/gtkhruler.h +++ b/gtk/gtkhruler.h @@ -24,6 +24,16 @@ * GTK+ at ftp://ftp.gtk.org/pub/gtk/. */ +/* + * NOTE this widget is considered too specialized/little-used for + * GTK+, and will in the future be moved to some other package. If + * your application needs this widget, feel free to use it, as the + * widget does work and is useful in some applications; it's just not + * of general interest. However, we are not accepting new features for + * the widget, and it will eventually move out of the GTK+ + * distribution. + */ + #ifndef __GTK_HRULER_H__ #define __GTK_HRULER_H__ diff --git a/gtk/gtkiconfactory.c b/gtk/gtkiconfactory.c index ff724d4549..56d2fccc27 100644 --- a/gtk/gtkiconfactory.c +++ b/gtk/gtkiconfactory.c @@ -103,12 +103,49 @@ gtk_icon_factory_finalize (GObject *object) G_OBJECT_CLASS (parent_class)->finalize (object); } +/** + * gtk_icon_factory_new: + * + * Creates a new #GtkIconFactory. An icon factory manages a collection + * of #GtkIconSet; a #GtkIconSet manages a set of variants of a + * particular icon (i.e. a #GtkIconSet contains variants for different + * sizes and widget states). Icons in an icon factory are named by a + * stock ID, which is a simple string identifying the icon. Each + * #GtkStyle has a list of #GtkIconFactory derived from the current + * theme; those icon factories are consulted first when searching for + * an icon. If the theme doesn't set a particular icon, GTK+ looks for + * the icon in a list of default icon factories, maintained by + * gtk_icon_factory_add_default() and + * gtk_icon_factory_remove_default(). Applications with icons should + * add a default icon factory with their icons, which will allow + * themes to override the icons for the application. + * + * Return value: a new #GtkIconFactory + **/ GtkIconFactory* gtk_icon_factory_new (void) { return GTK_ICON_FACTORY (g_object_new (GTK_TYPE_ICON_FACTORY, NULL)); } +/** + * gtk_icon_factory_add: + * @factory: a #GtkIconFactory + * @stock_id: icon name + * @icon_set: icon set + * + * Adds the given @icon_set to the icon factory, under the name + * @stock_id. @stock_id should be namespaced for your application, + * e.g. "myapp-whatever-icon". Normally applications create a + * #GtkIconFactory, then add it to the list of default factories with + * gtk_icon_factory_add_default(). Then they pass the @stock_id to + * widgets such as #GtkImage to display the icon. Themes can provide + * an icon with the same name (such as "myapp-whatever-icon") to + * override your application's default icons. If an icon already + * existed in @factory for @stock_id, it is unreferenced and replaced + * with the new @icon_set. + * + **/ void gtk_icon_factory_add (GtkIconFactory *factory, const gchar *stock_id, @@ -139,6 +176,19 @@ gtk_icon_factory_add (GtkIconFactory *factory, gtk_icon_set_unref (old_value); } +/** + * gtk_icon_factory_lookup: + * @factory: a #GtkIconFactory + * @stock_id: an icon name + * + * Looks up @stock_id in the icon factory, returning an icon set + * if found, otherwise %NULL. For display to the user, you should + * use gtk_style_lookup_icon_set() on the #GtkStyle for the + * widget that will display the icon, instead of using this + * function directly, so that themes are taken into account. + * + * Return value: icon set of @stock_id. + **/ GtkIconSet * gtk_icon_factory_lookup (GtkIconFactory *factory, const gchar *stock_id) @@ -152,6 +202,18 @@ gtk_icon_factory_lookup (GtkIconFactory *factory, static GtkIconFactory *gtk_default_icons = NULL; static GSList *default_factories = NULL; +/** + * gtk_icon_factory_add_default: + * @factory: a #GtkIconFactory + * + * Adds an icon factory to the list of icon factories searched by + * gtk_style_lookup_icon_set(). This means that, for example, + * gtk_image_new_from_stock() will be able to find icons in @factory. + * There will normally be an icon factory added for each library or + * application that comes with icons. The default icon factories + * can be overridden by themes. + * + **/ void gtk_icon_factory_add_default (GtkIconFactory *factory) { @@ -162,6 +224,15 @@ gtk_icon_factory_add_default (GtkIconFactory *factory) default_factories = g_slist_prepend (default_factories, factory); } +/** + * gtk_icon_factory_remove_default: + * @factory: a #GtkIconFactory previously added with gtk_icon_factory_add_default() + * + * Removes an icon factory from the list of default icon + * factories. Not normally used; you might use it for a library that + * can be unloaded or shut down. + * + **/ void gtk_icon_factory_remove_default (GtkIconFactory *factory) { @@ -172,6 +243,19 @@ gtk_icon_factory_remove_default (GtkIconFactory *factory) g_object_unref (G_OBJECT (factory)); } +/** + * gtk_icon_factory_lookup_default: + * @stock_id: an icon name + * + * Looks for an icon in the list of default icon factories. For + * display to the user, you should use gtk_style_lookup_icon_set() on + * the #GtkStyle for the widget that will display the icon, instead of + * using this function directly, so that themes are taken into + * account. + * + * + * Return value: a #GtkIconSet, or %NULL + **/ GtkIconSet * gtk_icon_factory_lookup_default (const gchar *stock_id) { @@ -428,6 +512,22 @@ init_icon_sizes (void) } } +/** + * gtk_icon_size_lookup: + * @alias: name of an icon size + * @width: location to store icon width + * @height: location to store icon height + * + * Obtains the pixel size of an icon, normally @alias would be + * #GTK_ICON_SIZE_MENU, #GTK_ICON_SIZE_BUTTON, etc. This function + * isn't normally needed, gtk_widget_render_icon() is the usual + * way to get an icon for rendering, then just look at the size of + * the rendered pixbuf. The rendered pixbuf may not even correspond to + * the width/height returned by gtk_icon_size_lookup(), because themes + * are free to render the pixbuf however they like. + * + * Return value: %TRUE if @alias was known. + **/ gboolean gtk_icon_size_lookup (const gchar *alias, gint *widthp, @@ -453,6 +553,16 @@ gtk_icon_size_lookup (const gchar *alias, return TRUE; } +/** + * gtk_icon_size_register: + * @alias: name of the icon size + * @width: the icon width + * @height: the icon height + * + * Registers a new icon size, along the same lines as #GTK_ICON_SIZE_MENU, + * etc. + * + **/ void gtk_icon_size_register (const gchar *alias, gint width, @@ -467,6 +577,15 @@ gtk_icon_size_register (const gchar *alias, icon_size_add (alias, width, height); } +/** + * gtk_icon_size_register_alias: + * @alias: an alias for @target + * @target: an existing icon size name + * + * Registers @alias as another name for @target, usable when calling + * gtk_icon_size_lookup(). + * + **/ void gtk_icon_size_register_alias (const gchar *alias, const gchar *target) @@ -523,6 +642,21 @@ struct _GtkIconSet static guint cache_serial = 0; +/** + * gtk_icon_set_new: + * + * Creates a new #GtkIconSet. A #GtkIconSet represents a single icon + * in various sizes and widget states. It can provide a #GdkPixbuf + * for a given size and state on request, and automatically caches + * some of the rendered #GdkPixbuf objects. + * + * Normally you would use gtk_widget_render_icon() instead of + * using #GtkIconSet directly. The one case where you'd use + * #GtkIconSet is to create application-specific icon sets to place in + * a #GtkIconFactory. + * + * Return value: a new #GtkIconSet + **/ GtkIconSet* gtk_icon_set_new (void) { @@ -539,6 +673,14 @@ gtk_icon_set_new (void) return icon_set; } +/** + * gtk_icon_set_ref: + * @icon_set: a #GtkIconSet + * + * Increments the reference count on @icon_set + * + * Return value: @icon_set is returned + **/ GtkIconSet* gtk_icon_set_ref (GtkIconSet *icon_set) { @@ -550,6 +692,13 @@ gtk_icon_set_ref (GtkIconSet *icon_set) return icon_set; } +/** + * gtk_icon_set_unref: + * @icon_set: a #GtkIconSet + * + * Decrements the reference count on @icon_set, and frees memory + * if the reference count reaches 0. + **/ void gtk_icon_set_unref (GtkIconSet *icon_set) { @@ -574,6 +723,14 @@ gtk_icon_set_unref (GtkIconSet *icon_set) } } +/** + * gtk_icon_set_copy: + * @icon_set: a #GtkIconSet + * + * Copies @icon_set by value. + * + * Return value: a new #GtkIconSet identical to the first. + **/ GtkIconSet* gtk_icon_set_copy (GtkIconSet *icon_set) { @@ -693,6 +850,24 @@ find_and_prep_icon_source (GtkIconSet *icon_set, return source; } +/** + * gtk_icon_set_render_icon: + * @icon_set: a #GtkIconSet + * @style: a #GtkStyle associated with @widget, or %NULL + * @direction: text direction + * @state: widget state + * @size: icon size + * @widget: widget that will display the icon, or %NULL + * @detail: detail to pass to the theme engine, or %NULL + * + * Renders an icon using gtk_style_render_icon(). In most cases, + * gtk_widget_render_icon() is better, since it automatically + * provides most of the arguments from the current widget settings. + * A %NULL return value is possible if an icon file fails to load + * or the like. + * + * Return value: a #GdkPixbuf to be displayed, or %NULL + **/ GdkPixbuf* gtk_icon_set_render_icon (GtkIconSet *icon_set, GtkStyle *style, @@ -780,6 +955,19 @@ icon_source_compare (gconstpointer ap, gconstpointer bp) return 0; } +/** + * gtk_icon_set_add_source: + * @icon_set: a #GtkIconSet + * @source: a #GtkIconSource + * + * Icon sets have a list of #GtkIconSource, which they use as base + * icons for rendering icons in different states and sizes. Icons are + * scaled, made to look insensitive, etc. in + * gtk_icon_set_render_icon(), but #GtkIconSet needs base images to + * work with. The base images and when to use them are described by + * #GtkIconSource. + * + **/ void gtk_icon_set_add_source (GtkIconSet *icon_set, const GtkIconSource *source) @@ -799,7 +987,15 @@ gtk_icon_set_add_source (GtkIconSet *icon_set, icon_source_compare); } -GtkIconSource * +/** + * gtk_icon_source_copy: + * @source: a #GtkIconSource + * + * Creates a copy of @source; mostly useful for language bindings. + * + * Return value: a new #GtkIconSource + **/ +GtkIconSource* gtk_icon_source_copy (const GtkIconSource *source) { GtkIconSource *copy; @@ -818,6 +1014,13 @@ gtk_icon_source_copy (const GtkIconSource *source) return copy; } +/** + * gtk_icon_source_free: + * @source: a #GtkIconSource + * + * Frees a dynamically-allocated icon source, along with its + * filename, size, and pixbuf fields if those are not %NULL. + **/ void gtk_icon_source_free (GtkIconSource *source) { diff --git a/gtk/gtkimage.c b/gtk/gtkimage.c index c44ad0fe31..53ea859d38 100644 --- a/gtk/gtkimage.c +++ b/gtk/gtkimage.c @@ -105,6 +105,19 @@ gtk_image_destroy (GtkObject *object) } +/** + * gtk_image_new_from_pixmap: + * @pixmap: a #GdkPixmap, or %NULL + * @mask: a #GdkBitmap, or %NULL + * + * Creates a #GtkImage widget displaying @pixmap with a @mask. + * A #GdkImage is a server-side image buffer in the pixel format of the + * current display. The #GtkImage does not assume a reference to the + * pixmap or mask; you still need to unref them if you own references. + * #GtkImage will add its own reference rather than adopting yours. + * + * Return value: a new #GtkImage + **/ GtkWidget* gtk_image_new_from_pixmap (GdkPixmap *pixmap, GdkBitmap *mask) @@ -118,6 +131,20 @@ gtk_image_new_from_pixmap (GdkPixmap *pixmap, return GTK_WIDGET (image); } +/** + * gtk_image_new_from_image: + * @image: a #GdkImage, or %NULL + * @mask: a #GdkBitmap, or %NULL + * + * Creates a #GtkImage widget displaying a @image with a @mask. + * A #GdkImage is a client-side image buffer in the pixel format of the + * current display. + * The #GtkImage does not assume a reference to the + * image or mask; you still need to unref them if you own references. + * #GtkImage will add its own reference rather than adopting yours. + * + * Return value: a new #GtkImage + **/ GtkWidget* gtk_image_new_from_image (GdkImage *gdk_image, GdkBitmap *mask) @@ -131,6 +158,18 @@ gtk_image_new_from_image (GdkImage *gdk_image, return GTK_WIDGET (image); } +/** + * gtk_image_new_from_file: + * @filename: a filename + * + * Creates a new #GtkImage displaying the file @filename. If the + * file isn't found or can't be loaded, the #GtkImage will display + * a "broken image" icon. If you need to detect failures to load + * the file, use gdk_pixbuf_new_from_file() to load the file yourself, + * then create the #GtkImage from the pixbuf. + * + * Return value: a new #GtkImage + **/ GtkWidget* gtk_image_new_from_file (const gchar *filename) { @@ -143,6 +182,17 @@ gtk_image_new_from_file (const gchar *filename) return GTK_WIDGET (image); } +/** + * gtk_image_new_from_pixbuf: + * @pixbuf: a #GdkPixbuf, or %NULL + * + * Creates a new #GtkImage displaying @pixbuf. + * The #GtkImage does not assume a reference to the + * pixbuf; you still need to unref it if you own references. + * #GtkImage will add its own reference rather than adopting yours. + * + * Return value: a new #GtkImage + **/ GtkWidget* gtk_image_new_from_pixbuf (GdkPixbuf *pixbuf) { @@ -155,6 +205,18 @@ gtk_image_new_from_pixbuf (GdkPixbuf *pixbuf) return GTK_WIDGET (image); } +/** + * gtk_image_new_from_stock: + * @stock_id: a stock icon name + * @size: a stock icon size + * + * Creates a #GtkImage displaying a stock icon. Sample stock icon + * names are #GTK_STOCK_ICON_OPEN, #GTK_STOCK_ICON_EXIT. Sample stock sizes + * are #GTK_ICON_SIZE_MENU, #GTK_ICON_SIZE_SMALL_TOOLBAR. If the stock + * icon name isn't known, a "broken image" icon will be displayed instead. + * + * Return value: a new #GtkImage displaying the stock icon + **/ GtkWidget* gtk_image_new_from_stock (const gchar *stock_id, const gchar *size) @@ -168,6 +230,26 @@ gtk_image_new_from_stock (const gchar *stock_id, return GTK_WIDGET (image); } +/** + * gtk_image_new_from_icon_set: + * @icon_set: a #GtkIconSet + * @size: a stock icon size + * + * Creates a #GtkImage displaying an icon set. Sample stock sizes are + * #GTK_ICON_SIZE_MENU, #GTK_ICON_SIZE_SMALL_TOOLBAR. Instead of using + * this function, usually it's better to create a #GtkIconFactory, put + * your icon sets in the icon factory, add the icon factory to the + * list of default factories with gtk_icon_factory_add_default(), and + * then use gtk_image_new_from_stock(). This will allow themes to + * override the icon you ship with your application. + * + * The #GtkImage does not assume a reference to the + * icon set; you still need to unref it if you own references. + * #GtkImage will add its own reference rather than adopting yours. + * + * + * Return value: a new #GtkImage + **/ GtkWidget* gtk_image_new_from_icon_set (GtkIconSet *icon_set, const gchar *size) @@ -181,6 +263,15 @@ gtk_image_new_from_icon_set (GtkIconSet *icon_set, return GTK_WIDGET (image); } +/** + * gtk_image_set_from_pixmap: + * @image: a #GtkImage + * @pixmap: a #GdkPixmap or %NULL + * @mask: a #GdkBitmap or %NULL + * + * See gtk_image_new_from_pixmap() for details. + * + **/ void gtk_image_set_from_pixmap (GtkImage *image, GdkPixmap *pixmap, @@ -222,6 +313,15 @@ gtk_image_set_from_pixmap (GtkImage *image, } } +/** + * gtk_image_set_from_image: + * @image: a #GtkImage + * @gdk_image: a #GdkImage or %NULL + * @mask: a #GdkBitmap or %NULL + * + * See gtk_image_new_from_image() for details. + * + **/ void gtk_image_set_from_image (GtkImage *image, GdkImage *gdk_image, @@ -259,6 +359,14 @@ gtk_image_set_from_image (GtkImage *image, } } +/** + * gtk_image_set_from_file: + * @image: a #GtkImage + * @filename: a filename or %NULL + * + * See gtk_image_new_from_file() for details. + * + **/ void gtk_image_set_from_file (GtkImage *image, const gchar *filename) @@ -283,6 +391,14 @@ gtk_image_set_from_file (GtkImage *image, g_object_unref (G_OBJECT (pixbuf)); } +/** + * gtk_image_set_from_pixbuf: + * @image: a #GtkImage + * @pixbuf: a #GdkPixbuf or %NULL + * + * See gtk_image_new_from_pixbuf() for details. + * + **/ void gtk_image_set_from_pixbuf (GtkImage *image, GdkPixbuf *pixbuf) @@ -308,6 +424,15 @@ gtk_image_set_from_pixbuf (GtkImage *image, } } +/** + * gtk_image_set_from_stock: + * @image: a #GtkImage + * @stock_id: a stock icon name + * @size: a stock icon size + * + * See gtk_image_new_from_stock for details. + * + **/ void gtk_image_set_from_stock (GtkImage *image, const gchar *stock_id, @@ -331,6 +456,15 @@ gtk_image_set_from_stock (GtkImage *image, } } +/** + * gtk_image_set_from_icon_set: + * @image: a #GtkImage + * @icon_set: a #GtkIconSet + * @size: a stock icon size + * + * See gtk_image_new_from_icon_set() for details. + * + **/ void gtk_image_set_from_icon_set (GtkImage *image, GtkIconSet *icon_set, @@ -356,6 +490,16 @@ gtk_image_set_from_icon_set (GtkImage *image, } } +/** + * gtk_image_get_storage_type: + * @image: a #GtkImage + * + * Gets the type of representation being used by the #GtkImage + * to store image data. If the #GtkImage has no image data, + * the return value will be %GTK_IMAGE_EMPTY. + * + * Return value: image representation being used + **/ GtkImageType gtk_image_get_storage_type (GtkImage *image) { @@ -364,6 +508,19 @@ gtk_image_get_storage_type (GtkImage *image) return image->storage_type; } +/** + * gtk_image_get_pixmap: + * @image: a #GtkImage + * @pixmap: location to store the pixmap, or %NULL + * @mask: location to store the mask, or %NULL + * + * Gets the pixmap and mask being displayed by the #GtkImage. + * The storage type of the image must be %GTK_IMAGE_EMPTY or + * %GTK_IMAGE_PIXMAP (see gtk_image_get_storage_type()). + * The caller of this function does not own a reference to the + * returned pixmap and mask. + * + **/ void gtk_image_get_pixmap (GtkImage *image, GdkPixmap **pixmap, @@ -380,6 +537,18 @@ gtk_image_get_pixmap (GtkImage *image, *mask = image->data.pixmap.mask; } +/** + * gtk_image_get_image: + * @image: a #GtkImage + * @gdk_image: return location for a #GtkImage + * @mask: return location for a #GdkBitmap + * + * Gets the #GdkImage and mask being displayed by the #GtkImage. + * The storage type of the image must be %GTK_IMAGE_EMPTY or + * %GTK_IMAGE_IMAGE (see gtk_image_get_storage_type()). + * The caller of this function does not own a reference to the + * returned image and mask. + **/ void gtk_image_get_image (GtkImage *image, GdkImage **gdk_image, @@ -396,6 +565,19 @@ gtk_image_get_image (GtkImage *image, *mask = image->data.image.mask; } +/** + * gtk_image_get_pixbuf: + * @image: a #GtkImage + * + * + * Gets the #GdkPixbuf being displayed by the #GtkImage. + * The storage type of the image must be %GTK_IMAGE_EMPTY or + * %GTK_IMAGE_PIXBUF (see gtk_image_get_storage_type()). + * The caller of this function does not own a reference to the + * returned pixbuf. + * + * Return value: the displayed pixbuf, or %NULL if the image is empty + **/ GdkPixbuf* gtk_image_get_pixbuf (GtkImage *image) { @@ -409,6 +591,19 @@ gtk_image_get_pixbuf (GtkImage *image) return image->data.pixbuf.pixbuf; } +/** + * gtk_image_get_stock: + * @image: a #GtkImage + * @stock_id: place to store a stock icon name + * @size: place to store a stock icon size + * + * Gets the stock icon name and size being displayed by the #GtkImage. + * The storage type of the image must be %GTK_IMAGE_EMPTY or + * %GTK_IMAGE_STOCK (see gtk_image_get_storage_type()). + * The returned strings are owned by the #GtkImage and should not + * be freed. + * + **/ void gtk_image_get_stock (GtkImage *image, gchar **stock_id, @@ -422,12 +617,25 @@ gtk_image_get_stock (GtkImage *image, image->data.stock.stock_id = NULL; if (stock_id) - *stock_id = g_strdup (image->data.stock.stock_id); + *stock_id = image->data.stock.stock_id; if (size) *size = image->data.stock.size; } +/** + * gtk_image_get_icon_set: + * @image: a #GtkImage + * @icon_set: location to store a #GtkIconSet + * @size: location to store a stock icon size + * + * Gets the icon set and size being displayed by the #GtkImage. + * The storage type of the image must be %GTK_IMAGE_EMPTY or + * %GTK_IMAGE_ICON_SET (see gtk_image_get_storage_type()). + * The returned size string is owned by the #GtkImage and should not + * be freed. + * + **/ void gtk_image_get_icon_set (GtkImage *image, GtkIconSet **icon_set, @@ -441,7 +649,7 @@ gtk_image_get_icon_set (GtkImage *image, *icon_set = image->data.icon_set.icon_set; if (size) - *size = g_strdup (image->data.icon_set.size); + *size = image->data.icon_set.size; } GtkWidget* @@ -534,10 +742,10 @@ gtk_image_expose (GtkWidget *widget, break; case GTK_IMAGE_STOCK: - stock_pixbuf = gtk_widget_render_stock_icon (widget, - image->data.stock.stock_id, - image->data.stock.size, - NULL); + stock_pixbuf = gtk_widget_render_icon (widget, + image->data.stock.stock_id, + image->data.stock.size, + NULL); if (stock_pixbuf) { image_bound.width = gdk_pixbuf_get_width (stock_pixbuf); @@ -741,10 +949,10 @@ gtk_image_size_request (GtkWidget *widget, switch (image->storage_type) { case GTK_IMAGE_STOCK: - pixbuf = gtk_widget_render_stock_icon (GTK_WIDGET (image), - image->data.stock.stock_id, - image->data.stock.size, - NULL); + pixbuf = gtk_widget_render_icon (GTK_WIDGET (image), + image->data.stock.stock_id, + image->data.stock.size, + NULL); break; case GTK_IMAGE_ICON_SET: diff --git a/gtk/gtkimage.h b/gtk/gtkimage.h index 266d032e67..0c5da6db62 100644 --- a/gtk/gtkimage.h +++ b/gtk/gtkimage.h @@ -160,7 +160,7 @@ void gtk_image_get_icon_set (GtkImage *image, gchar **size); - +#ifndef GTK_DISABLE_DEPRECATED /* These three are deprecated */ GtkWidget* gtk_image_new (GdkImage *val, @@ -171,7 +171,7 @@ void gtk_image_set (GtkImage *image, void gtk_image_get (GtkImage *image, GdkImage **val, GdkBitmap **mask); - +#endif /* GTK_DISABLE_DEPRECATED */ #ifdef __cplusplus } diff --git a/gtk/gtkinputdialog.h b/gtk/gtkinputdialog.h index e7a7f8131e..a661c0b106 100644 --- a/gtk/gtkinputdialog.h +++ b/gtk/gtkinputdialog.h @@ -24,6 +24,16 @@ * GTK+ at ftp://ftp.gtk.org/pub/gtk/. */ +/* + * NOTE this widget is considered too specialized/little-used for + * GTK+, and will in the future be moved to some other package. If + * your application needs this widget, feel free to use it, as the + * widget does work and is useful in some applications; it's just not + * of general interest. However, we are not accepting new features for + * the widget, and it will eventually move out of the GTK+ + * distribution. + */ + #ifndef __GTK_INPUTDIALOG_H__ #define __GTK_INPUTDIALOG_H__ diff --git a/gtk/gtklabel.c b/gtk/gtklabel.c index 1a0939a37c..95facb2a7b 100644 --- a/gtk/gtklabel.c +++ b/gtk/gtklabel.c @@ -308,7 +308,7 @@ gtk_label_set_markup (GtkLabel *label, } /** - * gtk_label_set_markup: + * gtk_label_set_markup_with_accel: * @label: a #GtkLabel * @str: a markup string (see <link linkend="PangoMarkupFormat">Pango markup format</link>) * @@ -318,6 +318,8 @@ gtk_label_set_markup (GtkLabel *label, * indicating that they represent a keyboard accelerator, and the GDK * keyval for the first underlined accelerator is returned. If there are * no underlines in the text, GDK_VoidSymbol will be returned. + * + * Return value: GDK keyval for accelerator **/ guint gtk_label_set_markup_with_accel (GtkLabel *label, diff --git a/gtk/gtklabel.h b/gtk/gtklabel.h index 04c579c4cb..787ffed50f 100644 --- a/gtk/gtklabel.h +++ b/gtk/gtklabel.h @@ -47,8 +47,6 @@ extern "C" { typedef struct _GtkLabel GtkLabel; typedef struct _GtkLabelClass GtkLabelClass; -typedef struct _GtkLabelWord GtkLabelWord; - struct _GtkLabel { GtkMisc misc; @@ -101,9 +99,11 @@ guint gtk_label_parse_uline (GtkLabel *label, # define gtk_label_set gtk_label_set_text #endif /* GTK_DISABLE_COMPAT_H */ +#ifndef GTK_DISABLE_DEPRECATED /* Deprecated */ void gtk_label_get (GtkLabel *label, char **str); +#endif /* GTK_DISABLE_DEPRECATED */ #ifdef __cplusplus } diff --git a/gtk/gtklayout.h b/gtk/gtklayout.h index 54aa39e714..b0f2004aff 100644 --- a/gtk/gtklayout.h +++ b/gtk/gtklayout.h @@ -106,6 +106,8 @@ void gtk_layout_set_hadjustment (GtkLayout *layout, void gtk_layout_set_vadjustment (GtkLayout *layout, GtkAdjustment *adjustment); + +#ifndef GTK_DISABLE_DEPRECATED /* These disable and enable moving and repainting the scrolling window * of the GtkLayout, respectively. If you want to update the layout's * offsets but do not want it to repaint itself, you should use these @@ -116,6 +118,7 @@ void gtk_layout_set_vadjustment (GtkLayout *layout, */ void gtk_layout_freeze (GtkLayout *layout); void gtk_layout_thaw (GtkLayout *layout); +#endif /* GTK_DISABLE_DEPRECATED */ #ifdef __cplusplus } diff --git a/gtk/gtklist.h b/gtk/gtklist.h index 027930e3a5..e4e15bd94b 100644 --- a/gtk/gtklist.h +++ b/gtk/gtklist.h @@ -24,6 +24,8 @@ * GTK+ at ftp://ftp.gtk.org/pub/gtk/. */ +#ifndef GTK_DISABLE_DEPRECATED + #ifndef __GTK_LIST_H__ #define __GTK_LIST_H__ @@ -142,3 +144,5 @@ void gtk_list_end_drag_selection (GtkList *list); #endif /* __GTK_LIST_H__ */ + +#endif /* GTK_DISABLE_DEPRECATED */ diff --git a/gtk/gtkliststore.c b/gtk/gtkliststore.c index 2191146157..619594894e 100644 --- a/gtk/gtkliststore.c +++ b/gtk/gtkliststore.c @@ -235,12 +235,37 @@ gtk_list_store_init (GtkListStore *list_store) list_store->length = 0; } +/** + * gtk_list_store_new: + * + * Creates a new #GtkListStore. A #GtkListStore implements the + * #GtkTreeModel interface, and stores a linked list of + * rows; each row can have any number of columns. Columns are of uniform type, + * i.e. all cells in a column have the same type such as #G_TYPE_STRING or + * #GDK_TYPE_PIXBUF. Use #GtkListStore to store data to be displayed in a + * #GtkTreeView. + * + * Return value: a new #GtkListStore + **/ GtkListStore * gtk_list_store_new (void) { return GTK_LIST_STORE (gtk_type_new (gtk_list_store_get_type ())); } +/** + * gtk_list_store_new_with_types: + * @n_columns: number of columns in the list store + * @Varargs: pairs of column number and #GType + * + * Creates a new list store as with gtk_list_store_new(), + * simultaneously setting up the columns and column types as with + * gtk_list_store_set_n_columns() and + * gtk_list_store_set_column_type(). + * + * + * Return value: a new #GtkListStore + **/ GtkListStore * gtk_list_store_new_with_types (gint n_columns, ...) @@ -264,6 +289,14 @@ gtk_list_store_new_with_types (gint n_columns, return retval; } +/** + * gtk_list_store_set_n_columns: + * @store: a #GtkListStore + * @n_columns: number of columns + * + * Sets the number of columns in the #GtkListStore. + * + **/ void gtk_list_store_set_n_columns (GtkListStore *list_store, gint n_columns) @@ -293,6 +326,18 @@ gtk_list_store_set_n_columns (GtkListStore *list_store, list_store->n_columns = n_columns; } +/** + * gtk_list_store_set_column_type: + * @store: a #GtkListStore + * @column: column number + * @type: type of the data stored in @column + * + * Supported types include: %G_TYPE_UINT, %G_TYPE_INT, %G_TYPE_UCHAR, + * %G_TYPE_CHAR, %G_TYPE_BOOLEAN, %G_TYPE_POINTER, %G_TYPE_FLOAT, %G_TYPE_STRING, + * %G_TYPE_OBJECT, and %G_TYPE_BOXED, along with subclasses of those types such + * as %GDK_TYPE_PIXBUF. + * + **/ void gtk_list_store_set_column_type (GtkListStore *list_store, gint column, @@ -504,6 +549,19 @@ gtk_list_store_iter_parent (GtkTreeModel *tree_model, /* This is a somewhat inelegant function that does a lot of list * manipulations on it's own. */ + +/** + * gtk_list_store_set_cell: + * @store: a #GtkListStore + * @iter: iterator for the row you're modifying + * @column: column number to modify + * @value: new value for the cell + * + * Sets the data in the cell specified by @iter and @column. + * The type of @value must be convertible to the type of the + * column. + * + **/ void gtk_list_store_set_cell (GtkListStore *list_store, GtkTreeIter *iter, @@ -560,10 +618,20 @@ gtk_list_store_set_cell (GtkListStore *list_store, NULL, iter); } +/** + * gtk_list_store_set_valist: + * @list_store: a #GtkListStore + * @iter: row to set data for + * @var_args: va_list of column/value pairs + * + * See gtk_list_store_set(); this version takes a va_list for + * use by language bindings. + * + **/ void gtk_list_store_set_valist (GtkListStore *list_store, GtkTreeIter *iter, - va_list var_args) + va_list var_args) { gint column; @@ -614,7 +682,7 @@ gtk_list_store_set_valist (GtkListStore *list_store, * * Sets the value of one or more cells in the row referenced by @iter. * The variable argument list should contain integer column numbers, - * each column number followed by the value to be set. For example, + * each column number followed by the value to be set. * The list is terminated by a -1. For example, to set column 0 with type * %G_TYPE_STRING to "Foo", you would write gtk_list_store_set (store, iter, * 0, "Foo", -1). @@ -633,6 +701,16 @@ gtk_list_store_set (GtkListStore *list_store, va_end (var_args); } +/** + * gtk_list_store_get_valist: + * @list_store: a #GtkListStore + * @iter: a row in @list_store + * @var_args: va_list of column/return location pairs + * + * See gtk_list_store_get(), this version takes a va_list for + * language bindings to use. + * + **/ void gtk_list_store_get_valist (GtkListStore *list_store, GtkTreeIter *iter, @@ -675,6 +753,22 @@ gtk_list_store_get_valist (GtkListStore *list_store, } } +/** + * gtk_list_store_get: + * @list_store: a #GtkListStore + * @iter: a row in @list_store + * @Varargs: pairs of column number and value return locations, terminated by -1 + * + * Gets the value of one or more cells in the row referenced by @iter. + * The variable argument list should contain integer column numbers, + * each column number followed by a place to store the value being + * retrieved. The list is terminated by a -1. For example, to get a + * value from column 0 with type %G_TYPE_STRING, you would + * write: gtk_list_store_set (store, iter, 0, &place_string_here, -1), + * where place_string_here is a gchar* to be filled with the string. + * If appropriate, the returned values have to be freed or unreferenced. + * + **/ void gtk_list_store_get (GtkListStore *list_store, GtkTreeIter *iter, @@ -751,6 +845,15 @@ gtk_list_store_remove_silently (GtkListStore *list_store, list_store->stamp ++; } +/** + * gtk_list_store_remove: + * @store: a #GtkListStore + * @iter: a row in @list_store + * + * Removes the given row from the list store, emitting the + * "deleted" signal on #GtkTreeModel. + * + **/ void gtk_list_store_remove (GtkListStore *list_store, GtkTreeIter *iter) @@ -794,6 +897,17 @@ insert_after (GtkListStore *list_store, list_store->length += 1; } +/** + * gtk_list_store_insert: + * @store: a #GtkListStore + * @iter: iterator to initialize with the new row + * @position: position to insert the new row + * + * Creates a new row at @position, initializing @iter to point to the + * new row, and emitting the "inserted" signal from the #GtkTreeModel + * interface. + * + **/ void gtk_list_store_insert (GtkListStore *list_store, GtkTreeIter *iter, @@ -839,6 +953,17 @@ gtk_list_store_insert (GtkListStore *list_store, gtk_tree_path_free (path); } +/** + * gtk_list_store_insert_before: + * @store: a #GtkListStore + * @iter: iterator to initialize with the new row + * @sibling: an existing row + * + * Inserts a new row before @sibling, initializing @iter to point to + * the new row, and emitting the "inserted" signal from the + * #GtkTreeModel interface. + * + **/ void gtk_list_store_insert_before (GtkListStore *list_store, GtkTreeIter *iter, @@ -909,6 +1034,17 @@ gtk_list_store_insert_before (GtkListStore *list_store, gtk_tree_path_free (path); } +/** + * gtk_list_store_insert_after: + * @store: a #GtkListStore + * @iter: iterator to initialize with the new row + * @sibling: an existing row + * + * Inserts a new row after @sibling, initializing @iter to point to + * the new row, and emitting the "inserted" signal from the + * #GtkTreeModel interface. + * + **/ void gtk_list_store_insert_after (GtkListStore *list_store, GtkTreeIter *iter, @@ -952,6 +1088,16 @@ gtk_list_store_insert_after (GtkListStore *list_store, gtk_tree_path_free (path); } +/** + * gtk_list_store_prepend: + * @store: a #GtkListStore + * @iter: iterator to initialize with new row + * + * Prepends a row to @store, initializing @iter to point to the + * new row, and emitting the "inserted" signal on the #GtkTreeModel + * interface for the @store. + * + **/ void gtk_list_store_prepend (GtkListStore *list_store, GtkTreeIter *iter) @@ -983,6 +1129,16 @@ gtk_list_store_prepend (GtkListStore *list_store, gtk_tree_path_free (path); } +/** + * gtk_list_store_append: + * @store: a #GtkListStore + * @iter: iterator to initialize with the new row + * + * Appends a row to @store, initializing @iter to point to the + * new row, and emitting the "inserted" signal on the #GtkTreeModel + * interface for the @store. + * + **/ void gtk_list_store_append (GtkListStore *list_store, GtkTreeIter *iter) diff --git a/gtk/gtkmain.c b/gtk/gtkmain.c index ebb324efb0..a6695a34ec 100644 --- a/gtk/gtkmain.c +++ b/gtk/gtkmain.c @@ -540,6 +540,17 @@ gtk_set_locale (void) return gdk_set_locale (); } +/** + * gtk_get_default_language: + * + * Returns the ISO language code for the default language currently in + * effect. (Note that this can change over the life of an + * application.) The default language is derived from the current + * locale. It determines, for example, whether GTK+ uses the + * right-to-left or left-to-right text direction. + * + * Return value: the default language as an allocated string, must be freed + **/ gchar* gtk_get_default_language (void) { @@ -1304,6 +1315,17 @@ gtk_invoke_input (gpointer data, closure->marshal (NULL, closure->data, 2, args); } +/** + * gtk_get_current_event: + * + * Obtains a copy of the event currently being processed by GTK+. For + * example, if you get a "clicked" signal from #GtkButton, the current + * event will be the #GdkEventButton that triggered the "clicked" + * signal. The returned event must be freed with gdk_event_free(). + * If there is no current event, the function returns %NULL. + * + * Return value: a copy of the current event, or %NULL if no current event. + **/ GdkEvent* gtk_get_current_event (void) { @@ -1330,6 +1352,16 @@ gtk_get_current_event_time (void) return GDK_CURRENT_TIME; } +/** + * gtk_get_current_event_state: + * @state: a location to store the state of the current event + * + * If there is a current event and it has a state field, place + * that state field in @state and return %TRUE, otherwise return + * %FALSE. + * + * Return value: %TRUE if there was a current event and it had a state field + **/ gboolean gtk_get_current_event_state (GdkModifierType *state) { @@ -1344,6 +1376,16 @@ gtk_get_current_event_state (GdkModifierType *state) } } +/** + * gtk_get_event_widget: + * @event: a #GdkEvent + * + * If @event is %NULL or the event was not associated with any widget, + * returns %NULL, otherwise returns the widget that received the event + * originally. + * + * Return value: the widget that originally received @event, or %NULL + **/ GtkWidget* gtk_get_event_widget (GdkEvent *event) { @@ -1386,6 +1428,29 @@ gtk_quit_invoke_function (GtkQuitFunction *quitf) } } +/** + * gtk_propagate_event: + * @widget: a #GtkWidget + * @event: an event + * + * Sends an event to a widget, propagating the event to parent widgets + * if the event remains unhandled. Events received by GTK+ from GDK + * normally begin in gtk_main_do_event(). Depending on the type of + * event, existence of modal dialogs, grabs, etc., the event may be + * propagated; if so, this function is used. gtk_propagate_event() + * calls gtk_widget_event() on each widget it decides to send the + * event to. So gtk_widget_event() is the lowest-level function; it + * simply emits the "event" and possibly an event-specific signal on a + * widget. gtk_propagate_event() is a bit higher-level, and + * gtk_main_do_event() is the highest level. + * + * All that said, you most likely don't want to use any of these + * functions; synthesizing events is rarely needed. Consider asking on + * the mailing list for better ways to achieve your goals. For + * example, use gdk_window_invalidate_rect() or + * gtk_widget_queue_draw() instead of making up expose events. + * + **/ void gtk_propagate_event (GtkWidget *widget, GdkEvent *event) diff --git a/gtk/gtkmain.h b/gtk/gtkmain.h index 0f7651edb1..5701588ea7 100644 --- a/gtk/gtkmain.h +++ b/gtk/gtkmain.h @@ -103,7 +103,9 @@ gboolean gtk_init_check_abi_check (int *argc, #endif +#ifndef GTK_DISABLE_DEPRECATED void gtk_exit (gint error_code); +#endif /* GTK_DISABLE_DEPRECATED */ gchar* gtk_set_locale (void); gchar* gtk_get_default_language (void); gint gtk_events_pending (void); diff --git a/gtk/gtkoldeditable.h b/gtk/gtkoldeditable.h index 5736539477..702332331e 100644 --- a/gtk/gtkoldeditable.h +++ b/gtk/gtkoldeditable.h @@ -24,6 +24,8 @@ * GTK+ at ftp://ftp.gtk.org/pub/gtk/. */ +#ifndef GTK_DISABLE_DEPRECATED + #ifndef __GTK_OLD_EDITABLE_H__ #define __GTK_OLD_EDITABLE_H__ @@ -140,3 +142,5 @@ void gtk_old_editable_changed (GtkOldEditable *old_editable); #endif /* __GTK_OLD_EDITABLE_H__ */ + +#endif /* GTK_DISABLE_DEPRECATED */ diff --git a/gtk/gtkoptionmenu.c b/gtk/gtkoptionmenu.c index 65802151b2..9d9a259968 100644 --- a/gtk/gtkoptionmenu.c +++ b/gtk/gtkoptionmenu.c @@ -256,6 +256,15 @@ gtk_option_menu_set_history (GtkOptionMenu *option_menu, } } +/** + * gtk_option_menu_get_history: + * @option_menu: a #GtkOptionMenu + * + * Retrieves the index of the currently selected menu item. The menu + * items are numbered from top to bottom, starting with 0. + * + * Return value: index of the selected menu item, or -1 if there are no menu items + **/ gint gtk_option_menu_get_history (GtkOptionMenu *option_menu) { diff --git a/gtk/gtkpacker.h b/gtk/gtkpacker.h index a483c9da6d..130e35418f 100644 --- a/gtk/gtkpacker.h +++ b/gtk/gtkpacker.h @@ -27,6 +27,8 @@ * GTK+ at ftp://ftp.gtk.org/pub/gtk/. */ +#ifndef GTK_DISABLE_DEPRECATED + #ifndef __GTK_PACKER_H__ #define __GTK_PACKER_H__ @@ -171,3 +173,5 @@ void gtk_packer_set_default_ipad (GtkPacker *packer, #endif /* __GTK_PACKER_H__ */ + +#endif /* GTK_DISABLE_DEPRECATED */ diff --git a/gtk/gtkpaned.c b/gtk/gtkpaned.c index 483084702b..dba1ebf584 100644 --- a/gtk/gtkpaned.c +++ b/gtk/gtkpaned.c @@ -480,6 +480,14 @@ gtk_paned_forall (GtkContainer *container, (*callback) (paned->child2, callback_data); } +/** + * gtk_paned_get_position: + * @paned: a #GtkPaned widget + * + * Obtains the position of the divider between the two panes. + * + * Return value: position of the divider + **/ gint gtk_paned_get_position (GtkPaned *paned) { @@ -489,6 +497,13 @@ gtk_paned_get_position (GtkPaned *paned) return paned->child1_size; } +/** + * gtk_paned_set_position: + * @paned: a #GtkPaned widget + * @position: pixel position of divider + * + * Sets the position of the divider between the two panes. + **/ void gtk_paned_set_position (GtkPaned *paned, gint position) diff --git a/gtk/gtkpixmap.h b/gtk/gtkpixmap.h index 3e386179ba..652457a416 100644 --- a/gtk/gtkpixmap.h +++ b/gtk/gtkpixmap.h @@ -24,6 +24,8 @@ * GTK+ at ftp://ftp.gtk.org/pub/gtk/. */ +#ifndef GTK_DISABLE_DEPRECATED + #ifndef __GTK_PIXMAP_H__ #define __GTK_PIXMAP_H__ @@ -85,3 +87,5 @@ void gtk_pixmap_set_build_insensitive (GtkPixmap *pixmap, #endif /* __GTK_PIXMAP_H__ */ + +#endif /* GTK_DISABLE_DEPRECATED */ diff --git a/gtk/gtkpreview.h b/gtk/gtkpreview.h index 224ddfce07..0dd5d7fdeb 100644 --- a/gtk/gtkpreview.h +++ b/gtk/gtkpreview.h @@ -24,6 +24,8 @@ * GTK+ at ftp://ftp.gtk.org/pub/gtk/. */ +#ifndef GTK_DISABLE_DEPRECATED + #ifndef __GTK_PREVIEW_H__ #define __GTK_PREVIEW_H__ @@ -141,3 +143,5 @@ void gtk_preview_reset (void); #endif /* __GTK_PREVIEW_H__ */ + +#endif /* GTK_DISABLE_DEPRECATED */ diff --git a/gtk/gtkprogress.h b/gtk/gtkprogress.h index 0764262c5c..00c398c625 100644 --- a/gtk/gtkprogress.h +++ b/gtk/gtkprogress.h @@ -37,6 +37,7 @@ extern "C" { #endif /* __cplusplus */ +#ifndef GTK_DISABLE_DEPRECATED #define GTK_TYPE_PROGRESS (gtk_progress_get_type ()) #define GTK_PROGRESS(obj) (GTK_CHECK_CAST ((obj), GTK_TYPE_PROGRESS, GtkProgress)) @@ -45,6 +46,7 @@ extern "C" { #define GTK_IS_PROGRESS_CLASS(klass) (GTK_CHECK_CLASS_TYPE ((klass), GTK_TYPE_PROGRESS)) #define GTK_PROGRESS_GET_CLASS(obj) (GTK_CHECK_GET_CLASS ((obj), GTK_TYPE_PROGRESS, GtkProgressClass)) +#endif /* GTK_DISABLE_DEPRECATED */ typedef struct _GtkProgress GtkProgress; typedef struct _GtkProgressClass GtkProgressClass; @@ -78,6 +80,8 @@ struct _GtkProgressClass * directly. */ +#ifndef GTK_DISABLE_DEPRECATED + GtkType gtk_progress_get_type (void) G_GNUC_CONST; void gtk_progress_set_show_text (GtkProgress *progress, gint show_text); @@ -106,6 +110,7 @@ gfloat gtk_progress_get_current_percentage (GtkProgress *progress); gfloat gtk_progress_get_percentage_from_value (GtkProgress *progress, gfloat value); +#endif /* GTK_DISABLE_DEPRECATED */ #ifdef __cplusplus } diff --git a/gtk/gtkprogressbar.h b/gtk/gtkprogressbar.h index 71d5713642..b4252960e3 100644 --- a/gtk/gtkprogressbar.h +++ b/gtk/gtkprogressbar.h @@ -115,7 +115,7 @@ GtkWidget* gtk_progress_bar_new (void); * rest deprecated. However, the changes are 100% backward-compatible and * should break no existing code. * - * The following 5 functions are the new programming interface. + * The following 9 functions are the new programming interface. */ void gtk_progress_bar_pulse (GtkProgressBar *pbar); void gtk_progress_bar_set_text (GtkProgressBar *pbar, @@ -135,6 +135,8 @@ gfloat gtk_progress_bar_get_pulse_step (GtkProgressBar *pbar); GtkProgressBarOrientation gtk_progress_bar_get_orientation (GtkProgressBar *pbar); +#ifndef GTK_DISABLE_DEPRECATED + /* Everything below here is deprecated */ GtkWidget* gtk_progress_bar_new_with_adjustment (GtkAdjustment *adjustment); void gtk_progress_bar_set_bar_style (GtkProgressBar *pbar, @@ -152,6 +154,8 @@ void gtk_progress_bar_set_activity_blocks (GtkProgressBar *pbar, void gtk_progress_bar_update (GtkProgressBar *pbar, gfloat percentage); +#endif /* GTK_DISABLE_DEPRECATED */ + #ifdef __cplusplus } #endif /* __cplusplus */ diff --git a/gtk/gtkruler.h b/gtk/gtkruler.h index 2adb80cdb8..f9d4b20892 100644 --- a/gtk/gtkruler.h +++ b/gtk/gtkruler.h @@ -24,6 +24,16 @@ * GTK+ at ftp://ftp.gtk.org/pub/gtk/. */ +/* + * NOTE this widget is considered too specialized/little-used for + * GTK+, and will in the future be moved to some other package. If + * your application needs this widget, feel free to use it, as the + * widget does work and is useful in some applications; it's just not + * of general interest. However, we are not accepting new features for + * the widget, and it will eventually move out of the GTK+ + * distribution. + */ + #ifndef __GTK_RULER_H__ #define __GTK_RULER_H__ diff --git a/gtk/gtkscrolledwindow.c b/gtk/gtkscrolledwindow.c index af5d485140..8ffd505e82 100644 --- a/gtk/gtkscrolledwindow.c +++ b/gtk/gtkscrolledwindow.c @@ -470,6 +470,15 @@ gtk_scrolled_window_set_placement (GtkScrolledWindow *scrolled_window, } } +/** + * gtk_scrolled_window_set_shadow_type: + * @scrolled_window: a #GtkScrolledWindow + * @type: kind of shadow to draw around scrolled window contents + * + * Changes the type of shadow drawn around the contents of + * @scrolled_window. + * + **/ void gtk_scrolled_window_set_shadow_type (GtkScrolledWindow *scrolled_window, GtkShadowType type) diff --git a/gtk/gtkstatusbar.c b/gtk/gtkstatusbar.c index 1c0d343775..9f2be1b62f 100644 --- a/gtk/gtkstatusbar.c +++ b/gtk/gtkstatusbar.c @@ -30,6 +30,14 @@ #include "gtksignal.h" #include "gtkstatusbar.h" +typedef struct _GtkStatusbarMsg GtkStatusbarMsg; + +struct _GtkStatusbarMsg +{ + gchar *text; + guint context_id; + guint message_id; +}; enum { diff --git a/gtk/gtkstatusbar.h b/gtk/gtkstatusbar.h index ccfc2c244e..e29d796b60 100644 --- a/gtk/gtkstatusbar.h +++ b/gtk/gtkstatusbar.h @@ -45,7 +45,6 @@ extern "C" { typedef struct _GtkStatusbar GtkStatusbar; typedef struct _GtkStatusbarClass GtkStatusbarClass; -typedef struct _GtkStatusbarMsg GtkStatusbarMsg; struct _GtkStatusbar { @@ -75,12 +74,6 @@ struct _GtkStatusbarClass const gchar *text); }; -struct _GtkStatusbarMsg -{ - gchar *text; - guint context_id; - guint message_id; -}; GtkType gtk_statusbar_get_type (void) G_GNUC_CONST; GtkWidget* gtk_statusbar_new (void); diff --git a/gtk/gtkstock.c b/gtk/gtkstock.c index 64700232aa..60f3e9d6a8 100644 --- a/gtk/gtkstock.c +++ b/gtk/gtkstock.c @@ -65,6 +65,19 @@ real_add (const GtkStockItem *items, } } +/** + * gtk_stock_add: + * @items: a #GtkStockItem or array of items + * @n_items: number of #GtkStockItem in @items + * + * Registers each of the stock items in @items. If an item already + * exists with the same stock ID as one of the @items, the old item + * gets replaced. The stock items are copied, so GTK+ does not hold + * any pointer into @items and @items can be freed. Use + * gtk_stock_add_static() if @items is persistent and GTK+ need not + * copy the array. + * + **/ void gtk_stock_add (const GtkStockItem *items, guint n_items) @@ -74,6 +87,15 @@ gtk_stock_add (const GtkStockItem *items, real_add (items, n_items, TRUE); } +/** + * gtk_stock_add_static: + * @items: a #GtkStockItem or array of #GtkStockItem + * @n_items: number of items + * + * Same as gtk_stock_add(), but doesn't copy @items, so + * @items must persist until application exit. + * + **/ void gtk_stock_add_static (const GtkStockItem *items, guint n_items) @@ -83,6 +105,17 @@ gtk_stock_add_static (const GtkStockItem *items, real_add (items, n_items, FALSE); } +/** + * gtk_stock_lookup: + * @stock_id: a stock item name + * @item: stock item to initialize with values + * + * Fills @item with the registered values for @stock_id, returning %TRUE + * if @stock_id was known. + * + * + * Return value: %TRUE if @item was initialized + **/ gboolean gtk_stock_lookup (const gchar *stock_id, GtkStockItem *item) @@ -124,6 +157,15 @@ g_hash_table_get_values (GHashTable *table) return list; } +/** + * gtk_stock_list_items: + * + * Retrieves a list of all known #GtkStockItem. The items are not copied; + * they should not be freed. However, the list itself must be freed + * with g_slist_free(). + * + * Return value: a list of registered stock items + **/ GSList * gtk_stock_list_items (void) { @@ -132,6 +174,14 @@ gtk_stock_list_items (void) return g_hash_table_get_values (stock_hash); } +/** + * gtk_stock_item_copy: + * @item: a #GtkStockItem + * + * Copies a stock item, mostly useful for language bindings and not in applications. + * + * Return value: a new #GtkStockItem + **/ GtkStockItem * gtk_stock_item_copy (const GtkStockItem *item) { @@ -150,6 +200,15 @@ gtk_stock_item_copy (const GtkStockItem *item) return copy; } +/** + * gtk_stock_item_free: + * @item: a #GtkStockItem + * + * Frees a stock item allocated on the heap, such as one returned by + * gtk_stock_item_copy(). Also frees the fields inside the stock item, + * if they are not %NULL. + * + **/ void gtk_stock_item_free (GtkStockItem *item) { diff --git a/gtk/gtkstock.h b/gtk/gtkstock.h index a11fa95154..d40cb95602 100644 --- a/gtk/gtkstock.h +++ b/gtk/gtkstock.h @@ -45,9 +45,9 @@ struct _GtkStockItem gchar *translation_domain; }; -void gtk_stock_add (const GtkStockItem *item, +void gtk_stock_add (const GtkStockItem *items, guint n_items); -void gtk_stock_add_static (const GtkStockItem *item, +void gtk_stock_add_static (const GtkStockItem *items, guint n_items); gboolean gtk_stock_lookup (const gchar *stock_id, GtkStockItem *item); diff --git a/gtk/gtkstyle.h b/gtk/gtkstyle.h index fff657cd71..d52248ae4d 100644 --- a/gtk/gtkstyle.h +++ b/gtk/gtkstyle.h @@ -461,12 +461,14 @@ void gtk_draw_diamond (GtkStyle *style, gint y, gint width, gint height); +#ifndef GTK_DISABLE_DEPRECATED void gtk_draw_string (GtkStyle *style, GdkWindow *window, GtkStateType state_type, gint x, gint y, const gchar *string); +#endif /* GTK_DISABLE_DEPRECATED */ void gtk_draw_box (GtkStyle *style, GdkWindow *window, GtkStateType state_type, @@ -638,6 +640,7 @@ void gtk_paint_diamond (GtkStyle *style, gint y, gint width, gint height); +#ifndef GTK_DISABLE_DEPRECATED void gtk_paint_string (GtkStyle *style, GdkWindow *window, GtkStateType state_type, @@ -647,6 +650,7 @@ void gtk_paint_string (GtkStyle *style, gint x, gint y, const gchar *string); +#endif /* GTK_DISABLE_DEPRECATED */ void gtk_paint_box (GtkStyle *style, GdkWindow *window, GtkStateType state_type, diff --git a/gtk/gtktextbtree.c b/gtk/gtktextbtree.c index 3e9d1648fb..db30bd9b5c 100644 --- a/gtk/gtktextbtree.c +++ b/gtk/gtktextbtree.c @@ -2705,6 +2705,18 @@ _gtk_text_btree_get_mark_by_name (GtkTextBTree *tree, return seg ? seg->body.mark.obj : NULL; } +/** + * gtk_text_mark_set_visible: + * @mark: a #GtkTextMark + * @setting: visibility of mark + * + * Sets the visibility of @mark; the insertion point is normally + * visible, i.e. you can see it as a vertical bar. Also, the text + * widget uses a visible mark to indicate where a drop will occur when + * dragging-and-dropping text. Most other marks are not visible. + * Marks are not visible by default. + * + **/ void gtk_text_mark_set_visible (GtkTextMark *mark, gboolean setting) diff --git a/gtk/gtktextbuffer.c b/gtk/gtktextbuffer.c index a2c13ac0d3..1a4ccdb1f0 100644 --- a/gtk/gtktextbuffer.c +++ b/gtk/gtktextbuffer.c @@ -1394,6 +1394,22 @@ gtk_text_buffer_real_insert_pixbuf (GtkTextBuffer *buffer, g_signal_emit (G_OBJECT (buffer), signals[CHANGED], 0); } +/** + * gtk_text_buffer_insert_pixbuf: + * @buffer: a #GtkTextBuffer + * @iter: location to insert the pixbuf + * @pixbuf: a #GdkPixbuf + * + * Inserts an image into the text buffer at @iter. The image will be + * counted as one character in character counts, and when obtaining + * the buffer contents as a string, will be represented by the Unicode + * "object replacement character" 0xFFFC. Note that the "slice" + * variants for obtaining portions of the buffer as a string include + * this character for pixbufs, but the "text" variants do + * not. e.g. see gtk_text_buffer_get_slice() and + * gtk_text_buffer_get_text(). + * + **/ void gtk_text_buffer_insert_pixbuf (GtkTextBuffer *buffer, GtkTextIter *iter, @@ -1889,6 +1905,18 @@ gtk_text_buffer_emit_tag (GtkTextBuffer *buffer, } +/** + * gtk_text_buffer_apply_tag: + * @buffer: a #GtkTextBuffer + * @tag: a #GtkTextTag + * @start: one bound of range to be tagged + * @end: other bound of range to be tagged + * + * Emits the "apply_tag" signal on @buffer. The default + * handler for the signal applies @tag to the given range. + * @start and @end do not have to be in order. + * + **/ void gtk_text_buffer_apply_tag (GtkTextBuffer *buffer, GtkTextTag *tag, @@ -1903,6 +1931,18 @@ gtk_text_buffer_apply_tag (GtkTextBuffer *buffer, gtk_text_buffer_emit_tag (buffer, tag, TRUE, start, end); } +/** + * gtk_text_buffer_remove_tag: + * @buffer: a #GtkTextBuffer + * @tag: a #GtkTextTag + * @start: one bound of range to be untagged + * @end: other bound of range to be untagged + * + * Emits the "remove_tag" signal. The default handler for the signal + * removes all occurrences of @tag from the given range. @start and + * @end don't have to be in order. + * + **/ void gtk_text_buffer_remove_tag (GtkTextBuffer *buffer, GtkTextTag *tag, @@ -1919,9 +1959,20 @@ gtk_text_buffer_remove_tag (GtkTextBuffer *buffer, } +/** + * gtk_text_buffer_apply_tag_by_name: + * @buffer: a #GtkTextBuffer + * @name: name of a named #GtkTextTag + * @start: one bound of range to be tagged + * @end: other bound of range to be tagged + * + * Calls gtk_text_tag_table_lookup() on the buffer's tag table to + * get a #GtkTextTag, then calls gtk_text_buffer_apply_tag(). + * + **/ void gtk_text_buffer_apply_tag_by_name (GtkTextBuffer *buffer, - const gchar *name, + const gchar *name, const GtkTextIter *start, const GtkTextIter *end) { @@ -1944,6 +1995,18 @@ gtk_text_buffer_apply_tag_by_name (GtkTextBuffer *buffer, gtk_text_buffer_emit_tag (buffer, tag, TRUE, start, end); } +/** + * gtk_text_buffer_remove_tag_by_name: + * @buffer: a #GtkTextBuffer + * @name: name of a #GtkTextTag + * @start: one bound of range to be untagged + * @end: other bound of range to be untagged + * + * Calls gtk_text_tag_table_lookup() on the buffer's tag table to + * get a #GtkTextTag, then calls gtk_text_buffer_remove_tag(). + * + * + **/ void gtk_text_buffer_remove_tag_by_name (GtkTextBuffer *buffer, const gchar *name, @@ -1974,6 +2037,19 @@ gtk_text_buffer_remove_tag_by_name (GtkTextBuffer *buffer, * Obtain various iterators */ +/** + * gtk_text_buffer_get_iter_at_line_offset: + * @buffer: a #GtkTextBuffer + * @iter: iterator to initialize + * @line_number: line number counting from 0 + * @char_offset: char offset from start of line + * + * Obtains an iterator pointing to @char_offset within the given + * line. The @char_offset must exist, offsets off the end of the line + * are not allowed. Note <emphasis>characters</emphasis>, not bytes; + * UTF-8 may encode one character as multiple bytes. + * + **/ void gtk_text_buffer_get_iter_at_line_offset (GtkTextBuffer *buffer, GtkTextIter *iter, @@ -1984,9 +2060,22 @@ gtk_text_buffer_get_iter_at_line_offset (GtkTextBuffer *buffer, g_return_if_fail (GTK_IS_TEXT_BUFFER (buffer)); _gtk_text_btree_get_iter_at_line_char (get_btree (buffer), - iter, line_number, char_offset); + iter, line_number, char_offset); } +/** + * gtk_text_buffer_get_iter_at_line_index: + * @buffer: a #GtkTextBuffer + * @iter: iterator to initialize + * @line_number: line number counting from 0 + * @byte_index: byte index from start of line + * + * Obtains an iterator pointing to @byte_index within the given line. + * @byte_index must be the start of a UTF-8 character, and must not be + * beyond the end of the line. Note <emphasis>bytes</emphasis>, not + * characters; UTF-8 may encode one character as multiple bytes. + * + **/ void gtk_text_buffer_get_iter_at_line_index (GtkTextBuffer *buffer, GtkTextIter *iter, @@ -1997,9 +2086,17 @@ gtk_text_buffer_get_iter_at_line_index (GtkTextBuffer *buffer, g_return_if_fail (GTK_IS_TEXT_BUFFER (buffer)); _gtk_text_btree_get_iter_at_line_byte (get_btree (buffer), - iter, line_number, byte_index); + iter, line_number, byte_index); } +/** + * gtk_text_buffer_get_iter_at_line: + * @buffer: a #GtkTextBuffer + * @iter: iterator to initialize + * @line_number: line number counting from 0 + * + * Initializes @iter to the start of the given line. + **/ void gtk_text_buffer_get_iter_at_line (GtkTextBuffer *buffer, GtkTextIter *iter, @@ -2011,6 +2108,16 @@ gtk_text_buffer_get_iter_at_line (GtkTextBuffer *buffer, gtk_text_buffer_get_iter_at_line_offset (buffer, iter, line_number, 0); } +/** + * gtk_text_buffer_get_iter_at_offset: + * @buffer: a #GtkTextBuffer + * @iter: iterator to initialize + * @char_offset: char offset from start of buffer, counting from 0 + * + * Initializes @iter to a position @char_offset chars from the start + * of the entire buffer. + * + **/ void gtk_text_buffer_get_iter_at_offset (GtkTextBuffer *buffer, GtkTextIter *iter, @@ -2022,6 +2129,19 @@ gtk_text_buffer_get_iter_at_offset (GtkTextBuffer *buffer, _gtk_text_btree_get_iter_at_char (get_btree (buffer), iter, char_offset); } +/** + * gtk_text_buffer_get_last_iter: + * @buffer: a #GtkTextBuffer + * @iter: iterator to initialize + * + * Initializes @iter with the "end iterator," one past the last valid + * character in the text buffer. If dereferenced with + * gtk_text_iter_get_char(), the end iterator has a character value of + * 0. The entire buffer lies in the range from the first position in + * the buffer (call gtk_text_buffer_get_iter_at_offset() to get + * character position 0) to the end iterator. + * + **/ void gtk_text_buffer_get_last_iter (GtkTextBuffer *buffer, GtkTextIter *iter) @@ -2032,6 +2152,16 @@ gtk_text_buffer_get_last_iter (GtkTextBuffer *buffer, _gtk_text_btree_get_last_iter (get_btree (buffer), iter); } +/** + * gtk_text_buffer_get_bounds: + * @buffer: a #GtkTextBuffer + * @start: iterator to initialize with first position in the buffer + * @end: iterator to initialize with the end iterator + * + * Retrieves the first and last iterators in the buffer, i.e. the + * entire buffer lies within the range [@start,@end). + * + **/ void gtk_text_buffer_get_bounds (GtkTextBuffer *buffer, GtkTextIter *start, @@ -2049,6 +2179,17 @@ gtk_text_buffer_get_bounds (GtkTextBuffer *buffer, * Modified flag */ +/** + * gtk_text_buffer_modified: + * @buffer: a #GtkTextBuffer + * + * Indicates whether the buffer has been modified since the last call + * to gtk_text_buffer_set_modified() set the modification flag to + * %FALSE. Used for example to enable a "save" function in a text + * editor. + * + * Return value: %TRUE if the buffer has been modified + **/ gboolean gtk_text_buffer_modified (GtkTextBuffer *buffer) { @@ -2057,6 +2198,18 @@ gtk_text_buffer_modified (GtkTextBuffer *buffer) return buffer->modified; } +/** + * gtk_text_buffer_set_modified: + * @buffer: a #GtkTextBuffer + * @setting: modification flag setting + * + * Used to keep track of whether the buffer has been modified since the + * last time it was saved. Whenever the buffer is saved to disk, call + * gtk_text_buffer_set_modified (@buffer, FALSE). When the buffer is modified, + * it will automatically toggled on the modified bit again. When the modified + * bit flips, the buffer emits a "modified_changed" signal. + * + **/ void gtk_text_buffer_set_modified (GtkTextBuffer *buffer, gboolean setting) @@ -2081,6 +2234,15 @@ gtk_text_buffer_set_modified (GtkTextBuffer *buffer, * Assorted other stuff */ +/** + * gtk_text_buffer_get_line_count: + * @buffer: a #GtkTextBuffer + * + * Obtains the number of lines in the buffer. This value is cached, so + * the function is very fast. + * + * Return value: number of lines in the buffer + **/ gint gtk_text_buffer_get_line_count (GtkTextBuffer *buffer) { @@ -2089,6 +2251,17 @@ gtk_text_buffer_get_line_count (GtkTextBuffer *buffer) return _gtk_text_btree_line_count (get_btree (buffer)); } +/** + * gtk_text_buffer_get_char_count: + * @buffer: a #GtkTextBuffer + * + * Gets the number of characters in the buffer; note that characters + * and bytes are not the same, you can't e.g. expect the contents of + * the buffer in string form to be this many bytes long. The character + * count is cached, so this function is very fast. + * + * Return value: number of characters in the buffer + **/ gint gtk_text_buffer_get_char_count (GtkTextBuffer *buffer) { @@ -2539,6 +2712,17 @@ paste (GtkTextBuffer *buffer, clipboard_selection_buffer_received, data); } +/** + * gtk_text_buffer_paste_primary: + * @buffer: a #GtkTextBuffer + * @override_location: location to insert pasted text, or %NULL for at the cursor + * @default_editable: whether the buffer is editable by default + * + * Pastes the primary selection at the insertion point, or at @override_location. + * (Note: pasting is asynchronous, that is, we'll ask for the paste data + * and return, and at some point later after the main loop runs, the paste + * data will be inserted.) + **/ void gtk_text_buffer_paste_primary (GtkTextBuffer *buffer, const GtkTextIter *override_location, @@ -2552,6 +2736,17 @@ gtk_text_buffer_paste_primary (GtkTextBuffer *buffer, paste (buffer, FALSE, TRUE, default_editable); } +/** + * gtk_text_buffer_paste_clipboard: + * @buffer: a #GtkTextBuffer + * @default_editable: whether the buffer is editable by default + * + * Pastes the clipboard contents at the insertion point. (Note: + * pasting is asynchronous, that is, we'll ask for the paste data and + * return, and at some point later after the main loop runs, the paste + * data will be inserted.) + * + **/ void gtk_text_buffer_paste_clipboard (GtkTextBuffer *buffer, gboolean default_editable) @@ -2559,6 +2754,19 @@ gtk_text_buffer_paste_clipboard (GtkTextBuffer *buffer, paste (buffer, TRUE, TRUE, default_editable); } +/** + * gtk_text_buffer_delete_selection: + * @buffer: a #GtkTextBuffer + * @interactive: whether the deletion is caused by user interaction + * @default_editable: whether the buffer is editable by default + * + * Deletes the range between the "insert" and "selection_bound" marks, + * that is, the currently-selected text. If @interactive is %TRUE, + * the editability of the selection will be considered (users can't delete + * uneditable text). + * + * Return value: whether there was a non-empty selection to delete + **/ gboolean gtk_text_buffer_delete_selection (GtkTextBuffer *buffer, gboolean interactive, @@ -2655,6 +2863,15 @@ cut_or_copy (GtkTextBuffer *buffer, } } +/** + * gtk_text_buffer_cut_clipboard: + * @buffer: a #GtkTextBuffer + * @default_editable: default editability of the buffer + * + * Copies the currently-selected text to the clipboard, then deletes + * said text if it's editable. + * + **/ void gtk_text_buffer_cut_clipboard (GtkTextBuffer *buffer, gboolean default_editable) @@ -2664,6 +2881,13 @@ gtk_text_buffer_cut_clipboard (GtkTextBuffer *buffer, gtk_text_buffer_end_user_action (buffer); } +/** + * gtk_text_buffer_copy_clipboard: + * @buffer: a #GtkTextBuffer + * + * Copies the currently-selected text to the clipboard. + * + **/ void gtk_text_buffer_copy_clipboard (GtkTextBuffer *buffer) { @@ -2675,7 +2899,7 @@ gtk_text_buffer_copy_clipboard (GtkTextBuffer *buffer) /** * gtk_text_buffer_get_selection_bounds: - * @buffer: a #GtkTextBuffer + * @buffer: a #GtkTextBuffer a #GtkTextBuffer * @start: iterator to initialize with selection start * @end: iterator to initialize with selection end * @@ -2715,9 +2939,9 @@ gtk_text_buffer_get_selection_bounds (GtkTextBuffer *buffer, * * The "interactive" buffer mutation functions, such as * gtk_text_buffer_insert_interactive(), automatically call begin/end - * user action around the buffer operations they perform, so there's no - * need to add extra calls if you user action consists solely of those - * functions. + * user action around the buffer operations they perform, so there's + * no need to add extra calls if you user action consists solely of a + * single call to one of those functions. **/ void gtk_text_buffer_begin_user_action (GtkTextBuffer *buffer) diff --git a/gtk/gtktextbuffer.h b/gtk/gtktextbuffer.h index ae7f7570ce..88bf91190b 100644 --- a/gtk/gtktextbuffer.h +++ b/gtk/gtktextbuffer.h @@ -252,20 +252,20 @@ void gtk_text_buffer_place_cursor (GtkTextBuffer *buffer, /* Tag manipulation */ void gtk_text_buffer_apply_tag (GtkTextBuffer *buffer, GtkTextTag *tag, - const GtkTextIter *start_index, - const GtkTextIter *end_index); + const GtkTextIter *start, + const GtkTextIter *end); void gtk_text_buffer_remove_tag (GtkTextBuffer *buffer, GtkTextTag *tag, - const GtkTextIter *start_index, - const GtkTextIter *end_index); + const GtkTextIter *start, + const GtkTextIter *end); void gtk_text_buffer_apply_tag_by_name (GtkTextBuffer *buffer, const gchar *name, - const GtkTextIter *start_index, - const GtkTextIter *end_index); + const GtkTextIter *start, + const GtkTextIter *end); void gtk_text_buffer_remove_tag_by_name (GtkTextBuffer *buffer, const gchar *name, - const GtkTextIter *start_index, - const GtkTextIter *end_index); + const GtkTextIter *start, + const GtkTextIter *end); /* You can either ignore the return value, or use it to diff --git a/gtk/gtktextiter.c b/gtk/gtktextiter.c index 549dcb2179..c216d4ca3c 100644 --- a/gtk/gtktextiter.c +++ b/gtk/gtktextiter.c @@ -264,6 +264,13 @@ iter_init_from_byte_offset (GtkTextIter *iter, iter_set_from_byte_offset (real, line, line_byte_offset); + if (real->segment->type == >k_text_char_type && + (real->segment->body.chars[real->segment_byte_offset] & 0xc0) == 0x80) + g_warning ("Incorrect line byte index %d falls in the middle of a UTF-8 " + "character; this will crash the text buffer. " + "Byte indexes must refer to the start of a character.", + line_byte_offset); + return real; } @@ -2699,12 +2706,36 @@ find_by_log_attrs (GtkTextIter *iter, } } +/** + * gtk_text_iter_forward_word_end: + * @iter: a #GtkTextIter + * + * Moves forward to the next word end. (If @iter is currently on a + * word end, moves forward to the next one after that.) Word breaks + * are determined by Pango and should be correct for nearly any + * language (if not, the correct fix would be to the Pango word break + * algorithms). + * + * Return value: %TRUE if @iter moved and is not the end iterator + **/ gboolean gtk_text_iter_forward_word_end (GtkTextIter *iter) { return find_by_log_attrs (iter, find_word_end_func, TRUE, FALSE); } +/** + * gtk_text_iter_forward_word_end: + * @iter: a #GtkTextIter + * + * Moves backward to the next word start. (If @iter is currently on a + * word start, moves backward to the next one after that.) Word breaks + * are determined by Pango and should be correct for nearly any + * language (if not, the correct fix would be to the Pango word break + * algorithms). + * + * Return value: %TRUE if @iter moved and is not the end iterator + **/ gboolean gtk_text_iter_backward_word_start (GtkTextIter *iter) { @@ -2714,6 +2745,16 @@ gtk_text_iter_backward_word_start (GtkTextIter *iter) /* FIXME a loop around a truly slow function means * a truly spectacularly slow function. */ + +/** + * gtk_text_iter_forward_word_ends: + * @iter: a #GtkTextIter + * @count: number of times to move + * + * Calls gtk_text_iter_forward_word_end() up to @count times. + * + * Return value: %TRUE if @iter moved and is not the end iterator + **/ gboolean gtk_text_iter_forward_word_ends (GtkTextIter *iter, gint count) @@ -2739,6 +2780,15 @@ gtk_text_iter_forward_word_ends (GtkTextIter *iter, return TRUE; } +/** + * gtk_text_iter_backward_word_starts + * @iter: a #GtkTextIter + * @count: number of times to move + * + * Calls gtk_text_iter_backward_word_starts() up to @count times. + * + * Return value: %TRUE if @iter moved and is not the end iterator + **/ gboolean gtk_text_iter_backward_word_starts (GtkTextIter *iter, gint count) @@ -2761,48 +2811,139 @@ gtk_text_iter_backward_word_starts (GtkTextIter *iter, return TRUE; } +/** + * gtk_text_iter_starts_word: + * @iter: a #GtkTextIter + * + * Determines whether @iter begins a natural-language word. Word + * breaks are determined by Pango and should be correct for nearly any + * language (if not, the correct fix would be to the Pango word break + * algorithms). + * + * Return value: %TRUE if @iter is at the start of a word + **/ gboolean gtk_text_iter_starts_word (const GtkTextIter *iter) { return test_log_attrs (iter, is_word_start_func); } +/** + * gtk_text_iter_ends_word: + * @iter: a #GtkTextIter + * + * Determines whether @iter ends a natural-language word. Word breaks + * are determined by Pango and should be correct for nearly any + * language (if not, the correct fix would be to the Pango word break + * algorithms). + * + * Return value: %TRUE if @iter is at the end of a word + **/ gboolean gtk_text_iter_ends_word (const GtkTextIter *iter) { return test_log_attrs (iter, is_word_end_func); } +/** + * gtk_text_iter_inside_word: + * @iter: a #GtkTextIter + * + * Determines whether @iter is inside a natural-language word (as + * opposed to say inside some whitespace). Word breaks are determined + * by Pango and should be correct for nearly any language (if not, the + * correct fix would be to the Pango word break algorithms). + * + * Return value: %TRUE if @iter is inside a word + **/ gboolean gtk_text_iter_inside_word (const GtkTextIter *iter) { return test_log_attrs (iter, inside_word_func); } +/** + * gtk_text_iter_starts_sentence: + * @iter: a #GtkTextIter + * + * Determines whether @iter begins a sentence. Sentence boundaries are + * determined by Pango and should be correct for nearly any language + * (if not, the correct fix would be to the Pango text boundary + * algorithms). + * + * Return value: %TRUE if @iter is at the start of a sentence. + **/ gboolean gtk_text_iter_starts_sentence (const GtkTextIter *iter) { return test_log_attrs (iter, is_sentence_start_func); } +/** + * gtk_text_iter_ends_sentence: + * @iter: a #GtkTextIter + * + * Determines whether @iter ends a sentence. Sentence boundaries are + * determined by Pango and should be correct for nearly any language + * (if not, the correct fix would be to the Pango text boundary + * algorithms). + * + * Return value: %TRUE if @iter is at the end of a sentence. + **/ gboolean gtk_text_iter_ends_sentence (const GtkTextIter *iter) { return test_log_attrs (iter, is_sentence_end_func); } +/** + * gtk_text_iter_inside_sentence: + * @iter: a #GtkTextIter + * + * Determines whether @iter is inside a sentence (as opposed to in + * between two sentences, e.g. after a period and before the first + * letter of the next sentence). Sentence boundaries are determined + * by Pango and should be correct for nearly any language (if not, the + * correct fix would be to the Pango text boundary algorithms). + * + * Return value: %TRUE if @iter is inside a sentence. + **/ gboolean gtk_text_iter_inside_sentence (const GtkTextIter *iter) { return test_log_attrs (iter, inside_sentence_func); } +/** + * gtk_text_iter_forward_sentence_end: + * @iter: a #GtkTextIter + * + * Moves forward to the next sentence end. (If @iter is at the end of + * a sentence, moves to the next end of sentence.) Sentence + * boundaries are determined by Pango and should be correct for nearly + * any language (if not, the correct fix would be to the Pango text + * boundary algorithms). + * + * Return value: %TRUE if @iter moved and is not the end iterator + **/ gboolean gtk_text_iter_forward_sentence_end (GtkTextIter *iter) { return find_by_log_attrs (iter, find_sentence_end_func, TRUE, FALSE); } +/** + * gtk_text_iter_backward_sentence_start: + * @iter: a #GtkTextIter + * + * Moves backward to the next sentence start; if @iter is already at + * the start of a sentence, moves backward to the next one. Sentence + * boundaries are determined by Pango and should be correct for nearly + * any language (if not, the correct fix would be to the Pango text + * boundary algorithms). + * + * Return value: %TRUE if @iter moved and is not the end iterator + **/ gboolean gtk_text_iter_backward_sentence_start (GtkTextIter *iter) { @@ -2812,6 +2953,15 @@ gtk_text_iter_backward_sentence_start (GtkTextIter *iter) /* FIXME a loop around a truly slow function means * a truly spectacularly slow function. */ +/** + * gtk_text_iter_forward_sentence_ends: + * @iter: a #GtkTextIter + * @count: number of sentences to move + * + * Calls gtk_text_iter_forward_sentence_end() up to @count times. + * + * Return value: %TRUE if @iter moved and is not the end iterator + **/ gboolean gtk_text_iter_forward_sentence_ends (GtkTextIter *iter, gint count) @@ -2837,6 +2987,15 @@ gtk_text_iter_forward_sentence_ends (GtkTextIter *iter, return TRUE; } +/** + * gtk_text_iter_forward_sentence_ends: + * @iter: a #GtkTextIter + * @count: number of sentences to move + * + * Calls gtk_text_iter_backward_sentence_start() up to @count times. + * + * Return value: %TRUE if @iter moved and is not the end iterator + **/ gboolean gtk_text_iter_backward_sentence_starts (GtkTextIter *iter, gint count) @@ -2908,18 +3067,53 @@ is_cursor_pos_func (const PangoLogAttr *attrs, return attrs[offset].is_cursor_position; } +/** + * gtk_text_iter_forward_cursor_position: + * @iter: a #GtkTextIter + * + * Moves @iter forward by a single cursor position. Cursor positions + * are (unsurprisingly) positions where the cursor can appear. Perhaps + * surprisingly, there may not be a cursor position between all + * characters. The most common example for European languages would be + * a carriage return/newline sequence. For some Unicode characters, + * the equivalent of say the letter "a" with an accent mark will be + * represented as two characters, first the letter then a "combining + * mark" that causes the accent to be rendered; so the cursor can't go + * between those two characters. See also the #PangoLogAttr structure and + * pango_break() function. + * + * Return value: %TRUE if we moved and the new position is dereferenceable + **/ gboolean gtk_text_iter_forward_cursor_position (GtkTextIter *iter) { return find_by_log_attrs (iter, find_forward_cursor_pos_func, TRUE, FALSE); } +/** + * gtk_text_iter_backward_cursor_position: + * @iter: a #GtkTextIter + * + * Like gtk_text_iter_forward_cursor_position(), but moves backward. + * + * Return value: %TRUE if we moved and the new position is dereferenceable + **/ gboolean gtk_text_iter_backward_cursor_position (GtkTextIter *iter) { return find_by_log_attrs (iter, find_backward_cursor_pos_func, FALSE, FALSE); } +/** + * gtk_text_iter_forward_cursor_positions: + * @iter: a #GtkTextIter + * @count: number of positions to move + * + * Moves up to @count cursor positions. See + * gtk_text_iter_forward_cursor_position() for details. + * + * Return value: %TRUE if we moved and the new position is dereferenceable + **/ gboolean gtk_text_iter_forward_cursor_positions (GtkTextIter *iter, gint count) @@ -2945,6 +3139,16 @@ gtk_text_iter_forward_cursor_positions (GtkTextIter *iter, return TRUE; } +/** + * gtk_text_iter_backward_cursor_positions: + * @iter: a #GtkTextIter + * @count: number of positions to move + * + * Moves up to @count cursor positions. See + * gtk_text_iter_forward_cursor_position() for details. + * + * Return value: %TRUE if we moved and the new position is dereferenceable + **/ gboolean gtk_text_iter_backward_cursor_positions (GtkTextIter *iter, gint count) @@ -2970,12 +3174,34 @@ gtk_text_iter_backward_cursor_positions (GtkTextIter *iter, return TRUE; } +/** + * gtk_text_iter_is_cursor_position: + * @iter: a #GtkTextIter + * + * See gtk_text_iter_forward_cursor_position() or #PangoLogAttr or + * pango_break() for details on what a cursor position is. + * + * Return value: %TRUE if the cursor can be placed at @iter + **/ gboolean gtk_text_iter_is_cursor_position (const GtkTextIter *iter) { return test_log_attrs (iter, is_cursor_pos_func); } +/** + * gtk_text_iter_set_line_offset: + * @iter: a #GtkTextIter + * @char_on_line: a character offset relative to the start of @iter's current line + * + * Moves @iter within a line, to a new <emphasis>character</emphasis> + * (not byte) offset. The given character offset must be less than or + * equal to the number of characters in the line; if equal, @iter + * moves to the start of the next line. See + * gtk_text_iter_set_line_index() if you have a byte index rather than + * a character offset. + * + **/ void gtk_text_iter_set_line_offset (GtkTextIter *iter, gint char_on_line) @@ -3004,6 +3230,17 @@ gtk_text_iter_set_line_offset (GtkTextIter *iter, check_invariants (iter); } +/** + * gtk_text_iter_set_line_index: + * @iter: a #GtkTextIter + * @byte_on_line: a byte index relative to the start of @iter's current line + * + * Same as gtk_text_iter_set_line_offset(), but works with a + * <emphasis>byte</emphasis> index. The given byte index must be at + * the start of a character, it can't be in the middle of a UTF-8 + * encoded character. + * + **/ void gtk_text_iter_set_line_index (GtkTextIter *iter, gint byte_on_line) @@ -3039,6 +3276,14 @@ gtk_text_iter_set_line_index (GtkTextIter *iter, check_invariants (iter); } +/** + * gtk_text_iter_set_line: + * @iter: a #GtkTextIter + * @line_number: line number (counted from 0) + * + * Moves iterator @iter to the start of the line @line_number. + * + **/ void gtk_text_iter_set_line (GtkTextIter *iter, gint line_number) @@ -3066,8 +3311,18 @@ gtk_text_iter_set_line (GtkTextIter *iter, check_invariants (iter); } +/** + * gtk_text_iter_set_offset: + * @iter: a #GtkTextIter + * @char_offset: a character number + * + * Sets @iter to point to @char_offset. @char_offset counts from the start + * of the entire text buffer, starting with 0. + * + **/ void -gtk_text_iter_set_offset (GtkTextIter *iter, gint char_index) +gtk_text_iter_set_offset (GtkTextIter *iter, + gint char_offset) { GtkTextLine *line; GtkTextRealIter *real; @@ -3084,11 +3339,11 @@ gtk_text_iter_set_offset (GtkTextIter *iter, gint char_index) check_invariants (iter); if (real->cached_char_index >= 0 && - real->cached_char_index == char_index) + real->cached_char_index == char_offset) return; line = _gtk_text_btree_get_line_at_char (real->tree, - char_index, + char_offset, &line_start, &real_char_index); @@ -3100,8 +3355,17 @@ gtk_text_iter_set_offset (GtkTextIter *iter, gint char_index) check_invariants (iter); } +/** + * gtk_text_iter_forward_to_end: + * @iter: a #GtkTextIter + * + * Moves @iter forward to the "end iterator," which points one past the last + * valid character in the buffer. gtk_text_iter_get_char() called on the + * end iterator returns 0, which is convenient for writing loops. + * + **/ void -gtk_text_iter_forward_to_end (GtkTextIter *iter) +gtk_text_iter_forward_to_end (GtkTextIter *iter) { GtkTextBuffer *buffer; GtkTextRealIter *real; @@ -3399,6 +3663,17 @@ gtk_text_iter_forward_find_char (GtkTextIter *iter, return FALSE; } +/** + * gtk_text_iter_backward_find_char: + * @iter: a #GtkTextIter + * @pred: function to be called on each character + * @user_data: user data for @pred + * @limit: search limit, or %NULL for none + * + * Same as gtk_text_iter_forward_find_char(), but goes backward from @iter. + * + * Return value: whether a match was found + **/ gboolean gtk_text_iter_backward_find_char (GtkTextIter *iter, GtkTextCharPredicate pred, @@ -3623,7 +3898,9 @@ strbreakup (const char *string, * @match_end: return location for end of match, or %NULL * @limit: bound for the search, or %NULL for the end of the buffer * - * + * Searches forward for @str. Any match is returned as the range @match_start, + * @match_end. If you specify @visible_only or @slice, the match may have + * invisible text, pixbufs, or child widgets interspersed in @str. * * Return value: whether a match was found **/ @@ -3941,7 +4218,7 @@ my_strrstr (const gchar *haystack, * @match_end: return location for end of match, or %NULL * @limit: location of last possible @match_start, or %NULL for start of buffer * - * + * Same as gtk_text_iter_forward_search(), but moves backward. * * Return value: whether a match was found **/ @@ -4079,6 +4356,19 @@ gtk_text_iter_backward_search (const GtkTextIter *iter, * Comparisons */ +/** + * gtk_text_iter_equal: + * @lhs: a #GtkTextIter + * @rhs: another #GtkTextIter + * + * Tests whether two iterators are equal, using the fastest possible + * mechanism. This function is very fast; you can expect it to perform + * better than e.g. getting the character offset for each iterator and + * comparing the offsets yourself. Also, it's a bit faster than + * gtk_text_iter_compare(). + * + * Return value: %TRUE if the iterators point to the same place in the buffer + **/ gboolean gtk_text_iter_equal (const GtkTextIter *lhs, const GtkTextIter *rhs) @@ -4107,8 +4397,21 @@ gtk_text_iter_equal (const GtkTextIter *lhs, } } +/** + * gtk_text_iter_compare: + * @lhs: a #GtkTextIter + * @rhs: another #GtkTextIter + * + * A qsort()-style function that returns negative if @lhs is less than + * @rhs, positive if @lhs is greater than @rhs, and 0 if they're equal. + * Ordering is in character offset order, i.e. the first character in the buffer + * is less than the second character in the buffer. + * + * Return value: -1 if @lhs is less than @rhs, 1 if @lhs is greater, 0 if they are equal + **/ gint -gtk_text_iter_compare (const GtkTextIter *lhs, const GtkTextIter *rhs) +gtk_text_iter_compare (const GtkTextIter *lhs, + const GtkTextIter *rhs) { GtkTextRealIter *real_lhs; GtkTextRealIter *real_rhs; @@ -4116,13 +4419,13 @@ gtk_text_iter_compare (const GtkTextIter *lhs, const GtkTextIter *rhs) real_lhs = gtk_text_iter_make_surreal (lhs); real_rhs = gtk_text_iter_make_surreal (rhs); - check_invariants (lhs); - check_invariants (rhs); - if (real_lhs == NULL || real_rhs == NULL) return -1; /* why not */ + check_invariants (lhs); + check_invariants (rhs); + if (real_lhs->line == real_rhs->line) { gint left_index, right_index; @@ -4165,6 +4468,18 @@ gtk_text_iter_compare (const GtkTextIter *lhs, const GtkTextIter *rhs) } } +/** + * gtk_text_iter_in_range: + * @iter: a #GtkTextIter + * @start: start of range + * @end: end of range + * + * @start and @end must be in order, unlike most text buffer + * functions, for efficiency reasons. The function returns %TRUE if + * @iter falls in the range [@start, @end). + * + * Return value: %TRUE if @iter is in the range + **/ gboolean gtk_text_iter_in_range (const GtkTextIter *iter, const GtkTextIter *start, @@ -4174,6 +4489,19 @@ gtk_text_iter_in_range (const GtkTextIter *iter, gtk_text_iter_compare (iter, end) < 0; } +/** + * gtk_text_iter_reorder: + * @first: a #GtkTextIter + * @second: another #GtkTextIter + * + * Swaps the value of @first and @second if @second comes before + * @first in the buffer. That is, ensures that @first and @second are + * in sequence. Most text buffer functions that take a range call this + * automatically on your behalf, so there's no real reason to call it yourself + * in those cases. There are some exceptions, such as gtk_text_iter_in_range(), + * that expect a pre-sorted range. + * + **/ void gtk_text_iter_reorder (GtkTextIter *first, GtkTextIter *second) @@ -4261,13 +4589,6 @@ _gtk_text_btree_get_iter_at_line_byte (GtkTextBTree *tree, /* We might as well cache this, since we know it. */ real->cached_line_number = real_line; - if (real->segment->type == >k_text_char_type && - (real->segment->body.chars[real->segment_byte_offset] & 0xc0) == 0x80) - g_warning ("%s: Incorrect byte offset %d falls in the middle of a UTF-8 " - "character; this will crash the text buffer. " - "Byte indexes must refer to the start of a character.", - G_STRLOC, byte_index); - check_invariants (iter); } diff --git a/gtk/gtktexttag.c b/gtk/gtktexttag.c index 1cd630bdbb..153f3417e1 100644 --- a/gtk/gtktexttag.c +++ b/gtk/gtktexttag.c @@ -1735,6 +1735,14 @@ gtk_text_attributes_new (void) return values; } +/** + * gtk_text_attributes_copy: + * @src: a #GtkTextAttributes to be copied + * + * Copies @src and returns a new #GtkTextAttributes. + * + * Return value: a copy of @src + **/ GtkTextAttributes* gtk_text_attributes_copy (GtkTextAttributes *src) { @@ -1752,7 +1760,7 @@ gtk_text_attributes_copy (GtkTextAttributes *src) * @dest: another #GtkTextAttributes * * Copies the values from @src to @dest so that @dest has the same values - * as @src. + * as @src. Frees existing values in @dest. **/ void gtk_text_attributes_copy_values (GtkTextAttributes *src, @@ -1803,6 +1811,12 @@ gtk_text_attributes_copy_values (GtkTextAttributes *src, dest->realized = FALSE; } +/** + * gtk_text_attributes_ref: + * @values: a #GtkTextAttributes + * + * Increments the reference count on @values. + **/ void gtk_text_attributes_ref (GtkTextAttributes *values) { @@ -1811,6 +1825,13 @@ gtk_text_attributes_ref (GtkTextAttributes *values) values->refcount += 1; } +/** + * gtk_text_attributes_unref: + * @values: a #GtkTextAttributes + * + * Decrements the reference count on @values, freeing the structure + * if the reference count reaches 0. + **/ void gtk_text_attributes_unref (GtkTextAttributes *values) { diff --git a/gtk/gtktipsquery.h b/gtk/gtktipsquery.h index da1ec6adf5..03b022d0b4 100644 --- a/gtk/gtktipsquery.h +++ b/gtk/gtktipsquery.h @@ -27,6 +27,8 @@ * GTK+ at ftp://ftp.gtk.org/pub/gtk/. */ +#ifndef GTK_DISABLE_DEPRECATED + #ifndef __GTKTIPSQUERY_H__ #define __GTKTIPSQUERY_H__ @@ -106,3 +108,5 @@ void gtk_tips_query_set_labels (GtkTipsQuery *tips_query, #endif /* __GTKTIPSQUERY_H__ */ + +#endif /* GTK_DISABLE_DEPRECATED */ diff --git a/gtk/gtktreesortable.h b/gtk/gtktreesortable.h new file mode 100644 index 0000000000..403073e5b9 --- /dev/null +++ b/gtk/gtktreesortable.h @@ -0,0 +1,59 @@ +/* gtktreesortable.h + * Copyright (C) 2001 Red Hat, Inc. + * + * This library is free software; you can redistribute it and/or + * modify it under the terms of the GNU Library General Public + * License as published by the Free Software Foundation; either + * version 2 of the License, or (at your option) any later version. + * + * This library is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + * Library General Public License for more details. + * + * You should have received a copy of the GNU Library General Public + * License along with this library; if not, write to the + * Free Software Foundation, Inc., 59 Temple Place - Suite 330, + * Boston, MA 02111-1307, USA. + */ + +#ifndef __GTK_TREE_SORTABLE_H__ +#define __GTK_TREE_SORTABLE_H__ + +#include <gtk/gtktreemodel.h> + +#ifdef __cplusplus +extern "C" { +#endif /* __cplusplus */ + +#define GTK_TYPE_TREE_SORTABLE (gtk_tree_sortable_get_type ()) +#define GTK_TREE_SORTABLE(obj) (G_TYPE_CHECK_INSTANCE_CAST ((obj), GTK_TYPE_TREE_SORTABLE, GtkTreeSortable)) +#define GTK_IS_TREE_SORTABLE(obj) (G_TYPE_CHECK_INSTANCE_TYPE ((obj), GTK_TYPE_TREE_SORTABLE)) +#define GTK_TREE_SORTABLE_GET_IFACE(obj) ((GtkTreeSortableIface *)g_type_interface_peek (((GTypeInstance *)GTK_TREE_SORTABLE (obj))->g_class, GTK_TYPE_TREE_SORTABLE)) + +typedef struct _GtkTreeSortable GtkTreeSortable; /* Dummy typedef */ +typedef struct _GtkTreeSortableIface GtkTreeSortableIface; + +struct _GtkTreeSortableIface +{ + GTypeInterface g_iface; + + /* FIXME think about sorting reverse when the column is clicked + * a second time. + */ + gboolean (* column_sortable) (GtkTreeSortable *sortable, + gint column); + gint (* get_sort_column) (GtkTreeSortable *sortable); + void (* set_sort_column) (GtkTreeSortable *sortable, + gint column); +}; + + +GType gtk_tree_sortable_get_type (void) G_GNUC_CONST; + +#ifdef __cplusplus +} +#endif /* __cplusplus */ + + +#endif /* __GTK_TREE_SORTABLE_H__ */ diff --git a/gtk/gtkvruler.h b/gtk/gtkvruler.h index a18a1305ce..e47db489e5 100644 --- a/gtk/gtkvruler.h +++ b/gtk/gtkvruler.h @@ -24,6 +24,16 @@ * GTK+ at ftp://ftp.gtk.org/pub/gtk/. */ +/* + * NOTE this widget is considered too specialized/little-used for + * GTK+, and will in the future be moved to some other package. If + * your application needs this widget, feel free to use it, as the + * widget does work and is useful in some applications; it's just not + * of general interest. However, we are not accepting new features for + * the widget, and it will eventually move out of the GTK+ + * distribution. + */ + #ifndef __GTK_VRULER_H__ #define __GTK_VRULER_H__ @@ -69,3 +79,4 @@ GtkWidget* gtk_vruler_new (void); #endif /* __GTK_VRULER_H__ */ + diff --git a/gtk/gtkwidget.c b/gtk/gtkwidget.c index c78479ce6f..e9fee7463d 100644 --- a/gtk/gtkwidget.c +++ b/gtk/gtkwidget.c @@ -3661,7 +3661,7 @@ gtk_widget_create_pango_layout (GtkWidget *widget, } /** - * gtk_widget_render_stock_icon: + * gtk_widget_render_icon: * @widget: a #GtkWidget * @stock_id: a stock ID * @size: a stock size @@ -3678,10 +3678,10 @@ gtk_widget_create_pango_layout (GtkWidget *widget, * Return value: a new pixbuf, or NULL if the stock ID wasn't known **/ GdkPixbuf* -gtk_widget_render_stock_icon (GtkWidget *widget, - const gchar *stock_id, - const gchar *size, - const gchar *detail) +gtk_widget_render_icon (GtkWidget *widget, + const gchar *stock_id, + const gchar *size, + const gchar *detail) { GtkIconSet *icon_set; GdkPixbuf *retval; @@ -3770,14 +3770,24 @@ gtk_widget_get_parent_window (GtkWidget *widget) return (parent_window != NULL) ? parent_window : widget->parent->window; } -/***************************************** +/** * gtk_widget_set_uposition: + * @widget: a #GtkWidget + * @x: x position + * @y: y position + * * - * arguments: + * Sets the position of a widget. The funny "u" in the name comes from + * the "user position" hint specified by the X window system, and + * exists for legacy reasons. This function doesn't work if a widget + * is inside a container; it's only really useful on #GtkWindow. * - * results: - *****************************************/ - + * Don't use this function to center dialogs over the main application + * window; most window managers will do the centering on your behalf + * if you call gtk_window_set_transient_for(), and it's really not + * possible to get the centering to work correctly in all cases from + * application code. + **/ void gtk_widget_set_uposition (GtkWidget *widget, gint x, @@ -3811,14 +3821,31 @@ gtk_widget_set_uposition (GtkWidget *widget, gtk_widget_size_allocate (widget, &widget->allocation); } -/***************************************** +/** * gtk_widget_set_usize: + * @widget: a #GtkWidget + * @width: minimum width, or -1 to unset + * @height: minimum height, or -1 to unset * - * arguments: - * - * results: - *****************************************/ - + * Sets the minimum size of a widget; that is, the widget's size + * request will be @width by @height. You can use this function to + * force a widget to be either larger or smaller than it is. The + * strange "usize" name dates from the early days of GTK+, and derives + * from X Window System terminology. In many cases, + * gtk_window_set_default_size() is a better choice for toplevel + * windows than this function; setting the default size will still + * allow users to shrink the window. Setting the usize will force them + * to leave the window at least as large as the usize. When dealing + * with window sizes, gtk_window_set_geometry_hints() can be a useful + * function as well. + * + * Note the inherent danger of setting any fixed size - themes, + * translations into other languages, different fonts, and user action + * can all change the appropriate size for a given widget. So, it's + * basically impossible to hardcode a size that will always be + * correct. + * + **/ void gtk_widget_set_usize (GtkWidget *widget, gint width, @@ -3847,14 +3874,23 @@ gtk_widget_set_usize (GtkWidget *widget, gtk_widget_queue_resize (widget); } -/***************************************** +/** * gtk_widget_set_events: + * @widget: a #GtkWidget + * @events: event mask * - * arguments: - * - * results: - *****************************************/ - + * Sets the event mask (see #GdkEventMask) for a widget. The event + * mask determines which events a widget will receive. Keep in mind + * that different widgets have different default event masks, and by + * changing the event mask you may disrupt a widget's functionality, + * so be careful. This function must be called while a widget is + * unrealized. Consider gtk_widget_add_events() for widgets that are + * already realized, or if you want to preserve the existing event + * mask. This function can't be used with #GTK_NO_WINDOW widgets; + * to get events on those widgets, place them inside a #GtkEventBox + * and receive events on the event box. + * + **/ void gtk_widget_set_events (GtkWidget *widget, gint events) @@ -3885,14 +3921,15 @@ gtk_widget_set_events (GtkWidget *widget, } } -/***************************************** +/** * gtk_widget_add_events: + * @widget: a #GtkWidget + * @events: an event mask, see #GdkEventMask * - * arguments: - * - * results: - *****************************************/ - + * Adds the events in the bitfield @events to the event mask for + * @widget. See gtk_widget_set_events() for details. + * + **/ void gtk_widget_add_events (GtkWidget *widget, gint events) @@ -3931,14 +3968,15 @@ gtk_widget_add_events (GtkWidget *widget, } } -/***************************************** +/** * gtk_widget_set_extension_events: + * @widget: a #GtkWidget + * @mode: bitfield of extension events to receive * - * arguments: - * - * results: - *****************************************/ - + * Sets the extension events mask to @mode. See #GdkExtensionMode + * and gdk_input_set_extension_events(). + * + **/ void gtk_widget_set_extension_events (GtkWidget *widget, GdkExtensionMode mode) @@ -3959,14 +3997,21 @@ gtk_widget_set_extension_events (GtkWidget *widget, gtk_object_set_data_by_id (GTK_OBJECT (widget), extension_event_key_id, modep); } -/***************************************** +/** * gtk_widget_get_toplevel: + * @widget: a #GtkWidget + * + * This function returns the topmost widget in the container hierarchy + * @widget is a part of. If @widget has no parent widgets, it will be + * returned as the topmost widget. No reference will be added to the + * returned widget; it should not be unreferenced. * - * arguments: - * - * results: - *****************************************/ - + * Note the difference in behavior vs. gtk_widget_get_ancestor(); + * gtk_widget_get_ancestor (widget, GTK_TYPE_WINDOW) would return + * %NULL if @widget wasn't inside a toplevel window. + * + * Return value: the topmost ancestor of @widget, or @widget itself if there's no ancestor + **/ GtkWidget* gtk_widget_get_toplevel (GtkWidget *widget) { @@ -3979,14 +4024,18 @@ gtk_widget_get_toplevel (GtkWidget *widget) return widget; } -/***************************************** +/** * gtk_widget_get_ancestor: - * - * arguments: - * - * results: - *****************************************/ - + * @widget: a #GtkWidget + * @widget_type: ancestor type + * + * Gets the first ancestor of @widget with type @widget_type. For example, + * gtk_widget_get_ancestor (widget, GTK_TYPE_BOX) gets the first #GtkBox that's + * an ancestor of @widget. No reference will be added to the returned widget; + * it should not be unreferenced. + * + * Return value: the ancestor widget, or %NULL if not found + **/ GtkWidget* gtk_widget_get_ancestor (GtkWidget *widget, GtkType widget_type) @@ -4003,14 +4052,15 @@ gtk_widget_get_ancestor (GtkWidget *widget, return widget; } -/***************************************** +/** * gtk_widget_get_colormap: - * - * arguments: - * - * results: - *****************************************/ - + * @widget: a #GtkWidget + * + * Gets the colormap that will be used to render @widget. No reference will + * be added to the returned colormap; it should not be unreferenced. + * + * Return value: the colormap used by @widget + **/ GdkColormap* gtk_widget_get_colormap (GtkWidget *widget) { @@ -4034,14 +4084,14 @@ gtk_widget_get_colormap (GtkWidget *widget) return gtk_widget_get_default_colormap (); } -/***************************************** +/** * gtk_widget_get_visual: - * - * arguments: - * - * results: - *****************************************/ - + * @widget: a #GtkWidget + * + * Gets the visual that will be used to render @widget. + * + * Return value: the visual for @widget + **/ GdkVisual* gtk_widget_get_visual (GtkWidget *widget) { @@ -4050,42 +4100,44 @@ gtk_widget_get_visual (GtkWidget *widget) return gdk_colormap_get_visual (gtk_widget_get_colormap (widget)); } -/***************************************** - * gtk_widget_set_colormap: - * Set the colormap for the widget to the given - * value. Widget must not have been previously - * realized. This probably should only be used - * from an init() function. - * arguments: - * widget: - * colormap: - * results: - *****************************************/ +/** + * gtk_widget_set_colormap: + * @widget: a #GtkWidget + * @colormap: a colormap + * + * Set the colormap for the widget to the given value. Widget must not + * have been previously realized. This probably should only be used + * from an init() function (i.e. from the constructor for the widget). + * + **/ void -gtk_widget_set_colormap (GtkWidget *widget, GdkColormap *colormap) +gtk_widget_set_colormap (GtkWidget *widget, + GdkColormap *colormap) { g_return_if_fail (widget != NULL); g_return_if_fail (GTK_IS_WIDGET (widget)); g_return_if_fail (!GTK_WIDGET_REALIZED (widget)); - g_return_if_fail (colormap != NULL); + g_return_if_fail (GDK_IS_COLORMAP (colormap)); - /* FIXME: reference count the colormap. - */ + g_object_ref (G_OBJECT (colormap)); - gtk_object_set_data (GTK_OBJECT (widget), - colormap_key, - colormap); + gtk_object_set_data_full (GTK_OBJECT (widget), + colormap_key, + colormap, + (GtkDestroyNotify) g_object_unref); } -/***************************************** +/** * gtk_widget_get_events: - * - * arguments: - * - * results: - *****************************************/ - + * @widget: a #GtkWidget + * + * Returns the event mask for the widget (a bitfield containing flags + * from the #GdkEventMask enumeration). These are the events that the widget + * will receive. + * + * Return value: event mask for @widget + **/ gint gtk_widget_get_events (GtkWidget *widget) { @@ -4101,14 +4153,15 @@ gtk_widget_get_events (GtkWidget *widget) return 0; } -/***************************************** +/** * gtk_widget_get_extension_events: - * - * arguments: - * - * results: - *****************************************/ - + * @widget: a #GtkWidget + * + * Retrieves the extension events the widget will receive; see + * gdk_input_set_extension_events(). + * + * Return value: extension events for @widget + **/ GdkExtensionMode gtk_widget_get_extension_events (GtkWidget *widget) { @@ -4124,14 +4177,19 @@ gtk_widget_get_extension_events (GtkWidget *widget) return 0; } -/***************************************** +/** * gtk_widget_get_pointer: + * @widget: a #GtkWidget + * @x: return location for the X coordinate, or %NULL + * @y: return location for the Y coordinate, or %NULL * - * arguments: - * - * results: - *****************************************/ - + * Obtains the location of the mouse pointer in widget coordinates. + * Widget coordinates are a bit odd; for historical reasons, they are + * defined as widget->window coordinates for widgets that are not + * #GTK_NO_WINDOW widgets, and are relative to widget->allocation.x, + * widget->allocation.y for widgets that are #GTK_NO_WINDOW widgets. + * + **/ void gtk_widget_get_pointer (GtkWidget *widget, gint *x, @@ -4159,14 +4217,16 @@ gtk_widget_get_pointer (GtkWidget *widget, } } -/***************************************** +/** * gtk_widget_is_ancestor: - * - * arguments: - * - * results: - *****************************************/ - + * @widget: a #GtkWidget + * @ancestor: another #GtkWidget + * + * Determines whether @widget is somewhere inside @ancestor, possibly with + * intermediate containers. + * + * Return value: %TRUE if @ancestor contains @widget as a child, grandchild, great grandchild, etc. + **/ gboolean gtk_widget_is_ancestor (GtkWidget *widget, GtkWidget *ancestor) @@ -4231,14 +4291,16 @@ gtk_widget_pop_composite_child (void) composite_child_stack--; } -/***************************************** +/** * gtk_widget_push_colormap: + * @cmap: a #GdkColormap * - * arguments: - * - * results: - *****************************************/ - + * Pushes @cmap onto a global stack of colormaps; the topmost + * colormap on the stack will be used to create all widgets. + * Remove @cmap with gtk_widget_pop_colormap(). There's little + * reason to use this function. + * + **/ void gtk_widget_push_colormap (GdkColormap *cmap) { @@ -4247,14 +4309,12 @@ gtk_widget_push_colormap (GdkColormap *cmap) colormap_stack = g_slist_prepend (colormap_stack, cmap); } -/***************************************** +/** * gtk_widget_pop_colormap: * - * arguments: - * - * results: - *****************************************/ - + * Removes a colormap pushed with gtk_widget_push_colormap(). + * + **/ void gtk_widget_pop_colormap (void) { @@ -4268,14 +4328,15 @@ gtk_widget_pop_colormap (void) } } -/***************************************** +/** * gtk_widget_set_default_colormap: - * - * arguments: - * - * results: - *****************************************/ - + * @colormap: a #GdkColormap + * + * Sets the default colormap to use when creating widgets. + * gtk_widget_push_colormap() is a better function to use if + * you only want to affect a few widgets, rather than all widgets. + * + **/ void gtk_widget_set_default_colormap (GdkColormap *colormap) { @@ -4289,31 +4350,30 @@ gtk_widget_set_default_colormap (GdkColormap *colormap) } } -/***************************************** +/** * gtk_widget_get_default_colormap: - * - * arguments: - * - * results: - *****************************************/ - + * + * Obtains the default colormap used to create widgets. + * + * Return value: default widget colormap + **/ GdkColormap* gtk_widget_get_default_colormap (void) { if (!default_colormap) - default_colormap = gdk_colormap_get_system (); + gtk_widget_set_default_colormap (gdk_colormap_get_system ()); return default_colormap; } -/***************************************** +/** * gtk_widget_get_default_visual: - * - * arguments: - * - * results: - *****************************************/ - + * + * Obtains the visual of the default colormap. Not really useful; + * used to be useful before gdk_colormap_get_visual() existed. + * + * Return value: visual of the default colormap + **/ GdkVisual* gtk_widget_get_default_visual (void) { @@ -4898,6 +4958,17 @@ gtk_widget_reset_shapes (GtkWidget *widget) gtk_reset_shapes_recurse (widget, widget->window); } +/** + * gtk_widget_ref: + * @widget: a #GtkWidget + * + * Adds a reference to a widget. This function is exactly the same + * as calling g_object_ref(), and exists mostly for historical + * reasons. It can still be convenient to avoid casting a widget + * to a #GObject, it saves a small amount of typing. + * + * Return value: the widget that was referenced + **/ GtkWidget* gtk_widget_ref (GtkWidget *widget) { @@ -4906,6 +4977,13 @@ gtk_widget_ref (GtkWidget *widget) return (GtkWidget*) g_object_ref ((GObject*) widget); } +/** + * gtk_widget_unref: + * @widget: a #GtkWidget + * + * Inverse of gtk_widget_ref(). Equivalent to g_object_unref(). + * + **/ void gtk_widget_unref (GtkWidget *widget) { @@ -4914,6 +4992,27 @@ gtk_widget_unref (GtkWidget *widget) g_object_unref ((GObject*) widget); } +/** + * gtk_widget_path: + * @widget: a #GtkWidget + * @path_length: location to store length of the path + * @path: location to store allocated path string + * @path_reversed: location to store allocated reverse path string + * + * Obtains the full path to @widget. The path is simply the name of a + * widget and all its parents in the container hierarchy, separated by + * periods. The name of a widget comes from + * gtk_widget_get_name(). Paths are used to apply styles to a widget + * in gtkrc configuration files. Widget names are the type of the + * widget by default (e.g. "GtkButton") or can be set to an + * application-specific value with gtk_widget_set_name(). By setting + * the name of a widget, you allow users or theme authors to apply + * styles to that specific widget in their gtkrc + * file. @path_reversed_p fills in the path in reverse order, + * i.e. starting with @widget's name instead of starting with the name + * of @widget's outermost ancestor. + * + **/ void gtk_widget_path (GtkWidget *widget, guint *path_length_p, @@ -4967,6 +5066,17 @@ gtk_widget_path (GtkWidget *widget, } } +/** + * gtk_widget_class_path: + * @widget: a #GtkWidget + * @path_length: location to store the length of the class path + * @path: location to store the class path as an allocated string + * @path_reversed: location to store the reverse class path as an allocated string + * + * Same as gtk_widget_path(), but always uses the name of a widget's type, + * never uses a custom name set with gtk_widget_set_name(). + * + **/ void gtk_widget_class_path (GtkWidget *widget, guint *path_length_p, diff --git a/gtk/gtkwidget.h b/gtk/gtkwidget.h index aa36d1572a..527132673a 100644 --- a/gtk/gtkwidget.h +++ b/gtk/gtkwidget.h @@ -426,17 +426,21 @@ void gtk_widget_queue_draw_area (GtkWidget *widget, gint y, gint width, gint height); +#ifndef GTK_DISABLE_DEPRECATED void gtk_widget_queue_clear (GtkWidget *widget); void gtk_widget_queue_clear_area (GtkWidget *widget, gint x, gint y, gint width, gint height); +#endif /* GTK_DISABLE_DEPRECATED */ void gtk_widget_queue_resize (GtkWidget *widget); +#ifndef GTK_DISABLE_DEPRECATED void gtk_widget_draw (GtkWidget *widget, GdkRectangle *area); +#endif /* GTK_DISABLE_DEPRECATED */ void gtk_widget_draw_focus (GtkWidget *widget); void gtk_widget_draw_default (GtkWidget *widget); void gtk_widget_size_request (GtkWidget *widget, @@ -575,10 +579,10 @@ PangoContext *gtk_widget_get_pango_context (GtkWidget *widget); PangoLayout *gtk_widget_create_pango_layout (GtkWidget *widget, const gchar *text); -GdkPixbuf* gtk_widget_render_stock_icon (GtkWidget *widget, - const gchar *stock_id, - const gchar *size, - const gchar *detail); +GdkPixbuf *gtk_widget_render_icon (GtkWidget *widget, + const gchar *stock_id, + const gchar *size, + const gchar *detail); /* handle composite names for GTK_COMPOSITE_CHILD widgets, * the returned name is newly allocated. diff --git a/gtk/gtkwindow.c b/gtk/gtkwindow.c index 09f39f9d92..3d87ca2527 100644 --- a/gtk/gtkwindow.c +++ b/gtk/gtkwindow.c @@ -433,6 +433,20 @@ gtk_window_get_arg (GtkObject *object, } } +/** + * gtk_window_new: + * @type: type of window + * + * Creates a new #GtkWindow, which is a toplevel window that can + * contain other widgets. Nearly always, the type of the window should + * be #GTK_WINDOW_TOPLEVEL. If you're implementing something like a + * popup menu from scratch (which is a bad idea, just use #GtkMenu), + * you might use #GTK_WINDOW_TOPLEVEL. #GTK_WINDOW_DIALOG is not + * useful; dialogs should be of type #GTK_WINDOW_TOPLEVEL. (Probably + * you want to use the #GtkDialog widget for dialogs anyway). + * + * Return value: a new #GtkWindow. + **/ GtkWidget* gtk_window_new (GtkWindowType type) { @@ -447,6 +461,19 @@ gtk_window_new (GtkWindowType type) return GTK_WIDGET (window); } +/** + * gtk_window_set_title: + * @window: a #GtkWindow + * @title: title of the window + * + * Sets the title of the #GtkWindow. The title of a window will be displayed in + * its title bar; on the X Window System, the title bar is rendered by the + * window manager, so exactly how the title appears to users may vary according + * to a user's exact configuration. The title should help a user distinguish + * this window from other windows they may have open. A good title might + * include the application name and current document filename, for example. + * + **/ void gtk_window_set_title (GtkWindow *window, const gchar *title) @@ -466,6 +493,21 @@ gtk_window_set_title (GtkWindow *window, } } +/** + * gtk_window_set_wmclass: + * @window: a #GtkWindow + * @wmclass_name: window name hint + * @wmclass_class: window class hint + * + * This function sets the X Window System "class" and "name" hints for a window. + * According to the ICCCM, you should always set these to the same value for + * all windows in an application, and GTK sets them to that value by default, + * so calling this function is sort of pointless. However, you may want to + * call gtk_window_set_role() on each window in your application, for the + * benefit of the session manager. Setting the role allows the window manager + * to restore window positions when loading a saved session. + * + **/ void gtk_window_set_wmclass (GtkWindow *window, const gchar *wmclass_name, @@ -484,6 +526,18 @@ gtk_window_set_wmclass (GtkWindow *window, g_warning ("shouldn't set wmclass after window is realized!\n"); } +/** + * gtk_window_set_focus: + * @window: a #GtkWindow + * @focus: widget to be the new focus widget + * + * If @focus is not the current focus widget, and is focusable, emits + * the "set_focus" signal to set @focus as the focus widget for the + * window. This function is more or less GTK-internal; to focus an + * entry widget or the like, you should use gtk_widget_grab_focus() + * instead of this function. + * + **/ void gtk_window_set_focus (GtkWindow *window, GtkWidget *focus) @@ -501,6 +555,20 @@ gtk_window_set_focus (GtkWindow *window, gtk_signal_emit (GTK_OBJECT (window), window_signals[SET_FOCUS], focus); } +/** + * gtk_window_set_default: + * @window: a #GtkWindow + * @default_widget: widget to be the default + * + * The default widget is the widget that's activated when the user + * presses Enter in a dialog (for example). This function tells a + * #GtkWindow about the current default widget; it's really a GTK + * internal function and you shouldn't need it. Instead, to change the + * default widget, first set the #GTK_CAN_DEFAULT flag on the widget + * you'd like to make the default using GTK_WIDGET_SET_FLAGS(), then + * call gtk_widget_grab_default() to move the default. + * + **/ void gtk_window_set_default (GtkWindow *window, GtkWidget *default_widget) @@ -635,6 +703,20 @@ gtk_window_activate_default (GtkWindow *window) return FALSE; } +/** + * gtk_window_set_modal: + * @window: a #GtkWindow + * @modal: whether the window is modal + * + * Sets a window modal or non-modal. Modal windows prevent interaction + * with other windows in the same application. To keep modal dialogs + * on top of main application windows, use + * gtk_window_set_transient_for() to make the dialog transient for the + * parent; most window managers will then disallow lowering the dialog + * below the parent. + * + * + **/ void gtk_window_set_modal (GtkWindow *window, gboolean modal) @@ -651,6 +733,15 @@ gtk_window_set_modal (GtkWindow *window, gtk_grab_remove (GTK_WIDGET (window)); } +/** + * gtk_window_list_toplevels: + * + * Returns a list of all existing toplevel windows. Each widget + * in the list has a reference added to it; to free the + * list, first unref each widget in the list, then free the list. + * + * Return value: list of referenced toplevel widgets + **/ GList* gtk_window_list_toplevels (void) { @@ -825,6 +916,19 @@ gtk_window_unset_transient_for (GtkWindow *window) } } +/** + * gtk_window_set_transient_for: + * @window: a #GtkWindow + * @parent: parent window + * + * Dialog windows should be set transient for the main application + * window they were spawned from. This allows window managers to + * e.g. keep the dialog on top of the main window, or center the + * dialog over the main window. gtk_dialog_new_with_buttons() and + * other convenience functions in GTK+ will sometimes call + * gtk_window_set_transient_for() on yoru behalf. + * + **/ void gtk_window_set_transient_for (GtkWindow *window, GtkWindow *parent) @@ -938,6 +1042,19 @@ gtk_window_get_geometry_info (GtkWindow *window, return info; } +/** + * gtk_window_set_geometry_hints: + * @window: a #GdkWindow + * @geometry_widget: widget the geometry hints will be applied to + * @geometry: struct containing geometry information + * @geom_mask: mask indicating which struct fields should be paid attention to + * + * This function sets up hints about how a window can be resized by + * the user. You can set a minimum and maximum size; allowed resize + * increments (e.g. for xterm, you can only resize by the size of a + * character); aspect ratios; and more. See the #GdkGeometry struct. + * + **/ void gtk_window_set_geometry_hints (GtkWindow *window, GtkWidget *geometry_widget, @@ -969,6 +1086,25 @@ gtk_window_set_geometry_hints (GtkWindow *window, gtk_widget_queue_resize (GTK_WIDGET (window)); } +/** + * gtk_window_set_default_size: + * @window: a #GtkWindow + * @width: width in pixels, or -1 to leave the default width unchanged + * @height: height in pixels, or -1 to leave the default height unchanged + * + * Sets the default size of a window. If the window's "natural" size + * (its size request) is larger than the default, the default will be + * ignored. So the default size is a minimum initial size. Unlike + * gtk_widget_set_usize(), which sets a size request for a widget and + * thus would keep users from shrinking the window, this function only + * sets the initial size, just as if the user had resized the window + * themselves. Users can still shrink the window again as they + * normally would. + * + * For more control over a window's initial size and how resizing works, + * investigate gtk_window_set_geometry_hints(). + * + **/ void gtk_window_set_default_size (GtkWindow *window, gint width, diff --git a/gtk/testgtk.c b/gtk/testgtk.c index c5c460d531..df318a0fed 100644 --- a/gtk/testgtk.c +++ b/gtk/testgtk.c @@ -969,23 +969,6 @@ statusbar_contexts (GtkStatusbar *statusbar) } static void -statusbar_dump_stack (GtkStatusbar *statusbar) -{ - GSList *list; - - for (list = statusbar->messages; list; list = list->next) - { - GtkStatusbarMsg *msg; - - msg = list->data; - g_print ("context_id: %d, message_id: %d, status_text: \"%s\"\n", - msg->context_id, - msg->message_id, - msg->text); - } -} - -static void create_statusbar (void) { static GtkWidget *window = NULL; @@ -1048,15 +1031,6 @@ create_statusbar (void) NULL); button = gtk_widget_new (gtk_button_get_type (), - "label", "dump stack", - "visible", TRUE, - "parent", box2, - NULL); - g_object_set (G_OBJECT (button), - "swapped_signal::clicked", statusbar_dump_stack, statusbar, - NULL); - - button = gtk_widget_new (gtk_button_get_type (), "label", "test contexts", "visible", TRUE, "parent", box2, diff --git a/tests/testgtk.c b/tests/testgtk.c index c5c460d531..df318a0fed 100644 --- a/tests/testgtk.c +++ b/tests/testgtk.c @@ -969,23 +969,6 @@ statusbar_contexts (GtkStatusbar *statusbar) } static void -statusbar_dump_stack (GtkStatusbar *statusbar) -{ - GSList *list; - - for (list = statusbar->messages; list; list = list->next) - { - GtkStatusbarMsg *msg; - - msg = list->data; - g_print ("context_id: %d, message_id: %d, status_text: \"%s\"\n", - msg->context_id, - msg->message_id, - msg->text); - } -} - -static void create_statusbar (void) { static GtkWidget *window = NULL; @@ -1048,15 +1031,6 @@ create_statusbar (void) NULL); button = gtk_widget_new (gtk_button_get_type (), - "label", "dump stack", - "visible", TRUE, - "parent", box2, - NULL); - g_object_set (G_OBJECT (button), - "swapped_signal::clicked", statusbar_dump_stack, statusbar, - NULL); - - button = gtk_widget_new (gtk_button_get_type (), "label", "test contexts", "visible", TRUE, "parent", box2, |