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