src/lib/elm_hover.h

   1 /**
   2  * @defgroup Hover Hover
   3  *
   4  * @image html img/widget/hover/preview-00.png
   5  * @image latex img/widget/hover/preview-00.eps
   6  *
   7  * A Hover object will hover over its @p parent object at the @p target
   8  * location. Anything in the background will be given a darker coloring to
   9  * indicate that the hover object is on top (at the default theme). When the
  10  * hover is clicked it is dismissed(hidden), if the contents of the hover are
  11  * clicked that @b doesn't cause the hover to be dismissed.
  12  *
  13  * A Hover object has two parents. One parent that owns it during creation
  14  * and the other parent being the one over which the hover object spans.
  15  *
  16  *
  17  * @note The hover object will take up the entire space of @p target
  18  * object.
  19  *
  20  * Elementary has the following styles for the hover widget:
  21  * @li default
  22  * @li popout
  23  * @li menu
  24  * @li hoversel_vertical
  25  *
  26  * The following are the available position for content:
  27  * @li left
  28  * @li top-left
  29  * @li top
  30  * @li top-right
  31  * @li right
  32  * @li bottom-right
  33  * @li bottom
  34  * @li bottom-left
  35  * @li middle
  36  * @li smart
  37  *
  38  * Signals that you can add callbacks for are:
  39  * @li "clicked" - the user clicked the empty space in the hover to dismiss
  40  * @li "smart,changed" - a content object placed under the "smart"
  41  *                   policy was replaced to a new slot direction.
  42  *
  43  * See @ref tutorial_hover for more information.
  44  *
  45  * @{
  46  */
  47 typedef enum _Elm_Hover_Axis
  48 {
  49    ELM_HOVER_AXIS_NONE, /**< ELM_HOVER_AXIS_NONE -- no prefered orientation */
  50    ELM_HOVER_AXIS_HORIZONTAL, /**< ELM_HOVER_AXIS_HORIZONTAL -- horizontal */
  51    ELM_HOVER_AXIS_VERTICAL, /**< ELM_HOVER_AXIS_VERTICAL -- vertical */
  52    ELM_HOVER_AXIS_BOTH /**< ELM_HOVER_AXIS_BOTH -- both */
  53 } Elm_Hover_Axis;
  54
  55 /**
  56  * @brief Adds a hover object to @p parent
  57  *
  58  * @param parent The parent object
  59  * @return The hover object or NULL if one could not be created
  60  */
  61 EAPI Evas_Object *
  62                   elm_hover_add(Evas_Object *parent)
  63 EINA_ARG_NONNULL(1);
  64
  65 /**
  66  * @brief Sets the target object for the hover.
  67  *
  68  * @param obj The hover object
  69  * @param target The object to center the hover onto.
  70  *
  71  * This function will cause the hover to be centered on the target object.
  72  */
  73 EAPI void         elm_hover_target_set(Evas_Object *obj, Evas_Object *target) EINA_ARG_NONNULL(1);
  74
  75 /**
  76  * @brief Gets the target object for the hover.
  77  *
  78  * @param obj The hover object
  79  * @return The target object for the hover.
  80  *
  81  * @see elm_hover_target_set()
  82  */
  83 EAPI Evas_Object *elm_hover_target_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
  84
  85 /**
  86  * @brief Sets the parent object for the hover.
  87  *
  88  * @param obj The hover object
  89  * @param parent The object to locate the hover over.
  90  *
  91  * This function will cause the hover to take up the entire space that the
  92  * parent object fills.
  93  */
  94 EAPI void         elm_hover_parent_set(Evas_Object *obj, Evas_Object *parent) EINA_ARG_NONNULL(1);
  95
  96 /**
  97  * @brief Gets the parent object for the hover.
  98  *
  99  * @param obj The hover object
 100  * @return The parent object to locate the hover over.
 101  *
 102  * @see elm_hover_parent_set()
 103  */
 104 EAPI Evas_Object *elm_hover_parent_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
 105
 106 /**
 107  * @brief Sets the content of the hover object and the direction in which it
 108  * will pop out.
 109  *
 110  * @param obj The hover object
 111  * @param swallow The direction that the object will be displayed
 112  * at. Accepted values are "left", "top-left", "top", "top-right",
 113  * "right", "bottom-right", "bottom", "bottom-left", "middle" and
 114  * "smart".
 115  * @param content The content to place at @p swallow
 116  *
 117  * Once the content object is set for a given direction, a previously
 118  * set one (on the same direction) will be deleted. If you want to
 119  * keep that old content object, use the elm_hover_content_unset()
 120  * function.
 121  *
 122  * All directions may have contents at the same time, except for
 123  * "smart". This is a special placement hint and its use case
 124  * independs of the calculations coming from
 125  * elm_hover_best_content_location_get(). Its use is for cases when
 126  * one desires only one hover content, but with a dynamic special
 127  * placement within the hover area. The content's geometry, whenever
 128  * it changes, will be used to decide on a best location, not
 129  * extrapolating the hover's parent object view to show it in (still
 130  * being the hover's target determinant of its medium part -- move and
 131  * resize it to simulate finger sizes, for example). If one of the
 132  * directions other than "smart" are used, a previously content set
 133  * using it will be deleted, and vice-versa.
 134  */
 135 EAPI void         elm_hover_content_set(Evas_Object *obj, const char *swallow, Evas_Object *content) EINA_ARG_NONNULL(1);
 136
 137 /**
 138  * @brief Get the content of the hover object, in a given direction.
 139  *
 140  * Return the content object which was set for this widget in the
 141  * @p swallow direction.
 142  *
 143  * @param obj The hover object
 144  * @param swallow The direction that the object was display at.
 145  * @return The content that was being used
 146  *
 147  * @see elm_hover_content_set()
 148  */
 149 EAPI Evas_Object *elm_hover_content_get(const Evas_Object *obj, const char *swallow) EINA_ARG_NONNULL(1);
 150
 151 /**
 152  * @brief Unset the content of the hover object, in a given direction.
 153  *
 154  * Unparent and return the content object set at @p swallow direction.
 155  *
 156  * @param obj The hover object
 157  * @param swallow The direction that the object was display at.
 158  * @return The content that was being used.
 159  *
 160  * @see elm_hover_content_set()
 161  */
 162 EAPI Evas_Object *elm_hover_content_unset(Evas_Object *obj, const char *swallow) EINA_ARG_NONNULL(1);
 163
 164 /**
 165  * @brief Returns the best swallow location for content in the hover.
 166  *
 167  * @param obj The hover object
 168  * @param pref_axis The preferred orientation axis for the hover object to use
 169  * @return The edje location to place content into the hover or @c
 170  *         NULL, on errors.
 171  *
 172  * Best is defined here as the location at which there is the most available
 173  * space.
 174  *
 175  * @p pref_axis may be one of
 176  * - @c ELM_HOVER_AXIS_NONE -- no prefered orientation
 177  * - @c ELM_HOVER_AXIS_HORIZONTAL -- horizontal
 178  * - @c ELM_HOVER_AXIS_VERTICAL -- vertical
 179  * - @c ELM_HOVER_AXIS_BOTH -- both
 180  *
 181  * If ELM_HOVER_AXIS_HORIZONTAL is choosen the returned position will
 182  * nescessarily be along the horizontal axis("left" or "right"). If
 183  * ELM_HOVER_AXIS_VERTICAL is choosen the returned position will nescessarily
 184  * be along the vertical axis("top" or "bottom"). Chossing
 185  * ELM_HOVER_AXIS_BOTH or ELM_HOVER_AXIS_NONE has the same effect and the
 186  * returned position may be in either axis.
 187  *
 188  * @see elm_hover_content_set()
 189  */
 190 EAPI const char  *elm_hover_best_content_location_get(const Evas_Object *obj, Elm_Hover_Axis pref_axis) EINA_ARG_NONNULL(1);
 191
 192 /**
 193  * @}
 194  */