1 #ifndef __DALI_TOOLKIT_ITEM_VIEW_H__
2 #define __DALI_TOOLKIT_ITEM_VIEW_H__
5 // Copyright (c) 2014 Samsung Electronics Co., Ltd.
7 // Licensed under the Flora License, Version 1.0 (the License);
8 // you may not use this file except in compliance with the License.
9 // You may obtain a copy of the License at
11 // http://floralicense.org/license/
13 // Unless required by applicable law or agreed to in writing, software
14 // distributed under the License is distributed on an AS IS BASIS,
15 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
16 // See the License for the specific language governing permissions and
17 // limitations under the License.
21 * @addtogroup CAPI_DALI_FRAMEWORK
26 #include <dali/dali.h>
28 #include <dali-toolkit/public-api/controls/scrollable/scrollable.h>
30 namespace Dali DALI_IMPORT_API
36 namespace Internal DALI_INTERNAL
44 typedef IntrusivePtr<ItemLayout> ItemLayoutPtr;
47 * ItemView is a scrollable layout container.
48 * Multiple ItemLayouts may be provided, to determine the logical position of each item a layout.
49 * Actors are provided from an external ItemFactory, to display the currently visible items.
51 class ItemView : public Scrollable
56 * Create an uninitialized ItemView; this can be initialized with ItemView::New()
57 * Calling member functions with an uninitialized Dali::Object is not allowed.
64 ItemView( const ItemView& itemView );
67 * Assignment operator.
69 ItemView& operator=( const ItemView& itemView );
73 * Dali::Object derived classes typically do not contain member data.
78 * Create an initialized ItemView.
79 * @param[in] factory The factory which provides ItemView with items.
80 * @return A handle to a newly allocated Dali resource.
82 static ItemView New(ItemFactory& factory);
85 * Downcast an Object handle to ItemView. If handle points to a ItemView the
86 * downcast produces valid handle. If not the returned handle is left uninitialized.
87 * @param[in] handle Handle to an object
88 * @return handle to a ItemView or an uninitialized handle
90 static ItemView DownCast( BaseHandle handle );
93 * Query the number of layouts.
94 * @return The number of layouts.
96 unsigned int GetLayoutCount() const;
100 * @param[in] layout The layout.
102 void AddLayout(ItemLayout& layout);
106 * @pre layoutIndex is less than GetLayoutCount().
107 * @param[in] layoutIndex The index of one of the ItemView layouts.
109 void RemoveLayout(unsigned int layoutIndex);
113 * @pre layoutIndex is less than GetLayoutCount().
116 ItemLayoutPtr GetLayout(unsigned int layoutIndex) const;
119 * Retrieve the currently active layout, if any.
120 * @return The layout, or an uninitialized pointer if no layout is active.
122 ItemLayoutPtr GetActiveLayout() const;
125 * Retrieve the current layout-position of an item in the ItemView.
126 * @param[in] itemId The item identifier.
127 * @return The current layout-position.
129 float GetCurrentLayoutPosition(unsigned int itemId) const;
132 * Activate one of the layouts; this will resize the ItemView & relayout actors within the ItemView.
133 * This is done by applying constraints from the new layout, and removing constraints from the previous layout.
134 * @pre layoutIndex is less than GetLayoutCount().
135 * @pre durationSeconds is greater or equal to zero.
136 * @param[in] layoutIndex The index of one of the ItemView layouts.
137 * @param[in] targetSize The target ItemView & layout size.
138 * @param[in] durationSeconds The time taken to relayout in seconds (zero for immediate).
140 void ActivateLayout(unsigned int layoutIndex, Vector3 targetSize, float durationSeconds);
143 * Deactivate the current layout, if any.
144 * The constraints applied by the layout will be removed.
146 void DeactivateCurrentLayout();
149 * Set the minimum swipe speed in pixels per second; A pan gesture must exceed this to trigger a swipe.
150 * @param[in] speed The minimum swipe speed
152 void SetMinimumSwipeSpeed(float speed);
155 * Get the minimum swipe speed in pixels per second.
156 * @return The minimum swipe speed
158 float GetMinimumSwipeSpeed() const;
161 * Set the minimum swipe distance in actor coordinates; A pan gesture must exceed this to trigger a swipe.
162 * @param[in] distance The minimum swipe distance.
164 void SetMinimumSwipeDistance(float distance);
167 * Get the minimum swipe distance in actor coordinates.
168 * @return The minimum swipe distance
170 float GetMinimumSwipeDistance() const;
173 * Set the step of scroll distance in actor coordinates for each mouse wheel event received.
174 * @param[in] step The step of scroll distance(pixel).
176 void SetMouseWheelScrollDistanceStep(float step);
179 * Get the step of scroll distance in actor coordinates for each mouse wheel event received.
180 * @return The step of scroll distance(pixel)
182 float GetMouseWheelScrollDistanceStep() const;
185 * Set whether to enable the animation for the layout to scroll to its anchor position after
186 * dragging or swiping. The anchor position is the position where all the items in the layout
187 * are aligned to their closest rounded layout positions in integer.
188 * @param[in] enabled Whether the anchor animation is enabled or not.
190 void SetAnchoring(bool enabled);
193 * Get whether the anchor animation is enabled or not
194 * @return Whether the anchor animation is enabled or not.
196 bool GetAnchoring() const;
199 * Set the duration of the anchor animation in seconds. This is the time taken to reach the nearest
200 * anchor position after a drag or swipe gesture ends.
201 * @pre durationSeconds must be greater than zero.
202 * @param[in] durationSeconds The duration of the anchor animation in seconds.
204 void SetAnchoringDuration(float durationSeconds);
207 * Get the duration of the anchor animation in seconds
208 * @return The duration of the anchor animation
210 float GetAnchoringDuration() const;
213 * Scroll the current layout to a particular item.
214 * @pre durationSeconds must be zero or greater; zero means the layout should scroll to the particular item instantly.
215 * If calling this with zero second of duration immediately after calling ActivateLayout, it might not work unless
216 * the duration of relayout animation for ActivateLayout is also set to be zero.
217 * @param[in] itemId The ID of an item in the layout.
218 * @param[in] durationSeconds How long the scrolling takes in seconds.
220 void ScrollToItem(unsigned int itemId, float durationSeconds);
223 * Set the interval between refreshes, during which new items are requested from ItemFactory.
224 * @param[in] intervalMilliseconds The refresh interval in milliseconds.
226 void SetRefreshInterval(unsigned int intervalMilliseconds);
229 * Get the interval between refreshes in milliseconds.
230 * @return The refresh interval
232 unsigned int GetRefreshInterval() const;
235 * Given the Item ID, this returns the accompanying actor.
236 * @param[in] itemId The Item ID of the actor required.
237 * @return The Actor corresponding to the Item ID.
239 Actor GetItem(unsigned int itemId) const;
242 * Returns the Item ID of the specified actor.
243 * @param[in] actor The actor whose Item ID is required.
244 * @return The Item ID of the item.
245 * @pre The actor should be an item of ItemView.
247 unsigned int GetItemId(Actor actor) const;
250 * Removes an item with the given ID.
251 * @pre durationSeconds must be zero or greater; zero means when the item is deleted the remaining items
252 * will finish the relayout instantly.
253 * @param[in] itemId The Item ID of the item to remove.
254 * @param[in] durationSeconds How long the realyout takes in seconds after the item is deleted.
256 void RemoveItem(unsigned int itemId, float durationSeconds);
258 public: // Not intended for application developers
261 * Creates a handle using the Toolkit::Internal implementation.
262 * @param[in] implementation The Control implementation.
264 ItemView(Internal::ItemView& implementation);
267 * Allows the creation of this Control from an Internal::CustomActor pointer.
268 * @param[in] internal A pointer to the internal CustomActor.
270 ItemView( Dali::Internal::CustomActor* internal );
273 } // namespace Toolkit
280 #endif // __DALI_TOOLKIT_ITEM_VIEW_H__