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, write to the
  16  * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
  17  * Boston, MA 02111-1307, USA.
  18  */
  19
  20 /**
  21  * SECTION:gtkscrollable
  22  * @Short_Description: An interface for scrollable widgets
  23  * @Title: GtkScrollable
  24  *
  25  * #GtkScrollable is interface that is implemented by widgets with native
  26  * scrolling ability.
  27  *
  28  * To implement this interface, all one needs to do is to override
  29  * #GtkScrollable:hadjustment and #GtkScrollable:vadjustment properties.
  30  *
  31  * <refsect2>
  32  * <title>Creating a scrollable widget</title>
  33  * <para>
  34  * There are some common things all scrollable widgets will need to do.
  35  *
  36  * <orderedlist>
  37  *   <listitem>
  38  *     <para>
  39  *       When parent sets adjustments, widget needs to populate adjustment's
  40  *       #GtkAdjustment:lower, #GtkAdjustment:upper,
  41  *       #GtkAdjustment:step-increment, #GtkAdjustment:page-increment and
  42  *       #GtkAdjustment:page-size properties and connect to
  43  *       #GtkAdjustment::value-changed signal.
  44  *     </para>
  45  *   </listitem>
  46  *   <listitem>
  47  *     <para>
  48  *       When parent allocates space to child, scrollable widget needs to update
  49  *       properties listed under 1 with new values.
  50  *     </para>
  51  *   </listitem>
  52  *   <listitem>
  53  *     <para>
  54  *       When any of the adjustments emits #GtkAdjustment::value-changed signal,
  55  *       scrollable widget needs to scroll it's contents.
  56  *     </para>
  57  *   </listitem>
  58  * </orderedlist>
  59  * </para>
  60  * </refsect2>
  61  */
  62
  63 #include "config.h"
  64
  65 #include "gtkscrollable.h"
  66 #include "gtktypeutils.h"
  67 #include "gtkprivate.h"
  68 #include "gtkintl.h"
  69
  70 G_DEFINE_INTERFACE (GtkScrollable, gtk_scrollable, G_TYPE_OBJECT)
  71
  72 static void
  73 gtk_scrollable_default_init (GtkScrollableInterface *iface)
  74 {
  75   GParamSpec *pspec;
  76
  77   /**
  78    * GtkScrollable:hadjustment:
  79    *
  80    * Horizontal #GtkAdjustment of scrollable widget. This adjustment is
  81    * shared between scrollable widget and it's parent.
  82    *
  83    * Since: 3.0
  84    */
  85   pspec = g_param_spec_object ("hadjustment",
  86                                P_("Horizontal adjustment"),
  87                                P_("Horizontal adjustment that is shared "
  88                                   "between scrollable widget and it's "
  89                                   "controller"),
  90                                GTK_TYPE_ADJUSTMENT,
  91                                GTK_PARAM_READWRITE | G_PARAM_CONSTRUCT);
  92   g_object_interface_install_property (iface, pspec);
  93
  94   /**
  95    * GtkScrollable:vadjustment:
  96    *
  97    * Verical #GtkAdjustment of scrollable widget. This adjustment is shared
  98    * between scrollable widget and it's parent.
  99    *
 100    * Since: 3.0
 101    */
 102   pspec = g_param_spec_object ("vadjustment",
 103                                P_("Vertical adjustment"),
 104                                P_("Vertical adjustment that is shared "
 105                                   "between scrollable widget and it's "
 106                                   "controller"),
 107                                GTK_TYPE_ADJUSTMENT,
 108                                GTK_PARAM_READWRITE | G_PARAM_CONSTRUCT);
 109   g_object_interface_install_property (iface, pspec);
 110
 111   /**
 112    * GtkScrollable:hscroll-policy:
 113    *
 114    * Determines whether horizontal scrolling should commence once the scrollable
 115    * widget is allocated less than it's minimum width or less than it's natural width.
 116    *
 117    * Since: 3.0
 118    */
 119   pspec = g_param_spec_enum ("hscroll-policy",
 120                              P_("Horizontal Scrollable Policy"),
 121                              P_("How the size of the content should be determined"),
 122                              GTK_TYPE_SCROLLABLE_POLICY,
 123                              GTK_SCROLL_MINIMUM,
 124                              GTK_PARAM_READWRITE);
 125   g_object_interface_install_property (iface, pspec);
 126
 127   /**
 128    * GtkScrollable:vscroll-policy:
 129    *
 130    * Determines whether vertical scrolling should commence once the scrollable
 131    * widget is allocated less than it's minimum height or less than it's natural height.
 132    *
 133    * Since: 3.0
 134    */
 135   pspec = g_param_spec_enum ("vscroll-policy",
 136                              P_("Vertical Scrollable Policy"),
 137                              P_("How the size of the content should be determined"),
 138                              GTK_TYPE_SCROLLABLE_POLICY,
 139                              GTK_SCROLL_MINIMUM,
 140                              GTK_PARAM_READWRITE);
 141   g_object_interface_install_property (iface, pspec);
 142 }
 143
 144 /**
 145  * gtk_scrollable_get_hadjustment:
 146  * @scrollable: a #GtkScrollable
 147  *
 148  * Retrieves the #GtkAdjustment, used for horizontal scrolling.
 149  *
 150  * Return value: (transfer none): horizontal #GtkAdjustment.
 151  *
 152  * Since: 3.0
 153  **/
 154 GtkAdjustment *
 155 gtk_scrollable_get_hadjustment (GtkScrollable *scrollable)
 156 {
 157   GtkAdjustment *adj = NULL;
 158
 159   g_return_val_if_fail (GTK_IS_SCROLLABLE (scrollable), NULL);
 160
 161   g_object_get (scrollable, "hadjustment", &adj, NULL);
 162
 163   /* Horrid hack; g_object_get() returns a new reference but
 164    * that contradicts the memory management conventions
 165    * for accessors.
 166    */
 167   if (adj)
 168     g_object_unref (adj);
 169
 170   return adj;
 171 }
 172
 173 /**
 174  * gtk_scrollable_set_hadjustment:
 175  * @scrollable: a #GtkScrollable
 176  * @hadjustment: (allow-none): a #GtkAdjustment
 177  *
 178  * Sets the horizontal adjustment of the #GtkScrollable.
 179  *
 180  * Since: 3.0
 181  **/
 182 void
 183 gtk_scrollable_set_hadjustment (GtkScrollable *scrollable,
 184                                 GtkAdjustment *hadjustment)
 185 {
 186   g_return_if_fail (GTK_IS_SCROLLABLE (scrollable));
 187   g_return_if_fail (hadjustment == NULL || GTK_IS_ADJUSTMENT (hadjustment));
 188
 189   g_object_set (scrollable, "hadjustment", hadjustment, NULL);
 190 }
 191
 192 /**
 193  * gtk_scrollable_get_vadjustment:
 194  * @scrollable: a #GtkScrollable
 195  *
 196  * Retrieves the #GtkAdjustment, used for vertical scrolling.
 197  *
 198  * Return value: (transfer none): vertical #GtkAdjustment.
 199  *
 200  * Since: 3.0
 201  **/
 202 GtkAdjustment *
 203 gtk_scrollable_get_vadjustment (GtkScrollable *scrollable)
 204 {
 205   GtkAdjustment *adj = NULL;
 206
 207   g_return_val_if_fail (GTK_IS_SCROLLABLE (scrollable), NULL);
 208
 209   g_object_get (scrollable, "vadjustment", &adj, NULL);
 210
 211   /* Horrid hack; g_object_get() returns a new reference but
 212    * that contradicts the memory management conventions
 213    * for accessors.
 214    */
 215   if (adj)
 216     g_object_unref (adj);
 217
 218   return adj;
 219 }
 220
 221 /**
 222  * gtk_scrollable_set_vadjustment:
 223  * @scrollable: a #GtkScrollable
 224  * @vadjustment: (allow-none): a #GtkAdjustment
 225  *
 226  * Sets the vertical adjustment of the #GtkScrollable.
 227  *
 228  * Since: 3.0
 229  **/
 230 void
 231 gtk_scrollable_set_vadjustment (GtkScrollable *scrollable,
 232                                 GtkAdjustment *vadjustment)
 233 {
 234   g_return_if_fail (GTK_IS_SCROLLABLE (scrollable));
 235   g_return_if_fail (vadjustment == NULL || GTK_IS_ADJUSTMENT (vadjustment));
 236
 237   g_object_set (scrollable, "vadjustment", vadjustment, NULL);
 238 }
 239
 240
 241 /**
 242  * gtk_scrollable_get_hscroll_policy:
 243  * @scrollable: a #GtkScrollable
 244  *
 245  * Gets the horizontal #GtkScrollablePolicy.
 246  *
 247  * Return value: The horizontal #GtkScrollablePolicy.
 248  *
 249  * Since: 3.0
 250  **/
 251 GtkScrollablePolicy
 252 gtk_scrollable_get_hscroll_policy (GtkScrollable *scrollable)
 253 {
 254   GtkScrollablePolicy policy;
 255
 256   g_return_val_if_fail (GTK_IS_SCROLLABLE (scrollable), GTK_SCROLL_MINIMUM);
 257
 258   g_object_get (scrollable, "hscroll-policy", &policy, NULL);
 259
 260   return policy;
 261 }
 262
 263 /**
 264  * gtk_scrollable_set_hscroll_policy:
 265  * @scrollable: a #GtkScrollable
 266  * @policy: the horizontal #GtkScrollablePolicy
 267  *
 268  * Sets the #GtkScrollablePolicy to determine whether
 269  * horizontal scrolling should commence below minimum or
 270  * below natural width.
 271  *
 272  * Since: 3.0
 273  **/
 274 void
 275 gtk_scrollable_set_hscroll_policy (GtkScrollable       *scrollable,
 276                                    GtkScrollablePolicy  policy)
 277 {
 278   g_return_if_fail (GTK_IS_SCROLLABLE (scrollable));
 279
 280   g_object_set (scrollable, "hscroll-policy", policy, NULL);
 281 }
 282
 283 /**
 284  * gtk_scrollable_get_vscroll_policy:
 285  * @scrollable: a #GtkScrollable
 286  *
 287  * Gets the vertical #GtkScrollablePolicy.
 288  *
 289  * Return value: The vertical #GtkScrollablePolicy.
 290  *
 291  * Since: 3.0
 292  **/
 293 GtkScrollablePolicy
 294 gtk_scrollable_get_vscroll_policy (GtkScrollable *scrollable)
 295 {
 296   GtkScrollablePolicy policy;
 297
 298   g_return_val_if_fail (GTK_IS_SCROLLABLE (scrollable), GTK_SCROLL_MINIMUM);
 299
 300   g_object_get (scrollable, "vscroll-policy", &policy, NULL);
 301
 302   return policy;
 303 }
 304
 305 /**
 306  * gtk_scrollable_set_vscroll_policy:
 307  * @scrollable: a #GtkScrollable
 308  * @policy: the vertical #GtkScrollablePolicy
 309  *
 310  * Sets the #GtkScrollablePolicy to determine whether
 311  * vertical scrolling should commence below minimum or
 312  * below natural height.
 313  *
 314  * Since: 3.0
 315  **/
 316 void
 317 gtk_scrollable_set_vscroll_policy (GtkScrollable       *scrollable,
 318                                    GtkScrollablePolicy  policy)
 319 {
 320   g_return_if_fail (GTK_IS_SCROLLABLE (scrollable));
 321
 322   g_object_set (scrollable, "vscroll-policy", policy, NULL);
 323 }