src/lib/elc_ctxpopup.h

   1 /**
   2  * @defgroup Ctxpopup Ctxpopup
   3  * @ingroup Elementary
   4  *
   5  * @image html ctxpopup_inheritance_tree.png
   6  * @image latex ctxpopup_inheritance_tree.eps
   7  *
   8  * @image html img/widget/ctxpopup/preview-00.png
   9  * @image latex img/widget/ctxpopup/preview-00.eps
  10  *
  11  * @brief Context popup widget.
  12  *
  13  * A ctxpopup is a widget that, when shown, pops up a list of items.
  14  * It automatically chooses an area inside its parent object's view
  15  * (set via elm_ctxpopup_add() and elm_ctxpopup_hover_parent_set()) to
  16  * optimally fit into it. In the default theme, it will also point an
  17  * arrow to it's top left position at the time one shows it. Ctxpopup
  18  * items have a label and/or an icon. It is intended for a small
  19  * number of items (hence the use of list, not genlist).
  20  *
  21  * This widget inherits from the @ref Layout one, so that all the
  22  * functions acting on it also work for context popup objects
  23  * (@since 1.8).
  24  *
  25  * This widget emits the following signals, besides the ones sent from
  26  * @ref Layout:
  27  * - @c "dismissed" - this is called when the outside of ctxpopup was clicked or
  28  * it's parent area is changed or the language is changed. and then ctxpopup is
  29  * dismissed.
  30  *
  31  * Default content parts of the ctxpopup widget that you can use for are:
  32  * @li "default" - A content of the ctxpopup
  33  *
  34  * Default content parts of the ctxpopup items that you can use for are:
  35  * @li "icon" - An icon in the title area
  36  *
  37  * Default text parts of the ctxpopup items that you can use for are:
  38  * @li "default" - Title label in the title area
  39  *
  40  * Supported elm_object common APIs.
  41  * @li @ref elm_object_disabled_set
  42  * @li @ref elm_object_disabled_get
  43  *
  44  * Supported elm_object_item common APIs.
  45  * @li @ref elm_object_item_disabled_set
  46  * @li @ref elm_object_item_disabled_get
  47  * @li @ref elm_object_item_part_text_set
  48  * @li @ref elm_object_item_part_text_get
  49  * @li @ref elm_object_item_part_content_set
  50  * @li @ref elm_object_item_part_content_get
  51  * @li @ref elm_object_item_signal_emit
  52  *
  53  * @ref tutorial_ctxpopup shows the usage of a good deal of the API.
  54  * @{
  55  */
  56
  57 typedef enum
  58 {
  59    ELM_CTXPOPUP_DIRECTION_DOWN, /**< ctxpopup show appear below clicked area */
  60    ELM_CTXPOPUP_DIRECTION_RIGHT, /**< ctxpopup show appear to the right of the clicked area */
  61    ELM_CTXPOPUP_DIRECTION_LEFT, /**< ctxpopup show appear to the left of the clicked area */
  62    ELM_CTXPOPUP_DIRECTION_UP, /**< ctxpopup show appear above the clicked area */
  63    ELM_CTXPOPUP_DIRECTION_UNKNOWN, /**< ctxpopup does not determine it's direction yet*/
  64 } Elm_Ctxpopup_Direction; /**< Direction in which to show the popup */
  65
  66 /**
  67  * @brief Add a new Ctxpopup object to the parent.
  68  *
  69  * @param parent Parent object
  70  * @return New object or @c NULL, if it cannot be created
  71  *
  72  * @ingroup Ctxpopup
  73  */
  74 EAPI Evas_Object                 *elm_ctxpopup_add(Evas_Object *parent);
  75
  76 /**
  77  * @brief Set the Ctxpopup's parent
  78  *
  79  * @param obj The ctxpopup object
  80  * @param parent The parent to use
  81  *
  82  * Set the parent object.
  83  *
  84  * @note elm_ctxpopup_add() will automatically call this function
  85  * with its @c parent argument.
  86  *
  87  * @see elm_ctxpopup_add()
  88  * @see elm_hover_parent_set()
  89  *
  90  * @ingroup Ctxpopup
  91  */
  92 EAPI void                         elm_ctxpopup_hover_parent_set(Evas_Object *obj, Evas_Object *parent);
  93
  94 /**
  95  * @brief Get the Ctxpopup's parent
  96  *
  97  * @param obj The ctxpopup object
  98  *
  99  * @see elm_ctxpopup_hover_parent_set() for more information
 100  *
 101  * @ingroup Ctxpopup
 102  */
 103 EAPI Evas_Object                 *elm_ctxpopup_hover_parent_get(const Evas_Object *obj);
 104
 105 /**
 106  * @brief Clear all items in the given ctxpopup object.
 107  *
 108  * @param obj Ctxpopup object
 109  *
 110  * @ingroup Ctxpopup
 111  */
 112 EAPI void                         elm_ctxpopup_clear(Evas_Object *obj);
 113
 114 /**
 115  * @brief Change the ctxpopup's orientation to horizontal or vertical.
 116  *
 117  * @param obj Ctxpopup object
 118  * @param horizontal @c EINA_TRUE for horizontal mode, @c EINA_FALSE for vertical
 119  *
 120  * @ingroup Ctxpopup
 121  */
 122 EAPI void                         elm_ctxpopup_horizontal_set(Evas_Object *obj, Eina_Bool horizontal);
 123
 124 /**
 125  * @brief Get the value of current ctxpopup object's orientation.
 126  *
 127  * @param obj Ctxpopup object
 128  * @return @c EINA_TRUE for horizontal mode, @c EINA_FALSE for vertical mode (or errors)
 129  *
 130  * @see elm_ctxpopup_horizontal_set()
 131  *
 132  * @ingroup Ctxpopup
 133  */
 134 EAPI Eina_Bool                    elm_ctxpopup_horizontal_get(const Evas_Object *obj);
 135
 136 /**
 137  * @brief Add a new item to a ctxpopup object.
 138  *
 139  * @param obj Ctxpopup object
 140  * @param icon Icon to be set on new item
 141  * @param label The Label of the new item
 142  * @param func Convenience function called when item selected
 143  * @param data Data passed to @p func
 144  * @return A handle to the item added or @c NULL, on errors
 145  *
 146  * @warning Ctxpopup can't hold both an item list and a content at the same
 147  * time. When an item is added, any previous content will be removed.
 148  *
 149  * @see elm_object_content_set()
 150  *
 151  * @ingroup Ctxpopup
 152  */
 153 EAPI Elm_Object_Item             *elm_ctxpopup_item_append(Evas_Object *obj, const char *label, Evas_Object *icon, Evas_Smart_Cb func, const void *data);
 154
 155 /**
 156  * @brief Set the direction priority of a ctxpopup.
 157  *
 158  * @param obj Ctxpopup object
 159  * @param first 1st priority of direction
 160  * @param second 2nd priority of direction
 161  * @param third 3th priority of direction
 162  * @param fourth 4th priority of direction
 163  *
 164  * This functions gives a chance to user to set the priority of ctxpopup
 165  * showing direction. This doesn't guarantee the ctxpopup will appear in the
 166  * requested direction.
 167  *
 168  * @see Elm_Ctxpopup_Direction
 169  *
 170  * @ingroup Ctxpopup
 171  */
 172 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);
 173
 174 /**
 175  * @brief Get the direction priority of a ctxpopup.
 176  *
 177  * @param obj Ctxpopup object
 178  * @param first 1st priority of direction to be returned
 179  * @param second 2nd priority of direction to be returned
 180  * @param third 3th priority of direction to be returned
 181  * @param fourth 4th priority of direction to be returned
 182  *
 183  * @see elm_ctxpopup_direction_priority_set() for more information.
 184  *
 185  * @ingroup Ctxpopup
 186  */
 187 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);
 188
 189 /**
 190  * @brief Get the current direction of a ctxpopup.
 191  *
 192  * @param obj Ctxpopup object
 193  * @return current direction of a ctxpopup
 194  *
 195  * @warning Once the ctxpopup showed up, the direction would be determined
 196  *
 197  * @ingroup Ctxpopup
 198  */
 199 EAPI Elm_Ctxpopup_Direction       elm_ctxpopup_direction_get(const Evas_Object *obj);
 200
 201 /**
 202  * @brief Dismiss a ctxpopup object
 203  *
 204  * @param obj The ctxpopup object
 205  * Use this function to simulate clicking outside the ctxpopup to dismiss it.
 206  * In this way, the ctxpopup will be hidden and the "clicked" signal will be
 207  * emitted.
 208  */
 209 EAPI void                         elm_ctxpopup_dismiss(Evas_Object *obj);
 210
 211 /**
 212  * @}
 213  */