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 <<<<<<< HEAD
  44  * Default contents parts of the hover widget that you can use for are:
  45 =======
  46  * Default content parts of the hover widget that you can use for are:
  47 >>>>>>> remotes/origin/upstream
  48  * @li "left"
  49  * @li "top-left"
  50  * @li "top"
  51  * @li "top-right"
  52  * @li "right"
  53  * @li "bottom-right"
  54  * @li "bottom"
  55  * @li "bottom-left"
  56  * @li "middle"
  57  * @li "smart"
  58  *
  59 <<<<<<< HEAD
  60  * @note These contents parts indicates the direction that the content will be
  61 =======
  62  * @note These content parts indicates the direction that the content will be
  63 >>>>>>> remotes/origin/upstream
  64  * displayed
  65  *
  66  * All directions may have contents at the same time, except for
  67  * "smart". This is a special placement hint and its use case
  68 <<<<<<< HEAD
  69  * independs of the calculations coming from
  70 =======
  71  * depends of the calculations coming from
  72 >>>>>>> remotes/origin/upstream
  73  * elm_hover_best_content_location_get(). Its use is for cases when
  74  * one desires only one hover content, but with a dynamic special
  75  * placement within the hover area. The content's geometry, whenever
  76  * it changes, will be used to decide on a best location, not
  77  * extrapolating the hover's parent object view to show it in (still
  78  * being the hover's target determinant of its medium part -- move and
  79  * resize it to simulate finger sizes, for example). If one of the
  80  * directions other than "smart" are used, a previously content set
  81  * using it will be deleted, and vice-versa.
  82  *
  83  * Supported elm_object common APIs.
  84  * @li elm_object_signal_emit
  85  * @li elm_object_signal_callback_add
  86  * @li elm_object_signal_callback_del
  87  * @li elm_object_part_content_set
  88  * @li elm_object_part_content_get
  89  * @li elm_object_part_content_unset
  90  *
  91  * See @ref tutorial_hover for more information.
  92  *
  93  * @{
  94  */
  95 typedef enum
  96 {
  97 <<<<<<< HEAD
  98    ELM_HOVER_AXIS_NONE, /**< ELM_HOVER_AXIS_NONE -- no prefered orientation */
  99 =======
 100    ELM_HOVER_AXIS_NONE, /**< ELM_HOVER_AXIS_NONE -- no preferred orientation */
 101 >>>>>>> remotes/origin/upstream
 102    ELM_HOVER_AXIS_HORIZONTAL, /**< ELM_HOVER_AXIS_HORIZONTAL -- horizontal */
 103    ELM_HOVER_AXIS_VERTICAL, /**< ELM_HOVER_AXIS_VERTICAL -- vertical */
 104    ELM_HOVER_AXIS_BOTH /**< ELM_HOVER_AXIS_BOTH -- both */
 105 } Elm_Hover_Axis;
 106
 107 /**
 108  * @brief Adds a hover object to @p parent
 109  *
 110  * @param parent The parent object
 111  * @return The hover object or NULL if one could not be created
 112  */
 113 EAPI Evas_Object *elm_hover_add(Evas_Object *parent);
 114
 115 /**
 116  * @brief Sets the target object for the hover.
 117  *
 118  * @param obj The hover object
 119  * @param target The object to center the hover onto.
 120  *
 121  * This function will cause the hover to be centered on the target object.
 122  */
 123 EAPI void         elm_hover_target_set(Evas_Object *obj, Evas_Object *target);
 124
 125 /**
 126  * @brief Gets the target object for the hover.
 127  *
 128  * @param obj The hover object
 129  * @return The target object for the hover.
 130  *
 131  * @see elm_hover_target_set()
 132  */
 133 EAPI Evas_Object *elm_hover_target_get(const Evas_Object *obj);
 134
 135 /**
 136  * @brief Sets the parent object for the hover.
 137  *
 138  * @param obj The hover object
 139  * @param parent The object to locate the hover over.
 140  *
 141  * This function will cause the hover to take up the entire space that the
 142  * parent object fills.
 143  */
 144 EAPI void         elm_hover_parent_set(Evas_Object *obj, Evas_Object *parent);
 145
 146 /**
 147  * @brief Gets the parent object for the hover.
 148  *
 149  * @param obj The hover object
 150  * @return The parent object to locate the hover over.
 151  *
 152  * @see elm_hover_parent_set()
 153  */
 154 EAPI Evas_Object *elm_hover_parent_get(const Evas_Object *obj);
 155
 156 /**
 157  * @brief Returns the best swallow location for content in the hover.
 158  *
 159  * @param obj The hover object
 160  * @param pref_axis The preferred orientation axis for the hover object to use
 161  * @return The edje location to place content into the hover or @c
 162  *         NULL, on errors.
 163  *
 164  * Best is defined here as the location at which there is the most available
 165  * space.
 166  *
 167  * @p pref_axis may be one of
 168 <<<<<<< HEAD
 169  * - @c ELM_HOVER_AXIS_NONE -- no prefered orientation
 170 =======
 171  * - @c ELM_HOVER_AXIS_NONE -- no preferred orientation
 172 >>>>>>> remotes/origin/upstream
 173  * - @c ELM_HOVER_AXIS_HORIZONTAL -- horizontal
 174  * - @c ELM_HOVER_AXIS_VERTICAL -- vertical
 175  * - @c ELM_HOVER_AXIS_BOTH -- both
 176  *
 177 <<<<<<< HEAD
 178  * If ELM_HOVER_AXIS_HORIZONTAL is choosen the returned position will
 179  * nescessarily be along the horizontal axis("left" or "right"). If
 180  * ELM_HOVER_AXIS_VERTICAL is choosen the returned position will nescessarily
 181  * be along the vertical axis("top" or "bottom"). Chossing
 182 =======
 183  * If ELM_HOVER_AXIS_HORIZONTAL is chosen the returned position will
 184  * necessarily be along the horizontal axis("left" or "right"). If
 185  * ELM_HOVER_AXIS_VERTICAL is chosen the returned position will necessarily
 186  * be along the vertical axis("top" or "bottom"). Choosing
 187 >>>>>>> remotes/origin/upstream
 188  * ELM_HOVER_AXIS_BOTH or ELM_HOVER_AXIS_NONE has the same effect and the
 189  * returned position may be in either axis.
 190  *
 191  * @see elm_object_part_content_set()
 192  */
 193 EAPI const char  *elm_hover_best_content_location_get(const Evas_Object *obj, Elm_Hover_Axis pref_axis);
 194
 195 /**
 196  * @brief Dismiss a hover object
 197  *
 198  * @param obj The hover object
 199  * Use this function to simulate clicking outside the hover to dismiss it.
 200  * In this way, the hover will be hidden and the "clicked" signal will be emitted.
 201  */
 202 EAPI void elm_hover_dismiss(Evas_Object *obj);
 203 /**
 204  * @}
 205  */