mobile/src/lib/elm_hover.h

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