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
  73 #include "gtkadjustment.h"
  74 #include "gtkprivate.h"
  75 #include "gtktypebuiltins.h"
  76 #include "gtkintl.h"
  77
  78 G_DEFINE_INTERFACE (GtkScrollable, gtk_scrollable, G_TYPE_OBJECT)
  79
  80 static void
  81 gtk_scrollable_default_init (GtkScrollableInterface *iface)
  82 {
  83   GParamSpec *pspec;
  84
  85   /**
  86    * GtkScrollable:hadjustment:
  87    *
  88    * Horizontal #GtkAdjustment of the scrollable widget. This adjustment is
  89    * shared between the scrollable widget and its parent.
  90    *
  91    * Since: 3.0
  92    */
  93   pspec = g_param_spec_object ("hadjustment",
  94                                P_("Horizontal adjustment"),
  95                                P_("Horizontal adjustment that is shared "
  96                                   "between the scrollable widget and its "
  97                                   "controller"),
  98                                GTK_TYPE_ADJUSTMENT,
  99                                GTK_PARAM_READWRITE | G_PARAM_CONSTRUCT);
 100   g_object_interface_install_property (iface, pspec);
 101
 102   /**
 103    * GtkScrollable:vadjustment:
 104    *
 105    * Verical #GtkAdjustment of the scrollable widget. This adjustment is shared
 106    * between the scrollable widget and its parent.
 107    *
 108    * Since: 3.0
 109    */
 110   pspec = g_param_spec_object ("vadjustment",
 111                                P_("Vertical adjustment"),
 112                                P_("Vertical adjustment that is shared "
 113                                   "between the scrollable widget and its "
 114                                   "controller"),
 115                                GTK_TYPE_ADJUSTMENT,
 116                                GTK_PARAM_READWRITE | G_PARAM_CONSTRUCT);
 117   g_object_interface_install_property (iface, pspec);
 118
 119   /**
 120    * GtkScrollable:hscroll-policy:
 121    *
 122    * Determines whether horizontal scrolling should start once the scrollable
 123    * widget is allocated less than its minimum width or less than its natural width.
 124    *
 125    * Since: 3.0
 126    */
 127   pspec = g_param_spec_enum ("hscroll-policy",
 128                              P_("Horizontal Scrollable Policy"),
 129                              P_("How the size of the content should be determined"),
 130                              GTK_TYPE_SCROLLABLE_POLICY,
 131                              GTK_SCROLL_MINIMUM,
 132                              GTK_PARAM_READWRITE);
 133   g_object_interface_install_property (iface, pspec);
 134
 135   /**
 136    * GtkScrollable:vscroll-policy:
 137    *
 138    * Determines whether vertical scrolling should start once the scrollable
 139    * widget is allocated less than its minimum height or less than its natural height.
 140    *
 141    * Since: 3.0
 142    */
 143   pspec = g_param_spec_enum ("vscroll-policy",
 144                              P_("Vertical Scrollable Policy"),
 145                              P_("How the size of the content should be determined"),
 146                              GTK_TYPE_SCROLLABLE_POLICY,
 147                              GTK_SCROLL_MINIMUM,
 148                              GTK_PARAM_READWRITE);
 149   g_object_interface_install_property (iface, pspec);
 150 }
 151
 152 /**
 153  * gtk_scrollable_get_hadjustment:
 154  * @scrollable: a #GtkScrollable
 155  *
 156  * Retrieves the #GtkAdjustment used for horizontal scrolling.
 157  *
 158  * Return value: (transfer none): horizontal #GtkAdjustment.
 159  *
 160  * Since: 3.0
 161  **/
 162 GtkAdjustment *
 163 gtk_scrollable_get_hadjustment (GtkScrollable *scrollable)
 164 {
 165   GtkAdjustment *adj = NULL;
 166
 167   g_return_val_if_fail (GTK_IS_SCROLLABLE (scrollable), NULL);
 168
 169   g_object_get (scrollable, "hadjustment", &adj, NULL);
 170
 171   /* Horrid hack; g_object_get() returns a new reference but
 172    * that contradicts the memory management conventions
 173    * for accessors.
 174    */
 175   if (adj)
 176     g_object_unref (adj);
 177
 178   return adj;
 179 }
 180
 181 /**
 182  * gtk_scrollable_set_hadjustment:
 183  * @scrollable: a #GtkScrollable
 184  * @hadjustment: (allow-none): a #GtkAdjustment
 185  *
 186  * Sets the horizontal adjustment of the #GtkScrollable.
 187  *
 188  * Since: 3.0
 189  **/
 190 void
 191 gtk_scrollable_set_hadjustment (GtkScrollable *scrollable,
 192                                 GtkAdjustment *hadjustment)
 193 {
 194   g_return_if_fail (GTK_IS_SCROLLABLE (scrollable));
 195   g_return_if_fail (hadjustment == NULL || GTK_IS_ADJUSTMENT (hadjustment));
 196
 197   g_object_set (scrollable, "hadjustment", hadjustment, NULL);
 198 }
 199
 200 /**
 201  * gtk_scrollable_get_vadjustment:
 202  * @scrollable: a #GtkScrollable
 203  *
 204  * Retrieves the #GtkAdjustment used for vertical scrolling.
 205  *
 206  * Return value: (transfer none): vertical #GtkAdjustment.
 207  *
 208  * Since: 3.0
 209  **/
 210 GtkAdjustment *
 211 gtk_scrollable_get_vadjustment (GtkScrollable *scrollable)
 212 {
 213   GtkAdjustment *adj = NULL;
 214
 215   g_return_val_if_fail (GTK_IS_SCROLLABLE (scrollable), NULL);
 216
 217   g_object_get (scrollable, "vadjustment", &adj, NULL);
 218
 219   /* Horrid hack; g_object_get() returns a new reference but
 220    * that contradicts the memory management conventions
 221    * for accessors.
 222    */
 223   if (adj)
 224     g_object_unref (adj);
 225
 226   return adj;
 227 }
 228
 229 /**
 230  * gtk_scrollable_set_vadjustment:
 231  * @scrollable: a #GtkScrollable
 232  * @vadjustment: (allow-none): a #GtkAdjustment
 233  *
 234  * Sets the vertical adjustment of the #GtkScrollable.
 235  *
 236  * Since: 3.0
 237  **/
 238 void
 239 gtk_scrollable_set_vadjustment (GtkScrollable *scrollable,
 240                                 GtkAdjustment *vadjustment)
 241 {
 242   g_return_if_fail (GTK_IS_SCROLLABLE (scrollable));
 243   g_return_if_fail (vadjustment == NULL || GTK_IS_ADJUSTMENT (vadjustment));
 244
 245   g_object_set (scrollable, "vadjustment", vadjustment, NULL);
 246 }
 247
 248
 249 /**
 250  * gtk_scrollable_get_hscroll_policy:
 251  * @scrollable: a #GtkScrollable
 252  *
 253  * Gets the horizontal #GtkScrollablePolicy.
 254  *
 255  * Return value: The horizontal #GtkScrollablePolicy.
 256  *
 257  * Since: 3.0
 258  **/
 259 GtkScrollablePolicy
 260 gtk_scrollable_get_hscroll_policy (GtkScrollable *scrollable)
 261 {
 262   GtkScrollablePolicy policy;
 263
 264   g_return_val_if_fail (GTK_IS_SCROLLABLE (scrollable), GTK_SCROLL_MINIMUM);
 265
 266   g_object_get (scrollable, "hscroll-policy", &policy, NULL);
 267
 268   return policy;
 269 }
 270
 271 /**
 272  * gtk_scrollable_set_hscroll_policy:
 273  * @scrollable: a #GtkScrollable
 274  * @policy: the horizontal #GtkScrollablePolicy
 275  *
 276  * Sets the #GtkScrollablePolicy to determine whether
 277  * horizontal scrolling should start below the minimum width or
 278  * below the natural width.
 279  *
 280  * Since: 3.0
 281  **/
 282 void
 283 gtk_scrollable_set_hscroll_policy (GtkScrollable       *scrollable,
 284                                    GtkScrollablePolicy  policy)
 285 {
 286   g_return_if_fail (GTK_IS_SCROLLABLE (scrollable));
 287
 288   g_object_set (scrollable, "hscroll-policy", policy, NULL);
 289 }
 290
 291 /**
 292  * gtk_scrollable_get_vscroll_policy:
 293  * @scrollable: a #GtkScrollable
 294  *
 295  * Gets the vertical #GtkScrollablePolicy.
 296  *
 297  * Return value: The vertical #GtkScrollablePolicy.
 298  *
 299  * Since: 3.0
 300  **/
 301 GtkScrollablePolicy
 302 gtk_scrollable_get_vscroll_policy (GtkScrollable *scrollable)
 303 {
 304   GtkScrollablePolicy policy;
 305
 306   g_return_val_if_fail (GTK_IS_SCROLLABLE (scrollable), GTK_SCROLL_MINIMUM);
 307
 308   g_object_get (scrollable, "vscroll-policy", &policy, NULL);
 309
 310   return policy;
 311 }
 312
 313 /**
 314  * gtk_scrollable_set_vscroll_policy:
 315  * @scrollable: a #GtkScrollable
 316  * @policy: the vertical #GtkScrollablePolicy
 317  *
 318  * Sets the #GtkScrollablePolicy to determine whether
 319  * vertical scrolling should start below the minimum height or
 320  * below the natural height.
 321  *
 322  * Since: 3.0
 323  **/
 324 void
 325 gtk_scrollable_set_vscroll_policy (GtkScrollable       *scrollable,
 326                                    GtkScrollablePolicy  policy)
 327 {
 328   g_return_if_fail (GTK_IS_SCROLLABLE (scrollable));
 329
 330   g_object_set (scrollable, "vscroll-policy", policy, NULL);
 331 }