#ifndef __DALI_TOOLKIT_INTERNAL_ITEM_VIEW_H__
#define __DALI_TOOLKIT_INTERNAL_ITEM_VIEW_H__
-//
-// Copyright (c) 2014 Samsung Electronics Co., Ltd.
-//
-// Licensed under the Flora License, Version 1.0 (the License);
-// you may not use this file except in compliance with the License.
-// You may obtain a copy of the License at
-//
-// http://floralicense.org/license/
-//
-// Unless required by applicable law or agreed to in writing, software
-// distributed under the License is distributed on an AS IS BASIS,
-// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-// See the License for the specific language governing permissions and
-// limitations under the License.
-//
+/*
+ * Copyright (c) 2014 Samsung Electronics Co., Ltd.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ *
+ */
// EXTERNAL INCLUDES
-#include <dali/dali.h>
+#include <dali/public-api/adaptor-framework/timer.h>
+#include <dali/public-api/animation/animation.h>
+#include <dali/public-api/object/property-notification.h>
+#include <dali/devel-api/common/map-wrapper.h>
// INTERNAL INCLUDES
#include <dali-toolkit/public-api/controls/control-impl.h>
#include <dali-toolkit/public-api/controls/scrollable/item-view/item-view.h>
#include <dali-toolkit/public-api/controls/scrollable/item-view/item-layout.h>
-#include <dali-toolkit/public-api/controls/scrollable/scroll-connector.h>
#include <dali-toolkit/internal/controls/scrollable/scrollable-impl.h>
#include <dali-toolkit/public-api/focus-manager/keyboard-focus-manager.h>
-#include <dali-toolkit/internal/controls/scrollable/scroll-view/scroll-overshoot-indicator-impl.h>
namespace Dali
{
typedef IntrusivePtr<ItemView> ItemViewPtr;
/**
- * ItemPool is container of Actor/ID pairs stored by ItemView
- */
-class ItemPool
-{
-public: // types
-
- typedef std::pair<unsigned int, Actor> IDKeyPair;
- typedef std::map<unsigned int, Actor> IDKeyContainer;
- typedef IDKeyContainer::iterator IDKeyIter;
- typedef IDKeyContainer::const_iterator IDKeyConstIter;
-
- typedef std::pair<Actor, unsigned int> ActorKeyPair;
- typedef std::map<Actor, unsigned int> ActorKeyContainer;
- typedef ActorKeyContainer::iterator ActorKeyIter;
- typedef ActorKeyContainer::const_iterator ActorKeyConstIter;
-
-public: // Construction & Destruction
-
- /**
- * Constructor
- * @param[in] itemView A reference to the ItemView class that owns this.
- */
- ItemPool(ItemView& itemView)
- : mItemView(itemView)
- {
- }
-
-public: // Methods
-
- /**
- * Returns a const reference to the IDKeyContainer whose key is based on the Item ID.
- * @return Const reference to IDKeyContainer.
- */
- const IDKeyContainer& GetIDKeyContainer() const
- {
- return mIdKeyContainer;
- }
-
- /**
- * Returns a const reference to the ActorKeyContainer whose key is based on the Actor.
- * @return Const reference to IDKeyContainer.
- */
- const ActorKeyContainer& GetActorKeyContainer() const
- {
- return mActorKeyContainer;
- }
-
- /**
- * Add a range of items to the ItemPool, if they are not already in the ItemPool.
- * @param[in] scrollingTowardsLast Should be true if scrolling towards the last item in the range.
- * @param[in] range The range of Item IDs to associate with the new actors.
- * @param[in] targetSize The current size of the layout.
- */
- void AddItems(bool scrollingTowardsLast, ItemRange range, const Vector3& targetSize);
-
- /**
- * Remove items from the ItemPool that are outside the given range.
- * @param[in] range The range of required items.
- */
- void RemoveItems(ItemRange range);
-
- /**
- * Remove an item from the ItemPool.
- * @param[in] itemId The item to remove.
- * @return Whether the item is found and removed or not.
- */
- bool RemoveItem(unsigned int itemId);
-
-private:
-
- /**
- * Adds an item, if not already in the ItemPool.
- * @param[in] itemId The item to add.
- * @param[in] targetSize The target size of the layout.
- */
- void AddItem(unsigned int itemId, const Vector3& targetSize);
-
-private:
-
- IDKeyContainer mIdKeyContainer;
- ActorKeyContainer mActorKeyContainer;
- ItemView& mItemView;
-};
-
-/**
* ItemView is a scrollable layout container.
* Multiple ItemLayouts may be provided, to determine the logical position of each item a layout.
* Actor-ID pairs are provided from a shared ItemFactory, to display the currently visible items.
{
public:
+ // Signals
+ typedef Toolkit::ItemView::LayoutActivatedSignalType LayoutActivatedSignalType;
+
+public:
+
/**
* Create a new ItemView.
* @param[in] factory The factory which provides ItemView with items.
static Dali::Toolkit::ItemView New(ItemFactory& factory);
/**
- * @copydoc Toolkit::ItemView::GetScrollConnector
- */
- Dali::Toolkit::ScrollConnector GetScrollConnector() const;
-
- /**
* @copydoc Toolkit::ItemView::GetLayoutCount
*/
unsigned int GetLayoutCount() const;
float GetMinimumSwipeDistance() const;
/**
- * @copydoc Toolkit::ItemView::SetMouseWheelScrollDistanceStep
+ * @copydoc Toolkit::ItemView::SetWheelScrollDistanceStep
*/
- void SetMouseWheelScrollDistanceStep(float step);
+ void SetWheelScrollDistanceStep(float step);
/**
- * @copydoc Toolkit::ItemView::GetMouseWheelScrollDistanceStep
+ * @copydoc Toolkit::ItemView::GetWheelScrollDistanceStep
*/
- float GetMouseWheelScrollDistanceStep() const;
+ float GetWheelScrollDistanceStep() const;
/**
* @copydoc Toolkit::ItemView::SetAnchoring
/**
* @copydoc Toolkit::ItemView::SetRefreshInterval
*/
- void SetRefreshInterval(unsigned int intervalMilliseconds);
+ void SetRefreshInterval(float intervalLayoutPositions);
/**
* @copydoc Toolkit::ItemView::GetRefreshInterval
*/
- unsigned int GetRefreshInterval() const;
+ float GetRefreshInterval() const;
+
+ /**
+ * @copydoc Toolkit::ItemView::Refresh
+ */
+ void Refresh();
/**
* @copydoc Toolkit::ItemView::GetItem
unsigned int GetItemId(Actor actor) const;
/**
+ * @copydoc Toolkit::ItemView::InsertItem
+ */
+ void InsertItem(Item newItem, float durationSeconds);
+
+ /**
+ * @copydoc Toolkit::ItemView::InsertItem
+ */
+ void InsertItems(const ItemContainer& newItems, float durationSeconds);
+
+ /**
* @copydoc Toolkit::ItemView::RemoveItem
*/
- void RemoveItem(unsigned int itemId, float durationSeconds);
+ void RemoveItem(ItemId itemId, float durationSeconds);
/**
- * @copydoc Toolkit::Scrollable::GetDomainSize
+ * @copydoc Toolkit::ItemView::InsertItem
*/
- Vector3 GetDomainSize() const;
+ void RemoveItems(const ItemIdContainer& itemIds, float durationSeconds);
+
+ /**
+ * @copydoc Toolkit::ItemView::InsertItem
+ */
+ void ReplaceItem(Item replacementItem, float durationSeconds);
+
+ /**
+ * @copydoc Toolkit::ItemView::InsertItem
+ */
+ void ReplaceItems(const ItemContainer& replacementItems, float durationSeconds);
/**
* @copydoc Toolkit::Scrollable::GetCurrentScrollPosition
*/
- Vector3 GetCurrentScrollPosition() const;
+ Vector2 GetCurrentScrollPosition() const;
/**
* @copydoc Toolkit::Scrollable::AddOverlay()
void RemoveOverlay(Actor actor);
/**
- * @copydoc Toolkit::Scrollable::ScrollTo(const Vector3& position, float duration)
+ * @copydoc Toolkit::Scrollable::ScrollTo(const Vector2& position, float duration)
*/
- void ScrollTo(const Vector3& position, float duration);
+ void ScrollTo(const Vector2& position, float duration);
-public: // Used By ItemPool
+ /**
+ * @copydoc Toolkit::Internal::Scrollable::SetOvershootEffectColor
+ */
+ void SetOvershootEffectColor( const Vector4& color );
/**
- * Called by the ItemPool when it wishes to create an actor from the ItemFactory with the
- * specified ItemId.
- * @param[in] itemId The Item ID of the actor to create.
+ * @brief Set whether to enable automatic refresh or not. When refresh is disabled,
+ * ItemView will not automatically refresh the cache in the given interval when the
+ * layout position is changed. This is useful in some cases, for example, automatic
+ * refresh is not needed during fast scrolling, otherwise it will cache unneeded
+ * items when the layout position changes quickly.
+ *
+ * @param[in] enabled True to enable automatic refresh or false to disable it.
*/
- Actor CreateActor(unsigned int itemId);
+ void SetRefreshEnabled(bool enabled);
/**
- * Called by the ItemPool when an actor is added to the ItemPool.
- * @param[in] actor The actor that has been added.
- * @param[in] itemId The associated Item ID.
- * @param[in] targetSize The target size that was specified upon addition.
+ * @brief Helper to perform the refresh.
+ *
+ * @param[in] currentLayoutPosition The current layout position.
+ * @param[in] cacheExtra Whether to cache extra items during refresh.
*/
- void ActorAddedToItemPool(Actor actor, unsigned int itemId, const Vector3& targetSize);
+ void DoRefresh(float currentLayoutPosition, bool cacheExtra);
/**
- * Called by the ItemPool when an actor with the specified itemId is about to be removed from the
- * ItemPool.
- * @param[in] actor The actor about to be removed.
- * @param[in] itemId The associated Item ID.
+ * @copydoc Toolkit::ItemView::SetItemsParentOrigin
*/
- void ActorRemovedFromItemPool(Actor actor, unsigned int itemId);
+ void SetItemsParentOrigin( const Vector3& parentOrigin );
+
+ /**
+ * @copydoc Toolkit::ItemView::GetItemsParentOrigin
+ */
+ Vector3 GetItemsParentOrigin() const;
+
+ /**
+ * @copydoc Toolkit::ItemView::SetItemsAnchorPoint
+ */
+ void SetItemsAnchorPoint( const Vector3& anchorPoint );
+
+ /**
+ * @copydoc Toolkit::ItemView::GetItemsAnchorPoint
+ */
+ Vector3 GetItemsAnchorPoint() const;
+
+ /**
+ * @copydoc Toolkit::ItemView::GetItemsRange
+ */
+ void GetItemsRange(ItemRange& range);
+
+ /**
+ * @copydoc Toolkit::ItemView::LayoutActivatedSignal()
+ */
+ LayoutActivatedSignalType& LayoutActivatedSignal()
+ {
+ return mLayoutActivatedSignal;
+ }
+
+ /**
+ * Connects a callback function with the object's signals.
+ * @param[in] object The object providing the signal.
+ * @param[in] tracker Used to disconnect the signal.
+ * @param[in] signalName The signal to connect to.
+ * @param[in] functor A newly allocated FunctorDelegate.
+ * @return True if the signal was connected.
+ * @post If a signal was connected, ownership of functor was passed to CallbackBase. Otherwise the caller is responsible for deleting the unused functor.
+ */
+ static bool DoConnectSignal( BaseObject* object, ConnectionTrackerInterface* tracker, const std::string& signalName, FunctorDelegate* functor );
+
+ //properties
+
+ /**
+ * Called when a property of an object of this type is set.
+ * @param[in] object The object whose property is set.
+ * @param[in] index The property index.
+ * @param[in] value The new property value.
+ */
+ static void SetProperty( BaseObject* object, Property::Index index, const Property::Value& value );
+
+ /**
+ * Called to retrieve a property of an object of this type.
+ * @param[in] object The object whose property is to be retrieved.
+ * @param[in] index The property index.
+ * @return The current value of the property.
+ */
+ static Property::Value GetProperty( BaseObject* object, Property::Index index );
+
+ /**
+ * Performs actions as requested using the action name.
+ * @param[in] object The object on which to perform the action.
+ * @param[in] actionName The action to perform.
+ * @param[in] attributes The attributes with which to perfrom this action.
+ * @return true if action has been accepted by this control
+ */
+ static bool DoAction( BaseObject* object, const std::string& actionName, const Property::Map& attributes );
+
+ /**
+ * Helper for DoAction( ACTION_STOP_SCROLLING ).
+ */
+ void DoStopScrolling();
+
+private:
+
+ /**
+ * Remove an Actor if found in the ItemPool.
+ * @param[in] itemId The item to remove.
+ * @return True if the remaining actors were reordered.
+ */
+ bool RemoveActor( unsigned int itemId );
+
+ /**
+ * Remove any Actors outside a given range.
+ * @param[in] @param[in] range The range of required items.
+ */
+ void RemoveActorsOutsideRange( ItemRange range );
+
+ /**
+ * Add a range of Actors, if they are not already in the ItemPool.
+ * @param[in] range The range of Item IDs to associate with the new actors.
+ * @param[in] layoutSize The layout-size.
+ */
+ void AddActorsWithinRange( ItemRange range, const Vector3& layoutSize );
+
+ /**
+ * Add a new Actor, if not already in the ItemPool.
+ * @param[in] item The ID for the new item.
+ * @param[in] layoutSize The layout-size.
+ */
+ void AddNewActor( ItemId item, const Vector3& layoutSize );
+
+ /**
+ * Apply the constraints etc. that are required for ItemView children.
+ * @param[in] item The item to setup.
+ * @param[in] layoutSize The layout-size.
+ */
+ void SetupActor( Item item, const Vector3& layoutSize );
+
+ /**
+ * Remove the Actor from the ItemPool and notify the ItemFactory the actor has been released by ItemView.
+ * @param[in] item The ID for the item to be released.
+ * @param[in] actor The actor to be removed from ItemView.
+ */
+ void ReleaseActor( ItemId item, Actor actor );
private: // From CustomActorImpl
/**
- * From CustomActorImpl; called after a touch-signal is received by the owning actor.
- * @param[in] event The touch event.
- * @return True if the event should be consumed.
+ * From CustomActorImpl; called after a child has been added to the owning actor.
+ * @param[in] child The child which has been added.
*/
- virtual bool OnTouchEvent(const TouchEvent& event);
+ virtual void OnChildAdd(Actor& child);
/**
- * From CustomActorImpl; called after a mouse-wheel-event is received by the owning actor.
- * @param[in] event The mouse wheel event.
+ * From CustomActorImpl; called after a wheel-event is received by the owning actor.
+ * @param[in] event The wheel event.
* @return True if the event should be consumed.
*/
- virtual bool OnMouseWheelEvent(const MouseWheelEvent& event);
+ virtual bool OnWheelEvent(const WheelEvent& event);
-private: // From ControlImpl
+private: // From Control
/**
* @copydoc Toolkit::Control::OnInitialize()
/**
* @copydoc Toolkit::Control::GetNextKeyboardFocusableActor()
*/
- virtual Actor GetNextKeyboardFocusableActor(Actor actor, Control::KeyboardFocusNavigationDirection direction, bool loopEnabled);
+ virtual Actor GetNextKeyboardFocusableActor(Actor actor, Toolkit::Control::KeyboardFocus::Direction direction, bool loopEnabled);
/**
* @copydoc Toolkit::Control::OnKeyboardFocusChangeCommitted()
ItemView& operator=(const ItemView& rhs);
/**
- * Helper to apply constraints to an actor.
- * @param[in] actor The actor to constrain.
- * @param[in] layout The active layout.
- * @param[in] itemId The ID of the item represented by the actor.
+ * Helper to re-apply all the constraints after items have been inserted, removed etc.
* @param[in] durationSeconds The time taken to fully constrain the actors.
*/
- void ApplyConstraints(Actor& actor, ItemLayout& layout, unsigned int itemId, float durationSeconds);
+ void ReapplyAllConstraints();
+
+ /**
+ * Helper to relayout after item(s) are removed.
+ */
+ void OnItemsRemoved();
/**
* Helper to remove items outside a given range.
* @param[in] range The range of items.
* @param[in] reserveExtra True if reserve items should be included.
*/
- ItemRange GetItemRange(ItemLayout& layout, const Vector3& layoutSize, bool reserveExtra);
+ ItemRange GetItemRange(ItemLayout& layout, const Vector3& layoutSize, float layoutPosition, bool reserveExtra);
// Input Handling
/**
- * Helper to handle pressed (Down) events.
- * @param[in] x The X coordinate of the touch event.
- * @param[in] y The Y coordinate of the touch event.
- * @param[in] timeMs The time-stamp of the touch event.
- */
- void OnPressed(float x, float y, unsigned long timeMs);
-
- /**
* Helper to clamp the first-item position when dragging/swiping.
* @param[in] targetPosition The target position of the drag etc.
* @param[in] targetSize The target ItemView & layout size.
* @param[in] layout The current layout.
+ * @param[in] updateOvershoot False stops the current overshoot value from being clamped also.
* @return The clamped first-item position.
*/
- float ClampFirstItemPosition(float targetPosition, const Vector3& targetSize, ItemLayout& layout);
+ float ClampFirstItemPosition(float targetPosition, const Vector3& targetSize, ItemLayout& layout, bool updateOvershoot = true);
+
+ /**
+ * Called after a touch-signal is received by the owning actor.
+ * @param[in] actor The touched actor.
+ * @param[in] touch The touch information.
+ * @return True if the event should be consumed.
+ */
+ bool OnTouch( Actor actor, const TouchData& touch );
/**
* Called upon pan gesture event.
*
* @param[in] gesture The gesture event.
*/
- void OnPan(PanGesture pan);
+ void OnPan( const PanGesture& pan );
/**
* Helper to handle anchoring animations.
void OnScrollFinished(Animation& animation);
/**
+ * Callback from layout activation scroll animations
+ * @param[in] animation The scroll-animation which has finished.
+ */
+ void OnLayoutActivationScrollFinished(Animation& animation);
+
+ /**
* Called by animation system when overshoot has finished animating to maximum (either -1.0f or 1.0f)
*
* @param[in] animation the animation that has finished
void OnOvershootOnFinished(Animation& animation);
/**
- * Helper to start the refresh timer.
- */
- void StartRefreshTimer();
-
- /**
- * Helper to cancel the refresh timer.
- */
- void CancelRefreshTimer();
-
- /**
- * Refresh the ItemView; this is called after a timeout when scrolling.
- * During a refresh, ItemFactory::NewItem() will be called to create newly visible items.
- * @return True if the refresh timer should be kept running.
- */
- bool OnRefreshTick();
-
- /**
- * This is called after a timeout when no new mouse wheel event is received for a certain period of time.
+ * This is called after a timeout when no new wheel event is received for a certain period of time.
* @return will return false; one-shot timer.
*/
- bool OnMouseWheelEventFinished();
+ bool OnWheelEventFinished();
/**
* Stops and removes animation if exists.
void RemoveAnimation(Animation& animation);
/**
- * Helper to apply constraints to the overshoot overlay actor.
+ * @copydoc Toolkit::Internal::Scrollable::EnableScrollOvershoot
*/
- void ApplyOvershootOverlayConstraints();
+ virtual void EnableScrollOvershoot( bool enable );
/**
* Helper to calculate the scroll overshoot according to the pan gesture displacement.
*/
void CalculateDomainSize(const Vector3& layoutSize);
-
/**
* Calculates whether we want to allow current item view to scroll.
* @param[in] layoutSize The current size of the layout.
*/
bool IsLayoutScrollable(const Vector3& layoutSize);
+ /**
+ * Callback when the current layout position of ItemView changes in both positive
+ * and negative directions by the specified amount. Refresh the ItemView to create
+ * newly visible items.
+ * @param[in] source the property notification that triggered this callback
+ */
+ void OnRefreshNotification(PropertyNotification& source);
+
private:
- ItemFactory& mItemFactory;
+ typedef std::map<unsigned int, Actor> ItemPool;
+ typedef ItemPool::iterator ItemPoolIter;
+ typedef ItemPool::const_iterator ConstItemPoolIter;
ItemPool mItemPool;
-
- ItemLayoutContainer mLayouts;
- ItemLayout* mActiveLayout;
-
+ ItemFactory& mItemFactory;
+ std::vector< ItemLayoutPtr > mLayouts; ///< Container of Dali::Toolkit::ItemLayout objects
+ Actor mOvershootOverlay; ///< The overlay actor for overshoot effect
Animation mResizeAnimation;
Animation mScrollAnimation;
- Animation mScrollSpeedAnimation;
Animation mScrollOvershootAnimation;
- bool mAnimatingOvershootOn; ///< whether we are currently animating overshoot to 1.0f/-1.0f (on) or to 0.0f (off)
- bool mAnimateOvershootOff; ///< whether we are currently animating overshoot to 1.0f/-1.0f (on) or to 0.0f (off)
+ Timer mWheelEventFinishedTimer; ///< The timer to determine whether there is no wheel event received for a certain period of time.
+ PropertyNotification mRefreshNotification; ///< Stores the property notification used for item view refresh
+ LayoutActivatedSignalType mLayoutActivatedSignal;
+ Vector3 mActiveLayoutTargetSize;
+ Vector3 mItemsParentOrigin;
+ Vector3 mItemsAnchorPoint;
+ Vector2 mTotalPanDisplacement;
+ ItemLayout* mActiveLayout;
- bool mAnchoringEnabled;
float mAnchoringDuration;
-
- Timer mRefreshTimer;
- int mRefreshIntervalMilliseconds;
- bool mRefreshOrderHint; ///< True if scrolling towards the last item
-
- // Input handling
-
+ float mRefreshIntervalLayoutPositions; ///< Refresh item view when the layout position changes by this interval in both positive and negative directions.
float mMinimumSwipeSpeed;
float mMinimumSwipeDistance;
- float mMouseWheelScrollDistanceStep; ///< The step of scroll distance in actor coordinates for each mouse wheel event received.
-
+ float mWheelScrollDistanceStep; ///< The step of scroll distance in actor coordinates for each wheel event received.
float mScrollDistance;
float mScrollSpeed;
- Vector2 mTotalPanDisplacement;
-
float mScrollOvershoot;
- bool mIsFlicking;
-
- Timer mMouseWheelEventFinishedTimer; ///< The timer to determine whether there is no mouse wheel event received for a certain period of time.
-
- Dali::Gesture::State mGestureState;
-
- ImageActor mOvershootOverlay; ///< The overlay actor for overshoot effect
- OvershootRippleEffect mOvershootEffect; ///< The vertex/fragment shader used to display the overshoot ripple effect
-
- Dali::Toolkit::ScrollConnector mScrollConnector; ///< Connects ItemView with scrollable components e.g. scroll bars
- Constrainable mScrollPositionObject; ///< From mScrollConnector
- Property::Index mPropertyPosition; ///< The physical position of the first item within the layout
- Property::Index mPropertyMinimumLayoutPosition; ///< The minimum valid layout position in the layout.
- Property::Index mPropertyScrollSpeed; ///< The current scroll speed of item view
- Property::Index mPropertyOvershoot; ///< The scroll overshoot (difference of the layout position before and after clamping)
+ Dali::Gesture::State mGestureState : 3;
+ bool mAnimatingOvershootOn : 1; ///< Whether we are currently animating overshoot to 1.0f/-1.0f (on) or to 0.0f (off)
+ bool mAnimateOvershootOff : 1; ///< Whether we are currently animating overshoot to 1.0f/-1.0f (on) or to 0.0f (off)
+ bool mAnchoringEnabled : 1;
+ bool mRefreshOrderHint : 1; ///< True if scrolling towards the last item
+ bool mIsFlicking : 1;
+ bool mAddingItems : 1;
+ bool mRefreshEnabled : 1; ///< Whether to refresh the cache automatically
+ bool mInAnimation : 1; ///< Keeps track of whether an animation is controlling the overshoot property.
};
} // namespace Internal