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, write to the
16 * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
17 * Boston, MA 02111-1307, USA.
21 * SECTION:gtkscrollable
22 * @Short_Description: An interface for scrollable widgets
23 * @Title: GtkScrollable
25 * #GtkScrollable is an interface that is implemented by widgets with native
28 * To implement this interface you should override the
29 * #GtkScrollable:hadjustment and #GtkScrollable:vadjustment properties.
32 * <title>Creating a scrollable widget</title>
34 * All scrollable widgets should do the following.
39 * When a parent widget sets the scrollable child widget's adjustments, the widget should populate the adjustments'
40 * #GtkAdjustment:lower, #GtkAdjustment:upper,
41 * #GtkAdjustment:step-increment, #GtkAdjustment:page-increment and
42 * #GtkAdjustment:page-size properties and connect to the
43 * #GtkAdjustment::value-changed signal.
48 * When the parent allocates space to the scrollable child widget, the widget should update
49 * the adjustments' properties with new values.
54 * When any of the adjustments emits the #GtkAdjustment::value-changed signal,
55 * the scrollable widget should scroll its contents.
65 #include "gtkscrollable.h"
66 #include "gtktypeutils.h"
67 #include "gtkprivate.h"
70 G_DEFINE_INTERFACE (GtkScrollable, gtk_scrollable, G_TYPE_OBJECT)
73 gtk_scrollable_default_init (GtkScrollableInterface *iface)
78 * GtkScrollable:hadjustment:
80 * Horizontal #GtkAdjustment of the scrollable widget. This adjustment is
81 * shared between the scrollable widget and its parent.
85 pspec = g_param_spec_object ("hadjustment",
86 P_("Horizontal adjustment"),
87 P_("Horizontal adjustment that is shared "
88 "between the scrollable widget and its "
91 GTK_PARAM_READWRITE | G_PARAM_CONSTRUCT);
92 g_object_interface_install_property (iface, pspec);
95 * GtkScrollable:vadjustment:
97 * Verical #GtkAdjustment of the scrollable widget. This adjustment is shared
98 * between the scrollable widget and its parent.
102 pspec = g_param_spec_object ("vadjustment",
103 P_("Vertical adjustment"),
104 P_("Vertical adjustment that is shared "
105 "between the scrollable widget and its "
108 GTK_PARAM_READWRITE | G_PARAM_CONSTRUCT);
109 g_object_interface_install_property (iface, pspec);
112 * GtkScrollable:hscroll-policy:
114 * Determines whether horizontal scrolling should start once the scrollable
115 * widget is allocated less than its minimum width or less than its natural width.
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,
124 GTK_PARAM_READWRITE);
125 g_object_interface_install_property (iface, pspec);
128 * GtkScrollable:vscroll-policy:
130 * Determines whether vertical scrolling should start once the scrollable
131 * widget is allocated less than its minimum height or less than its natural height.
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,
140 GTK_PARAM_READWRITE);
141 g_object_interface_install_property (iface, pspec);
145 * gtk_scrollable_get_hadjustment:
146 * @scrollable: a #GtkScrollable
148 * Retrieves the #GtkAdjustment used for horizontal scrolling.
150 * Return value: (transfer none): horizontal #GtkAdjustment.
155 gtk_scrollable_get_hadjustment (GtkScrollable *scrollable)
157 GtkAdjustment *adj = NULL;
159 g_return_val_if_fail (GTK_IS_SCROLLABLE (scrollable), NULL);
161 g_object_get (scrollable, "hadjustment", &adj, NULL);
163 /* Horrid hack; g_object_get() returns a new reference but
164 * that contradicts the memory management conventions
168 g_object_unref (adj);
174 * gtk_scrollable_set_hadjustment:
175 * @scrollable: a #GtkScrollable
176 * @hadjustment: (allow-none): a #GtkAdjustment
178 * Sets the horizontal adjustment of the #GtkScrollable.
183 gtk_scrollable_set_hadjustment (GtkScrollable *scrollable,
184 GtkAdjustment *hadjustment)
186 g_return_if_fail (GTK_IS_SCROLLABLE (scrollable));
187 g_return_if_fail (hadjustment == NULL || GTK_IS_ADJUSTMENT (hadjustment));
189 g_object_set (scrollable, "hadjustment", hadjustment, NULL);
193 * gtk_scrollable_get_vadjustment:
194 * @scrollable: a #GtkScrollable
196 * Retrieves the #GtkAdjustment used for vertical scrolling.
198 * Return value: (transfer none): vertical #GtkAdjustment.
203 gtk_scrollable_get_vadjustment (GtkScrollable *scrollable)
205 GtkAdjustment *adj = NULL;
207 g_return_val_if_fail (GTK_IS_SCROLLABLE (scrollable), NULL);
209 g_object_get (scrollable, "vadjustment", &adj, NULL);
211 /* Horrid hack; g_object_get() returns a new reference but
212 * that contradicts the memory management conventions
216 g_object_unref (adj);
222 * gtk_scrollable_set_vadjustment:
223 * @scrollable: a #GtkScrollable
224 * @vadjustment: (allow-none): a #GtkAdjustment
226 * Sets the vertical adjustment of the #GtkScrollable.
231 gtk_scrollable_set_vadjustment (GtkScrollable *scrollable,
232 GtkAdjustment *vadjustment)
234 g_return_if_fail (GTK_IS_SCROLLABLE (scrollable));
235 g_return_if_fail (vadjustment == NULL || GTK_IS_ADJUSTMENT (vadjustment));
237 g_object_set (scrollable, "vadjustment", vadjustment, NULL);
242 * gtk_scrollable_get_hscroll_policy:
243 * @scrollable: a #GtkScrollable
245 * Gets the horizontal #GtkScrollablePolicy.
247 * Return value: The horizontal #GtkScrollablePolicy.
252 gtk_scrollable_get_hscroll_policy (GtkScrollable *scrollable)
254 GtkScrollablePolicy policy;
256 g_return_val_if_fail (GTK_IS_SCROLLABLE (scrollable), GTK_SCROLL_MINIMUM);
258 g_object_get (scrollable, "hscroll-policy", &policy, NULL);
264 * gtk_scrollable_set_hscroll_policy:
265 * @scrollable: a #GtkScrollable
266 * @policy: the horizontal #GtkScrollablePolicy
268 * Sets the #GtkScrollablePolicy to determine whether
269 * horizontal scrolling should start below the minimum width or
270 * below the natural width.
275 gtk_scrollable_set_hscroll_policy (GtkScrollable *scrollable,
276 GtkScrollablePolicy policy)
278 g_return_if_fail (GTK_IS_SCROLLABLE (scrollable));
280 g_object_set (scrollable, "hscroll-policy", policy, NULL);
284 * gtk_scrollable_get_vscroll_policy:
285 * @scrollable: a #GtkScrollable
287 * Gets the vertical #GtkScrollablePolicy.
289 * Return value: The vertical #GtkScrollablePolicy.
294 gtk_scrollable_get_vscroll_policy (GtkScrollable *scrollable)
296 GtkScrollablePolicy policy;
298 g_return_val_if_fail (GTK_IS_SCROLLABLE (scrollable), GTK_SCROLL_MINIMUM);
300 g_object_get (scrollable, "vscroll-policy", &policy, NULL);
306 * gtk_scrollable_set_vscroll_policy:
307 * @scrollable: a #GtkScrollable
308 * @policy: the vertical #GtkScrollablePolicy
310 * Sets the #GtkScrollablePolicy to determine whether
311 * vertical scrolling should start below the minimum height or
312 * below the natural height.
317 gtk_scrollable_set_vscroll_policy (GtkScrollable *scrollable,
318 GtkScrollablePolicy policy)
320 g_return_if_fail (GTK_IS_SCROLLABLE (scrollable));
322 g_object_set (scrollable, "vscroll-policy", policy, NULL);