2 * Copyright (C) 2008 Tadej Borovšak <tadeboro@gmail.com>
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.
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.
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/>.
19 * SECTION:gtkscrollable
20 * @Short_Description: An interface for scrollable widgets
21 * @Title: GtkScrollable
23 * #GtkScrollable is an interface that is implemented by widgets with native
26 * To implement this interface you should override the
27 * #GtkScrollable:hadjustment and #GtkScrollable:vadjustment properties.
30 * <title>Creating a scrollable widget</title>
32 * All scrollable widgets should do the following.
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.
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.
54 * When the parent allocates space to the scrollable child widget, the widget should update
55 * the adjustments' properties with new values.
60 * When any of the adjustments emits the #GtkAdjustment::value-changed signal,
61 * the scrollable widget should scroll its contents.
71 #include "gtkscrollable.h"
73 #include "gtkadjustment.h"
74 #include "gtkprivate.h"
75 #include "gtktypebuiltins.h"
78 G_DEFINE_INTERFACE (GtkScrollable, gtk_scrollable, G_TYPE_OBJECT)
81 gtk_scrollable_default_init (GtkScrollableInterface *iface)
86 * GtkScrollable:hadjustment:
88 * Horizontal #GtkAdjustment of the scrollable widget. This adjustment is
89 * shared between the scrollable widget and its parent.
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 "
99 GTK_PARAM_READWRITE | G_PARAM_CONSTRUCT);
100 g_object_interface_install_property (iface, pspec);
103 * GtkScrollable:vadjustment:
105 * Verical #GtkAdjustment of the scrollable widget. This adjustment is shared
106 * between the scrollable widget and its parent.
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 "
116 GTK_PARAM_READWRITE | G_PARAM_CONSTRUCT);
117 g_object_interface_install_property (iface, pspec);
120 * GtkScrollable:hscroll-policy:
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.
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,
132 GTK_PARAM_READWRITE);
133 g_object_interface_install_property (iface, pspec);
136 * GtkScrollable:vscroll-policy:
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.
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,
148 GTK_PARAM_READWRITE);
149 g_object_interface_install_property (iface, pspec);
153 * gtk_scrollable_get_hadjustment:
154 * @scrollable: a #GtkScrollable
156 * Retrieves the #GtkAdjustment used for horizontal scrolling.
158 * Return value: (transfer none): horizontal #GtkAdjustment.
163 gtk_scrollable_get_hadjustment (GtkScrollable *scrollable)
165 GtkAdjustment *adj = NULL;
167 g_return_val_if_fail (GTK_IS_SCROLLABLE (scrollable), NULL);
169 g_object_get (scrollable, "hadjustment", &adj, NULL);
171 /* Horrid hack; g_object_get() returns a new reference but
172 * that contradicts the memory management conventions
176 g_object_unref (adj);
182 * gtk_scrollable_set_hadjustment:
183 * @scrollable: a #GtkScrollable
184 * @hadjustment: (allow-none): a #GtkAdjustment
186 * Sets the horizontal adjustment of the #GtkScrollable.
191 gtk_scrollable_set_hadjustment (GtkScrollable *scrollable,
192 GtkAdjustment *hadjustment)
194 g_return_if_fail (GTK_IS_SCROLLABLE (scrollable));
195 g_return_if_fail (hadjustment == NULL || GTK_IS_ADJUSTMENT (hadjustment));
197 g_object_set (scrollable, "hadjustment", hadjustment, NULL);
201 * gtk_scrollable_get_vadjustment:
202 * @scrollable: a #GtkScrollable
204 * Retrieves the #GtkAdjustment used for vertical scrolling.
206 * Return value: (transfer none): vertical #GtkAdjustment.
211 gtk_scrollable_get_vadjustment (GtkScrollable *scrollable)
213 GtkAdjustment *adj = NULL;
215 g_return_val_if_fail (GTK_IS_SCROLLABLE (scrollable), NULL);
217 g_object_get (scrollable, "vadjustment", &adj, NULL);
219 /* Horrid hack; g_object_get() returns a new reference but
220 * that contradicts the memory management conventions
224 g_object_unref (adj);
230 * gtk_scrollable_set_vadjustment:
231 * @scrollable: a #GtkScrollable
232 * @vadjustment: (allow-none): a #GtkAdjustment
234 * Sets the vertical adjustment of the #GtkScrollable.
239 gtk_scrollable_set_vadjustment (GtkScrollable *scrollable,
240 GtkAdjustment *vadjustment)
242 g_return_if_fail (GTK_IS_SCROLLABLE (scrollable));
243 g_return_if_fail (vadjustment == NULL || GTK_IS_ADJUSTMENT (vadjustment));
245 g_object_set (scrollable, "vadjustment", vadjustment, NULL);
250 * gtk_scrollable_get_hscroll_policy:
251 * @scrollable: a #GtkScrollable
253 * Gets the horizontal #GtkScrollablePolicy.
255 * Return value: The horizontal #GtkScrollablePolicy.
260 gtk_scrollable_get_hscroll_policy (GtkScrollable *scrollable)
262 GtkScrollablePolicy policy;
264 g_return_val_if_fail (GTK_IS_SCROLLABLE (scrollable), GTK_SCROLL_MINIMUM);
266 g_object_get (scrollable, "hscroll-policy", &policy, NULL);
272 * gtk_scrollable_set_hscroll_policy:
273 * @scrollable: a #GtkScrollable
274 * @policy: the horizontal #GtkScrollablePolicy
276 * Sets the #GtkScrollablePolicy to determine whether
277 * horizontal scrolling should start below the minimum width or
278 * below the natural width.
283 gtk_scrollable_set_hscroll_policy (GtkScrollable *scrollable,
284 GtkScrollablePolicy policy)
286 g_return_if_fail (GTK_IS_SCROLLABLE (scrollable));
288 g_object_set (scrollable, "hscroll-policy", policy, NULL);
292 * gtk_scrollable_get_vscroll_policy:
293 * @scrollable: a #GtkScrollable
295 * Gets the vertical #GtkScrollablePolicy.
297 * Return value: The vertical #GtkScrollablePolicy.
302 gtk_scrollable_get_vscroll_policy (GtkScrollable *scrollable)
304 GtkScrollablePolicy policy;
306 g_return_val_if_fail (GTK_IS_SCROLLABLE (scrollable), GTK_SCROLL_MINIMUM);
308 g_object_get (scrollable, "vscroll-policy", &policy, NULL);
314 * gtk_scrollable_set_vscroll_policy:
315 * @scrollable: a #GtkScrollable
316 * @policy: the vertical #GtkScrollablePolicy
318 * Sets the #GtkScrollablePolicy to determine whether
319 * vertical scrolling should start below the minimum height or
320 * below the natural height.
325 gtk_scrollable_set_vscroll_policy (GtkScrollable *scrollable,
326 GtkScrollablePolicy policy)
328 g_return_if_fail (GTK_IS_SCROLLABLE (scrollable));
330 g_object_set (scrollable, "vscroll-policy", policy, NULL);