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