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                 *elm_hoversel_add(Evas_Object *parent);
  51
  52 /**
  53  * @brief This sets the hoversel to expand horizontally.
  54  *
  55  * @param obj The hoversel object
  56  * @param horizontal If true, the hover will expand horizontally to the
  57  * right.
  58  *
  59  * @note The initial button will display horizontally regardless of this
  60  * setting.
  61  */
  62 EAPI void                         elm_hoversel_horizontal_set(Evas_Object *obj, Eina_Bool horizontal);
  63
  64 /**
  65  * @brief This returns whether the hoversel is set to expand horizontally.
  66  *
  67  * @param obj The hoversel object
  68  * @return If true, the hover will expand horizontally to the right.
  69  *
  70  * @see elm_hoversel_horizontal_set()
  71  */
  72 EAPI Eina_Bool                    elm_hoversel_horizontal_get(const Evas_Object *obj);
  73
  74 /**
  75  * @brief Set the Hover parent
  76  *
  77  * @param obj The hoversel object
  78  * @param parent The parent to use
  79  *
  80  * Sets the hover parent object, the area that will be darkened when the
  81  * hoversel is clicked. Should probably be the window that the hoversel is
  82  * in. See @ref Hover objects for more information.
  83  */
  84 EAPI void                         elm_hoversel_hover_parent_set(Evas_Object *obj, Evas_Object *parent);
  85 /**
  86  * @brief Get the Hover parent
  87  *
  88  * @param obj The hoversel object
  89  * @return The used parent
  90  *
  91  * Gets the hover parent object.
  92  *
  93  * @see elm_hoversel_hover_parent_set()
  94  */
  95 EAPI Evas_Object                 *elm_hoversel_hover_parent_get(const Evas_Object *obj);
  96
  97 /**
  98  * @brief This triggers the hoversel popup from code, the same as if the user
  99  * had clicked the button.
 100  *
 101  * @param obj The hoversel object
 102  */
 103 EAPI void                         elm_hoversel_hover_begin(Evas_Object *obj);
 104
 105 /**
 106  * @brief This dismisses the hoversel popup as if the user had clicked
 107  * outside the hover.
 108  *
 109  * @param obj The hoversel object
 110  */
 111 EAPI void                         elm_hoversel_hover_end(Evas_Object *obj);
 112
 113 /**
 114  * @brief Returns whether the hoversel is expanded.
 115  *
 116  * @param obj The hoversel object
 117  * @return  This will return EINA_TRUE if the hoversel is expanded or
 118  * EINA_FALSE if it is not expanded.
 119  */
 120 EAPI Eina_Bool                    elm_hoversel_expanded_get(const Evas_Object *obj);
 121
 122 /**
 123  * @brief This will remove all the children items from the hoversel.
 124  *
 125  * @param obj The hoversel object
 126  *
 127  * @warning Should @b not be called while the hoversel is active; use
 128  * elm_hoversel_expanded_get() to check first.
 129  *
 130  * @see elm_hoversel_item_del()
 131  */
 132 EAPI void                         elm_hoversel_clear(Evas_Object *obj);
 133
 134 /**
 135  * @brief Get the list of items within the given hoversel.
 136  *
 137  * @param obj The hoversel object
 138  * @return Returns a list of Elm_Object_Item*
 139  *
 140  * @see elm_hoversel_item_add()
 141  */
 142 EAPI const Eina_List             *elm_hoversel_items_get(const Evas_Object *obj);
 143
 144 /**
 145  * @brief Add an item to the hoversel button
 146  *
 147  * @param obj The hoversel object
 148  * @param label The text label to use for the item (NULL if not desired)
 149  * @param icon_file An image file path on disk to use for the icon or standard
 150  * icon name (NULL if not desired)
 151  * @param icon_type The icon type if relevant
 152  * @param func Convenience function to call when this item is selected
 153  * @param data Data to pass to item-related functions
 154  * @return A handle to the item added.
 155  *
 156  * This adds an item to the hoversel to show when it is clicked. Note: if you
 157  * need to use an icon from an edje file then use
 158  * elm_hoversel_item_icon_set() right after the this function, and set
 159  * icon_file to NULL here.
 160  *
 161  * For more information on what @p icon_file and @p icon_type are see the
 162  * @ref Icon "icon documentation".
 163  */
 164 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);
 165
 166 /**
 167  * @brief Delete an item from the hoversel
 168  *
 169  * @param it The item to delete
 170  *
 171  * This deletes the item from the hoversel (should not be called while the
 172  * hoversel is active; use elm_hoversel_expanded_get() to check first).
 173  *
 174  * @see elm_hoversel_item_add()
 175  */
 176 EAPI void                         elm_hoversel_item_del(Elm_Object_Item *it);
 177
 178 /**
 179  * @brief This sets the icon for the given hoversel item.
 180  *
 181  * @param it The item to set the icon
 182  * @param icon_file An image file path on disk to use for the icon or standard
 183  * icon name
 184  * @param icon_group The edje group to use if @p icon_file is an edje file. Set this
 185  * to NULL if the icon is not an edje file
 186  * @param icon_type The icon type
 187  *
 188  * The icon can be loaded from the standard set, from an image file, or from
 189  * an edje file.
 190  *
 191  * @see elm_hoversel_item_add()
 192  */
 193 EAPI void                         elm_hoversel_item_icon_set(Elm_Object_Item *it, const char *icon_file, const char *icon_group, Elm_Icon_Type icon_type);
 194
 195 /**
 196  * @brief Get the icon object of the hoversel item
 197  *
 198  * @param it The item to get the icon from
 199  * @param icon_file The image file path on disk used for the icon or standard
 200  * icon name
 201  * @param icon_group The edje group used if @p icon_file is an edje file. NULL
 202  * if the icon is not an edje file
 203  * @param icon_type The icon type
 204  *
 205  * @see elm_hoversel_item_icon_set()
 206  * @see elm_hoversel_item_add()
 207  */
 208 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);
 209
 210 /**
 211  * @}
 212  */