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