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