src/lib/elm_hover.h

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