src/lib/elc_hoversel.h

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