src/lib/elc_anchorview.h

   1 /**
   2  * @defgroup Anchorview Anchorview
   3  *
   4  * @image html img/widget/anchorview/preview-00.png
   5  * @image latex img/widget/anchorview/preview-00.eps
   6  *
   7  * Anchorview is for displaying text that contains markup with anchors
   8  * like <c>\<a href=1234\>something\</\></c> in it.
   9  *
  10  * Besides being styled differently, the anchorview widget provides the
  11  * necessary functionality so that clicking on these anchors brings up a
  12  * popup with user defined content such as "call", "add to contacts" or
  13  * "open web page". This popup is provided using the @ref Hover widget.
  14  *
  15  * This widget is very similar to @ref Anchorblock, so refer to that
  16  * widget for an example. The only difference Anchorview has is that the
  17  * widget is already provided with scrolling functionality, so if the
  18  * text set to it is too large to fit in the given space, it will scroll,
  19  * whereas the @ref Anchorblock widget will keep growing to ensure all the
  20  * text can be displayed.
  21  *
  22  * This widget emits the following signals:
  23  * @li "anchor,clicked": will be called when an anchor is clicked. The
  24  * @p event_info parameter on the callback will be a pointer of type
  25  * ::Elm_Entry_Anchorview_Info.
  26  *
  27  * See @ref Anchorblock for an example on how to use both of them.
  28  *
  29  * @see Anchorblock
  30  * @see Entry
  31  * @see Hover
  32  *
  33  * @{
  34  */
  35
  36 /**
  37  * @typedef Elm_Entry_Anchorview_Info
  38  *
  39  * The info sent in the callback for "anchor,clicked" signals emitted by
  40  * the Anchorview widget.
  41  */
  42 typedef struct _Elm_Entry_Anchorview_Info Elm_Entry_Anchorview_Info;
  43
  44 /**
  45  * @struct _Elm_Entry_Anchorview_Info
  46  *
  47  * The info sent in the callback for "anchor,clicked" signals emitted by
  48  * the Anchorview widget.
  49  */
  50 struct _Elm_Entry_Anchorview_Info
  51 {
  52    const char  *name; /**< Name of the anchor, as indicated in its href
  53                            attribute */
  54    int          button; /**< The mouse button used to click on it */
  55    Evas_Object *hover; /**< The hover object to use for the popup */
  56    struct
  57    {
  58       Evas_Coord x, y, w, h;
  59    } anchor, /**< Geometry selection of text used as anchor */
  60      hover_parent; /**< Geometry of the object used as parent by the
  61                         hover */
  62    Eina_Bool    hover_left : 1; /**< Hint indicating if there's space
  63                                      for content on the left side of
  64                                      the hover. Before calling the
  65                                      callback, the widget will make the
  66                                      necessary calculations to check
  67                                      which sides are fit to be set with
  68                                      content, based on the position the
  69                                      hover is activated and its distance
  70                                      to the edges of its parent object
  71                                  */
  72    Eina_Bool    hover_right : 1; /**< Hint indicating content fits on
  73                                       the right side of the hover.
  74                                       See @ref hover_left */
  75    Eina_Bool    hover_top : 1; /**< Hint indicating content fits on top
  76                                     of the hover. See @ref hover_left */
  77    Eina_Bool    hover_bottom : 1; /**< Hint indicating content fits
  78                                        below the hover. See @ref
  79                                        hover_left */
  80 };
  81
  82 /**
  83  * Add a new Anchorview object
  84  *
  85  * @param parent The parent object
  86  * @return The new object or NULL if it cannot be created
  87  */
  88 EAPI Evas_Object *
  89                                  elm_anchorview_add(Evas_Object *parent)
  90 EINA_ARG_NONNULL(1);
  91
  92 /**
  93  * Set the text to show in the anchorview
  94  *
  95  * Sets the text of the anchorview to @p text. This text can include markup
  96  * format tags, including <c>\<a href=anchorname\></c> to begin a segment of
  97  * text that will be specially styled and react to click events, ended with
  98  * either of \</a\> or \</\>. When clicked, the anchor will emit an
  99  * "anchor,clicked" signal that you can attach a callback to with
 100  * evas_object_smart_callback_add(). The name of the anchor given in the
 101  * event info struct will be the one set in the href attribute, in this
 102  * case, anchorname.
 103  *
 104  * Other markup can be used to style the text in different ways, but it's
 105  * up to the style defined in the theme which tags do what.
 106  * @deprecated use elm_object_text_set() instead.
 107  */
 108 EINA_DEPRECATED EAPI void        elm_anchorview_text_set(Evas_Object *obj, const char *text) EINA_ARG_NONNULL(1);
 109
 110 /**
 111  * Get the markup text set for the anchorview
 112  *
 113  * Retrieves the text set on the anchorview, with markup tags included.
 114  *
 115  * @param obj The anchorview object
 116  * @return The markup text set or @c NULL if nothing was set or an error
 117  * occurred
 118  * @deprecated use elm_object_text_set() instead.
 119  */
 120 EINA_DEPRECATED EAPI const char *elm_anchorview_text_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
 121
 122 /**
 123  * Set the parent of the hover popup
 124  *
 125  * Sets the parent object to use by the hover created by the anchorview
 126  * when an anchor is clicked. See @ref Hover for more details on this.
 127  * If no parent is set, the same anchorview object will be used.
 128  *
 129  * @param obj The anchorview object
 130  * @param parent The object to use as parent for the hover
 131  */
 132 EAPI void                        elm_anchorview_hover_parent_set(Evas_Object *obj, Evas_Object *parent) EINA_ARG_NONNULL(1);
 133
 134 /**
 135  * Get the parent of the hover popup
 136  *
 137  * Get the object used as parent for the hover created by the anchorview
 138  * widget. See @ref Hover for more details on this.
 139  *
 140  * @param obj The anchorview object
 141  * @return The object used as parent for the hover, NULL if none is set.
 142  */
 143 EAPI Evas_Object                *elm_anchorview_hover_parent_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
 144
 145 /**
 146  * Set the style that the hover should use
 147  *
 148  * When creating the popup hover, anchorview will request that it's
 149  * themed according to @p style.
 150  *
 151  * @param obj The anchorview object
 152  * @param style The style to use for the underlying hover
 153  *
 154  * @see elm_object_style_set()
 155  */
 156 EAPI void                        elm_anchorview_hover_style_set(Evas_Object *obj, const char *style) EINA_ARG_NONNULL(1);
 157
 158 /**
 159  * Get the style that the hover should use
 160  *
 161  * Get the style the hover created by anchorview will use.
 162  *
 163  * @param obj The anchorview object
 164  * @return The style to use by the hover. NULL means the default is used.
 165  *
 166  * @see elm_object_style_set()
 167  */
 168 EAPI const char                 *elm_anchorview_hover_style_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
 169
 170 /**
 171  * Ends the hover popup in the anchorview
 172  *
 173  * When an anchor is clicked, the anchorview widget will create a hover
 174  * object to use as a popup with user provided content. This function
 175  * terminates this popup, returning the anchorview to its normal state.
 176  *
 177  * @param obj The anchorview object
 178  */
 179 EAPI void                        elm_anchorview_hover_end(Evas_Object *obj) EINA_ARG_NONNULL(1);
 180
 181 /**
 182  * Set bouncing behaviour when the scrolled content reaches an edge
 183  *
 184  * Tell the internal scroller object whether it should bounce or not
 185  * when it reaches the respective edges for each axis.
 186  *
 187  * @param obj The anchorview object
 188  * @param h_bounce Whether to bounce or not in the horizontal axis
 189  * @param v_bounce Whether to bounce or not in the vertical axis
 190  *
 191  * @see elm_scroller_bounce_set()
 192  */
 193 EAPI void                        elm_anchorview_bounce_set(Evas_Object *obj, Eina_Bool h_bounce, Eina_Bool v_bounce) EINA_ARG_NONNULL(1);
 194
 195 /**
 196  * Get the set bouncing behaviour of the internal scroller
 197  *
 198  * Get whether the internal scroller should bounce when the edge of each
 199  * axis is reached scrolling.
 200  *
 201  * @param obj The anchorview object
 202  * @param h_bounce Pointer where to store the bounce state of the horizontal
 203  *                 axis
 204  * @param v_bounce Pointer where to store the bounce state of the vertical
 205  *                 axis
 206  *
 207  * @see elm_scroller_bounce_get()
 208  */
 209 EAPI void                        elm_anchorview_bounce_get(const Evas_Object *obj, Eina_Bool *h_bounce, Eina_Bool *v_bounce) EINA_ARG_NONNULL(1);
 210
 211 /**
 212  * Appends a custom item provider to the given anchorview
 213  *
 214  * Appends the given function to the list of items providers. This list is
 215  * called, one function at a time, with the given @p data pointer, the
 216  * anchorview object and, in the @p item parameter, the item name as
 217  * referenced in its href string. Following functions in the list will be
 218  * called in order until one of them returns something different to NULL,
 219  * which should be an Evas_Object which will be used in place of the item
 220  * element.
 221  *
 222  * Items in the markup text take the form \<item relsize=16x16 vsize=full
 223  * href=item/name\>\</item\>
 224  *
 225  * @param obj The anchorview object
 226  * @param func The function to add to the list of providers
 227  * @param data User data that will be passed to the callback function
 228  *
 229  * @see elm_entry_item_provider_append()
 230  */
 231 EAPI void                        elm_anchorview_item_provider_append(Evas_Object *obj, Evas_Object * (*func)(void *data, Evas_Object * anchorview, const char *item), void *data) EINA_ARG_NONNULL(1, 2);
 232
 233 /**
 234  * Prepend a custom item provider to the given anchorview
 235  *
 236  * Like elm_anchorview_item_provider_append(), but it adds the function
 237  * @p func to the beginning of the list, instead of the end.
 238  *
 239  * @param obj The anchorview object
 240  * @param func The function to add to the list of providers
 241  * @param data User data that will be passed to the callback function
 242  */
 243 EAPI void                        elm_anchorview_item_provider_prepend(Evas_Object *obj, Evas_Object * (*func)(void *data, Evas_Object * anchorview, const char *item), void *data) EINA_ARG_NONNULL(1, 2);
 244
 245 /**
 246  * Remove a custom item provider from the list of the given anchorview
 247  *
 248  * Removes the function and data pairing that matches @p func and @p data.
 249  * That is, unless the same function and same user data are given, the
 250  * function will not be removed from the list. This allows us to add the
 251  * same callback several times, with different @p data pointers and be
 252  * able to remove them later without conflicts.
 253  *
 254  * @param obj The anchorview object
 255  * @param func The function to remove from the list
 256  * @param data The data matching the function to remove from the list
 257  */
 258 EAPI void                        elm_anchorview_item_provider_remove(Evas_Object *obj, Evas_Object * (*func)(void *data, Evas_Object * anchorview, const char *item), void *data) EINA_ARG_NONNULL(1, 2);
 259
 260 /**
 261  * @}
 262  */