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