summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorHavoc Pennington <hp@redhat.com>2001-02-03 01:09:41 +0000
committerHavoc Pennington <hp@src.gnome.org>2001-02-03 01:09:41 +0000
commit2c5d938ff81480846539d9659dd92ca90cfb9e40 (patch)
tree023e97fe3fa238c3a2104859ac082b5f52505a43
parentcc00e1c5ee5c8bb971d00b7bca465f257b989424 (diff)
downloadgdk-pixbuf-2c5d938ff81480846539d9659dd92ca90cfb9e40.tar.gz
CVS is doing its broken pipe thing, this is more of the previous commit
2001-02-02 Havoc Pennington <hp@redhat.com>
-rw-r--r--demos/Makefile.am1
-rw-r--r--demos/gtk-demo/Makefile.am1
-rw-r--r--demos/testpixbuf-drawable.c6
-rw-r--r--demos/testpixbuf.c2
-rw-r--r--docs/reference/ChangeLog22
-rw-r--r--docs/reference/gtk/gtk-docs.sgml20
-rw-r--r--docs/reference/gtk/gtk-sections.txt17
-rw-r--r--docs/reference/gtk/tmpl/gtk-unused.sgml26
-rw-r--r--docs/reference/gtk/tmpl/gtkcurve.sgml9
-rw-r--r--docs/reference/gtk/tmpl/gtkgamma.sgml9
-rw-r--r--docs/reference/gtk/tmpl/gtkhruler.sgml9
-rw-r--r--docs/reference/gtk/tmpl/gtkiconfactory.sgml18
-rw-r--r--docs/reference/gtk/tmpl/gtkinputdialog.sgml10
-rw-r--r--docs/reference/gtk/tmpl/gtklabel.sgml6
-rw-r--r--docs/reference/gtk/tmpl/gtkruler.sgml9
-rw-r--r--docs/reference/gtk/tmpl/gtkstatusbar.sgml9
-rw-r--r--docs/reference/gtk/tmpl/gtkstock.sgml8
-rw-r--r--docs/reference/gtk/tmpl/gtktextbuffer.sgml12
-rw-r--r--docs/reference/gtk/tmpl/gtktreeview.sgml12
-rw-r--r--docs/reference/gtk/tmpl/gtktreeviewcolumn.sgml27
-rw-r--r--docs/reference/gtk/tmpl/gtkvruler.sgml9
-rw-r--r--docs/reference/gtk/tmpl/gtkwidget.sgml2
-rw-r--r--gtk/gtkcellrenderer.c32
-rw-r--r--gtk/gtkcellrendererpixbuf.c13
-rw-r--r--gtk/gtkcellrenderertext.c13
-rw-r--r--gtk/gtkcellrenderertextpixbuf.c14
-rw-r--r--gtk/gtkcellrenderertoggle.c54
-rw-r--r--gtk/gtkclist.h4
-rw-r--r--gtk/gtkcontainer.c75
-rw-r--r--gtk/gtkctree.h4
-rw-r--r--gtk/gtkcurve.h10
-rw-r--r--gtk/gtkdrawingarea.h3
-rw-r--r--gtk/gtkentry.c14
-rw-r--r--gtk/gtkgamma.h10
-rw-r--r--gtk/gtkhruler.h10
-rw-r--r--gtk/gtkiconfactory.c205
-rw-r--r--gtk/gtkimage.c228
-rw-r--r--gtk/gtkimage.h4
-rw-r--r--gtk/gtkinputdialog.h10
-rw-r--r--gtk/gtklabel.c4
-rw-r--r--gtk/gtklabel.h4
-rw-r--r--gtk/gtklayout.h3
-rw-r--r--gtk/gtklist.h4
-rw-r--r--gtk/gtkliststore.c160
-rw-r--r--gtk/gtkmain.c65
-rw-r--r--gtk/gtkmain.h2
-rw-r--r--gtk/gtkoldeditable.h4
-rw-r--r--gtk/gtkoptionmenu.c9
-rw-r--r--gtk/gtkpacker.h4
-rw-r--r--gtk/gtkpaned.c15
-rw-r--r--gtk/gtkpixmap.h4
-rw-r--r--gtk/gtkpreview.h4
-rw-r--r--gtk/gtkprogress.h5
-rw-r--r--gtk/gtkprogressbar.h6
-rw-r--r--gtk/gtkruler.h10
-rw-r--r--gtk/gtkscrolledwindow.c9
-rw-r--r--gtk/gtkstatusbar.c8
-rw-r--r--gtk/gtkstatusbar.h7
-rw-r--r--gtk/gtkstock.c59
-rw-r--r--gtk/gtkstock.h4
-rw-r--r--gtk/gtkstyle.h4
-rw-r--r--gtk/gtktextbtree.c12
-rw-r--r--gtk/gtktextbuffer.c238
-rw-r--r--gtk/gtktextbuffer.h16
-rw-r--r--gtk/gtktextiter.c355
-rw-r--r--gtk/gtktexttag.c23
-rw-r--r--gtk/gtktipsquery.h4
-rw-r--r--gtk/gtktreesortable.h59
-rw-r--r--gtk/gtkvruler.h11
-rw-r--r--gtk/gtkwidget.c390
-rw-r--r--gtk/gtkwidget.h12
-rw-r--r--gtk/gtkwindow.c136
-rw-r--r--gtk/testgtk.c26
-rw-r--r--tests/testgtk.c26
74 files changed, 2325 insertions, 324 deletions
diff --git a/demos/Makefile.am b/demos/Makefile.am
index f6c8b4ae9..8a43035b5 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 d3548fb5a..2327c53e9 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 7b3170520..aee537459 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 8a5d8f2dd..0af6d368e 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 89b57955c..e327fbb90 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 4792e3d61..7f4bc58b4 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;
&gtk-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 8206ca5d9..02d47762a 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 25cbfa812..7f37ff2ca 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 919f6295f..8701b8517 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 28f392d5c..a3326cee5 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 e6ceadc29..ef99f9b00 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 933586279..d617f266b 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 2abb5bc1a..436f014e0 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 f26cf204c..921328c1f 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 679d28430..ab4af18d3 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 09e7b1dd2..c4b37a46e 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 24280e4b5..0345dc380 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 64ad8b400..980fb9c0f 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 aaf95374b..83b41ba5a 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 ff4911e87..11ebd1902 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 aad5d12e2..15f498012 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 2790ec369..9180b2ede 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 d7724f49a..0b69d98bc 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 61a557237..f3a434e37 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 e98e6fd09..751659fc5 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 8d8fe804b..2f007dcc4 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 4ff6c7e52..2213f3c16 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 3c41ed98e..568c31f32 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 5f04910f9..d32eb5297 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 b2dd4f39a..69cc0b982 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 ba0235156..027a86c5e 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 8ba240f45..72e713b4b 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 a74589936..dfc9a8166 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 4875df82a..931860e6e 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 1c482331b..829665c62 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 ff724d454..56d2fccc2 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 c44ad0fe3..53ea859d3 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 266d032e6..0c5da6db6 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 e7a7f8131..a661c0b10 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 1a0939a37..95facb2a7 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 04c579c4c..787ffed50 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 54aa39e71..b0f2004af 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 027930e3a..e4e15bd94 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 219114615..619594894 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 ebb324efb..a6695a34e 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 0f7651edb..5701588ea 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 573653947..702332331 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 65802151b..9d9a25996 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 a483c9da6..130e35418 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 483084702..dba1ebf58 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 3e386179b..652457a41 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 224ddfce0..0dd5d7fde 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 0764262c5..00c398c62 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 71d571364..b4252960e 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 2adb80cdb..f9d4b2089 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 af5d48514..8ffd505e8 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 1c0d34377..9f2be1b62 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 ccfc2c244..e29d796b6 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 64700232a..60f3e9d6a 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 a11fa9515..d40cb9560 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 fff657cd7..d52248ae4 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 3e9d1648f..db30bd9b5 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 a2c13ac0d..1a4ccdb1f 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 ae7f7570c..88bf91190 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 549dcb217..c216d4ca3 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 == &gtk_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 == &gtk_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 1cd630bdb..153f3417e 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 da1ec6adf..03b022d0b 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 000000000..403073e5b
--- /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 a18a1305c..e47db489e 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 c78479ce6..e9fee7463 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 aa36d1572..527132673 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 09f39f9d9..3d87ca252 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 c5c460d53..df318a0fe 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 c5c460d53..df318a0fe 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,