diff options
author | Tadej Borovšak <tadeboro@gmail.com> | 2010-10-18 00:21:39 -0400 |
---|---|---|
committer | Matthias Clasen <mclasen@redhat.com> | 2010-10-22 11:03:45 +0200 |
commit | 55196a705f00564a44647bfc97981db0a783369a (patch) | |
tree | 101187f418d74b2cb16929f0dcd4ce2ed4575e44 /gtk/gtkscrollable.c | |
parent | 86b3c1b65e6fefc6f686279b1bc15b10895b61fe (diff) | |
download | gtk+-55196a705f00564a44647bfc97981db0a783369a.tar.gz |
Add GtkScrollable interface
The GtkScrollable interface provides "hadjustment" and "vadjustment"
properties that are used by GtkScrolledWindow. It replaces
the ::set_scroll_adjustment signal. The scrollable interface
also has ::min-display-width/height properties that can be
used to control the minimally visible part inside a scrolled window.
Diffstat (limited to 'gtk/gtkscrollable.c')
-rw-r--r-- | gtk/gtkscrollable.c | 327 |
1 files changed, 327 insertions, 0 deletions
diff --git a/gtk/gtkscrollable.c b/gtk/gtkscrollable.c new file mode 100644 index 0000000000..33744456f2 --- /dev/null +++ b/gtk/gtkscrollable.c @@ -0,0 +1,327 @@ +/* gtkscrollable.c + * Copyright (C) 2008 Tadej Borovšak <tadeboro@gmail.com> + * + * This library is free software; you can redistribute it and/or + * modify it under the terms of the GNU Lesser 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 + * Lesser General Public License for more details. + * + * You should have received a copy of the GNU Lesser 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. + */ + +/** + * SECTION:gtkscrollable + * @Short_Description: An interface for scrollable widgets + * @Title: GtkScrollable + * + * #GtkScrollable is interface that is implemented by widgets with native + * scrolling ability. + * + * To implement this interface, all one needs to do is to override + * #GtkScrollable:hadjustment and #GtkScrollable:vadjustment properties. + * + * <refsect2> + * <title>Creating a scrollable widget</title> + * <para> + * There are some common things all scrollable widgets will need to do. + * + * <orderedlist> + * <listitem> + * <para> + * When parent sets adjustments, widget needs to populate adjustment's + * #GtkAdjustment:lower, #GtkAdjustment:upper, + * #GtkAdjustment:step-increment, #GtkAdjustment:page-increment and + * #GtkAdjustment:page-size properties and connect to + * #GtkAdjustment::value-changed signal. + * </para> + * </listitem> + * <listitem> + * <para> + * When parent allocates space to child, scrollable widget needs to update + * properties listed under 1 with new values. + * </para> + * </listitem> + * <listitem> + * <para> + * When any of the adjustments emits #GtkAdjustment::value-changed signal, + * scrollable widget needs to scroll it's contents. + * </para> + * </listitem> + * </orderedlist> + * </para> + * </refsect2> + */ + +#include "config.h" + +#include "gtkscrollable.h" +#include "gtkprivate.h" +#include "gtkintl.h" + +G_DEFINE_INTERFACE (GtkScrollable, gtk_scrollable, G_TYPE_OBJECT) + +static void +gtk_scrollable_default_init (GtkScrollableInterface *iface) +{ + GParamSpec *pspec; + + /** + * GtkScrollable:hadjustment: + * + * Horizontal #GtkAdjustment of scrollable widget. This adjustment is + * shared between scrollable widget and it's parent. + * + * Since: 3.0 + */ + pspec = g_param_spec_object ("hadjustment", + P_("Horizontal adjustment"), + P_("Horizontal adjustment that is shared " + "between scrollable widget and it's " + "controller"), + GTK_TYPE_ADJUSTMENT, + GTK_PARAM_READWRITE | G_PARAM_CONSTRUCT); + g_object_interface_install_property (iface, pspec); + + /** + * GtkScrollable:vadjustment: + * + * Verical #GtkAdjustment of scrollable widget. This adjustment is shared + * between scrollable widget and it's parent. + * + * Since: 3.0 + */ + pspec = g_param_spec_object ("vadjustment", + P_("Vertical adjustment"), + P_("Vertical adjustment that is shared " + "between scrollable widget and it's " + "controller"), + GTK_TYPE_ADJUSTMENT, + GTK_PARAM_READWRITE | G_PARAM_CONSTRUCT); + g_object_interface_install_property (iface, pspec); + + + /** + * GtkScrollable:min-display-width: + * + * Minimum width to display in the parent scrolled window, this + * can be greater or less than the scrollable widget's real minimum + * width. + * + * Since: 3.0 + */ + pspec = g_param_spec_int ("min-display-width", + P_("Minimum Display Width"), + P_("Minimum width to display in the parent scrolled window"), + -1, G_MAXINT, -1, + GTK_PARAM_READWRITE); + g_object_interface_install_property (iface, pspec); + + + /** + * GtkScrollable:min-display-height: + * + * Minimum height to display in the parent scrolled window, this + * can be greater or less than the scrollable widget's real minimum + * height. + * + * Since: 3.0 + */ + pspec = g_param_spec_int ("min-display-height", + P_("Minimum Display Height"), + P_("Minimum height to display in the parent scrolled window"), + -1, G_MAXINT, -1, + GTK_PARAM_READWRITE); + g_object_interface_install_property (iface, pspec); + +} + +/** + * gtk_scrollable_get_hadjustment: + * @scrollable: a #GtkScrollable + * + * Retrieves the #GtkAdjustment, used for horizontal scrolling. + * + * Return value: (transfer none): horizontal #GtkAdjustment. + * + * Since: 3.0 + **/ +GtkAdjustment * +gtk_scrollable_get_hadjustment (GtkScrollable *scrollable) +{ + GtkAdjustment *adj = NULL; + + g_return_val_if_fail (GTK_IS_SCROLLABLE (scrollable), NULL); + + g_object_get (scrollable, "hadjustment", &adj, NULL); + + /* Horrid hack; g_object_get() returns a new reference but + * that contradicts the memory management conventions + * for accessors. + */ + if (adj) + g_object_unref (adj); + + return adj; +} + +/** + * gtk_scrollable_set_hadjustment: + * @scrollable: a #GtkScrollable + * @hadjustment: (allow-none): a #GtkAdjustment + * + * Sets the horizontal adjustment of the #GtkScrollable. + * + * Since: 3.0 + **/ +void +gtk_scrollable_set_hadjustment (GtkScrollable *scrollable, + GtkAdjustment *hadjustment) +{ + g_return_if_fail (GTK_IS_SCROLLABLE (scrollable)); + g_return_if_fail (hadjustment == NULL || GTK_IS_ADJUSTMENT (hadjustment)); + + g_object_set (scrollable, "hadjustment", hadjustment, NULL); +} + +/** + * gtk_scrollable_get_vadjustment: + * @scrollable: a #GtkScrollable + * + * Retrieves the #GtkAdjustment, used for vertical scrolling. + * + * Return value: (transfer none): vertical #GtkAdjustment. + * + * Since: 3.0 + **/ +GtkAdjustment * +gtk_scrollable_get_vadjustment (GtkScrollable *scrollable) +{ + GtkAdjustment *adj = NULL; + + g_return_val_if_fail (GTK_IS_SCROLLABLE (scrollable), NULL); + + g_object_get (scrollable, "vadjustment", &adj, NULL); + + /* Horrid hack; g_object_get() returns a new reference but + * that contradicts the memory management conventions + * for accessors. + */ + if (adj) + g_object_unref (adj); + + return adj; +} + +/** + * gtk_scrollable_set_vadjustment: + * @scrollable: a #GtkScrollable + * @vadjustment: (allow-none): a #GtkAdjustment + * + * Sets the vertical adjustment of the #GtkScrollable. + * + * Since: 3.0 + **/ +void +gtk_scrollable_set_vadjustment (GtkScrollable *scrollable, + GtkAdjustment *vadjustment) +{ + g_return_if_fail (GTK_IS_SCROLLABLE (scrollable)); + g_return_if_fail (vadjustment == NULL || GTK_IS_ADJUSTMENT (vadjustment)); + + g_object_set (scrollable, "vadjustment", vadjustment, NULL); +} + + +/** + * gtk_scrollable_get_min_display_width: + * @scrollable: a #GtkScrollable + * + * Retrieves the minimum width of content to display in the + * parent scrolled window. + * + * Return value: The minimum display width. + * + * Since: 3.0 + **/ +gint +gtk_scrollable_get_min_display_width (GtkScrollable *scrollable) +{ + gint width; + + g_return_val_if_fail (GTK_IS_SCROLLABLE (scrollable), NULL); + + g_object_get (scrollable, "min-display-width", &width, NULL); + + return width; +} + +/** + * gtk_scrollable_set_min_display_width: + * @scrollable: a #GtkScrollable + * @width: the minimum width of scrollable content to display + * + * Sets the minimum width of content to display in the parent scrolled window, + * this can be greater or less than the scrollable widget's real minimum + * width. + * + * Since: 3.0 + **/ +void +gtk_scrollable_set_min_display_width (GtkScrollable *scrollable, + gint width) +{ + g_return_if_fail (GTK_IS_SCROLLABLE (scrollable)); + + g_object_set (scrollable, "min-display-width", width, NULL); +} + +/** + * gtk_scrollable_get_min_display_height: + * @scrollable: a #GtkScrollable + * + * Retrieves the minimum height of content to display in the + * parent scrolled window. + * + * Return value: The minimum display height. + * + * Since: 3.0 + **/ +gint +gtk_scrollable_get_min_display_height (GtkScrollable *scrollable) +{ + gint height; + + g_return_val_if_fail (GTK_IS_SCROLLABLE (scrollable), NULL); + + g_object_get (scrollable, "min-display-height", &height, NULL); + + return height; +} + +/** + * gtk_scrollable_set_min_display_height: + * @scrollable: a #GtkScrollable + * @height: the minimum height of scrollable content to display + * + * Sets the minimum height of content to display in the parent scrolled window, + * this can be greater or less than the scrollable widget's real minimum + * height. + * + * Since: 3.0 + **/ +void +gtk_scrollable_set_min_display_height (GtkScrollable *scrollable, + gint height) +{ + g_return_if_fail (GTK_IS_SCROLLABLE (scrollable)); + + g_object_set (scrollable, "min-display-height", height, NULL); +} |