src/lib/elc_anchorblock.h

   1 /**
   2  * @defgroup Anchorblock Anchorblock
   3  *
   4  * @image html img/widget/anchorblock/preview-00.png
   5  * @image latex img/widget/anchorblock/preview-00.eps
   6  *
   7  * Anchorblock 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 anchorblock 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 emits the following signals:
  16  * @li "anchor,clicked": will be called when an anchor is clicked. The
  17  * @p event_info parameter on the callback will be a pointer of type
  18  * ::Elm_Entry_Anchorblock_Info.
  19  *
  20  * @see Anchorview
  21  * @see Entry
  22  * @see Hover
  23  *
  24  * Default text parts of the anchorblock widget that you can use for are:
  25  * @li "default" - A label of the anchorblock
  26  *
  27  * Supported elm_object common APIs.
  28  * @li elm_object_part_text_set
  29  * @li elm_object_part_text_get
  30  *
  31  * Since examples are usually better than plain words, we might as well
  32  * try @ref tutorial_anchorblock_example "one".
  33  */
  34
  35 /**
  36  * @addtogroup Anchorblock
  37  * @{
  38  */
  39
  40 /* XXX: Remove this awful widget. */
  41
  42 /**
  43  * @typedef Elm_Entry_Anchorblock_Info
  44  *
  45  * The info sent in the callback for "anchor,clicked" signals emitted by
  46  * the Anchorblock widget.
  47  */
  48 typedef struct _Elm_Entry_Anchorblock_Info Elm_Entry_Anchorblock_Info;
  49
  50 /**
  51  * @struct _Elm_Entry_Anchorblock_Info
  52  *
  53  * The info sent in the callback for "anchor,clicked" signals emitted by
  54  * the Anchorblock widget.
  55  */
  56 struct _Elm_Entry_Anchorblock_Info
  57 {
  58    const char  *name; /**< Name of the anchor, as indicated in its href
  59                            attribute */
  60    int          button; /**< The mouse button used to click on it */
  61    Evas_Object *hover; /**< The hover object to use for the popup */
  62    struct
  63    {
  64       Evas_Coord x, y, w, h;
  65    } anchor, /**< Geometry selection of text used as anchor */
  66      hover_parent; /**< Geometry of the object used as parent by the
  67                         hover */
  68    Eina_Bool    hover_left : 1; /**< Hint indicating if there's space
  69                                      for content on the left side of
  70                                      the hover. Before calling the
  71                                      callback, the widget will make the
  72                                      necessary calculations to check
  73                                      which sides are fit to be set with
  74                                      content, based on the position the
  75                                      hover is activated and its distance
  76                                      to the edges of its parent object
  77                                  */
  78    Eina_Bool    hover_right : 1; /**< Hint indicating content fits on
  79                                       the right side of the hover.
  80                                       See @ref hover_left */
  81    Eina_Bool    hover_top : 1; /**< Hint indicating content fits on top
  82                                     of the hover. See @ref hover_left */
  83    Eina_Bool    hover_bottom : 1; /**< Hint indicating content fits
  84                                        below the hover. See @ref
  85                                        hover_left */
  86 };
  87
  88 /**
  89  * Add a new Anchorblock object
  90  *
  91  * @param parent The parent object
  92  * @return The new object or NULL if it cannot be created
  93  */
  94 EAPI Evas_Object                *elm_anchorblock_add(Evas_Object *parent);
  95
  96 /**
  97  * Set the parent of the hover popup
  98  *
  99  * Sets the parent object to use by the hover created by the anchorblock
 100  * when an anchor is clicked. See @ref Hover for more details on this.
 101  *
 102  * @param obj The anchorblock object
 103  * @param parent The object to use as parent for the hover
 104  */
 105 EAPI void                        elm_anchorblock_hover_parent_set(Evas_Object *obj, Evas_Object *parent);
 106
 107 /**
 108  * Get the parent of the hover popup
 109  *
 110  * Get the object used as parent for the hover created by the anchorblock
 111  * widget. See @ref Hover for more details on this.
 112  * If no parent is set, the same anchorblock object will be used.
 113  *
 114  * @param obj The anchorblock object
 115  * @return The object used as parent for the hover, NULL if none is set.
 116  */
 117 EAPI Evas_Object                *elm_anchorblock_hover_parent_get(const Evas_Object *obj);
 118
 119 /**
 120  * Set the style that the hover should use
 121  *
 122  * When creating the popup hover, anchorblock will request that it's
 123  * themed according to @p style.
 124  *
 125  * @param obj The anchorblock object
 126  * @param style The style to use for the underlying hover
 127  *
 128  * @see elm_object_style_set()
 129  */
 130 EAPI void                        elm_anchorblock_hover_style_set(Evas_Object *obj, const char *style);
 131
 132 /**
 133  * Get the style that the hover should use
 134  *
 135  * Get the style, the hover created by anchorblock will use.
 136  *
 137  * @param obj The anchorblock object
 138  * @return The style to use by the hover. NULL means the default is used.
 139  *
 140  * @see elm_object_style_set()
 141  */
 142 EAPI const char                 *elm_anchorblock_hover_style_get(const Evas_Object *obj);
 143
 144 /**
 145  * Ends the hover popup in the anchorblock
 146  *
 147  * When an anchor is clicked, the anchorblock widget will create a hover
 148  * object to use as a popup with user provided content. This function
 149  * terminates this popup, returning the anchorblock to its normal state.
 150  *
 151  * @param obj The anchorblock object
 152  */
 153 EAPI void                        elm_anchorblock_hover_end(Evas_Object *obj);
 154
 155 /**
 156  * Appends a custom item provider to the given anchorblock
 157  *
 158  * Appends the given function to the list of items providers. This list is
 159  * called, one function at a time, with the given @p data pointer, the
 160  * anchorblock object and, in the @p item parameter, the item name as
 161  * referenced in its href string. Following functions in the list will be
 162  * called in order until one of them returns something different to NULL,
 163  * which should be an Evas_Object which will be used in place of the item
 164  * element.
 165  *
 166  * Items in the markup text take the form \<item relsize=16x16 vsize=full
 167  * href=item/name\>\</item\>
 168  *
 169  * @param obj The anchorblock object
 170  * @param func The function to add to the list of providers
 171  * @param data User data that will be passed to the callback function
 172  *
 173  * @see elm_entry_item_provider_append()
 174  */
 175 EAPI void                        elm_anchorblock_item_provider_append(Evas_Object *obj, Evas_Object * (*func)(void *data, Evas_Object * anchorblock, const char *item), void *data);
 176
 177 /**
 178  * Prepend a custom item provider to the given anchorblock
 179  *
 180  * Like elm_anchorblock_item_provider_append(), but it adds the function
 181  * @p func to the beginning of the list, instead of the end.
 182  *
 183  * @param obj The anchorblock object
 184  * @param func The function to add to the list of providers
 185  * @param data User data that will be passed to the callback function
 186  */
 187 EAPI void                        elm_anchorblock_item_provider_prepend(Evas_Object *obj, Evas_Object * (*func)(void *data, Evas_Object * anchorblock, const char *item), void *data);
 188
 189 /**
 190  * Remove a custom item provider from the list of the given anchorblock
 191  *
 192  * Removes the function and data pairing that matches @p func and @p data.
 193  * That is, unless the same function and same user data are given, the
 194  * function will not be removed from the list. This allows us to add the
 195  * same callback several times, with different @p data pointers and be
 196  * able to remove them later without conflicts.
 197  *
 198  * @param obj The anchorblock object
 199  * @param func The function to remove from the list
 200  * @param data The data matching the function to remove from the list
 201  */
 202 EAPI void                        elm_anchorblock_item_provider_remove(Evas_Object *obj, Evas_Object * (*func)(void *data, Evas_Object * anchorblock, const char *item), void *data);
 203
 204 /**
 205  * @}
 206  */