/* gtkscrollable.c * Copyright (C) 2008 Tadej Borovšak * * 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. * * * Creating a scrollable widget * * There are some common things all scrollable widgets will need to do. * * * * * 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. * * * * * When parent allocates space to child, scrollable widget needs to update * properties listed under 1 with new values. * * * * * When any of the adjustments emits #GtkAdjustment::value-changed signal, * scrollable widget needs to scroll it's contents. * * * * * */ #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); }