Pileus Git - ~andy/gtk/blob - gtk/gtkscrollable.c

   1 /* gtkscrollable.c
   2  * Copyright (C) 2008 Tadej Borovšak <tadeboro@gmail.com>
   3  *
   4  * This library is free software; you can redistribute it and/or
   5  * modify it under the terms of the GNU Lesser General Public
   6  * License as published by the Free Software Foundation; either
   7  * version 2 of the License, or (at your option) any later version.
   8  *
   9  * This library is distributed in the hope that it will be useful,
  10  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  11  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  12  * Lesser General Public License for more details.
  13  *
  14  * You should have received a copy of the GNU Lesser General Public
  15  * License along with this library. If not, see <http://www.gnu.org/licenses/>.
  16  */
  17
  18 /**
  19  * SECTION:gtkscrollable
  20  * @Short_Description: An interface for scrollable widgets
  21  * @Title: GtkScrollable
  22  *
  23  * #GtkScrollable is an interface that is implemented by widgets with native
  24  * scrolling ability.
  25  *
  26  * To implement this interface you should override the
  27  * #GtkScrollable:hadjustment and #GtkScrollable:vadjustment properties.
  28  *
  29  * <refsect2>
  30  * <title>Creating a scrollable widget</title>
  31  * <para>
  32  * All scrollable widgets should do the following.
  33  *
  34  * <orderedlist>
  35  *   <listitem>
  36  *     <para>
  37  *       When a parent widget sets the scrollable child widget's adjustments, the widget should populate the adjustments'
  38  *       #GtkAdjustment:lower, #GtkAdjustment:upper,
  39  *       #GtkAdjustment:step-increment, #GtkAdjustment:page-increment and
  40  *       #GtkAdjustment:page-size properties and connect to the
  41  *       #GtkAdjustment::value-changed signal.
  42  *     </para>
  43  *   </listitem>
  44  *   <listitem>
  45  *     <para>
  46  *       Because its preferred size is the size for a fully expanded widget,
  47  *       the scrollable widget must be able to cope with underallocations.
  48  *       This means that it must accept any value passed to its
  49  *       #GtkWidgetClass.size_allocate() function.
  50  *     </para>
  51  *   </listitem>
  52  *   <listitem>
  53  *     <para>
  54  *       When the parent allocates space to the scrollable child widget, the widget should update
  55  *       the adjustments' properties with new values.
  56  *     </para>
  57  *   </listitem>
  58  *   <listitem>
  59  *     <para>
  60  *       When any of the adjustments emits the #GtkAdjustment::value-changed signal,
  61  *       the scrollable widget should scroll its contents.
  62  *     </para>
  63  *   </listitem>
  64  * </orderedlist>
  65  * </para>
  66  * </refsect2>
  67  */
  68
  69 #include "config.h"
  70
  71 #include "gtkscrollable.h"
  72 #include "gtkprivate.h"
  73 #include "gtktypebuiltins.h"
  74 #include "gtkintl.h"
  75
  76 G_DEFINE_INTERFACE (GtkScrollable, gtk_scrollable, G_TYPE_OBJECT)
  77
  78 static void
  79 gtk_scrollable_default_init (GtkScrollableInterface *iface)
  80 {
  81   GParamSpec *pspec;
  82
  83   /**
  84    * GtkScrollable:hadjustment:
  85    *
  86    * Horizontal #GtkAdjustment of the scrollable widget. This adjustment is
  87    * shared between the scrollable widget and its parent.
  88    *
  89    * Since: 3.0
  90    */
  91   pspec = g_param_spec_object ("hadjustment",
  92                                P_("Horizontal adjustment"),
  93                                P_("Horizontal adjustment that is shared "
  94                                   "between the scrollable widget and its "
  95                                   "controller"),
  96                                GTK_TYPE_ADJUSTMENT,
  97                                GTK_PARAM_READWRITE | G_PARAM_CONSTRUCT);
  98   g_object_interface_install_property (iface, pspec);
  99
 100   /**
 101    * GtkScrollable:vadjustment:
 102    *
 103    * Verical #GtkAdjustment of the scrollable widget. This adjustment is shared
 104    * between the scrollable widget and its parent.
 105    *
 106    * Since: 3.0
 107    */
 108   pspec = g_param_spec_object ("vadjustment",
 109                                P_("Vertical adjustment"),
 110                                P_("Vertical adjustment that is shared "
 111                                   "between the scrollable widget and its "
 112                                   "controller"),
 113                                GTK_TYPE_ADJUSTMENT,
 114                                GTK_PARAM_READWRITE | G_PARAM_CONSTRUCT);
 115   g_object_interface_install_property (iface, pspec);
 116
 117   /**
 118    * GtkScrollable:hscroll-policy:
 119    *
 120    * Determines whether horizontal scrolling should start once the scrollable
 121    * widget is allocated less than its minimum width or less than its natural width.
 122    *
 123    * Since: 3.0
 124    */
 125   pspec = g_param_spec_enum ("hscroll-policy",
 126                              P_("Horizontal Scrollable Policy"),
 127                              P_("How the size of the content should be determined"),
 128                              GTK_TYPE_SCROLLABLE_POLICY,
 129                              GTK_SCROLL_MINIMUM,
 130                              GTK_PARAM_READWRITE);
 131   g_object_interface_install_property (iface, pspec);
 132
 133   /**
 134    * GtkScrollable:vscroll-policy:
 135    *
 136    * Determines whether vertical scrolling should start once the scrollable
 137    * widget is allocated less than its minimum height or less than its natural height.
 138    *
 139    * Since: 3.0
 140    */
 141   pspec = g_param_spec_enum ("vscroll-policy",
 142                              P_("Vertical Scrollable Policy"),
 143                              P_("How the size of the content should be determined"),
 144                              GTK_TYPE_SCROLLABLE_POLICY,
 145                              GTK_SCROLL_MINIMUM,
 146                              GTK_PARAM_READWRITE);
 147   g_object_interface_install_property (iface, pspec);
 148 }
 149
 150 /**
 151  * gtk_scrollable_get_hadjustment:
 152  * @scrollable: a #GtkScrollable
 153  *
 154  * Retrieves the #GtkAdjustment used for horizontal scrolling.
 155  *
 156  * Return value: (transfer none): horizontal #GtkAdjustment.
 157  *
 158  * Since: 3.0
 159  **/
 160 GtkAdjustment *
 161 gtk_scrollable_get_hadjustment (GtkScrollable *scrollable)
 162 {
 163   GtkAdjustment *adj = NULL;
 164
 165   g_return_val_if_fail (GTK_IS_SCROLLABLE (scrollable), NULL);
 166
 167   g_object_get (scrollable, "hadjustment", &adj, NULL);
 168
 169   /* Horrid hack; g_object_get() returns a new reference but
 170    * that contradicts the memory management conventions
 171    * for accessors.
 172    */
 173   if (adj)
 174     g_object_unref (adj);
 175
 176   return adj;
 177 }
 178
 179 /**
 180  * gtk_scrollable_set_hadjustment:
 181  * @scrollable: a #GtkScrollable
 182  * @hadjustment: (allow-none): a #GtkAdjustment
 183  *
 184  * Sets the horizontal adjustment of the #GtkScrollable.
 185  *
 186  * Since: 3.0
 187  **/
 188 void
 189 gtk_scrollable_set_hadjustment (GtkScrollable *scrollable,
 190                                 GtkAdjustment *hadjustment)
 191 {
 192   g_return_if_fail (GTK_IS_SCROLLABLE (scrollable));
 193   g_return_if_fail (hadjustment == NULL || GTK_IS_ADJUSTMENT (hadjustment));
 194
 195   g_object_set (scrollable, "hadjustment", hadjustment, NULL);
 196 }
 197
 198 /**
 199  * gtk_scrollable_get_vadjustment:
 200  * @scrollable: a #GtkScrollable
 201  *
 202  * Retrieves the #GtkAdjustment used for vertical scrolling.
 203  *
 204  * Return value: (transfer none): vertical #GtkAdjustment.
 205  *
 206  * Since: 3.0
 207  **/
 208 GtkAdjustment *
 209 gtk_scrollable_get_vadjustment (GtkScrollable *scrollable)
 210 {
 211   GtkAdjustment *adj = NULL;
 212
 213   g_return_val_if_fail (GTK_IS_SCROLLABLE (scrollable), NULL);
 214
 215   g_object_get (scrollable, "vadjustment", &adj, NULL);
 216
 217   /* Horrid hack; g_object_get() returns a new reference but
 218    * that contradicts the memory management conventions
 219    * for accessors.
 220    */
 221   if (adj)
 222     g_object_unref (adj);
 223
 224   return adj;
 225 }
 226
 227 /**
 228  * gtk_scrollable_set_vadjustment:
 229  * @scrollable: a #GtkScrollable
 230  * @vadjustment: (allow-none): a #GtkAdjustment
 231  *
 232  * Sets the vertical adjustment of the #GtkScrollable.
 233  *
 234  * Since: 3.0
 235  **/
 236 void
 237 gtk_scrollable_set_vadjustment (GtkScrollable *scrollable,
 238                                 GtkAdjustment *vadjustment)
 239 {
 240   g_return_if_fail (GTK_IS_SCROLLABLE (scrollable));
 241   g_return_if_fail (vadjustment == NULL || GTK_IS_ADJUSTMENT (vadjustment));
 242
 243   g_object_set (scrollable, "vadjustment", vadjustment, NULL);
 244 }
 245
 246
 247 /**
 248  * gtk_scrollable_get_hscroll_policy:
 249  * @scrollable: a #GtkScrollable
 250  *
 251  * Gets the horizontal #GtkScrollablePolicy.
 252  *
 253  * Return value: The horizontal #GtkScrollablePolicy.
 254  *
 255  * Since: 3.0
 256  **/
 257 GtkScrollablePolicy
 258 gtk_scrollable_get_hscroll_policy (GtkScrollable *scrollable)
 259 {
 260   GtkScrollablePolicy policy;
 261
 262   g_return_val_if_fail (GTK_IS_SCROLLABLE (scrollable), GTK_SCROLL_MINIMUM);
 263
 264   g_object_get (scrollable, "hscroll-policy", &policy, NULL);
 265
 266   return policy;
 267 }
 268
 269 /**
 270  * gtk_scrollable_set_hscroll_policy:
 271  * @scrollable: a #GtkScrollable
 272  * @policy: the horizontal #GtkScrollablePolicy
 273  *
 274  * Sets the #GtkScrollablePolicy to determine whether
 275  * horizontal scrolling should start below the minimum width or
 276  * below the natural width.
 277  *
 278  * Since: 3.0
 279  **/
 280 void
 281 gtk_scrollable_set_hscroll_policy (GtkScrollable       *scrollable,
 282                                    GtkScrollablePolicy  policy)
 283 {
 284   g_return_if_fail (GTK_IS_SCROLLABLE (scrollable));
 285
 286   g_object_set (scrollable, "hscroll-policy", policy, NULL);
 287 }
 288
 289 /**
 290  * gtk_scrollable_get_vscroll_policy:
 291  * @scrollable: a #GtkScrollable
 292  *
 293  * Gets the vertical #GtkScrollablePolicy.
 294  *
 295  * Return value: The vertical #GtkScrollablePolicy.
 296  *
 297  * Since: 3.0
 298  **/
 299 GtkScrollablePolicy
 300 gtk_scrollable_get_vscroll_policy (GtkScrollable *scrollable)
 301 {
 302   GtkScrollablePolicy policy;
 303
 304   g_return_val_if_fail (GTK_IS_SCROLLABLE (scrollable), GTK_SCROLL_MINIMUM);
 305
 306   g_object_get (scrollable, "vscroll-policy", &policy, NULL);
 307
 308   return policy;
 309 }
 310
 311 /**
 312  * gtk_scrollable_set_vscroll_policy:
 313  * @scrollable: a #GtkScrollable
 314  * @policy: the vertical #GtkScrollablePolicy
 315  *
 316  * Sets the #GtkScrollablePolicy to determine whether
 317  * vertical scrolling should start below the minimum height or
 318  * below the natural height.
 319  *
 320  * Since: 3.0
 321  **/
 322 void
 323 gtk_scrollable_set_vscroll_policy (GtkScrollable       *scrollable,
 324                                    GtkScrollablePolicy  policy)
 325 {
 326   g_return_if_fail (GTK_IS_SCROLLABLE (scrollable));
 327
 328   g_object_set (scrollable, "vscroll-policy", policy, NULL);
 329 }