optional/dali-toolkit/public-api/controls/page-turn-view/page-turn-view.h

   1 #ifndef __DALI_TOOLKIT_PAGE_TURN_VIEW_H__
   2 #define __DALI_TOOLKIT_PAGE_TURN_VIEW_H__
   3
   4 //
   5 // Copyright (c) 2014 Samsung Electronics Co., Ltd.
   6 //
   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
  10 //
  11 //     http://floralicense.org/license/
  12 //
  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.
  18 //
  19
  20 // INTERNAL INCLUDES
  21 #include <dali-toolkit/public-api/controls/control.h>
  22
  23 namespace Dali DALI_IMPORT_API
  24 {
  25
  26 namespace Toolkit
  27 {
  28
  29 // Forward declarations
  30 class PageFactory;
  31
  32 namespace Internal DALI_INTERNAL
  33 {
  34 class PageTurnView;
  35 }
  36
  37 /**
  38  * PageTurnView is a base class of different mode of pageTurnViews ( portrait or landscape )
  39  * Page actors are provided from an external PageFactory
  40  * PanGesture is used to activate the page bending, streching and tuning forward/backward
  41  *
  42  * Signal usage: There are four signals. Two matching pairs for panning and page turning:
  43  * PagePanStarted/PagePanFinished and PageTurnStarted/PageTurnFinished. Panning relates to user interaction with
  44  * the screen while page turning refers to animation of the page. There are three scenarios for these
  45  * events: normal page turn (forwards or backwards), aborted page turn (forwards or backwards)
  46  * and pan with no animation. The order of events is as follows:
  47  * 1) Normal page turn: PagePanStarted -> PageTurnStarted direction -> PagePanFinished -> PageTurnFinished direction
  48  * 2) Aborted page turn: PagePanStarted -> PageTurnStarted direction -> PageTurnStarted opposite direction
  49  *                       -> PagePanFinished -> PageTurnFinished opposite direction
  50  * 3) Pan with no animation: PagePanStarted -> PagePanFinished
  51  * Pan with no animation will occur when the user touches the page in an area that does not start the
  52  * page turning.
  53  */
  54 class PageTurnView : public Control
  55 {
  56 public:
  57
  58   /**
  59    * Creates an empty PageTurnView handle. Only derived versions can be instantiated.
  60    * Calling member function with an uninitialized handle is not allowed.
  61    */
  62   PageTurnView();
  63
  64   /**
  65    * Copy constructor. Creates another handle that points to the same real object
  66    * @param[in] handle Handle to copy from
  67    */
  68   PageTurnView( const PageTurnView& handle );
  69
  70   /**
  71    * Assignment operator. Changes this handle to point to another real object
  72    */
  73   PageTurnView& operator=( const PageTurnView& handle );
  74
  75   /**
  76    * Virtual destructor.
  77    */
  78   virtual ~PageTurnView();
  79
  80   /**
  81    * Downcast an Object handle to PageTurnView.
  82    * If handle points to an PageTurnView the downcast produces valid handle.
  83    * If not the returned handle is left uninitialized.
  84    * @param[in] handle Handle to an object
  85    * @return handle to a PageTurnView or an uninitialized handle
  86    */
  87   static PageTurnView DownCast( BaseHandle handle );
  88
  89   /**
  90    * Set the spine shadow parameter to the shader effects
  91    * The two parameters are the major&minor radius (in pixels) to form an ellipse shape
  92    * The top-left quarter of this ellipse is used to calculate spine normal for simulating shadow
  93    * @param [in] spineShadowParameter The major&minor ellipse radius for the simulated spine shadow
  94    */
  95   void SetSpineShadowParameter( const Vector2& spineShadowParameter );
  96
  97   /**
  98    * Retrieve the spine shadow parameter of the shader effects
  99    * @return The major&minor ellipse radius for the simulated spine shadow
 100    */
 101   Vector2 GetSpineShadowParameter();
 102
 103   /*
 104    * Go to a specific page
 105    * @param[in] pageId The new current page index
 106    */
 107   void GoToPage( unsigned int pageId );
 108
 109   /**
 110    * Retrieve the index of the current Page
 111    * @return The index of the current page
 112    */
 113   unsigned int GetCurrentPage();
 114
 115   /**
 116    * Enter edit mode
 117    * Case 1, the page factory passes image actor into the view as page content, do nothing.
 118    * Case 2, the page factory passes an actor tree into the view as page content,
 119    *    the actor tree will receive the touch event in edit mode, and set the refresh rate of the off screen render task to always
 120    * @return an empty actor in case 1; the actor tree root of the current page
 121    */
 122   Actor EnterEditMode();
 123
 124   /**
 125    * Leave edit mode
 126    * Case 1, the page factory passes image actor into the view as page content, do nothing.
 127    * Case 2, the page factory passes an actor tree into the view as page content,
 128    *   the page actor will receive all the touch event, and set the refresh rage of the off screen render task to once.
 129    */
 130   void LeaveEditMode();
 131
 132   /**
 133    * Return the actor get hit in the actor tree of the current page by given the touch position on the PageTurnView
 134    * @param[in] screenCoordinates The hit position of the PageTurnView
 135    * @param[out] actorCoordinates The local hit position of the hitted actor
 136    * @return the hitted actor
 137    */
 138   Actor GetHitActor( Vector2& screenCoordinates, Vector2& actorCoordinates );
 139
 140   /**
 141    * Refresh all the cached pages by calling the render task to refresh.
 142    */
 143   void RefreshAll();
 144
 145   /**
 146    * Refresh current page by calling the render task to refresh
 147    */
 148   void RefreshCurrentPage();
 149
 150 public: //Signal
 151
 152   // Page Turned signal, with page index and boolean turning direction (true = forward, false = backward)
 153   typedef SignalV2< void ( PageTurnView, unsigned int, bool ) > PageTurnSignal;
 154   typedef SignalV2< void ( PageTurnView ) > PagePanSignal;
 155
 156   /**
 157    * Signal emitted when a page has started to turn over.
 158    * A callback of the following type may be connected:
 159    * @code
 160    *   void YourCallBackName( PageTurnView pageTurnView, unsigned int pageIndex, bool isTurningForward );
 161    * @endcode
 162    * @return The signal to connect to
 163    */
 164   PageTurnSignal& PageTurnStartedSignal();
 165
 166   /**
 167    * Signal emitted when a page has finished turning over.
 168    * A callback of the following type may be connected:
 169    * @code
 170    *   void YourCallBackName( PageTurnView pageTurnView, unsigned int pageIndex, bool isTurningForward );
 171    * @endcode
 172    * @return The signal to connect to
 173    */
 174   PageTurnSignal& PageTurnFinishedSignal();
 175
 176   /**
 177    * Signal emitted when a page pan has commenced
 178    * A callback of the following type may be connected:
 179    * @code
 180    *   void YourCallBackName( PageTurnView pageTurnView );
 181    * @endcode
 182    * @return The signal to connect to
 183    */
 184   PagePanSignal& PagePanStartedSignal();
 185
 186   /**
 187    * Signal emitted when a page pan has finished
 188    * A callback of the following type may be connected:
 189    * @code
 190    *   void YourCallBackName( PageTurnView pageTurnView );
 191    * @endcode
 192    * @return The signal to connect to
 193    */
 194   PagePanSignal& PagePanFinishedSignal();
 195
 196 public: // Not intended for application developers
 197
 198   /**
 199    * Creates a handle using the Toolkit::Internal implementation.
 200    * @param[in]  implementation  The Control implementation.
 201    */
 202   DALI_INTERNAL PageTurnView(Internal::PageTurnView& implementation);
 203
 204   /**
 205    * Allows the creation of this Control from an Internal::CustomActor pointer.
 206    * @param[in]  internal  A pointer to the internal CustomActor.
 207    */
 208   DALI_INTERNAL PageTurnView(Dali::Internal::CustomActor* internal);
 209 };
 210
 211 } // namespace Toolkit
 212
 213 } // namespace Dali
 214
 215 #endif /* __DALI_TOOLKIT_PAGE_TURN_VIEW_H__ */