src/lib/elm_flip.h

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