src/lib/elm_flip.h

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