2 * @defgroup Anchorview Anchorview
4 * @image html img/widget/anchorview/preview-00.png
5 * @image latex img/widget/anchorview/preview-00.eps
7 * Anchorview is for displaying text that contains markup with anchors
8 * like <c>\<a href=1234\>something\</\></c> in it.
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.
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.
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.
27 * See @ref Anchorblock for an example on how to use both of them.
37 * @typedef Elm_Entry_Anchorview_Info
39 * The info sent in the callback for "anchor,clicked" signals emitted by
40 * the Anchorview widget.
42 typedef struct _Elm_Entry_Anchorview_Info Elm_Entry_Anchorview_Info;
44 /* XXX: Merge into entry. */
47 * @struct _Elm_Entry_Anchorview_Info
49 * The info sent in the callback for "anchor,clicked" signals emitted by
50 * the Anchorview widget.
52 struct _Elm_Entry_Anchorview_Info
54 const char *name; /**< Name of the anchor, as indicated in its href
56 int button; /**< The mouse button used to click on it */
57 Evas_Object *hover; /**< The hover object to use for the popup */
60 Evas_Coord x, y, w, h;
61 } anchor, /**< Geometry selection of text used as anchor */
62 hover_parent; /**< Geometry of the object used as parent by the
64 Eina_Bool hover_left : 1; /**< Hint indicating if there's space
65 for content on the left side of
66 the hover. Before calling the
67 callback, the widget will make the
68 necessary calculations to check
69 which sides are fit to be set with
70 content, based on the position the
71 hover is activated and its distance
72 to the edges of its parent object
74 Eina_Bool hover_right : 1; /**< Hint indicating content fits on
75 the right side of the hover.
76 See @ref hover_left */
77 Eina_Bool hover_top : 1; /**< Hint indicating content fits on top
78 of the hover. See @ref hover_left */
79 Eina_Bool hover_bottom : 1; /**< Hint indicating content fits
80 below the hover. See @ref
85 * Add a new Anchorview object to the parent.
87 * @param parent The parent object
88 * @return The new object or NULL if it cannot be created
90 EAPI Evas_Object *elm_anchorview_add(Evas_Object *parent);
93 * Set the parent of the hover popup
95 * Sets the parent object to use by the hover created by the anchorview
96 * when an anchor is clicked. See @ref Hover for more details on this.
97 * If no parent is set, the same anchorview object will be used.
99 * @param obj The anchorview object
100 * @param parent The object to use as parent for the hover
102 EAPI void elm_anchorview_hover_parent_set(Evas_Object *obj, Evas_Object *parent);
105 * Get the parent of the hover popup
107 * Get the object used as parent for the hover created by the anchorview
108 * widget. See @ref Hover for more details on this.
110 * @param obj The anchorview object
111 * @return The object used as parent for the hover, NULL if none is set.
113 EAPI Evas_Object *elm_anchorview_hover_parent_get(const Evas_Object *obj);
116 * Set the style that the hover should use
118 * When creating the popup hover, anchorview will request that it is
119 * themed according to @p style.
121 * @param obj The anchorview object
122 * @param style The style to use for the underlying hover
124 * @see elm_object_style_set()
126 EAPI void elm_anchorview_hover_style_set(Evas_Object *obj, const char *style);
129 * Get the style that the hover uses.
131 * Get the style the hover created by anchorview will use.
133 * @param obj The anchorview object
134 * @return The style to use by the hover. NULL means the default is used.
136 * @see elm_object_style_set()
138 EAPI const char *elm_anchorview_hover_style_get(const Evas_Object *obj);
141 * Ends the hover popup in the anchorview
143 * When an anchor is clicked, the anchorview widget will create a hover
144 * object to use as a popup with user provided content. This function
145 * terminates this popup, returning the anchorview to its normal state.
147 * @param obj The anchorview object
149 EAPI void elm_anchorview_hover_end(Evas_Object *obj);
152 * Set bouncing behaviour when the scrolled content reaches an edge
154 * Tell the internal scroller object whether it should bounce or not
155 * when it reaches the respective edges for each axis.
157 * @param obj The anchorview object
158 * @param h_bounce Whether to bounce or not in the horizontal axis
159 * @param v_bounce Whether to bounce or not in the vertical axis
161 * @see elm_scroller_bounce_set()
163 EAPI void elm_anchorview_bounce_set(Evas_Object *obj, Eina_Bool h_bounce, Eina_Bool v_bounce);
166 * Get the bouncing behaviour of the internal scroller
168 * Get whether the internal scroller will bounce when the edge of each
169 * axis is reached scrolling.
171 * @param obj The anchorview object
172 * @param h_bounce Pointer to store the bounce state of the horizontal
174 * @param v_bounce Pointer to store the bounce state of the vertical
177 * @see elm_scroller_bounce_get()
179 EAPI void elm_anchorview_bounce_get(const Evas_Object *obj, Eina_Bool *h_bounce, Eina_Bool *v_bounce);
182 * Appends a custom item provider to the given anchorview
184 * Appends the given function to the list of items providers. This list is
185 * called, one function at a time, with the given @p data pointer, the
186 * anchorview object and, in the @p item parameter, the item name as
187 * referenced in its href string. Following functions in the list will be
188 * called in order until one of them returns something different to NULL,
189 * which should be an Evas_Object which will be used in place of the item
192 * Items in the markup text take the form \<item relsize=16x16 vsize=full
193 * href=item/name\>\</item\>
195 * @param obj The anchorview object
196 * @param func The function to add to the list of providers
197 * @param data User data that will be passed to the callback function
199 * @see elm_entry_item_provider_append()
201 EAPI void elm_anchorview_item_provider_append(Evas_Object *obj, Evas_Object * (*func)(void *data, Evas_Object * anchorview, const char *item), void *data);
204 * Prepend a custom item provider to the given anchorview
206 * Like elm_anchorview_item_provider_append(), but it adds the function
207 * @p func to the beginning of the list, instead of the end.
209 * @param obj The anchorview object
210 * @param func The function to add to the list of providers
211 * @param data User data that will be passed to the callback function
213 EAPI void elm_anchorview_item_provider_prepend(Evas_Object *obj, Evas_Object * (*func)(void *data, Evas_Object * anchorview, const char *item), void *data);
216 * Remove a custom item provider from the list of the given anchorview
218 * Removes the function and data pairing that matches @p func and @p data.
219 * That is, unless the same function and same user data are given, the
220 * function will not be removed from the list. This allows us to add the
221 * same callback several times, with different @p data pointers and be
222 * able to remove them later without conflicts.
224 * @param obj The anchorview object
225 * @param func The function to remove from the list
226 * @param data The data matching the function to remove from the list
228 EAPI void elm_anchorview_item_provider_remove(Evas_Object *obj, Evas_Object * (*func)(void *data, Evas_Object * anchorview, const char *item), void *data);