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