src/lib/elc_ctxpopup.h

   1    /**
   2     * @defgroup Ctxpopup Ctxpopup
   3     *
   4     * @image html img/widget/ctxpopup/preview-00.png
   5     * @image latex img/widget/ctxpopup/preview-00.eps
   6     *
   7     * @brief Context popup widet.
   8     *
   9     * A ctxpopup is a widget that, when shown, pops up a list of items.
  10     * It automatically chooses an area inside its parent object's view
  11     * (set via elm_ctxpopup_add() and elm_ctxpopup_hover_parent_set()) to
  12     * optimally fit into it. In the default theme, it will also point an
  13     * arrow to it's top left position at the time one shows it. Ctxpopup
  14     * items have a label and/or an icon. It is intended for a small
  15     * number of items (hence the use of list, not genlist).
  16     *
  17     * @note Ctxpopup is a especialization of @ref Hover.
  18     *
  19     * Signals that you can add callbacks for are:
  20     * "dismissed" - the ctxpopup was dismissed
  21     *
  22     * Default contents parts of the ctxpopup widget that you can use for are:
  23     * @li "default" - A content of the ctxpopup
  24     *
  25     * Default contents parts of the ctxpopup items that you can use for are:
  26     * @li "icon" - An icon in the title area
  27     *
  28     * Default text parts of the ctxpopup items that you can use for are:
  29     * @li "default" - Title label in the title area
  30     *
  31     * @ref tutorial_ctxpopup shows the usage of a good deal of the API.
  32     * @{
  33     */
  34
  35    /**
  36     * @addtogroup Ctxpopup
  37     * @{
  38     */
  39
  40    typedef enum _Elm_Ctxpopup_Direction
  41      {
  42         ELM_CTXPOPUP_DIRECTION_DOWN, /**< ctxpopup show appear below clicked
  43                                           area */
  44         ELM_CTXPOPUP_DIRECTION_RIGHT, /**< ctxpopup show appear to the right of
  45                                            the clicked area */
  46         ELM_CTXPOPUP_DIRECTION_LEFT, /**< ctxpopup show appear to the left of
  47                                           the clicked area */
  48         ELM_CTXPOPUP_DIRECTION_UP, /**< ctxpopup show appear above the clicked
  49                                         area */
  50         ELM_CTXPOPUP_DIRECTION_UNKNOWN, /**< ctxpopup does not determine it's direction yet*/
  51      } Elm_Ctxpopup_Direction;
  52
  53    /**
  54     * @brief Add a new Ctxpopup object to the parent.
  55     *
  56     * @param parent Parent object
  57     * @return New object or @c NULL, if it cannot be created
  58     *
  59     * @ingroup Ctxpopup
  60     */
  61    EAPI Evas_Object  *elm_ctxpopup_add(Evas_Object *parent) EINA_ARG_NONNULL(1);
  62
  63    /**
  64     * @brief Set the Ctxpopup's parent
  65     *
  66     * @param obj The ctxpopup object
  67     * @param area The parent to use
  68     *
  69     * Set the parent object.
  70     *
  71     * @note elm_ctxpopup_add() will automatically call this function
  72     * with its @c parent argument.
  73     *
  74     * @see elm_ctxpopup_add()
  75     * @see elm_hover_parent_set()
  76     *
  77     * @ingroup Ctxpopup
  78     */
  79    EAPI void          elm_ctxpopup_hover_parent_set(Evas_Object *obj, Evas_Object *parent) EINA_ARG_NONNULL(1, 2);
  80
  81    /**
  82     * @brief Get the Ctxpopup's parent
  83     *
  84     * @param obj The ctxpopup object
  85     *
  86     * @see elm_ctxpopup_hover_parent_set() for more information
  87     *
  88     * @ingroup Ctxpopup
  89     */
  90    EAPI Evas_Object  *elm_ctxpopup_hover_parent_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
  91
  92    /**
  93     * @brief Clear all items in the given ctxpopup object.
  94     *
  95     * @param obj Ctxpopup object
  96     *
  97     * @ingroup Ctxpopup
  98     */
  99    EAPI void          elm_ctxpopup_clear(Evas_Object *obj) EINA_ARG_NONNULL(1);
 100
 101    /**
 102     * @brief Change the ctxpopup's orientation to horizontal or vertical.
 103     *
 104     * @param obj Ctxpopup object
 105     * @param horizontal @c EINA_TRUE for horizontal mode, @c EINA_FALSE for vertical
 106     *
 107     * @ingroup Ctxpopup
 108     */
 109    EAPI void          elm_ctxpopup_horizontal_set(Evas_Object *obj, Eina_Bool horizontal) EINA_ARG_NONNULL(1);
 110
 111    /**
 112     * @brief Get the value of current ctxpopup object's orientation.
 113     *
 114     * @param obj Ctxpopup object
 115     * @return @c EINA_TRUE for horizontal mode, @c EINA_FALSE for vertical mode (or errors)
 116     *
 117     * @see elm_ctxpopup_horizontal_set()
 118     *
 119     * @ingroup Ctxpopup
 120     */
 121    EAPI Eina_Bool     elm_ctxpopup_horizontal_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
 122
 123    /**
 124     * @brief Add a new item to a ctxpopup object.
 125     *
 126     * @param obj Ctxpopup object
 127     * @param icon Icon to be set on new item
 128     * @param label The Label of the new item
 129     * @param func Convenience function called when item selected
 130     * @param data Data passed to @p func
 131     * @return A handle to the item added or @c NULL, on errors
 132     *
 133     * @warning Ctxpopup can't hold both an item list and a content at the same
 134     * time. When an item is added, any previous content will be removed.
 135     *
 136     * @see elm_ctxpopup_content_set()
 137     *
 138     * @ingroup Ctxpopup
 139     */
 140    Elm_Object_Item *elm_ctxpopup_item_append(Evas_Object *obj, const char *label, Evas_Object *icon, Evas_Smart_Cb func, const void *data) EINA_ARG_NONNULL(1);
 141
 142    /**
 143     * @brief Delete the given item in a ctxpopup object.
 144     *
 145     * @param it Ctxpopup item to be deleted
 146     *
 147     * @see elm_ctxpopup_item_append()
 148     *
 149     * @ingroup Ctxpopup
 150     */
 151    EAPI void          elm_ctxpopup_item_del(Elm_Object_Item *it) EINA_ARG_NONNULL(1);
 152
 153    /**
 154     * @brief Set the ctxpopup item's state as disabled or enabled.
 155     *
 156     * @param it Ctxpopup item to be enabled/disabled
 157     * @param disabled @c EINA_TRUE to disable it, @c EINA_FALSE to enable it
 158     *
 159     * When disabled the item is greyed out to indicate it's state.
 160     * @deprecated use elm_object_item_disabled_set() instead
 161     *
 162     * @ingroup Ctxpopup
 163     */
 164    EINA_DEPRECATED EAPI void          elm_ctxpopup_item_disabled_set(Elm_Object_Item *it, Eina_Bool disabled) EINA_ARG_NONNULL(1);
 165
 166    /**
 167     * @brief Get the ctxpopup item's disabled/enabled state.
 168     *
 169     * @param it Ctxpopup item to be enabled/disabled
 170     * @return disabled @c EINA_TRUE, if disabled, @c EINA_FALSE otherwise
 171     *
 172     * @see elm_ctxpopup_item_disabled_set()
 173     * @deprecated use elm_object_item_disabled_get() instead
 174     *
 175     * @ingroup Ctxpopup
 176     */
 177    EAPI Eina_Bool     elm_ctxpopup_item_disabled_get(const Elm_Object_Item *it) EINA_ARG_NONNULL(1);
 178
 179    /**
 180     * @brief Get the icon object for the given ctxpopup item.
 181     *
 182     * @param it Ctxpopup item
 183     * @return icon object or @c NULL, if the item does not have icon or an error
 184     * occurred
 185     *
 186     * @see elm_ctxpopup_item_append()
 187     * @see elm_ctxpopup_item_icon_set()
 188     *
 189     * @deprecated use elm_object_item_part_content_get() instead
 190     *
 191     * @ingroup Ctxpopup
 192     */
 193    EINA_DEPRECATED EAPI Evas_Object  *elm_ctxpopup_item_icon_get(const Elm_Object_Item *it) EINA_ARG_NONNULL(1);
 194
 195    /**
 196     * @brief Sets the side icon associated with the ctxpopup item
 197     *
 198     * @param it Ctxpopup item
 199     * @param icon Icon object to be set
 200     *
 201     * Once the icon object is set, a previously set one will be deleted.
 202     * @warning Setting the same icon for two items will cause the icon to
 203     * dissapear from the first item.
 204     *
 205     * @see elm_ctxpopup_item_append()
 206     *
 207     * @deprecated use elm_object_item_part_content_set() instead
 208     *
 209     * @ingroup Ctxpopup
 210     */
 211    EINA_DEPRECATED EAPI void          elm_ctxpopup_item_icon_set(Elm_Object_Item *it, Evas_Object *icon) EINA_ARG_NONNULL(1);
 212
 213    /**
 214     * @brief Get the label for the given ctxpopup item.
 215     *
 216     * @param it Ctxpopup item
 217     * @return label string or @c NULL, if the item does not have label or an
 218     * error occured
 219     *
 220     * @see elm_ctxpopup_item_append()
 221     * @see elm_ctxpopup_item_label_set()
 222     *
 223     * @deprecated use elm_object_item_text_get() instead
 224     *
 225     * @ingroup Ctxpopup
 226     */
 227    EINA_DEPRECATED EAPI const char   *elm_ctxpopup_item_label_get(const Elm_Object_Item *it) EINA_ARG_NONNULL(1);
 228
 229    /**
 230     * @brief (Re)set the label on the given ctxpopup item.
 231     *
 232     * @param it Ctxpopup item
 233     * @param label String to set as label
 234     *
 235     * @deprecated use elm_object_item_text_set() instead
 236     *
 237     * @ingroup Ctxpopup
 238     */
 239    EINA_DEPRECATED EAPI void          elm_ctxpopup_item_label_set(Elm_Object_Item *it, const char *label) EINA_ARG_NONNULL(1);
 240
 241    /**
 242     * @brief Set an elm widget as the content of the ctxpopup.
 243     *
 244     * @param obj Ctxpopup object
 245     * @param content Content to be swallowed
 246     *
 247     * If the content object is already set, a previous one will bedeleted. If
 248     * you want to keep that old content object, use the
 249     * elm_ctxpopup_content_unset() function.
 250     *
 251     * @warning Ctxpopup can't hold both a item list and a content at the same
 252     * time. When a content is set, any previous items will be removed.
 253     *
 254     * @deprecated use elm_object_content_set() instead
 255     *
 256     * @ingroup Ctxpopup
 257     */
 258    EINA_DEPRECATED EAPI void          elm_ctxpopup_content_set(Evas_Object *obj, Evas_Object *content) EINA_ARG_NONNULL(1, 2);
 259
 260    /**
 261     * @brief Unset the ctxpopup content
 262     *
 263     * @param obj Ctxpopup object
 264     * @return The content that was being used
 265     *
 266     * Unparent and return the content object which was set for this widget.
 267     *
 268     * @deprecated use elm_object_content_unset()
 269     *
 270     * @see elm_ctxpopup_content_set()
 271     *
 272     * @deprecated use elm_object_content_unset() instead
 273     *
 274     * @ingroup Ctxpopup
 275     */
 276    EINA_DEPRECATED EAPI Evas_Object  *elm_ctxpopup_content_unset(Evas_Object *obj) EINA_ARG_NONNULL(1);
 277
 278    /**
 279     * @brief Set the direction priority of a ctxpopup.
 280     *
 281     * @param obj Ctxpopup object
 282     * @param first 1st priority of direction
 283     * @param second 2nd priority of direction
 284     * @param third 3th priority of direction
 285     * @param fourth 4th priority of direction
 286     *
 287     * This functions gives a chance to user to set the priority of ctxpopup
 288     * showing direction. This doesn't guarantee the ctxpopup will appear in the
 289     * requested direction.
 290     *
 291     * @see Elm_Ctxpopup_Direction
 292     *
 293     * @ingroup Ctxpopup
 294     */
 295    EAPI void          elm_ctxpopup_direction_priority_set(Evas_Object *obj, Elm_Ctxpopup_Direction first, Elm_Ctxpopup_Direction second, Elm_Ctxpopup_Direction third, Elm_Ctxpopup_Direction fourth) EINA_ARG_NONNULL(1);
 296
 297    /**
 298     * @brief Get the direction priority of a ctxpopup.
 299     *
 300     * @param obj Ctxpopup object
 301     * @param first 1st priority of direction to be returned
 302     * @param second 2nd priority of direction to be returned
 303     * @param third 3th priority of direction to be returned
 304     * @param fourth 4th priority of direction to be returned
 305     *
 306     * @see elm_ctxpopup_direction_priority_set() for more information.
 307     *
 308     * @ingroup Ctxpopup
 309     */
 310    EAPI void          elm_ctxpopup_direction_priority_get(Evas_Object *obj, Elm_Ctxpopup_Direction *first, Elm_Ctxpopup_Direction *second, Elm_Ctxpopup_Direction *third, Elm_Ctxpopup_Direction *fourth) EINA_ARG_NONNULL(1);
 311
 312    /**
 313     * @brief Get the current direction of a ctxpopup.
 314     *
 315     * @param obj Ctxpopup object
 316     * @return current direction of a ctxpopup
 317     *
 318     * @warning Once the ctxpopup showed up, the direction would be determined
 319     *
 320     * @ingroup Ctxpopup
 321     */
 322    EAPI Elm_Ctxpopup_Direction elm_ctxpopup_direction_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
 323
 324    /**
 325     * @}
 326     */
 327