src/lib/elc_hoversel.h

   1 /**
   2  * @defgroup Hoversel Hoversel
   3  * @ingroup Elementary
   4  *
   5  * @image html hoversel_inheritance_tree.png
   6  * @image latex hoversel_inheritance_tree.eps
   7  *
   8  * @image html img/widget/hoversel/preview-00.png
   9  * @image latex img/widget/hoversel/preview-00.eps
  10  *
  11  * A hoversel is a button that pops up a list of items (automatically
  12  * choosing the direction to display) that have a label and, optionally, an
  13  * icon to select from. It is a convenience widget to avoid the need to do
  14  * all the piecing together yourself. It is intended for a small number of
  15  * items in the hoversel menu (no more than 8), though is capable of many
  16  * more.
  17  *
  18  * This widget inherits from the @ref Button one, so that all the
  19  * functions acting on it also work for hoversel objects.
  20  *
  21  * This widget emits the following signals, besides the ones sent from
  22  * @ref Button:
  23  * - @c "clicked" - the user clicked the hoversel button and popped up
  24  *   the sel
  25  * - @c "selected" - an item in the hoversel list is selected. event_info
  26  *   is the item
  27  * - @c "dismissed" - the hover is dismissed
  28  *
  29  * Default content parts of the hoversel widget that you can use for are:
  30  * @li "icon" - An icon of the hoversel
  31  *
  32  * Default text parts of the hoversel widget that you can use for are:
  33  * @li "default" - Label of the hoversel
  34  *
  35  * Supported elm_object common APIs.
  36  * @li @ref elm_object_disabled_set
  37  * @li @ref elm_object_disabled_get
  38  * @li @ref elm_object_part_text_set
  39  * @li @ref elm_object_part_text_get
  40  * @li @ref elm_object_part_content_set
  41  * @li @ref elm_object_part_content_unset
  42  *
  43  * Supported elm_object_item common APIs.
  44  * @li elm_object_item_part_text_get
  45  *
  46  * See @ref tutorial_hoversel for an example.
  47  * @{
  48  */
  49
  50 /**
  51  * @brief Add a new Hoversel object
  52  *
  53  * @param parent The parent object
  54  * @return The new object or NULL if it cannot be created
  55  *
  56  * @ingroup Hoversel
  57  */
  58 EAPI Evas_Object                 *elm_hoversel_add(Evas_Object *parent);
  59
  60 /**
  61  * @brief This sets the hoversel to expand horizontally.
  62  *
  63  * @param obj The hoversel object
  64  * @param horizontal If true, the hover will expand horizontally to the
  65  * right.
  66  *
  67  * @note The initial button will display horizontally regardless of this
  68  * setting.
  69  *
  70  * @ingroup Hoversel
  71  */
  72 EAPI void                         elm_hoversel_horizontal_set(Evas_Object *obj, Eina_Bool horizontal);
  73
  74 /**
  75  * @brief This returns whether the hoversel is set to expand horizontally.
  76  *
  77  * @param obj The hoversel object
  78  * @return If true, the hover will expand horizontally to the right.
  79  *
  80  * @see elm_hoversel_horizontal_set()
  81  *
  82  * @ingroup Hoversel
  83  */
  84 EAPI Eina_Bool                    elm_hoversel_horizontal_get(const Evas_Object *obj);
  85
  86 /**
  87  * @brief Set the Hover parent
  88  *
  89  * @param obj The hoversel object
  90  * @param parent The parent to use
  91  *
  92  * Sets the hover parent object, the area that will be darkened when the
  93  * hoversel is clicked. Should probably be the window that the hoversel is
  94  * in. See @ref Hover objects for more information.
  95  *
  96  * @ingroup Hoversel
  97  */
  98 EAPI void                         elm_hoversel_hover_parent_set(Evas_Object *obj, Evas_Object *parent);
  99
 100 /**
 101  * @brief Get the Hover parent
 102  *
 103  * @param obj The hoversel object
 104  * @return The used parent
 105  *
 106  * Gets the hover parent object.
 107  *
 108  * @see elm_hoversel_hover_parent_set()
 109  *
 110  * @ingroup Hoversel
 111  */
 112 EAPI Evas_Object                 *elm_hoversel_hover_parent_get(const Evas_Object *obj);
 113
 114 /**
 115  * @brief This triggers the hoversel popup from code, the same as if the user
 116  * had clicked the button.
 117  *
 118  * @param obj The hoversel object
 119  *
 120  * @ingroup Hoversel
 121  */
 122 EAPI void                         elm_hoversel_hover_begin(Evas_Object *obj);
 123
 124 /**
 125  * @brief This dismisses the hoversel popup as if the user had clicked
 126  * outside the hover.
 127  *
 128  * @param obj The hoversel object
 129  *
 130  * @ingroup Hoversel
 131  */
 132 EAPI void                         elm_hoversel_hover_end(Evas_Object *obj);
 133
 134 /**
 135  * @brief Returns whether the hoversel is expanded.
 136  *
 137  * @param obj The hoversel object
 138  * @return  This will return EINA_TRUE if the hoversel is expanded or
 139  * EINA_FALSE if it is not expanded.
 140  *
 141  * @ingroup Hoversel
 142  */
 143 EAPI Eina_Bool                    elm_hoversel_expanded_get(const Evas_Object *obj);
 144
 145 /**
 146  * @brief This will remove all the children items from the hoversel.
 147  *
 148  * @param obj The hoversel object
 149  *
 150  * @warning Should @b not be called while the hoversel is active; use
 151  * elm_hoversel_expanded_get() to check first.
 152  *
 153  * @see elm_object_item_del()
 154  *
 155  * @ingroup Hoversel
 156  */
 157 EAPI void                         elm_hoversel_clear(Evas_Object *obj);
 158
 159 /**
 160  * @brief Get the list of items within the given hoversel.
 161  *
 162  * @param obj The hoversel object
 163  * @return Returns a list of Elm_Object_Item*
 164  *
 165  * @see elm_hoversel_item_add()
 166  *
 167  * @ingroup Hoversel
 168  */
 169 EAPI const Eina_List             *elm_hoversel_items_get(const Evas_Object *obj);
 170
 171 /**
 172  * @brief Add an item to the hoversel button
 173  *
 174  * @param obj The hoversel object
 175  * @param label The text label to use for the item (NULL if not desired)
 176  * @param icon_file An image file path on disk to use for the icon or standard
 177  * icon name (NULL if not desired)
 178  * @param icon_type The icon type if relevant
 179  * @param func Convenience function to call when this item is selected
 180  * @param data Data to pass to item-related functions
 181  * @return A handle to the item added.
 182  *
 183  * This adds an item to the hoversel to show when it is clicked. Note: if you
 184  * need to use an icon from an edje file then use
 185  * elm_hoversel_item_icon_set() right after this function, and set
 186  * icon_file to NULL here.
 187  *
 188  * For more information on what @p icon_file and @p icon_type are, see the
 189  * @ref Icon "icon documentation".
 190  *
 191  * @ingroup Hoversel
 192  */
 193 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);
 194
 195 /**
 196  * @brief This sets the icon for the given hoversel item.
 197  *
 198  * @param it The item to set the icon
 199  * @param icon_file An image file path on disk to use for the icon or standard
 200  * icon name
 201  * @param icon_group The edje group to use if @p icon_file is an edje file. Set this
 202  * to NULL if the icon is not an edje file
 203  * @param icon_type The icon type
 204  *
 205  * The icon can be loaded from the standard set, from an image file, or from
 206  * an edje file.
 207  *
 208  * @see elm_hoversel_item_add()
 209  *
 210  * @ingroup Hoversel
 211  */
 212 EAPI void                         elm_hoversel_item_icon_set(Elm_Object_Item *it, const char *icon_file, const char *icon_group, Elm_Icon_Type icon_type);
 213
 214 /**
 215  * @brief Get the icon object of the hoversel item
 216  *
 217  * @param it The item to get the icon from
 218  * @param icon_file The image file path on disk used for the icon or standard
 219  * icon name
 220  * @param icon_group The edje group used if @p icon_file is an edje file. NULL
 221  * if the icon is not an edje file
 222  * @param icon_type The icon type
 223  *
 224  * @see elm_hoversel_item_icon_set()
 225  * @see elm_hoversel_item_add()
 226  *
 227  * @ingroup Hoversel
 228  */
 229 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);
 230
 231 /**
 232  * @}
 233  */