src/lib/elc_ctxpopup.h

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