1 /* |
|
2 * Copyright (c) 2007 Nokia Corporation and/or its subsidiary(-ies). |
|
3 * All rights reserved. |
|
4 * This component and the accompanying materials are made available |
|
5 * under the terms of "Eclipse Public License v1.0" |
|
6 * which accompanies this distribution, and is available |
|
7 * at the URL "http://www.eclipse.org/legal/epl-v10.html". |
|
8 * |
|
9 * Initial Contributors: |
|
10 * Nokia Corporation - initial contribution. |
|
11 * |
|
12 * Contributors: |
|
13 * |
|
14 * Description: Navigation interface for list-like widgets. |
|
15 * |
|
16 */ |
|
17 |
|
18 |
|
19 |
|
20 #ifndef I_ALFNAVIGATION_H |
|
21 #define I_ALFNAVIGATION_H |
|
22 |
|
23 #include <alf/ialfinterfacebase.h> |
|
24 |
|
25 namespace Alf |
|
26 { |
|
27 |
|
28 namespace alfnavigation |
|
29 { |
|
30 static const IfId ident = |
|
31 { |
|
32 0, "alfnavigation" |
|
33 }; |
|
34 } |
|
35 |
|
36 /** |
|
37 * An interface that defines functionality for navigation in a |
|
38 * one-dimensional array of items. In addition to the normal |
|
39 * one-dimansional behavior, a common use case is to have |
|
40 * a two-dimensional layout and navigation model for the items. |
|
41 * Therefore, both one- and two-dimensional navigation models are |
|
42 * supported by the interface. |
|
43 * |
|
44 * Since the logical behavior is decoupled from the presentation, |
|
45 * the navigation is controlled in terms of logical dimensions, |
|
46 * namely the primary and the secondary dimensions. The primary |
|
47 * dimension is the dimension in which the navigation space |
|
48 * expands when new items are inserted. In a one-dimensional layout, |
|
49 * only the primary dimension is needed. The secondary dimension |
|
50 * is used with two-dimensional layouts and navigation models. |
|
51 * The size of the navigation space in the secondary dimension |
|
52 * should be a constant. |
|
53 * |
|
54 * The navigation interface consists of navigation parameters, |
|
55 * scrolling parameters, and orientation parameters. The navigation |
|
56 * parameters are used to control the focused item in the logical |
|
57 * navigation events. The scrolling parameters are used to send |
|
58 * scrolling events according to the focused item. The orientation |
|
59 * parameters are used to convert directional navigation events |
|
60 * to the logical navigation events. In addition, the usage of |
|
61 * default navigation key events, i.e., arrow keys, can be enabled |
|
62 * or disabled. |
|
63 * |
|
64 * @lib alfwidgetmodel.lib |
|
65 * @since S60 ?S60_version |
|
66 * @status Draft |
|
67 */ |
|
68 class IAlfNavigation : public IAlfInterfaceBase |
|
69 { |
|
70 public: |
|
71 /** |
|
72 * Getter for the type identifier of this interface. |
|
73 * |
|
74 * @since S60 ?S60_version |
|
75 * @return A descriptor to identify the type of this interface. |
|
76 */ |
|
77 static inline const IfId& type() |
|
78 { |
|
79 return alfnavigation::ident; |
|
80 } |
|
81 |
|
82 /** |
|
83 * Getter for the index of the currently focused item. |
|
84 * |
|
85 * @since S60 ?S60_version |
|
86 * @return An index of the currently focused item. |
|
87 */ |
|
88 virtual int focusedIndex() const = 0; |
|
89 |
|
90 /** |
|
91 * Setter for the index of the currently focused item. |
|
92 * If the given index is outside the range of items, |
|
93 * the index is set to the first or the last index. |
|
94 * |
|
95 * @since S60 ?S60_version |
|
96 * @param aIndex The new index of the focused item. |
|
97 */ |
|
98 virtual void setFocusedIndex( int aIndex ) = 0; |
|
99 |
|
100 /** |
|
101 * Getter for the size of the page in primary dimension. |
|
102 * The page size is used for EEventNavigatePrimaryPageUp and |
|
103 * EEventNavigatePrimaryPageDown events, as well as for scrolling |
|
104 * in primary dimension. |
|
105 * |
|
106 * @since S60 ?S60_version |
|
107 * @return The page size in primary dimension. |
|
108 */ |
|
109 virtual int primaryPageSize() const = 0; |
|
110 |
|
111 /** |
|
112 * Getter for the size of the page in secondary dimension. |
|
113 * The page size is used for EEventNavigateSecondaryPageUp and |
|
114 * EEventNavigateSecondaryPageDown events, as well as for scrolling |
|
115 * in secondary dimension. |
|
116 * |
|
117 * @since S60 ?S60_version |
|
118 * @return The page size in secondary dimension. |
|
119 */ |
|
120 virtual int secondaryPageSize() const = 0; |
|
121 |
|
122 /** |
|
123 * Getter for the size of the navigation space in secondary dimension. |
|
124 * One step in the primary dimension changes the index of the focused |
|
125 * item by the secondary size. The size is also used for scrolling |
|
126 * in secondary dimension. The secondary size of a one-dimensional |
|
127 * list should be one. |
|
128 * |
|
129 * @since S60 ?S60_version |
|
130 * @return The size in secondary dimension. |
|
131 */ |
|
132 virtual int secondarySize() const = 0; |
|
133 |
|
134 /** |
|
135 * Getter for looping in primary dimension. |
|
136 * |
|
137 * @since S60 ?S60_version |
|
138 * @return <code>true</code> if the looping is enabled, |
|
139 * <code>false</code> otherwise. |
|
140 */ |
|
141 virtual bool primaryLooping() const = 0; |
|
142 |
|
143 /** |
|
144 * Getter for looping in secondary dimension. |
|
145 * |
|
146 * @since S60 ?S60_version |
|
147 * @return <code>true</code> if the looping is enabled, |
|
148 * <code>false</code> otherwise. |
|
149 */ |
|
150 virtual bool secondaryLooping() const = 0; |
|
151 |
|
152 /** |
|
153 * Set the navigation parameters for one-dimensional navigation. |
|
154 * The secondary size and the secondary page size are set to one, |
|
155 * to indicate that navigation and scrolling in secondary direction |
|
156 * is disabled. Also the secondary looping is disabled. |
|
157 * |
|
158 * @since S60 ?S60_version |
|
159 * @param aPrimaryPageSize The page size in primary dimension. |
|
160 * @param aPrimaryLooping Enable or disable looping. |
|
161 */ |
|
162 virtual void setNavigationParams( int aPrimaryPageSize, |
|
163 bool aPrimaryLooping ) = 0; |
|
164 |
|
165 /** |
|
166 * Set the navigation parameters for two-dimensional navigation. |
|
167 * The parameters determine the behavior of all navigation events. |
|
168 * Navigation and scrolling are supported in both dimensions. |
|
169 * If the secondary page size is equal to the size of the whole |
|
170 * navigation space, the scrolling in secondary dimension is disabled. |
|
171 * |
|
172 * @since S60 ?S60_version |
|
173 * @param aPrimaryPageSize The page size in primary dimension. |
|
174 * @param aPrimaryLooping Enable or disable looping. |
|
175 */ |
|
176 virtual void setNavigationParams( int aPrimaryPageSize, |
|
177 int aSecondarySize, |
|
178 int aSecondaryPageSize, |
|
179 bool aPrimaryLooping, |
|
180 bool aSecondaryLooping ) = 0; |
|
181 |
|
182 /** |
|
183 * Getter for scrolling distance in primary dimension. |
|
184 * The scrolling distance is the minimum number of items before |
|
185 * the first or the last visible item. For example, the scrolling |
|
186 * distance of one defines that the focus should never get to the |
|
187 * first or the last visible item, except in the beginning or the |
|
188 * end of the list. |
|
189 * |
|
190 * @since S60 ?S60_version |
|
191 * @return The scrolling distance in primary dimension. |
|
192 */ |
|
193 virtual int primaryScrollingDist() const = 0; |
|
194 |
|
195 /** |
|
196 * Getter for scrolling distance in secondary dimension. |
|
197 * |
|
198 * @since S60 ?S60_version |
|
199 * @return The scrolling distance in secondary dimension. |
|
200 */ |
|
201 virtual int secondaryScrollingDist() const = 0; |
|
202 |
|
203 /** |
|
204 * Set the scrolling distances for the list control. |
|
205 * The scrolling distances are used to determine when |
|
206 * to start scrolling. The scrolling distance of zero |
|
207 * indicates that the scrolling should start if the focus |
|
208 * is moved outside of the visible items. Similarly, |
|
209 * the scrolling distance of one indicates that the |
|
210 * scrolling should start when the first or the last |
|
211 * visible item is focused. |
|
212 * |
|
213 * @param aPrimaryScrollingDist The minimum number of items before the first |
|
214 * or the last visible item in primary dimension. |
|
215 * @param aSecondaryScrollingDist The minimum number of items before the first |
|
216 * or the last visible item in secondary dimension. |
|
217 * @since S60 ?S60_version |
|
218 */ |
|
219 virtual void setScrollingParams( int aPrimaryScrollingDist, |
|
220 int aSecondaryScrollingDist ) = 0; |
|
221 |
|
222 /** |
|
223 * Determine if the primary dimension on the screen is vertical. |
|
224 * This is used to convert directional navigation events to the |
|
225 * logical navigation events. |
|
226 * |
|
227 * @since S60 ?S60_version |
|
228 * @return <code>true</code> if the primary dimension is vertical, |
|
229 * <code>false</code> if the primary dimension is horizontal. |
|
230 */ |
|
231 virtual bool verticalPrimary() const = 0; |
|
232 |
|
233 /** |
|
234 * Determine if the indices in the navigation space |
|
235 * increase from left to right. This is used to determine |
|
236 * the direction of the horizontal navigation events. |
|
237 * |
|
238 * @since S60 ?S60_version |
|
239 * @return <code>true</code> if the indices increase from left to right, |
|
240 * <code>false</code> if the indices increase from right to left. |
|
241 */ |
|
242 virtual bool leftToRight() const = 0; |
|
243 |
|
244 /** |
|
245 * Determine if the indices in the navigation space |
|
246 * increase from up to down. This is used to determine |
|
247 * the direction of the vertical navigation events. |
|
248 * |
|
249 * @since S60 ?S60_version |
|
250 * @return <code>true</code> if the indices increase from up to down, |
|
251 * <code>false</code> if the indices increase from down to up. |
|
252 */ |
|
253 virtual bool upToDown() const = 0; |
|
254 |
|
255 /** |
|
256 * Set the orientation parameters. |
|
257 * The orientation parameters are used to convert directional |
|
258 * navigation events to logical navigation events. |
|
259 * |
|
260 * @since S60 ?S60_version |
|
261 * @param aVerticalPrimary Specify the orientation of the primary dimension. |
|
262 * @param aLeftToRight Specify the increasing order of horizontal indices. |
|
263 * @param aUpToDown Specify the increasing order of vertical indices. |
|
264 */ |
|
265 virtual void setOrientationParams( bool aVerticalPrimary, |
|
266 bool aLeftToRight, bool aUpToDown ) = 0; |
|
267 |
|
268 /** |
|
269 * Determine if the default key events are used for navigation. |
|
270 * |
|
271 * @since S60 ?S60_version |
|
272 * @return <code>true</code> if the default key events are used, |
|
273 * <code>false</code> otherwise. |
|
274 */ |
|
275 virtual bool defaultKeysEnabled() const = 0; |
|
276 |
|
277 /** |
|
278 * Enable or disable the default key events. |
|
279 * |
|
280 * @since S60 ?S60_version |
|
281 * @param aEnable The usage of the default key events. |
|
282 */ |
|
283 virtual void enableDefaultKeys( bool aEnable ) = 0; |
|
284 }; |
|
285 |
|
286 } // namespace Alf |
|
287 |
|
288 #endif // I_ALFNAVIGATION_H |
|
289 |
|
290 // End of File |
|