src/lib/elm_hover.h

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