src/lib/elc_hoversel.h

   1 /**
   2  * @defgroup Hoversel Hoversel
   3  *
   4  * @image html img/widget/hoversel/preview-00.png
   5  * @image latex img/widget/hoversel/preview-00.eps
   6  *
   7  * A hoversel is a button that pops up a list of items (automatically
   8  * choosing the direction to display) that have a label and, optionally, an
   9  * icon to select from. It is a convenience widget to avoid the need to do
  10  * all the piecing together yourself. It is intended for a small number of
  11  * items in the hoversel menu (no more than 8), though is capable of many
  12  * more.
  13  *
  14  * Signals that you can add callbacks for are:
  15  * "clicked" - the user clicked the hoversel button and popped up the sel
  16  * "selected" - an item in the hoversel list is selected. event_info is the item
  17  * "dismissed" - the hover is dismissed
  18  *
  19  * Default contents parts of the hoversel widget that you can use for are:
  20  * @li "icon" - An icon of the hoversel
  21  *
  22  * Default text parts of the hoversel widget that you can use for are:
  23  * @li "default" - Label of the hoversel
  24  *
  25  * Supported elm_object common APIs.
  26  * @li elm_object_disabled_set
  27  * @li elm_object_text_set
  28  * @li elm_object_part_text_set
  29  * @li elm_object_text_get
  30  * @li elm_object_part_text_get
  31  * @li elm_object_content_set
  32  * @li elm_object_part_content_set
  33  * @li elm_object_content_unset
  34  * @li elm_object_part_content_unset
  35  *
  36  * Supported elm_object_item common APIs.
  37  * @li elm_object_item_text_get
  38  * @li elm_object_item_part_text_get
  39  *
  40  * See @ref tutorial_hoversel for an example.
  41  * @{
  42  */
  43
  44 /**
  45  * @brief Add a new Hoversel object
  46  *
  47  * @param parent The parent object
  48  * @return The new object or NULL if it cannot be created
  49  */
  50 EAPI Evas_Object *
  51                                   elm_hoversel_add(Evas_Object *parent)
  52 EINA_ARG_NONNULL(1);
  53
  54 /**
  55  * @brief This sets the hoversel to expand horizontally.
  56  *
  57  * @param obj The hoversel object
  58  * @param horizontal If true, the hover will expand horizontally to the
  59  * right.
  60  *
  61  * @note The initial button will display horizontally regardless of this
  62  * setting.
  63  */
  64 EAPI void                         elm_hoversel_horizontal_set(Evas_Object *obj, Eina_Bool horizontal) EINA_ARG_NONNULL(1);
  65
  66 /**
  67  * @brief This returns whether the hoversel is set to expand horizontally.
  68  *
  69  * @param obj The hoversel object
  70  * @return If true, the hover will expand horizontally to the right.
  71  *
  72  * @see elm_hoversel_horizontal_set()
  73  */
  74 EAPI Eina_Bool                    elm_hoversel_horizontal_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
  75
  76 /**
  77  * @brief Set the Hover parent
  78  *
  79  * @param obj The hoversel object
  80  * @param parent The parent to use
  81  *
  82  * Sets the hover parent object, the area that will be darkened when the
  83  * hoversel is clicked. Should probably be the window that the hoversel is
  84  * in. See @ref Hover objects for more information.
  85  */
  86 EAPI void                         elm_hoversel_hover_parent_set(Evas_Object *obj, Evas_Object *parent) EINA_ARG_NONNULL(1);
  87 /**
  88  * @brief Get the Hover parent
  89  *
  90  * @param obj The hoversel object
  91  * @return The used parent
  92  *
  93  * Gets the hover parent object.
  94  *
  95  * @see elm_hoversel_hover_parent_set()
  96  */
  97 EAPI Evas_Object                 *elm_hoversel_hover_parent_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
  98
  99 /**
 100  * @brief Set the hoversel button label
 101  *
 102  * @param obj The hoversel object
 103  * @param label The label text.
 104  *
 105  * This sets the label of the button that is always visible (before it is
 106  * clicked and expanded).
 107  *
 108  * @deprecated elm_object_text_set()
 109  */
 110 EINA_DEPRECATED EAPI void         elm_hoversel_label_set(Evas_Object *obj, const char *label) EINA_ARG_NONNULL(1);
 111
 112 /**
 113  * @brief Get the hoversel button label
 114  *
 115  * @param obj The hoversel object
 116  * @return The label text.
 117  *
 118  * @deprecated elm_object_text_get()
 119  */
 120 EINA_DEPRECATED EAPI const char  *elm_hoversel_label_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
 121
 122 /**
 123  * @brief Set the icon of the hoversel button
 124  *
 125  * @param obj The hoversel object
 126  * @param icon The icon object
 127  *
 128  * Sets the icon of the button that is always visible (before it is clicked
 129  * and expanded).  Once the icon object is set, a previously set one will be
 130  * deleted, if you want to keep that old content object, use the
 131  * elm_hoversel_icon_unset() function.
 132  *
 133  * @see elm_object_content_set() for the button widget
 134  * @deprecated Use elm_object_item_part_content_set() instead
 135  */
 136 EINA_DEPRECATED EAPI void         elm_hoversel_icon_set(Evas_Object *obj, Evas_Object *icon) EINA_ARG_NONNULL(1);
 137
 138 /**
 139  * @brief Get the icon of the hoversel button
 140  *
 141  * @param obj The hoversel object
 142  * @return The icon object
 143  *
 144  * Get the icon of the button that is always visible (before it is clicked
 145  * and expanded). Also see elm_object_content_get() for the button widget.
 146  *
 147  * @see elm_hoversel_icon_set()
 148  * @deprecated Use elm_object_item_part_content_get() instead
 149  */
 150 EINA_DEPRECATED EAPI Evas_Object *elm_hoversel_icon_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
 151
 152 /**
 153  * @brief Get and unparent the icon of the hoversel button
 154  *
 155  * @param obj The hoversel object
 156  * @return The icon object that was being used
 157  *
 158  * Unparent and return the icon of the button that is always visible
 159  * (before it is clicked and expanded).
 160  *
 161  * @see elm_hoversel_icon_set()
 162  * @see elm_object_content_unset() for the button widget
 163  * @deprecated Use elm_object_item_part_content_unset() instead
 164  */
 165 EINA_DEPRECATED EAPI Evas_Object *elm_hoversel_icon_unset(Evas_Object *obj) EINA_ARG_NONNULL(1);
 166
 167 /**
 168  * @brief This triggers the hoversel popup from code, the same as if the user
 169  * had clicked the button.
 170  *
 171  * @param obj The hoversel object
 172  */
 173 EAPI void                         elm_hoversel_hover_begin(Evas_Object *obj) EINA_ARG_NONNULL(1);
 174
 175 /**
 176  * @brief This dismisses the hoversel popup as if the user had clicked
 177  * outside the hover.
 178  *
 179  * @param obj The hoversel object
 180  */
 181 EAPI void                         elm_hoversel_hover_end(Evas_Object *obj) EINA_ARG_NONNULL(1);
 182
 183 /**
 184  * @brief Returns whether the hoversel is expanded.
 185  *
 186  * @param obj The hoversel object
 187  * @return  This will return EINA_TRUE if the hoversel is expanded or
 188  * EINA_FALSE if it is not expanded.
 189  */
 190 EAPI Eina_Bool                    elm_hoversel_expanded_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
 191
 192 /**
 193  * @brief This will remove all the children items from the hoversel.
 194  *
 195  * @param obj The hoversel object
 196  *
 197  * @warning Should @b not be called while the hoversel is active; use
 198  * elm_hoversel_expanded_get() to check first.
 199  *
 200  * @see elm_hoversel_item_del_cb_set()
 201  * @see elm_hoversel_item_del()
 202  */
 203 EAPI void                         elm_hoversel_clear(Evas_Object *obj) EINA_ARG_NONNULL(1);
 204
 205 /**
 206  * @brief Get the list of items within the given hoversel.
 207  *
 208  * @param obj The hoversel object
 209  * @return Returns a list of Elm_Object_Item*
 210  *
 211  * @see elm_hoversel_item_add()
 212  */
 213 EAPI const Eina_List             *elm_hoversel_items_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
 214
 215 /**
 216  * @brief Add an item to the hoversel button
 217  *
 218  * @param obj The hoversel object
 219  * @param label The text label to use for the item (NULL if not desired)
 220  * @param icon_file An image file path on disk to use for the icon or standard
 221  * icon name (NULL if not desired)
 222  * @param icon_type The icon type if relevant
 223  * @param func Convenience function to call when this item is selected
 224  * @param data Data to pass to item-related functions
 225  * @return A handle to the item added.
 226  *
 227  * This adds an item to the hoversel to show when it is clicked. Note: if you
 228  * need to use an icon from an edje file then use
 229  * elm_hoversel_item_icon_set() right after the this function, and set
 230  * icon_file to NULL here.
 231  *
 232  * For more information on what @p icon_file and @p icon_type are see the
 233  * @ref Icon "icon documentation".
 234  */
 235 EAPI Elm_Object_Item             *elm_hoversel_item_add(Evas_Object *obj, const char *label, const char *icon_file, Elm_Icon_Type icon_type, Evas_Smart_Cb func, const void *data) EINA_ARG_NONNULL(1);
 236
 237 /**
 238  * @brief Delete an item from the hoversel
 239  *
 240  * @param it The item to delete
 241  *
 242  * This deletes the item from the hoversel (should not be called while the
 243  * hoversel is active; use elm_hoversel_expanded_get() to check first).
 244  *
 245  * @see elm_hoversel_item_add()
 246  * @see elm_hoversel_item_del_cb_set()
 247  */
 248 EAPI void                         elm_hoversel_item_del(Elm_Object_Item *it) EINA_ARG_NONNULL(1);
 249
 250 /**
 251  * @brief Set the function to be called when an item from the hoversel is
 252  * freed.
 253  *
 254  * @param item The item to set the callback on
 255  * @param func The function called
 256  *
 257  * That function will receive these parameters:
 258  * @li void * item data
 259  * @li Evas_Object * hoversel object
 260  * @li Elm_Object_Item * hoversel item
 261  *
 262  * @see elm_hoversel_item_add()
 263  */
 264 EAPI void                         elm_hoversel_item_del_cb_set(Elm_Object_Item *it, Evas_Smart_Cb func) EINA_ARG_NONNULL(1);
 265
 266 /**
 267  * @brief This returns the data pointer supplied with elm_hoversel_item_add()
 268  * that will be passed to associated function callbacks.
 269  *
 270  * @param it The item to get the data from
 271  * @return The data pointer set with elm_hoversel_item_add()
 272  *
 273  * @see elm_hoversel_item_add()
 274  * @deprecated Use elm_object_item_data_get() instead
 275  */
 276 EINA_DEPRECATED EAPI void        *elm_hoversel_item_data_get(const Elm_Object_Item *it) EINA_ARG_NONNULL(1);
 277
 278 /**
 279  * @brief This returns the label text of the given hoversel item.
 280  *
 281  * @param it The item to get the label
 282  * @return The label text of the hoversel item
 283  *
 284  * @see elm_hoversel_item_add()
 285  * @deprecated Use elm_object_item_text_get() instead
 286  */
 287 EINA_DEPRECATED EAPI const char  *elm_hoversel_item_label_get(const Elm_Object_Item *it) EINA_ARG_NONNULL(1);
 288
 289 /**
 290  * @brief This sets the icon for the given hoversel item.
 291  *
 292  * @param item The item to set the icon
 293  * @param icon_file An image file path on disk to use for the icon or standard
 294  * icon name
 295  * @param icon_group The edje group to use if @p icon_file is an edje file. Set this
 296  * to NULL if the icon is not an edje file
 297  * @param icon_type The icon type
 298  *
 299  * The icon can be loaded from the standard set, from an image file, or from
 300  * an edje file.
 301  *
 302  * @see elm_hoversel_item_add()
 303  */
 304 EAPI void                         elm_hoversel_item_icon_set(Elm_Object_Item *it, const char *icon_file, const char *icon_group, Elm_Icon_Type icon_type) EINA_ARG_NONNULL(1);
 305
 306 /**
 307  * @brief Get the icon object of the hoversel item
 308  *
 309  * @param item The item to get the icon from
 310  * @param icon_file The image file path on disk used for the icon or standard
 311  * icon name
 312  * @param icon_group The edje group used if @p icon_file is an edje file. NULL
 313  * if the icon is not an edje file
 314  * @param icon_type The icon type
 315  *
 316  * @see elm_hoversel_item_icon_set()
 317  * @see elm_hoversel_item_add()
 318  */
 319 EAPI void                         elm_hoversel_item_icon_get(const Elm_Object_Item *it, const char **icon_file, const char **icon_group, Elm_Icon_Type *icon_type) EINA_ARG_NONNULL(1);
 320
 321 /**
 322  * @}
 323  */