src/lib/elm_transit.h

   1 /**
   2  * @defgroup Transit Transit
   3  * @ingroup elm_infra_group
   4  * @brief This group provides functions to handle the effects of transition
   5  *        of Elementary widgets.
   6  *
   7  * Transit is designed to apply various animated transition effects to @c
   8  * Evas_Object, such as translation, rotation, etc. For using these
   9  * effects, create @ref Elm_Transit and add the desired transition effects.
  10  *
  11  * Once the effects are added into transit, they are automatically
  12  * managed (their callback is called for the set duration and
  13  * they are deleted upon completion).
  14  *
  15  * Example:
  16  * @code
  17  * Elm_Transit *trans = elm_transit_add();
  18  * elm_transit_object_add(trans, obj);
  19  * elm_transit_effect_translation_add(trans, 0, 0, 280, 280
  20  * elm_transit_duration_set(transit, 1);
  21  * elm_transit_auto_reverse_set(transit, EINA_TRUE);
  22  * elm_transit_tween_mode_set(transit, ELM_TRANSIT_TWEEN_MODE_DECELERATE);
  23  * elm_transit_repeat_times_set(transit, 3);
  24  * @endcode
  25  *
  26  * Some transition effects are used to change the properties of objects. They
  27  * are:
  28  * @li @ref elm_transit_effect_translation_add
  29  * @li @ref elm_transit_effect_color_add
  30  * @li @ref elm_transit_effect_rotation_add
  31  * @li @ref elm_transit_effect_wipe_add
  32  * @li @ref elm_transit_effect_zoom_add
  33  * @li @ref elm_transit_effect_resizing_add
  34  *
  35  * Other transition effects are used to make one object disappear and another
  36  * object appear on its place. These effects are:
  37  *
  38  * @li @ref elm_transit_effect_flip_add
  39  * @li @ref elm_transit_effect_resizable_flip_add
  40  * @li @ref elm_transit_effect_fade_add
  41  * @li @ref elm_transit_effect_blend_add
  42  *
  43  * It's also possible to make a transition chain with @ref
  44  * elm_transit_chain_transit_add.
  45  *
  46  * @remarks We strongly recommend to use elm_transit just when edje cannot do
  47  * the trick. Edje is better at handling transitions than Elm_Transit.
  48  * Edje has more flexibility and animations can be manipulated inside the theme.
  49  *
  50  * @{
  51  */
  52
  53 /**
  54  * @enum Elm_Transit_Tween_Mode
  55  *
  56  * @brief Enumeration of acceleration used in the transition.
  57  *
  58  * @if MOBILE @since_tizen 2.3
  59  * @elseif WEARABLE @since_tizen 2.3.1
  60  * @endif
  61  */
  62 typedef enum
  63 {
  64    ELM_TRANSIT_TWEEN_MODE_LINEAR, /**< Constant speed */
  65    ELM_TRANSIT_TWEEN_MODE_SINUSOIDAL, /**< Starts slow, increases speed
  66                                          over time, then decreases again
  67                                          and stops slowly, v1 being a power factor */
  68    ELM_TRANSIT_TWEEN_MODE_DECELERATE, /**< Starts fast and decreases
  69                                          speed over time, v1 being a power factor */
  70    ELM_TRANSIT_TWEEN_MODE_ACCELERATE, /**< Starts slow and increases speed
  71                                          over time, v1 being a power factor */
  72    ELM_TRANSIT_TWEEN_MODE_DIVISOR_INTERP, /**< Starts at gradient v1,
  73                                              interpolated via power of the v2 curve */
  74    ELM_TRANSIT_TWEEN_MODE_BOUNCE, /**< Starts at @c 0.0 then a "drop" like a ball
  75                                      bouncing to the ground at @c 1.0, and
  76                                      bounce v2 times, with decay factor of v1 */
  77    ELM_TRANSIT_TWEEN_MODE_SPRING, /**< Starts at @c 0.0 then a "wobble" like a spring
  78                                      at rest position @c 1.0, and wobble v2 times,
  79                                      with decay factor of v1 */
  80    ELM_TRANSIT_TWEEN_MODE_BEZIER_CURVE /**< @since_tizen 2.3.1
  81                                           Follow the cubic-bezier curve
  82                                           calculated with the control points
  83                                           (x1, y1), (x2, y2) */
  84 } Elm_Transit_Tween_Mode;
  85
  86 /**
  87  * @enum Elm_Transit_Effect_Flip_Axis
  88  *
  89  * @brief Enumeration of the axis along which flip effect should be applied.
  90  *
  91  * @if MOBILE @since_tizen 2.3
  92  * @elseif WEARABLE @since_tizen 2.3.1
  93  * @endif
  94  */
  95 typedef enum
  96 {
  97    ELM_TRANSIT_EFFECT_FLIP_AXIS_X, /**< Flip on X axis */
  98    ELM_TRANSIT_EFFECT_FLIP_AXIS_Y /**< Flip on Y axis */
  99 } Elm_Transit_Effect_Flip_Axis;
 100
 101 /**
 102  * @enum Elm_Transit_Effect_Wipe_Dir
 103  *
 104  * @brief Enumeration of the direction in which the wipe effect should occur.
 105  *
 106  * @if MOBILE @since_tizen 2.3
 107  * @elseif WEARABLE @since_tizen 2.3.1
 108  * @endif
 109  */
 110 typedef enum
 111 {
 112    ELM_TRANSIT_EFFECT_WIPE_DIR_LEFT, /**< Wipe to the left */
 113    ELM_TRANSIT_EFFECT_WIPE_DIR_RIGHT, /**< Wipe to the right */
 114    ELM_TRANSIT_EFFECT_WIPE_DIR_UP, /**< Wipe up */
 115    ELM_TRANSIT_EFFECT_WIPE_DIR_DOWN /**< Wipe down */
 116 } Elm_Transit_Effect_Wipe_Dir;
 117
 118 /** @enum Elm_Transit_Effect_Wipe_Type
 119  *
 120  * @brief Enumeration that indicates whether the wipe effect should show or hide the object.
 121  *
 122  * @if MOBILE @since_tizen 2.3
 123  * @elseif WEARABLE @since_tizen 2.3.1
 124  * @endif
 125  */
 126 typedef enum
 127 {
 128    ELM_TRANSIT_EFFECT_WIPE_TYPE_HIDE, /**< Hide the object during the
 129                                          animation */
 130    ELM_TRANSIT_EFFECT_WIPE_TYPE_SHOW /**< Show the object during the
 131                                         animation */
 132 } Elm_Transit_Effect_Wipe_Type;
 133
 134 /**
 135  * @typedef Elm_Transit
 136  *
 137  * @brief The Transit structure type created with elm_transit_add(). This type has the information
 138  *        about the objects to which the transition is applied, and the
 139  *        transition effects that are used. It also contains info about
 140  *        duration, number of repetitions, auto-reverse, etc.
 141  *
 142  * @if MOBILE @since_tizen 2.3
 143  * @elseif WEARABLE @since_tizen 2.3.1
 144  * @endif
 145  */
 146 typedef struct _Elm_Transit Elm_Transit;
 147 typedef void                Elm_Transit_Effect;
 148
 149 /**
 150  * @typedef Elm_Transit_Effect_Transition_Cb
 151  *
 152  * @brief Called for this effect on each transition iteration.
 153  *
 154  * @if MOBILE @since_tizen 2.3
 155  * @elseif WEARABLE @since_tizen 2.3.1
 156  * @endif
 157  */
 158 typedef void (*Elm_Transit_Effect_Transition_Cb)(Elm_Transit_Effect *effect, Elm_Transit *transit, double progress);
 159
 160 /**
 161  * Elm_Transit_Effect_End_Cb
 162  *
 163  * @brief Called for this effect when the transition is over.
 164  *
 165  * @if MOBILE @since_tizen 2.3
 166  * @elseif WEARABLE @since_tizen 2.3.1
 167  * @endif
 168  */
 169 typedef void (*Elm_Transit_Effect_End_Cb)(Elm_Transit_Effect *effect, Elm_Transit *transit);
 170
 171 /**
 172  * Elm_Transit_Del_Cb
 173  *
 174  * @brief Called when the transit is deleted.
 175  *
 176  * @if MOBILE @since_tizen 2.3
 177  * @elseif WEARABLE @since_tizen 2.3.1
 178  * @endif
 179  */
 180 typedef void (*Elm_Transit_Del_Cb)(void *data, Elm_Transit *transit);
 181
 182 /**
 183  * @brief Creates a new transit.
 184  *
 185  * @if MOBILE @since_tizen 2.3
 186  * @elseif WEARABLE @since_tizen 2.3.1
 187  * @endif
 188  *
 189  * @remarks It is not necessary to delete the transit object, it is deleted at
 190  *          the end of its operation.
 191  * @remarks The transit starts playing when the program enters the main loop.
 192  *
 193  * @return The transit object
 194  */
 195 EAPI Elm_Transit           *elm_transit_add(void);
 196
 197 /**
 198  * @brief Stops the animation and deletes the @a transit object.
 199  *
 200  * @if MOBILE @since_tizen 2.3
 201  * @elseif WEARABLE @since_tizen 2.3.1
 202  * @endif
 203  *
 204  * @remarks Call this function if you want to stop the animation before the
 205  *          transit time. Make sure the @a transit object is still alive using the
 206  *          elm_transit_del_cb_set() function.
 207  *          All added effects are deleted, calling its respective data_free_cb
 208  *          functions. The function set by elm_transit_del_cb_set() is called.
 209  *
 210  * @param[in] transit The transit object to be deleted
 211  *
 212  * @see elm_transit_del_cb_set()
 213  */
 214 EAPI void                   elm_transit_del(Elm_Transit *transit);
 215
 216 /**
 217  * @brief Adds a new effect to the transit.
 218  *
 219  * @if MOBILE @since_tizen 2.3
 220  * @elseif WEARABLE @since_tizen 2.3.1
 221  * @endif
 222  *
 223  * @remarks The @a cb function and @a data are the key to the effect.
 224  *          If you try to add an existing effect, nothing is done.
 225  * @remarks After the first addition of an effect to @a transit, if its
 226  *          effect list become empty again, the @a transit is killed by the
 227  *          elm_transit_del(transit) function.
 228  *
 229  * Example:
 230  * @code
 231  * Elm_Transit *transit = elm_transit_add();
 232  * elm_transit_effect_add(transit,
 233  *                        elm_transit_effect_blend_op,
 234  *                        elm_transit_effect_blend_context_new(),
 235  *                        elm_transit_effect_blend_context_free);
 236  * @endcode
 237  *
 238  * @remarks The transit frees the context data at the end of the
 239  *          transition with the @a data_free_cb function.
 240  * @remarks Do not share the context data in between different transit objects.
 241  *
 242  * @param[in] transit The transit object
 243  * @param[in] transition_cb The operation function \n
 244  *        It is called when the
 245  *        animation begins, it is the function that actually performs the animation \n
 246  *        It is called with the @a data, @a transit and the time progression of the
 247  *        animation (a double value between @c 0.0 and @c 1.0).
 248  * @param[in] effect The context data of the effect
 249  * @param[in] end_cb The function to free the context data, it is called
 250  *        at the end of the effect, it must finalize the animation and free the
 251  *        @a data.
 252  */
 253 EAPI void                   elm_transit_effect_add(Elm_Transit *transit, Elm_Transit_Effect_Transition_Cb transition_cb, Elm_Transit_Effect *effect, Elm_Transit_Effect_End_Cb end_cb);
 254
 255 /**
 256  * @brief Deletes an added effect.
 257  *
 258  * @details This function removes the effect from the @a transit, calling the
 259  *          @a data_free_cb to free the @a data.
 260  *
 261  * @if MOBILE @since_tizen 2.3
 262  * @elseif WEARABLE @since_tizen 2.3.1
 263  * @endif
 264  *
 265  * @remarks If the effect is not found, nothing is done.
 266  * @remarks If the effect list becomes empty, this function calls
 267  *          elm_transit_del(transit), i.e., it kills the @a transit.
 268  *
 269  * @param[in] transit The transit object
 270  * @param[in] transition_cb The operation function
 271  * @param[in] effect The context data of the effect
 272  *
 273  * @see elm_transit_effect_add()
 274  */
 275 EAPI void                   elm_transit_effect_del(Elm_Transit *transit, Elm_Transit_Effect_Transition_Cb transition_cb, Elm_Transit_Effect *effect);
 276
 277 /**
 278  * @brief Adds a new object to apply the effects.
 279  *
 280  * @if MOBILE @since_tizen 2.3
 281  * @elseif WEARABLE @since_tizen 2.3.1
 282  * @endif
 283  *
 284  * @remarks After the first addition of an object to @a transit, if its
 285  *          object list becomes empty again, the @a transit is killed by the
 286  *          elm_transit_del(transit) function.
 287  * @remarks If the @a obj belongs to another transit, the @a obj is
 288  *          removed from it and it only belongs to the other @a transit.
 289  *          If the old transit stays without objects, it dies.
 290  * @remarks When you add an object into @a transit, its state from
 291  *          evas_object_pass_events_get(obj) is saved, and it is applied when the
 292  *          transit ends, if you change this state using evas_object_pass_events_set()
 293  *          after adding the object, this state changes again when @a transit stops.
 294  * @remarks It is not allowed to add a new object after transit begins.
 295  *
 296  * @param[in] transit The transit object
 297  * @param[in] obj The object to be animated
 298  */
 299 EAPI void                   elm_transit_object_add(Elm_Transit *transit, Evas_Object *obj);
 300
 301 /**
 302  * @brief Removes an added object from the transit.
 303  *
 304  * @if MOBILE @since_tizen 2.3
 305  * @elseif WEARABLE @since_tizen 2.3.1
 306  * @endif
 307  *
 308  * @remarks If the @a obj is not in the @a transit, nothing is done.
 309  * @remarks If the list becomes empty, this function calls
 310  *          elm_transit_del(transit), i.e., it kills the @a transit.
 311  * @remarks It is not allowed to remove objects after transit begins.
 312  *
 313  * @param[in] transit The transit object
 314  * @param[in] obj The object to be removed from @a transit
 315  */
 316 EAPI void                   elm_transit_object_remove(Elm_Transit *transit, Evas_Object *obj);
 317
 318 /**
 319  * @brief Gets the objects of the transit.
 320  *
 321  * @if MOBILE @since_tizen 2.3
 322  * @elseif WEARABLE @since_tizen 2.3.1
 323  * @endif
 324  *
 325  * @param[in] transit The transit object
 326  * @return a The Eina_List with the objects from the transit
 327  */
 328 EAPI const Eina_List       *elm_transit_objects_get(const Elm_Transit *transit);
 329
 330 /**
 331  * @brief Enables or disables keeping up the object's states.
 332  *        If it is not kept, the object's states are reset when transition ends.
 333  *
 334  * @if MOBILE @since_tizen 2.3
 335  * @elseif WEARABLE @since_tizen 2.3.1
 336  * @endif
 337  *
 338  * @remarks @a transit cannot be @c NULL.
 339  * @remarks One state includes geometry, color, and map data.
 340  *
 341  * @param[in] transit The transit object
 342  * @param[in] state_keep The boolean value that indicates whether to retain the state
 343  */
 344 EAPI void                   elm_transit_objects_final_state_keep_set(Elm_Transit *transit, Eina_Bool state_keep);
 345
 346 /**
 347  * @brief Gets a value that indicates whether the object's states are reset.
 348  *
 349  * @if MOBILE @since_tizen 2.3
 350  * @elseif WEARABLE @since_tizen 2.3.1
 351  * @endif
 352  *
 353  * @remarks @a transit cannot be @c NULL
 354  *
 355  * @param[in] transit The transit object
 356  * @return @c EINA_TRUE indicates that the states of the objects are reset \n
 357  *         If @a transit is @c NULL, @c EINA_FALSE is returned
 358  *
 359  * @see elm_transit_objects_final_state_keep_set()
 360  */
 361 EAPI Eina_Bool              elm_transit_objects_final_state_keep_get(const Elm_Transit *transit);
 362
 363 /**
 364  * @brief Sets the events that are enabled when transit is operating.
 365  *
 366  * @if MOBILE @since_tizen 2.3
 367  * @elseif WEARABLE @since_tizen 2.3.1
 368  * @endif
 369  *
 370  * @remarks If @a enabled is @c EINA_TRUE, the objects of the transit receive
 371  *          events from a mouse and keyboard during the animation.
 372  * @remarks When you add an object with elm_transit_object_add(), its state from
 373  *          evas_object_freeze_events_get(obj) is saved, and it is applied when the
 374  *          transit ends. If you change this state using evas_object_freeze_events_set()
 375  *          after adding the object, this state changes again when @a transit stops
 376  *          to run.
 377  *
 378  * @param[in] transit The transit object
 379  * @param[in] enabled Events are received when enabled is @c EINA_TRUE,
 380  *                otherwise it is ignored
 381  */
 382 EAPI void                   elm_transit_event_enabled_set(Elm_Transit *transit, Eina_Bool enabled);
 383
 384 /**
 385  * @brief Gets the value of the event enabled status.
 386  *
 387  * @if MOBILE @since_tizen 2.3
 388  * @elseif WEARABLE @since_tizen 2.3.1
 389  * @endif
 390  *
 391  * @param[in] transit The transit object
 392  * @return @c EINA_TRUE if the event is enabled,
 393  *         otherwise @c EINA_FALSE is returned if @a transit is @c NULL
 394  *
 395  * @see elm_transit_event_enabled_set()
 396  */
 397 EAPI Eina_Bool              elm_transit_event_enabled_get(const Elm_Transit *transit);
 398
 399 /**
 400  * @brief Sets the user-callback function when the transit is deleted.
 401  *
 402  * @if MOBILE @since_tizen 2.3
 403  * @elseif WEARABLE @since_tizen 2.3.1
 404  * @endif
 405  *
 406  * @remarks Using this function twice overwrites the first function set.
 407  * @remarks The @a transit object is deleted after calling the @a cb function.
 408  *
 409  * @param[in] transit The transit object
 410  * @param[in] cb The callback function pointer \n
 411  *           This function is called before the deletion of the transit.
 412  * @param[in] data The callback function for user data \n
 413  *             It is the @a op parameter.
 414  */
 415 EAPI void                   elm_transit_del_cb_set(Elm_Transit *transit, Elm_Transit_Del_Cb cb, void *data);
 416
 417 /**
 418  * @brief Sets the reverse effect automatically.
 419  *
 420  * @if MOBILE @since_tizen 2.3
 421  * @elseif WEARABLE @since_tizen 2.3.1
 422  * @endif
 423  *
 424  * @remarks If auto reverse is set, after running the effects with the progress
 425  *          parameter from @c 0 to @c 1, it calls the effects again with the progress
 426  *          from @c 1 to @c 0. The transit lasts for a time equal to (2 * duration * repeat),
 427  *          where the duration is set using the function elm_transit_add and
 428  *          the repeat using the function elm_transit_repeat_times_set().
 429  *
 430  * @param[in] transit The transit object
 431  * @param[in] reverse If @c EINA_TRUE the auto_reverse is on, otherwise @c EINA_FALSE
 432  */
 433 EAPI void                   elm_transit_auto_reverse_set(Elm_Transit *transit, Eina_Bool reverse);
 434
 435 /**
 436  * @brief Gets whether the auto reverse is on.
 437  *
 438  * @if MOBILE @since_tizen 2.3
 439  * @elseif WEARABLE @since_tizen 2.3.1
 440  * @endif
 441  *
 442  * @param[in] transit The transit object
 443  * @return @c EINA_TRUE if the auto reverse is on,
 444  *         otherwise @c EINA_FALSE is returned if @a transit is @c NULL
 445  *
 446  * @see elm_transit_auto_reverse_set()
 447  */
 448 EAPI Eina_Bool              elm_transit_auto_reverse_get(const Elm_Transit *transit);
 449
 450 /**
 451  * @brief Sets the transit repeat count. The effect is repeated as per the repeat count.
 452  *
 453  * @details This function sets the number of repetitions that the transit runs after
 454  *          the first one, i.e., if @a repeat is @c 1, the transit runs @c 2 times.
 455  *          If @a repeat is a negative number, it repeats infinite times.
 456  *
 457  * @if MOBILE @since_tizen 2.3
 458  * @elseif WEARABLE @since_tizen 2.3.1
 459  * @endif
 460  *
 461  * @remarks If this function is called during the transit execution, the transit
 462  *          runs @a repeat times, ignoring the times it already performed.
 463  *
 464  * @param[in] transit The transit object
 465  * @param[in] repeat The repeat count
 466  */
 467 EAPI void                   elm_transit_repeat_times_set(Elm_Transit *transit, int repeat);
 468
 469 /**
 470  * @brief Gets the transit repeat count.
 471  *
 472  * @if MOBILE @since_tizen 2.3
 473  * @elseif WEARABLE @since_tizen 2.3.1
 474  * @endif
 475  *
 476  * @param[in] transit The transit object
 477  * @return The repeat count \n
 478  *         If @a transit is @c NULL, @c 0 is returned
 479  *
 480  * @see elm_transit_repeat_times_set()
 481  */
 482 EAPI int                    elm_transit_repeat_times_get(const Elm_Transit *transit);
 483
 484 /**
 485  * @brief Sets the transit animation acceleration type.
 486  *
 487  * @details This function sets the tween mode of the transit which can be:
 488  *          ELM_TRANSIT_TWEEN_MODE_LINEAR - The default mode.
 489  *          ELM_TRANSIT_TWEEN_MODE_SINUSOIDAL - Starts in the accelerate mode and ends
 490  *                                              decelerating with factor.
 491  *          ELM_TRANSIT_TWEEN_MODE_DECELERATE - The animation is slowed over time
 492  *                                              with factor.
 493  *          ELM_TRANSIT_TWEEN_MODE_ACCELERATE - The animation accelerates over time
 494  *                                              with factor.
 495  *          ELM_TRANSIT_TWEEN_MODE_DIVISOR_INTERP - Starts at gradient v1, interpolated
 496  *                                                  via power of the v2 curve.
 497  *          ELM_TRANSIT_TWEEN_MODE_BOUNCE - Starts at @c 0.0 then a "drop" like a ball bouncing
 498  *                                          to the ground at @c 1.0, and bounce v2 times, with decay factor of v1.
 499  *          ELM_TRANSIT_TWEEN_MODE_SPRING - Starts at @c 0.0 then a "wobble" like a spring in rest
 500  *                                          position @c 1.0, and wobble v2 times, with decay factor of v1.
 501  *
 502  * @if MOBILE @since_tizen 2.3
 503  * @elseif WEARABLE @since_tizen 2.3.1
 504  * @endif
 505  *
 506  * @param[in] transit The transit object
 507  * @param[in] tween_mode The tween type
 508  */
 509 EAPI void                   elm_transit_tween_mode_set(Elm_Transit *transit, Elm_Transit_Tween_Mode tween_mode);
 510
 511 /**
 512  * @brief Gets the transit animation acceleration type.
 513  *
 514  * @if MOBILE @since_tizen 2.3
 515  * @elseif WEARABLE @since_tizen 2.3.1
 516  * @endif
 517  *
 518  * @remarks @a transit cannot be @c NULL.
 519  *
 520  * @param[in] transit The transit object
 521  * @return The tween type \n
 522  *         If @a transit is @c NULL, @c ELM_TRANSIT_TWEEN_MODE_LINEAR is returned.
 523  */
 524 EAPI Elm_Transit_Tween_Mode elm_transit_tween_mode_get(const Elm_Transit *transit);
 525
 526 /**
 527  * @brief Sets the transit animation acceleration factor.
 528  *
 529  * @details This function sets the tween mode factor of the transit which can be:
 530  *          If you use the below tween modes, you have to set the factor using this API.
 531  *          ELM_TRANSIT_TWEEN_MODE_SINUSOIDAL - Starts slow, speeds up then slows down
 532  *                                              at the end, v1 being a power factor, @c 0.0 being linear, @c 1.0 being
 533  *          ELM_TRANSIT_TWEEN_MODE_SINUSOIDAL - Default, @c 2.0 being a much more pronounced
 534  *                                              sinusoidal(squared), @c 3.0 being cubed, etc.
 535  *          ELM_TRANSIT_TWEEN_MODE_DECELERATE - Starts fast then slows down, v1 being a
 536  *                                              power factor, @c 0.0 being linear, @c 1.0 being ELM_TRANSIT_TWEEN_MODE_DECELERATE
 537  *                                              default, @c 2.0 being a much more pronounced decelerate (squared), @c 3.0 being
 538  *                                              cubed, etc.
 539  *          ELM_TRANSIT_TWEEN_MODE_ACCELERATE - Starts slow then speeds up, v1 being a
 540  *                                              power factor, @c 0.0 being linear, @c 1.0 being ELM_TRANSIT_TWEEN_MODE_ACCELERATE
 541  *                                              default, @c 2.0 being a much more pronounced accelerate (squared), @c 3.0 being
 542  *                                              cubed, etc.
 543  *          ELM_TRANSIT_TWEEN_MODE_DIVISOR_INTERP - Starts at gradient * v1, interpolated
 544  *                                                  via power of the v2 curve.
 545  *          ELM_TRANSIT_TWEEN_MODE_BOUNCE - Starts at @c 0.0 then a "drop" like a ball bouncing
 546  *                                          to the ground at @c 1.0, and bounce v2 times, with decay factor of v1.
 547  *          ELM_TRANSIT_TWEEN_MODE_SPRING - Starts at @c 0.0 then a "wobble" like a spring in rest
 548  *                                          position @c 1.0, and wobble v2 times, with decay factor of v1.
 549  *
 550  * @if MOBILE @since_tizen 2.3
 551  * @elseif WEARABLE @since_tizen 2.3.1
 552  * @endif
 553  *
 554  * @param[in] transit The transit object
 555  * @param[in] v1 A parameter used by the mapping (default is @c 1.0)
 556  * @param[in] v2 A parameter used by the mapping (default is @c 0.0)
 557  *
 558  * @see elm_transit_tween_mode_factor_get()
 559  */
 560 EAPI void                   elm_transit_tween_mode_factor_set(Elm_Transit *transit, double v1, double v2);
 561
 562 /**
 563  * @brief Gets the transit animation acceleration factor.
 564  *
 565  * @if MOBILE @since_tizen 2.3
 566  * @elseif WEARABLE @since_tizen 2.3.1
 567  * @endif
 568  *
 569  * @remarks @a transit cannot be @c NULL.
 570  *
 571  * @param[in] transit The transit object
 572  * @param[out] v1      The pointer to a double in which to store the factor value
 573  * @param[out] v2      The pointer to a double in which to store the factor value2
 574  *
 575  * @see elm_transit_tween_mode_factor_set()
 576  */
 577 EAPI void                   elm_transit_tween_mode_factor_get(const Elm_Transit *transit, double *v1, double *v2);
 578
 579 /**
 580  * @brief Sets the transit animation time.
 581  *
 582  * @if MOBILE @since_tizen 2.3
 583  * @elseif WEARABLE @since_tizen 2.3.1
 584  * @endif
 585  *
 586  * @remarks @a transit cannot be @c NULL.
 587  *
 588  * @param[in] transit The transit object
 589  * @param[in] duration The animation time
 590  */
 591 EAPI void                   elm_transit_duration_set(Elm_Transit *transit, double duration);
 592
 593 /**
 594  * Set the transit animation acceleration factor.
 595  *
 596  * This function sets the tween mode factor of the transit that can be:
 597  * If you use the below tween modes, you have to set the factor using this API.
 598  * ELM_TRANSIT_TWEEN_MODE_SINUSOIDAL - Start slow, speed up then slow down
 599  * at end, v[0] being a power factor, 0.0 being linear, 1.0 being
 600  * ELM_TRANSIT_TWEEN_MODE_SINUSOIDAL default, 2.0 being much more pronounced
 601  * sinusoidal(squared), 3.0 being cubed, etc.
 602  * ELM_TRANSIT_TWEEN_MODE_DECELERATE - Start fast then slow down, v[0] being a
 603  * power factor, 0.0 being linear, 1.0 being ELM_TRANSIT_TWEEN_MODE_DECELERATE
 604  * default, 2.0 being much more pronounced decelerate (squared), 3.0 being
 605  * cubed, etc.
 606  * ELM_TRANSIT_TWEEN_MODE_ACCELERATE - Start slow then speed up, v[0] being a
 607  * power factor, 0.0 being linear, 1.0 being ELM_TRANSIT_TWEEN_MODE_ACCELERATE
 608  * default, 2.0 being much more pronounced accelerate (squared), 3.0 being
 609  * cubed, etc.
 610  * ELM_TRANSIT_TWEEN_MODE_DIVISOR_INTERP - Start at gradient v[0], interpolated
 611  * via power of v[1] curve
 612  * ELM_TRANSIT_TWEEN_MODE_BOUNCE - Start at 0.0 then "drop" like a ball bouncing
 613  * to the ground at 1.0, and bounce v[1] times, with decay factor of v[0]
 614  * ELM_TRANSIT_TWEEN_MODE_SPRING - Start at 0.0 then "wobble" like a spring rest
 615  * position 1.0, and wobble v[1] times, with decay factor of v[0]
 616  * ELM_TRANSIT_TWEEN_MODE_BEZIER_CURVE - Use an interpolated cubic-bezier curve
 617  * ajusted with parameters from v[0] to v[3]
 618  *
 619  * @param transit The transit object.
 620  * @param v_size The size of the array pointing to v
 621  * @param v The address of an array with the double parameters to be used by the mapping.
 622  *
 623  * @see elm_transit_tween_mode_factor_set()
 624  * @since_tizen 2.3.1
 625  * @ingroup Transit
 626  */
 627 EAPI void                   elm_transit_tween_mode_factor_n_set(Elm_Transit *transit, unsigned int v_size, double *v);
 628
 629 /**
 630  * @brief Gets the transit animation time.
 631  *
 632  * @if MOBILE @since_tizen 2.3
 633  * @elseif WEARABLE @since_tizen 2.3.1
 634  * @endif
 635  *
 636  * @remarks @a transit cannot be @c NULL.
 637  *
 638  * @param[in] transit The transit object
 639  *
 640  * @return The transit animation time
 641  */
 642 EAPI double                 elm_transit_duration_get(const Elm_Transit *transit);
 643
 644 /**
 645  * @brief Starts the transition.
 646  *
 647  * @if MOBILE @since_tizen 2.3
 648  * @elseif WEARABLE @since_tizen 2.3.1
 649  * @endif
 650  *
 651  * @remarks Once this API is called, the transit begins to measure the time.
 652  *
 653  * @remarks @a transit cannot be @c NULL.
 654  *
 655  * @param[in] transit The transit object
 656  */
 657 EAPI void                   elm_transit_go(Elm_Transit *transit);
 658
 659 /**
 660  * @brief Pauses and resumes the transition.
 661  *
 662  * @if MOBILE @since_tizen 2.3
 663  * @elseif WEARABLE @since_tizen 2.3.1
 664  * @endif
 665  *
 666  * @remarks If you call elm_transit_go() again, the transit is started from the
 667  *          beginning, and is played.
 668  *
 669  * @remarks @a transit cannot be @c NULL
 670  *
 671  * @param[in] transit The transit object
 672  * @param[in] paused The boolean value that indicates whether the transition should be paused
 673  */
 674 EAPI void                   elm_transit_paused_set(Elm_Transit *transit, Eina_Bool paused);
 675
 676 /**
 677  * @brief Gets the value of the paused status.
 678  *
 679  * @if MOBILE @since_tizen 2.3
 680  * @elseif WEARABLE @since_tizen 2.3.1
 681  * @endif
 682  *
 683  * @remarks @a transit cannot be @c NULL.
 684  *
 685  * @param[in] transit The transit object
 686  * @return @c EINA_TRUE if the transition is paused,
 687  *         otherwise @c EINA_FALSE is returned if @a transit is @c NULL
 688  *
 689  * @see elm_transit_paused_set()
 690  */
 691 EAPI Eina_Bool              elm_transit_paused_get(const Elm_Transit *transit);
 692
 693 /**
 694  * @brief Gets the time progression of the animation (a double value between @c 0.0 and @c 1.0).
 695  *
 696  * @if MOBILE @since_tizen 2.3
 697  * @elseif WEARABLE @since_tizen 2.3.1
 698  * @endif
 699  *
 700  * @remarks The value returned is a fraction (current time / total time). It
 701  *          represents the progression position relative to the total.
 702  *
 703  * @remarks @a transit cannot be @c NULL
 704  *
 705  * @param[in] transit The transit object
 706  *
 707  * @return The time progression value \n
 708  *         If @a transit is @c NULL, @c 0 is returned
 709  */
 710 EAPI double                 elm_transit_progress_value_get(const Elm_Transit *transit);
 711
 712 /**
 713  * @brief Makes the chain relationship between two transits.
 714  *
 715  * @if MOBILE @since_tizen 2.3
 716  * @elseif WEARABLE @since_tizen 2.3.1
 717  * @endif
 718  *
 719  * @remarks This function adds the @a chain_transit transition to a chain after the @a
 720  *          transit, and is started as soon as @a transit ends.
 721  *
 722  * @remarks @a transit cannot be @c NULL. Transit would have multiple chain transits.
 723  * @remarks @p chain_transit cannot be @c NULL. Chain transits could be chained to only one transit.
 724  *
 725  * @param[in] transit The transit object
 726  * @param[in] chain_transit The chain transit object \n
 727  *                      This transit is operated after transit is done.
 728  */
 729 EAPI void                   elm_transit_chain_transit_add(Elm_Transit *transit, Elm_Transit *chain_transit);
 730
 731 /**
 732  * @brief Cuts off the chain relationship between two transits.
 733  *
 734  * @if MOBILE @since_tizen 2.3
 735  * @elseif WEARABLE @since_tizen 2.3.1
 736  * @endif
 737  *
 738  * @remarks This function removes the @a chain_transit transition from the @a transit.
 739  *
 740  * @remarks @a transit cannot be @c NULL. Transit would have a chain relationship with @a chain transit.
 741  * @remarks @a chain_transit cannot be @c NULL. Chain transits should be chained to the @a transit.
 742  *
 743  * @param[in] transit The transit object
 744  * @param[in] chain_transit The chain transit object
 745  */
 746 EAPI void                   elm_transit_chain_transit_del(Elm_Transit *transit, Elm_Transit *chain_transit);
 747
 748 /**
 749  * @brief Gets the current chain transit list.
 750  *
 751  * @if MOBILE @since_tizen 2.3
 752  * @elseif WEARABLE @since_tizen 2.3.1
 753  * @endif
 754  *
 755  * @remarks @a transit cannot be @c NULL.
 756  *
 757  * @param[in] transit The transit object
 758  * @return The chain transit list
 759  */
 760 EAPI Eina_List             *elm_transit_chain_transits_get(const Elm_Transit *transit);
 761
 762 /**
 763  * @brief Sets the smooth effect for a transit.
 764  *
 765  * @details This sets smoothing for transit map rendering. If the object added in a
 766  *          transit is of a type that has its own smoothing settings, then both the smooth
 767  *          settings for this object and the map must be turned off. By default, smooth
 768  *          maps are enabled.
 769  *
 770  * @since 1.8
 771  *
 772  * @if MOBILE @since_tizen 2.3
 773  * @elseif WEARABLE @since_tizen 2.3.1
 774  * @endif
 775  *
 776  * @param[in] transit The transit object
 777  * @param[in] smooth enabled The boolean value that enables or disables smooth map rendering
 778  *
 779  * @see evas_map_smooth_set()
 780  */
 781 EAPI void                   elm_transit_smooth_set(Elm_Transit *transit, Eina_Bool smooth);
 782
 783 /**
 784  * @brief Gets smooth scaling for transit map rendering.
 785  *
 786  * @details This gets smooth scaling for transit map rendering.
 787  *
 788  * @since 1.8
 789  *
 790  * @if MOBILE @since_tizen 2.3
 791  * @elseif WEARABLE @since_tizen 2.3.1
 792  * @endif
 793  *
 794  * @param[in] transit The transit object
 795  * @return @c EINA_TRUE if smooth scaling is enabled, otherwise @c EINA_FALSE
 796  *
 797  * @see elm_transit_smooth_set()
 798  *
 799  */
 800 Eina_Bool                   elm_transit_smooth_get(const Elm_Transit *transit);
 801
 802 /**
 803  * @brief Adds the resizing effect to Elm_Transit.
 804  *
 805  * @if MOBILE @since_tizen 2.3
 806  * @elseif WEARABLE @since_tizen 2.3.1
 807  * @endif
 808  *
 809  * @remarks This API is one of the facades. It creates resizing effect context
 810  *          and adds its required APIs to elm_transit_effect_add().
 811  *
 812  * @param[in] transit The transit object
 813  * @param[in] from_w The object width size when the effect begins
 814  * @param[in] from_h The object height size when the effect begins
 815  * @param[in] to_w The object width size when the effect ends
 816  * @param[in] to_h The object height size when the effect ends
 817  * @return The resizing effect context data
 818  *
 819  * @see elm_transit_effect_add()
 820  */
 821 EAPI Elm_Transit_Effect    *elm_transit_effect_resizing_add(Elm_Transit *transit, Evas_Coord from_w, Evas_Coord from_h, Evas_Coord to_w, Evas_Coord to_h);
 822
 823 /**
 824  * @brief Adds the translation effect to Elm_Transit.
 825  *
 826  * @if MOBILE @since_tizen 2.3
 827  * @elseif WEARABLE @since_tizen 2.3.1
 828  * @endif
 829  *
 830  * @remarks This API is one of the facades. It creates translation effect context
 831  *          and adds its required APIs to elm_transit_effect_add().
 832  *
 833  * @remarks It is highly recommended to just create a transit with this effect when
 834  *          the window to which the objects of the transit belong has already been created.
 835  *          This is because this effect needs the geometry information about the objects,
 836  *          and if the window is not created yet, it can get wrong information.
 837  *
 838  * @param[in] transit The transit object
 839  * @param[in] from_dx The x position variation when the effect begins
 840  * @param[in] from_dy The y position variation when the effect begins
 841  * @param[in] to_dx The x position variation when the effect ends
 842  * @param[in] to_dy The y position variation when the effect ends
 843  * @return The translation effect context data
 844  *
 845  * @see elm_transit_effect_add()
 846  */
 847 EAPI Elm_Transit_Effect    *elm_transit_effect_translation_add(Elm_Transit *transit, Evas_Coord from_dx, Evas_Coord from_dy, Evas_Coord to_dx, Evas_Coord to_dy);
 848
 849 /**
 850  * @brief Adds the zoom effect to Elm_Transit.
 851  *
 852  * @if MOBILE @since_tizen 2.3
 853  * @elseif WEARABLE @since_tizen 2.3.1
 854  * @endif
 855  *
 856  * @remarks This API is one of the facades. It creates zoom effect context
 857  *          and adds its required APIs to elm_transit_effect_add().
 858  *
 859  * @remarks It is highly recommended to just create a transit with this effect when
 860  *          the window to which the objects of the transit belong has already been created.
 861  *          This is because this effect needs the geometry information about the objects,
 862  *          and if the window is not created yet, it can get wrong information.
 863  *
 864  * @param[in] transit The transit object
 865  * @param[in] from_rate The scale rate when the effect begins (@c 1 is the current rate)
 866  * @param[in] to_rate The scale rate when the effect ends
 867  * @return The zoom effect context data
 868  *
 869  * @see elm_transit_effect_add()
 870  */
 871 EAPI Elm_Transit_Effect    *elm_transit_effect_zoom_add(Elm_Transit *transit, float from_rate, float to_rate);
 872
 873 /**
 874  * @brief Adds the flip effect to Elm_Transit.
 875  *
 876  * @if MOBILE @since_tizen 2.3
 877  * @elseif WEARABLE @since_tizen 2.3.1
 878  * @endif
 879  *
 880  * @remarks This API is one of the facades. It creates flip effect context
 881  *          and adds its required APIs to elm_transit_effect_add().
 882  * @remarks This effect is applied to each pair of objects in the order they are listed
 883  *          in the transit list of objects. The first object in the pair is the
 884  *          "front" object and the second is the "back" object.
 885  *
 886  * @remarks It is highly recommended to just create a transit with this effect when
 887  *          the window to which the objects of the transit belong has already been created.
 888  *          This is because this effect needs the geometry information about the objects,
 889  *          and if the window is not created yet, it can get wrong information.
 890  *
 891  * @param[in] transit The transit object
 892  * @param[in] axis The flipping axis(x or y)
 893  * @param[in] cw The flipping direction \n
 894  *           @c EINA_TRUE is clock-wise.
 895  * @return The flip effect context data
 896  *
 897  * @see elm_transit_effect_add()
 898  */
 899 EAPI Elm_Transit_Effect    *elm_transit_effect_flip_add(Elm_Transit *transit, Elm_Transit_Effect_Flip_Axis axis, Eina_Bool cw);
 900
 901 /**
 902  * @brief Adds the resizeable flip effect to Elm_Transit.
 903  *
 904  * @if MOBILE @since_tizen 2.3
 905  * @elseif WEARABLE @since_tizen 2.3.1
 906  * @endif
 907  *
 908  * @remarks This API is one of the facades. It creates resizable flip effect context
 909  *          and adds its required APIs to elm_transit_effect_add().
 910  * @remarks This effect is applied to each pair of objects in the order they are listed
 911  *          in the transit list of objects. The first object in the pair is the
 912  *          "front" object and the second is the "back" object.
 913  *
 914  * @remarks It is highly recommended to just create a transit with this effect when
 915  *          the window to which the objects of the transit belong has already been created.
 916  *          This is because this effect needs the geometry information about the objects,
 917  *          and if the window is not created yet, it can get wrong information.
 918  *
 919  * @param[in] transit The transit object
 920  * @param[in] axis The flipping axis(x or y)
 921  * @param[in] cw The flipping direction \n
 922  *           @c EINA_TRUE is clock-wise.
 923  * @return The resizeable flip effect context data
 924  *
 925  * @see elm_transit_effect_add()
 926  */
 927 EAPI Elm_Transit_Effect    *elm_transit_effect_resizable_flip_add(Elm_Transit *transit, Elm_Transit_Effect_Flip_Axis axis, Eina_Bool cw);
 928
 929 /**
 930  * @brief Adds the wipe effect to Elm_Transit.
 931  *
 932  * @if MOBILE @since_tizen 2.3
 933  * @elseif WEARABLE @since_tizen 2.3.1
 934  * @endif
 935  *
 936  * @remarks This API is one of the facades. It creates wipe effect context
 937  *          and adds its required APIs to elm_transit_effect_add().
 938  *
 939  * @remarks It is highly recommended to just create a transit with this effect when
 940  *          the window to which the objects of the transit belong has already been created.
 941  *          This is because this effect needs the geometry information about the objects,
 942  *          and if the window is not created yet, it can get wrong information.
 943  *
 944  * @param[in] transit The transit object
 945  * @param[in] type The wipe type which is either hide or show
 946  * @param[in] dir The wipe direction
 947  * @return The wipe effect context data
 948  *
 949  * @see elm_transit_effect_add()
 950  */
 951 EAPI Elm_Transit_Effect    *elm_transit_effect_wipe_add(Elm_Transit *transit, Elm_Transit_Effect_Wipe_Type type, Elm_Transit_Effect_Wipe_Dir dir);
 952
 953 /**
 954  * @brief Adds the color effect to Elm_Transit.
 955  *
 956  * @if MOBILE @since_tizen 2.3
 957  * @elseif WEARABLE @since_tizen 2.3.1
 958  * @endif
 959  *
 960  * @remarks This API is one of the facades. It creates color effect context
 961  *          and adds its required APIs to elm_transit_effect_add().
 962  *
 963  *
 964  * @param[in] transit        The transit object
 965  * @param[in]  from_r        The RGB from R when the effect begins
 966  * @param[in]  from_g        The RGB from G when the effect begins
 967  * @param[in]  from_b        The RGB from B when the effect begins
 968  * @param[in]  from_a        The RGB from A when the effect begins
 969  * @param[in]  to_r          The RGB to R when the effect ends
 970  * @param[in]  to_g          The RGB to G when the effect ends
 971  * @param[in]  to_b          The RGB to B when the effect ends
 972  * @param[in]  to_a          The RGB to A when the effect ends
 973  * @return               The color effect context data
 974  *
 975  * @see elm_transit_effect_add()
 976  */
 977 EAPI Elm_Transit_Effect    *elm_transit_effect_color_add(Elm_Transit *transit, unsigned int from_r, unsigned int from_g, unsigned int from_b, unsigned int from_a, unsigned int to_r, unsigned int to_g, unsigned int to_b, unsigned int to_a);
 978
 979 /**
 980  * @brief Adds the fade effect to Elm_Transit.
 981  *
 982  * @if MOBILE @since_tizen 2.3
 983  * @elseif WEARABLE @since_tizen 2.3.1
 984  * @endif
 985  *
 986  * @remarks This API is one of the facades. It creates fade effect context
 987  *          and adds its required APIs to elm_transit_effect_add().
 988  * @remarks This effect is applied to each pair of objects in the order they are listed
 989  *          in the transit list of objects. The first object in the pair is the
 990  *          "before" object and the second is the "after" object.
 991  *
 992  * @remarks It is highly recommended to just create a transit with this effect when
 993  *          the window to which the objects of the transit belong has already been created.
 994  *          This is because this effect needs the color information about the objects,
 995  *          and if the window is not created yet, it can get wrong information.
 996  *
 997  * @param[in] transit The transit object
 998  * @return The fade effect context data
 999  *
1000  * @see elm_transit_effect_add()
1001  */
1002 EAPI Elm_Transit_Effect    *elm_transit_effect_fade_add(Elm_Transit *transit);
1003
1004 /**
1005  * @brief Adds the blend effect to Elm_Transit.
1006  *
1007  * @if MOBILE @since_tizen 2.3
1008  * @elseif WEARABLE @since_tizen 2.3.1
1009  * @endif
1010  *
1011  * @remarks This API is one of the facades. It creates blend effect context
1012  *          and adds its required APIs to elm_transit_effect_add().
1013  * @remarks This effect is applied to each pair of objects in the order they are listed
1014  *          in the transit list of objects. The first object in the pair is the
1015  *          "before" object and the second is the "after" object.
1016  *
1017  * @remarks It is highly recommended to just create a transit with this effect when
1018  *          the window that the objects of the transit belongs has already been created.
1019  *          This is because this effect needs the color information about the objects,
1020  *          and if the window is not created yet, it can get wrong information.
1021  *
1022  * @param[in] transit The transit object
1023  * @return The blend effect context data
1024  *
1025  * @see elm_transit_effect_add()
1026  */
1027 EAPI Elm_Transit_Effect    *elm_transit_effect_blend_add(Elm_Transit *transit);
1028
1029 /**
1030  * @brief Adds the rotation effect to Elm_Transit.
1031  *
1032  * @if MOBILE @since_tizen 2.3
1033  * @elseif WEARABLE @since_tizen 2.3.1
1034  * @endif
1035  *
1036  * @remarks This API is one of the facades. It creates rotation effect context
1037  *          and adds its required APIs to elm_transit_effect_add().
1038  *
1039  * @remarks It is highly recommended to just create a transit with this effect when
1040  *          the window to which the objects of the transit belong has already been created.
1041  *          This is because this effect needs the geometry information about the objects,
1042  *          and if the window is not created yet, it can get wrong information.
1043  *
1044  * @param[in] transit The transit object
1045  * @param[in] from_degree The degree when the effect begins
1046  * @param[in] to_degree The degree when the effect is ends
1047  * @return The rotation effect context data
1048  *
1049  * @see elm_transit_effect_add()
1050  */
1051 EAPI Elm_Transit_Effect    *elm_transit_effect_rotation_add(Elm_Transit *transit, float from_degree, float to_degree);
1052
1053 /**
1054  * @brief Adds the image animation effect to Elm_Transit.
1055  *
1056  * @if MOBILE @since_tizen 2.3
1057  * @elseif WEARABLE @since_tizen 2.3.1
1058  * @endif
1059  *
1060  * @remarks This API is one of the facades. It creates image animation effect context
1061  *          and adds its required APIs to elm_transit_effect_add.
1062  *          The @a images parameter is a list images paths. This list and
1063  *          its contents is deleted at the end of the effect by the
1064  *          elm_transit_effect_image_animation_context_free() function.
1065  *
1066  * Example:
1067  * @code
1068  * char buf[PATH_MAX];
1069  * Eina_List *images = NULL;
1070  * Elm_Transit *transi = elm_transit_add();
1071  *
1072  * snprintf(buf, sizeof(buf), "%s/images/icon_11.png", PACKAGE_DATA_DIR);
1073  * images = eina_list_append(images, eina_stringshare_add(buf));
1074  *
1075  * snprintf(buf, sizeof(buf), "%s/images/logo_small.png", PACKAGE_DATA_DIR);
1076  * images = eina_list_append(images, eina_stringshare_add(buf));
1077  * elm_transit_effect_image_animation_add(transi, images);
1078  *
1079  * @endcode
1080  *
1081  *
1082  * @param[in] transit The transit object
1083  * @param[in] images The Eina_List of images file paths \n
1084  *               This list and its contents are deleted at the end of the effect by the
1085  *               elm_transit_effect_image_animation_context_free() function.
1086  *
1087  * @return The image animation effect context data
1088  *
1089  * @see elm_transit_effect_add()
1090  */
1091 EAPI Elm_Transit_Effect    *elm_transit_effect_image_animation_add(Elm_Transit *transit, Eina_List *images);
1092
1093 /**
1094  * @}
1095  */