optional/dali-toolkit/public-api/transition-effects/cube-transition-effect.h

   1 #ifndef __DALI_TOOLKIT_CUBE_TRANSITION_EFFECT_H__
   2 #define __DALI_TOOLKIT_CUBE_TRANSITION_EFFECT_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/dali.h>
  22
  23 namespace Dali DALI_IMPORT_API
  24 {
  25
  26 namespace Toolkit
  27 {
  28
  29 namespace Internal DALI_INTERNAL
  30 {
  31
  32 /**
  33  * CubeTransitionEffect implementation class
  34  */
  35 class CubeTransitionEffect;
  36
  37 } // namespace Internal
  38
  39 /**
  40  * CubeTransitionEffect is a base class of custom transition effect on Image actors
  41  * The two images are partitioned into tiles and serves as two perpendicular faces of cubes
  42  * By rotating these cubes to transit from one image to another
  43  *
  44  * Usage example:
  45  *
  46  * @code
  47  *
  48  * //create a new CubeTransitionEffect
  49  * //use the New funtion of subclass ( CubeTransitionWaveEffect or CubeTransitionCrossEffect )
  50  * CubeTransitionEffect cubeEffect = CubeTransitionWaveEffect::New(numRows, numColumns, viewAreaSize);
  51  *
  52  * //set the duration of transition animation
  53  * cubeEffect.SetTransitionDuration( animationDuration );
  54  *
  55  * //set the displacement of bouncing movement during cube's rotation
  56  * cubeEffect.SetCubeDisplacement( cubeDisplacement  );
  57  *
  58  * // Add to stage
  59  * stage.Add( cubeEffect.GetRoot() );
  60  *
  61  * // Set the current image,
  62  * // only need to set at beginning or when the current image was transited to with no effect or other effect
  63  * cubeEffect.SetCurrentImage( firstImageActor );
  64  *
  65  * // Set target image, paired with startTransition. These two steps would be repeated as needed
  66  * cubeEffect.SetTargetimage( secondImageActor );
  67  * // Activate the effect
  68  * //   no param / param ture: default horizontally left panGesture
  69  * //   or param false:  default horizontally right panGesture
  70  * //   or params position & displacement: specified the panGesture
  71  * cubeEffect.StartTransition( );
  72  *
  73  * @endcode
  74  */
  75 class CubeTransitionEffect : public BaseHandle
  76 {
  77 public:
  78
  79   /**
  80    * Create an uninitialized CubeTransitionEffect;
  81    * this can be initialized by New function of its subclass
  82    */
  83   CubeTransitionEffect();
  84
  85   /**
  86    * Destructor
  87    */
  88   ~CubeTransitionEffect();
  89
  90   /**
  91    * Set the duration of transition animation
  92    * @param[in] duration The duration of transition animation
  93    */
  94   void SetTransitionDuration( float duration );
  95
  96   /**
  97    * Get the duration of transition animation
  98    * @return duration The duration of transition animation
  99    */
 100   float GetTransitionDuration() const;
 101
 102   /**
 103    * Set the displacement of bouncing animation during cube's rotation
 104    * @param[in] displacement The displacement of bouncing animation
 105    */
 106   void SetCubeDisplacement( float displacement );
 107
 108   /**
 109    * Getet the displacement of bouncing animation during cube's rotation
 110    * @return displacement The displacement of bouncing animation
 111    */
 112   float GetCubeDisplacement() const;
 113
 114   /**
 115    * Return the transition effect root actor, should then be added to stage
 116    * @return The transition effect root actor
 117    */
 118   Actor GetRoot();
 119
 120   /**
 121    * Return the transition status
 122    * @return True if the transition is under processing; false if finished
 123    */
 124   bool IsTransiting();
 125
 126   /**
 127    * Set the current image to transite from
 128    * if using this same effect continuely, only need to set once
 129    * @param[in] imageActor The current imageActor
 130    */
 131   void SetCurrentImage(ImageActor imageActor);
 132
 133   /**
 134    * Set the target image to transit to
 135    * @param[in] imageActor The new imageActor showing on stage
 136    */
 137   void SetTargetImage(ImageActor imageActor);
 138
 139   /**
 140    * Activate the transition animation with horizontally left/right panGesture
 141    * @pre target image is set
 142    * @param[in] toNextImage Horizontally left panGesture if ture, horizontally right if false
 143    */
 144   void StartTransition( bool toNextImage = true );
 145
 146   /**
 147    * Activate the transition animation with specified panGesture
 148    * @pre target image is set
 149    * @param[in] panPosition The press down position of panGesture
 150    * @param[in] panDisplacement The displacement vector of panGesture
 151    */
 152   void StartTransition( Vector2 panPosition, Vector2 panDisplacement );
 153
 154   /**
 155    * Pause the transition animation.
 156    * It does nothing if the animation is not running.
 157    */
 158   void PauseTransition();
 159
 160   /**
 161    * Re-Activate the transition animation after it is paused by calling PauseTransition().
 162    * It does nothing in other cases.
 163    */
 164   void ResumeTransition();
 165
 166   /**
 167    * Inactivate the transition animation if it is running.
 168    * Also set the rotation and position of cubes, colors of tile to the same as the final state when the animation if finished completely
 169    * It does nothing if the animation is not running.
 170    */
 171   void StopTransition();
 172
 173 public: //Signal
 174
 175   //signal name
 176   static const char* const SIGNAL_TRANSITION_COMPLETED;
 177
 178   //Transition animation completed signal
 179   typedef SignalV2< void ( CubeTransitionEffect, ImageActor ) > TransitionCompletedSignalV2;
 180
 181   /**
 182    * Signal emitted when the transition has completed animation
 183    * A callback of the following type may be connected
 184    * @code
 185    *   void YourCallbackName( CubeTransitionEffect cubeEffect, ImageActor currentImage );
 186    * @endcode
 187    * @return The Signal to connect to.
 188    */
 189   TransitionCompletedSignalV2& TransitionCompletedSignal();
 190
 191 public: // Not intended for developer use
 192
 193   CubeTransitionEffect( Internal::CubeTransitionEffect* impl );
 194
 195 }; //class CubeTransitionEffect
 196
 197 } // namespace Toolkit
 198
 199 } // namespace Dali
 200
 201 #endif /* __DALI_TOOLKIT_CUBE_TRANSITION_EFFECT_H__ */