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