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 *elm_hover_add(Evas_Object *parent) EINA_ARG_NONNULL(1);
  62
  63    /**
  64     * @brief Sets the target object for the hover.
  65     *
  66     * @param obj The hover object
  67     * @param target The object to center the hover onto.
  68     *
  69     * This function will cause the hover to be centered on the target object.
  70     */
  71    EAPI void         elm_hover_target_set(Evas_Object *obj, Evas_Object *target) EINA_ARG_NONNULL(1);
  72
  73    /**
  74     * @brief Gets the target object for the hover.
  75     *
  76     * @param obj The hover object
  77     * @return The target object for the hover.
  78     *
  79     * @see elm_hover_target_set()
  80     */
  81    EAPI Evas_Object *elm_hover_target_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
  82
  83    /**
  84     * @brief Sets the parent object for the hover.
  85     *
  86     * @param obj The hover object
  87     * @param parent The object to locate the hover over.
  88     *
  89     * This function will cause the hover to take up the entire space that the
  90     * parent object fills.
  91     */
  92    EAPI void         elm_hover_parent_set(Evas_Object *obj, Evas_Object *parent) EINA_ARG_NONNULL(1);
  93
  94    /**
  95     * @brief Gets the parent object for the hover.
  96     *
  97     * @param obj The hover object
  98     * @return The parent object to locate the hover over.
  99     *
 100     * @see elm_hover_parent_set()
 101     */
 102    EAPI Evas_Object *elm_hover_parent_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
 103
 104    /**
 105     * @brief Sets the content of the hover object and the direction in which it
 106     * will pop out.
 107     *
 108     * @param obj The hover object
 109     * @param swallow The direction that the object will be displayed
 110     * at. Accepted values are "left", "top-left", "top", "top-right",
 111     * "right", "bottom-right", "bottom", "bottom-left", "middle" and
 112     * "smart".
 113     * @param content The content to place at @p swallow
 114     *
 115     * Once the content object is set for a given direction, a previously
 116     * set one (on the same direction) will be deleted. If you want to
 117     * keep that old content object, use the elm_hover_content_unset()
 118     * function.
 119     *
 120     * All directions may have contents at the same time, except for
 121     * "smart". This is a special placement hint and its use case
 122     * independs of the calculations coming from
 123     * elm_hover_best_content_location_get(). Its use is for cases when
 124     * one desires only one hover content, but with a dynamic special
 125     * placement within the hover area. The content's geometry, whenever
 126     * it changes, will be used to decide on a best location, not
 127     * extrapolating the hover's parent object view to show it in (still
 128     * being the hover's target determinant of its medium part -- move and
 129     * resize it to simulate finger sizes, for example). If one of the
 130     * directions other than "smart" are used, a previously content set
 131     * using it will be deleted, and vice-versa.
 132     */
 133    EAPI void         elm_hover_content_set(Evas_Object *obj, const char *swallow, Evas_Object *content) EINA_ARG_NONNULL(1);
 134
 135    /**
 136     * @brief Get the content of the hover object, in a given direction.
 137     *
 138     * Return the content object which was set for this widget in the
 139     * @p swallow direction.
 140     *
 141     * @param obj The hover object
 142     * @param swallow The direction that the object was display at.
 143     * @return The content that was being used
 144     *
 145     * @see elm_hover_content_set()
 146     */
 147    EAPI Evas_Object *elm_hover_content_get(const Evas_Object *obj, const char *swallow) EINA_ARG_NONNULL(1);
 148
 149    /**
 150     * @brief Unset the content of the hover object, in a given direction.
 151     *
 152     * Unparent and return the content object set at @p swallow direction.
 153     *
 154     * @param obj The hover object
 155     * @param swallow The direction that the object was display at.
 156     * @return The content that was being used.
 157     *
 158     * @see elm_hover_content_set()
 159     */
 160    EAPI Evas_Object *elm_hover_content_unset(Evas_Object *obj, const char *swallow) EINA_ARG_NONNULL(1);
 161
 162    /**
 163     * @brief Returns the best swallow location for content in the hover.
 164     *
 165     * @param obj The hover object
 166     * @param pref_axis The preferred orientation axis for the hover object to use
 167     * @return The edje location to place content into the hover or @c
 168     *         NULL, on errors.
 169     *
 170     * Best is defined here as the location at which there is the most available
 171     * space.
 172     *
 173     * @p pref_axis may be one of
 174     * - @c ELM_HOVER_AXIS_NONE -- no prefered orientation
 175     * - @c ELM_HOVER_AXIS_HORIZONTAL -- horizontal
 176     * - @c ELM_HOVER_AXIS_VERTICAL -- vertical
 177     * - @c ELM_HOVER_AXIS_BOTH -- both
 178     *
 179     * If ELM_HOVER_AXIS_HORIZONTAL is choosen the returned position will
 180     * nescessarily be along the horizontal axis("left" or "right"). If
 181     * ELM_HOVER_AXIS_VERTICAL is choosen the returned position will nescessarily
 182     * be along the vertical axis("top" or "bottom"). Chossing
 183     * ELM_HOVER_AXIS_BOTH or ELM_HOVER_AXIS_NONE has the same effect and the
 184     * returned position may be in either axis.
 185     *
 186     * @see elm_hover_content_set()
 187     */
 188    EAPI const char  *elm_hover_best_content_location_get(const Evas_Object *obj, Elm_Hover_Axis pref_axis) EINA_ARG_NONNULL(1);
 189
 190    /**
 191     * @}
 192     */
 193