mobile/src/lib/elm_flip.h

   1 /**
   2  * @defgroup Flip Flip
   3  * @ingroup Elementary
   4  *
   5  * @image html flip_inheritance_tree.png
   6  * @image latex flip_inheritance_tree.eps
   7  *
   8  * @image html img/widget/flip/preview-00.png
   9  * @image latex img/widget/flip/preview-00.eps
  10  *
  11  * This widget holds 2 content objects(Evas_Object): one on the front and one
  12  * on the back. It allows you to flip from front to back and vice-versa using
  13  * various animations.
  14  *
  15  * If either the front or back contents are not set the flip will treat that
  16  * as transparent. So if you wore to set the front content but not the back,
  17  * and then call elm_flip_go() you would see whatever is below the flip.
  18  *
  19  * For a list of supported animations see elm_flip_go().
  20  *
  21  * Signals that you can add callbacks for are:
  22  * "animate,begin" - when a flip animation was started
  23  * "animate,done" - when a flip animation is finished
  24  *
  25  * Default content parts of the flip widget that you can use for are:
  26  * @li "front" - A front content of the flip
  27  * @li "back" - A back content of the flip
  28  *
  29  * This widget inherits from @ref elm-container-class, so that the
  30  * functions meant to act on it will work for mapbuf objects:
  31  *
  32  * @li @ref elm_object_part_content_set
  33  * @li @ref elm_object_part_content_get
  34  * @li @ref elm_object_part_content_unset
  35  *
  36  * @ref tutorial_flip show how to use most of the API.
  37  *
  38  * @{
  39  */
  40 typedef enum
  41 {
  42    ELM_FLIP_ROTATE_Y_CENTER_AXIS,
  43    ELM_FLIP_ROTATE_X_CENTER_AXIS,
  44    ELM_FLIP_ROTATE_XZ_CENTER_AXIS,
  45    ELM_FLIP_ROTATE_YZ_CENTER_AXIS,
  46    ELM_FLIP_CUBE_LEFT,
  47    ELM_FLIP_CUBE_RIGHT,
  48    ELM_FLIP_CUBE_UP,
  49    ELM_FLIP_CUBE_DOWN,
  50    ELM_FLIP_PAGE_LEFT,
  51    ELM_FLIP_PAGE_RIGHT,
  52    ELM_FLIP_PAGE_UP,
  53    ELM_FLIP_PAGE_DOWN
  54 } Elm_Flip_Mode;
  55
  56 typedef enum
  57 {
  58    ELM_FLIP_INTERACTION_NONE,
  59    ELM_FLIP_INTERACTION_ROTATE,
  60    ELM_FLIP_INTERACTION_CUBE,
  61    ELM_FLIP_INTERACTION_PAGE
  62 } Elm_Flip_Interaction;
  63
  64 typedef enum
  65 {
  66    ELM_FLIP_DIRECTION_UP, /**< Allows interaction with the top of the widget */
  67    ELM_FLIP_DIRECTION_DOWN, /**< Allows interaction with the bottom of the widget */
  68    ELM_FLIP_DIRECTION_LEFT, /**< Allows interaction with the left portion of the widget */
  69    ELM_FLIP_DIRECTION_RIGHT /**< Allows interaction with the right portion of the widget */
  70 } Elm_Flip_Direction;
  71
  72 /**
  73  * @brief Add a new flip to the parent
  74  *
  75  * @param parent The parent object
  76  * @return The new object or NULL if it cannot be created
  77  *
  78  * @ingroup Flip
  79  */
  80 EAPI Evas_Object *elm_flip_add(Evas_Object *parent);
  81
  82 /**
  83  * @brief Get flip front visibility state
  84  *
  85  * @param obj The flip object
  86  * @return EINA_TRUE if front front is showing, EINA_FALSE if the back is
  87  * showing.
  88  *
  89  * @ingroup Flip
  90  */
  91 Eina_Bool elm_flip_front_visible_get(const Evas_Object *obj);
  92
  93 /**
  94  * @brief Set flip perspective
  95  *
  96  * @param obj The flip object
  97  * @param foc The coordinate to set the focus on
  98  * @param x The X coordinate
  99  * @param y The Y coordinate
 100  *
 101  * @warning This function currently does nothing.
 102  *
 103  * @ingroup Flip
 104  */
 105 EAPI void                 elm_flip_perspective_set(Evas_Object *obj, Evas_Coord foc, Evas_Coord x, Evas_Coord y);
 106
 107 /**
 108  * @brief Runs the flip animation
 109  *
 110  * @param obj The flip object
 111  * @param mode The mode type
 112  *
 113  * Flips the front and back contents using the @p mode animation. This
 114  * effectively hides the currently visible content and shows the hidden one.
 115  *
 116  * There a number of possible animations to use for the flipping:
 117  * @li ELM_FLIP_ROTATE_X_CENTER_AXIS - Rotate the currently visible content
 118  * around a horizontal axis in the middle of its height, the other content
 119  * is shown as the other side of the flip.
 120  * @li ELM_FLIP_ROTATE_Y_CENTER_AXIS - Rotate the currently visible content
 121  * around a vertical axis in the middle of its width, the other content is
 122  * shown as the other side of the flip.
 123  * @li ELM_FLIP_ROTATE_XZ_CENTER_AXIS - Rotate the currently visible content
 124  * around a diagonal axis in the middle of its width, the other content is
 125  * shown as the other side of the flip.
 126  * @li ELM_FLIP_ROTATE_YZ_CENTER_AXIS - Rotate the currently visible content
 127  * around a diagonal axis in the middle of its height, the other content is
 128  * shown as the other side of the flip.
 129  * @li ELM_FLIP_CUBE_LEFT - Rotate the currently visible content to the left
 130  * as if the flip was a cube, the other content is show as the right face of
 131  * the cube.
 132  * @li ELM_FLIP_CUBE_RIGHT - Rotate the currently visible content to the
 133  * right as if the flip was a cube, the other content is show as the left
 134  * face of the cube.
 135  * @li ELM_FLIP_CUBE_UP - Rotate the currently visible content up as if the
 136  * flip was a cube, the other content is show as the bottom face of the cube.
 137  * @li ELM_FLIP_CUBE_DOWN - Rotate the currently visible content down as if
 138  * the flip was a cube, the other content is show as the upper face of the
 139  * cube.
 140  * @li ELM_FLIP_PAGE_LEFT - Move the currently visible content to the left as
 141  * if the flip was a book, the other content is shown as the page below that.
 142  * @li ELM_FLIP_PAGE_RIGHT - Move the currently visible content to the right
 143  * as if the flip was a book, the other content is shown as the page below
 144  * that.
 145  * @li ELM_FLIP_PAGE_UP - Move the currently visible content up as if the
 146  * flip was a book, the other content is shown as the page below that.
 147  * @li ELM_FLIP_PAGE_DOWN - Move the currently visible content down as if the
 148  * flip was a book, the other content is shown as the page below that.
 149  *
 150  * @image html elm_flip.png
 151  * @image latex elm_flip.eps width=\textwidth
 152  *
 153  * @see elm_flip_go_to()
 154  *
 155  * @ingroup Flip
 156  */
 157 EAPI void                 elm_flip_go(Evas_Object *obj, Elm_Flip_Mode mode);
 158
 159 /**
 160  * @brief Runs the flip animation to front or back.
 161  *
 162  * @param obj The flip object
 163  * @param front if @c EINA_TRUE, makes front visible, otherwise makes back.
 164  * @param mode The mode type
 165  *
 166  * Flips the front and back contents using the @p mode animation. This
 167  * effectively hides the currently visible content and shows the hidden one.
 168  *
 169  * There a number of possible animations to use for the flipping:
 170  * @li ELM_FLIP_ROTATE_X_CENTER_AXIS - Rotate the currently visible content
 171  * around a horizontal axis in the middle of its height, the other content
 172  * is shown as the other side of the flip.
 173  * @li ELM_FLIP_ROTATE_Y_CENTER_AXIS - Rotate the currently visible content
 174  * around a vertical axis in the middle of its width, the other content is
 175  * shown as the other side of the flip.
 176  * @li ELM_FLIP_ROTATE_XZ_CENTER_AXIS - Rotate the currently visible content
 177  * around a diagonal axis in the middle of its width, the other content is
 178  * shown as the other side of the flip.
 179  * @li ELM_FLIP_ROTATE_YZ_CENTER_AXIS - Rotate the currently visible content
 180  * around a diagonal axis in the middle of its height, the other content is
 181  * shown as the other side of the flip.
 182  * @li ELM_FLIP_CUBE_LEFT - Rotate the currently visible content to the left
 183  * as if the flip was a cube, the other content is show as the right face of
 184  * the cube.
 185  * @li ELM_FLIP_CUBE_RIGHT - Rotate the currently visible content to the
 186  * right as if the flip was a cube, the other content is show as the left
 187  * face of the cube.
 188  * @li ELM_FLIP_CUBE_UP - Rotate the currently visible content up as if the
 189  * flip was a cube, the other content is show as the bottom face of the cube.
 190  * @li ELM_FLIP_CUBE_DOWN - Rotate the currently visible content down as if
 191  * the flip was a cube, the other content is show as the upper face of the
 192  * cube.
 193  * @li ELM_FLIP_PAGE_LEFT - Move the currently visible content to the left as
 194  * if the flip was a book, the other content is shown as the page below that.
 195  * @li ELM_FLIP_PAGE_RIGHT - Move the currently visible content to the right
 196  * as if the flip was a book, the other content is shown as the page below
 197  * that.
 198  * @li ELM_FLIP_PAGE_UP - Move the currently visible content up as if the
 199  * flip was a book, the other content is shown as the page below that.
 200  * @li ELM_FLIP_PAGE_DOWN - Move the currently visible content down as if the
 201  * flip was a book, the other content is shown as the page below that.
 202  *
 203  * @image html elm_flip.png
 204  * @image latex elm_flip.eps width=\textwidth
 205  *
 206  * @since 1.7
 207  *
 208  * @ingroup Flip
 209  */
 210 EAPI void                 elm_flip_go_to(Evas_Object *obj, Eina_Bool front, Elm_Flip_Mode mode);
 211
 212 /**
 213  * @brief Set the interactive flip mode
 214  *
 215  * @param obj The flip object
 216  * @param mode The interactive flip mode to use
 217  *
 218  * This sets if the flip should be interactive (allow user to click and
 219  * drag a side of the flip to reveal the back page and cause it to flip).
 220  * By default a flip is not interactive. You may also need to set which
 221  * sides of the flip are "active" for flipping and how much space they use
 222  * (a minimum of a finger size) with elm_flip_interaction_direction_enabled_set()
 223  * and elm_flip_interaction_direction_hitsize_set()
 224  *
 225  * The four available mode of interaction are:
 226  * @li ELM_FLIP_INTERACTION_NONE - No interaction is allowed
 227  * @li ELM_FLIP_INTERACTION_ROTATE - Interaction will cause rotate animation
 228  * @li ELM_FLIP_INTERACTION_CUBE - Interaction will cause cube animation
 229  * @li ELM_FLIP_INTERACTION_PAGE - Interaction will cause page animation
 230  *
 231  * @note ELM_FLIP_INTERACTION_ROTATE won't cause
 232  * ELM_FLIP_ROTATE_XZ_CENTER_AXIS or ELM_FLIP_ROTATE_YZ_CENTER_AXIS to
 233  * happen, those can only be achieved with elm_flip_go();
 234  *
 235  * @ingroup Flip
 236  */
 237 EAPI void                 elm_flip_interaction_set(Evas_Object *obj, Elm_Flip_Interaction mode);
 238
 239 /**
 240  * @brief Get the interactive flip mode
 241  *
 242  * @param obj The flip object
 243  * @return The interactive flip mode
 244  *
 245  * Returns the interactive flip mode set by elm_flip_interaction_set()
 246  *
 247  * @ingroup Flip
 248  */
 249 EAPI Elm_Flip_Interaction elm_flip_interaction_get(const Evas_Object *obj);
 250
 251 /**
 252  * @brief Set which directions of the flip respond to interactive flip
 253  *
 254  * @param obj The flip object
 255  * @param dir The direction to change
 256  * @param enabled If that direction is enabled or not
 257  *
 258  * By default all directions are disabled, so you may want to enable the
 259  * desired directions for flipping if you need interactive flipping. You must
 260  * call this function once for each direction that should be enabled.
 261  *
 262  * @see elm_flip_interaction_set()
 263  *
 264  * @ingroup Flip
 265  */
 266 EAPI void                 elm_flip_interaction_direction_enabled_set(Evas_Object *obj, Elm_Flip_Direction dir, Eina_Bool enabled);
 267
 268 /**
 269  * @brief Get the enabled state of that flip direction
 270  *
 271  * @param obj The flip object
 272  * @param dir The direction to check
 273  * @return If that direction is enabled or not
 274  *
 275  * Gets the enabled state set by elm_flip_interaction_direction_enabled_set()
 276  *
 277  * @see elm_flip_interaction_set()
 278  *
 279  * @ingroup Flip
 280  */
 281 EAPI Eina_Bool            elm_flip_interaction_direction_enabled_get(Evas_Object *obj, Elm_Flip_Direction dir);
 282
 283 /**
 284  * @brief Set the amount of the flip that is sensitive to interactive flip
 285  *
 286  * @param obj The flip object
 287  * @param dir The direction to modify
 288  * @param hitsize The amount of that dimension (0.0 to 1.0) to use
 289  *
 290  * Set the amount of the flip that is sensitive to interactive flip, with 0
 291  * representing no area in the flip and 1 representing the entire flip. There
 292  * is however a consideration to be made in that the area will never be
 293  * smaller than the finger size set(as set in your Elementary configuration).
 294  *
 295  * @see elm_flip_interaction_set()
 296  *
 297  * @ingroup Flip
 298  */
 299 EAPI void                 elm_flip_interaction_direction_hitsize_set(Evas_Object *obj, Elm_Flip_Direction dir, double hitsize);
 300
 301 /**
 302  * @brief Get the amount of the flip that is sensitive to interactive flip
 303  *
 304  * @param obj The flip object
 305  * @param dir The direction to check
 306  * @return The size set for that direction
 307  *
 308  * Returns the amount of sensitive area set by
 309  * elm_flip_interaction_direction_hitsize_set().
 310  *
 311  * @ingroup Flip
 312  */
 313 EAPI double               elm_flip_interaction_direction_hitsize_get(Evas_Object *obj, Elm_Flip_Direction dir);
 314
 315 /**
 316  * @}
 317  */