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