No issues found
1 /* -*- mode: C; c-file-style: "gnu"; indent-tabs-mode: nil; -*- */
2 /*
3 * st-scrollable.c: Scrollable interface
4 *
5 * Copyright 2008 OpenedHand
6 * Copyright 2009 Intel Corporation.
7 * Copyright 2010 Red Hat, Inc.
8 *
9 * This program is free software; you can redistribute it and/or modify it
10 * under the terms and conditions of the GNU Lesser General Public License,
11 * version 2.1, as published by the Free Software Foundation.
12 *
13 * This program is distributed in the hope it will be useful, but WITHOUT ANY
14 * WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
15 * FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for
16 * more details.
17 *
18 * You should have received a copy of the GNU Lesser General Public License
19 * along with this program. If not, see <http://www.gnu.org/licenses/>.
20 */
21
22 #include "st-scrollable.h"
23
24 /**
25 * SECTION:st-scrollable
26 * @short_description: A #ClutterActor that can be scrolled
27 *
28 * The #StScrollable interface is exposed by actors that support scrolling.
29 *
30 * The interface contains methods for getting and setting the adjustments
31 * for scrolling; these adjustments will be used to hook the scrolled
32 * position up to scrollbars or other external controls. When a #StScrollable
33 * is added to a parent container, the parent container is responsible
34 * for setting the adjustments. The parent container then sets the adjustments
35 * back to %NULL when the scrollable is removed.
36 *
37 * For #StScrollable supporting height-for-width size negotation, size
38 * negotation works as follows:
39 *
40 * In response to get_preferred_width(), the scrollable should report
41 * the minimum width at which horizontal scrolling is needed for the
42 * preferred width, and natural width of the actor when not
43 * horizontally scrolled as the natural width.
44 *
45 * The for_width passed into get_preferred_height() is the width at which
46 * the scrollable will be allocated; this will be smaller than the minimum
47 * width when scrolling horizontally, so the scrollable may want to adjust
48 * it up to the minimum width before computing a preferred height. (Other
49 * scrollables may want to fit as much content into the allocated area
50 * as possible and only scroll what absolutely needs to scroll - consider,
51 * for example, the line-wrapping behavior of a text editor where there
52 * is a long line without any spaces.) As for width, get_preferred_height()
53 * should return the minimum size at which no scrolling is needed for the
54 * minimum height, and the natural size of the actor when not vertically scrolled
55 * as the natural height.
56 *
57 * In allocate() the allocation box passed in will be actual allocated
58 * size of the actor so will be smaller than the reported minimum
59 * width and/or height when scrolling is present. Any scrollable actor
60 * must support being allocated at any size down to 0x0 without
61 * crashing, however if the actor has content around the scrolled area
62 * and has an absolute minimum size that's bigger than 0x0 its
63 * acceptable for it to misdraw between 0x0 and the absolute minimum
64 * size. It's up to the application author to avoid letting the user
65 * resize the scroll view small enough so that the scrolled area
66 * vanishes.
67 *
68 * In response to allocate, in addition to normal handling, the
69 * scrollable should also set the limits of the the horizontal and
70 * vertical adjustments that were set on it earlier. The standard
71 * settings are:
72 *
73 * lower: 0
74 * page_size: allocated size (width or height)
75 * upper: MAX (total size of the scrolled area,allocated_size)
76 * step_increment: natural row/column height or a fixed fraction of the page size
77 * page_increment: page_size - step_increment
78 */
79 static void
80 st_scrollable_base_init (gpointer g_iface)
81 {
82 static gboolean initialized = FALSE;
83
84 if (!initialized)
85 {
86 g_object_interface_install_property (g_iface,
87 g_param_spec_object ("hadjustment",
88 "StAdjustment",
89 "Horizontal adjustment",
90 ST_TYPE_ADJUSTMENT,
91 G_PARAM_READWRITE));
92
93 g_object_interface_install_property (g_iface,
94 g_param_spec_object ("vadjustment",
95 "StAdjustment",
96 "Vertical adjustment",
97 ST_TYPE_ADJUSTMENT,
98 G_PARAM_READWRITE));
99
100 initialized = TRUE;
101 }
102 }
103
104 GType
105 st_scrollable_get_type (void)
106 {
107 static GType type = 0;
108 if (type == 0)
109 {
110 static const GTypeInfo info =
111 {
112 sizeof (StScrollableInterface),
113 st_scrollable_base_init, /* base_init */
114 NULL,
115 };
116 type = g_type_register_static (G_TYPE_INTERFACE,
117 "StScrollable", &info, 0);
118 }
119 return type;
120 }
121
122 void
123 st_scrollable_set_adjustments (StScrollable *scrollable,
124 StAdjustment *hadjustment,
125 StAdjustment *vadjustment)
126 {
127 ST_SCROLLABLE_GET_INTERFACE (scrollable)->set_adjustments (scrollable,
128 hadjustment,
129 vadjustment);
130 }
131
132 /**
133 * st_scroll_bar_get_adjustments:
134 * @hadjustment: (transfer none) (out) (allow-none): location to store the horizontal adjustment, or %NULL
135 * @vadjustment: (transfer none) (out) (allow-none): location to store the vertical adjustment, or %NULL
136 *
137 * Gets the adjustment objects that store the offsets of the scrollable widget
138 * into its possible scrolling area.
139 */
140 void
141 st_scrollable_get_adjustments (StScrollable *scrollable,
142 StAdjustment **hadjustment,
143 StAdjustment **vadjustment)
144 {
145 ST_SCROLLABLE_GET_INTERFACE (scrollable)->get_adjustments (scrollable,
146 hadjustment,
147 vadjustment);
148 }