src/lib/elm_bubble.h

   1 /**
   2  * @defgroup Bubble Bubble
   3  *
   4  * @image html img/widget/bubble/preview-00.png
   5  * @image latex img/widget/bubble/preview-00.eps
   6  * @image html img/widget/bubble/preview-01.png
   7  * @image latex img/widget/bubble/preview-01.eps
   8  * @image html img/widget/bubble/preview-02.png
   9  * @image latex img/widget/bubble/preview-02.eps
  10  *
  11  * @brief The Bubble is a widget to show text similar to how speech is
  12  * represented in comics.
  13  *
  14  * The bubble widget contains 5 important visual elements:
  15  * @li The frame is a rectangle with rounded edjes and an "arrow".
  16  * @li The @p icon is an image to which the frame's arrow points to.
  17  * @li The @p label is a text which appears to the right of the icon if the
  18  * corner is "top_left" or "bottom_left" and is right aligned to the frame
  19  * otherwise.
  20  * @li The @p info is a text which appears to the right of the label. Info's
  21  * font is of a ligther color than label.
  22  * @li The @p content is an evas object that is shown inside the frame.
  23  *
  24  * The position of the arrow, icon, label and info depends on which corner is
  25  * selected. The four available corners are:
  26  * @li "top_left" - Default
  27  * @li "top_right"
  28  * @li "bottom_left"
  29  * @li "bottom_right"
  30  *
  31  * Signals that you can add callbacks for are:
  32  * @li "clicked" - This is called when a user has clicked the bubble.
  33  *
  34  * Default contents parts of the bubble that you can use for are:
  35  * @li "default" - A content of the bubble
  36  * @li "icon" - An icon of the bubble
  37  *
  38  * Default text parts of the button widget that you can use for are:
  39  * @li NULL - Label of the bubble
  40  *
  41  * For an example of using a buble see @ref bubble_01_example_page "this".
  42  *
  43  * @{
  44  */
  45
  46 /**
  47  * Add a new bubble to the parent
  48  *
  49  * @param parent The parent object
  50  * @return The new object or NULL if it cannot be created
  51  *
  52  * This function adds a text bubble to the given parent evas object.
  53  */
  54 EAPI Evas_Object *
  55                                   elm_bubble_add(Evas_Object *parent)
  56 EINA_ARG_NONNULL(1);
  57
  58 /**
  59  * Set the label of the bubble
  60  *
  61  * @param obj The bubble object
  62  * @param label The string to set in the label
  63  *
  64  * This function sets the title of the bubble. Where this appears depends on
  65  * the selected corner.
  66  * @deprecated use elm_object_text_set() instead.
  67  */
  68 EINA_DEPRECATED EAPI void         elm_bubble_label_set(Evas_Object *obj, const char *label) EINA_ARG_NONNULL(1);
  69
  70 /**
  71  * Get the label of the bubble
  72  *
  73  * @param obj The bubble object
  74  * @return The string of set in the label
  75  *
  76  * This function gets the title of the bubble.
  77  * @deprecated use elm_object_text_get() instead.
  78  */
  79 EINA_DEPRECATED EAPI const char  *elm_bubble_label_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
  80
  81 /**
  82  * Set the info of the bubble
  83  *
  84  * @param obj The bubble object
  85  * @param info The given info about the bubble
  86  *
  87  * This function sets the info of the bubble. Where this appears depends on
  88  * the selected corner.
  89  * @deprecated use elm_object_part_text_set() instead. (with "info" as the parameter).
  90  */
  91 EINA_DEPRECATED EAPI void         elm_bubble_info_set(Evas_Object *obj, const char *info) EINA_ARG_NONNULL(1);
  92
  93 /**
  94  * Get the info of the bubble
  95  *
  96  * @param obj The bubble object
  97  *
  98  * @return The "info" string of the bubble
  99  *
 100  * This function gets the info text.
 101  * @deprecated use elm_object_part_text_get() instead. (with "info" as the parameter).
 102  */
 103 EINA_DEPRECATED EAPI const char  *elm_bubble_info_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
 104
 105 /**
 106  * Set the content to be shown in the bubble
 107  *
 108  * Once the content object is set, a previously set one will be deleted.
 109  * If you want to keep the old content object, use the
 110  * elm_bubble_content_unset() function.
 111  *
 112  * @param obj The bubble object
 113  * @param content The given content of the bubble
 114  *
 115  * This function sets the content shown on the middle of the bubble.
 116  *
 117  * @deprecated use elm_object_content_set() instead
 118  *
 119  */
 120 EINA_DEPRECATED EAPI void         elm_bubble_content_set(Evas_Object *obj, Evas_Object *content) EINA_ARG_NONNULL(1);
 121
 122 /**
 123  * Get the content shown in the bubble
 124  *
 125  * Return the content object which is set for this widget.
 126  *
 127  * @param obj The bubble object
 128  * @return The content that is being used
 129  *
 130  * @deprecated use elm_object_content_get() instead
 131  *
 132  */
 133 EINA_DEPRECATED EAPI Evas_Object *elm_bubble_content_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
 134
 135 /**
 136  * Unset the content shown in the bubble
 137  *
 138  * Unparent and return the content object which was set for this widget.
 139  *
 140  * @param obj The bubble object
 141  * @return The content that was being used
 142  *
 143  * @deprecated use elm_object_content_unset() instead
 144  *
 145  */
 146 EINA_DEPRECATED EAPI Evas_Object *elm_bubble_content_unset(Evas_Object *obj) EINA_ARG_NONNULL(1);
 147
 148 /**
 149  * Set the icon of the bubble
 150  *
 151  * Once the icon object is set, a previously set one will be deleted.
 152  * If you want to keep the old content object, use the
 153  * elm_icon_content_unset() function.
 154  *
 155  * @param obj The bubble object
 156  * @param icon The given icon for the bubble
 157  *
 158  * @deprecated use elm_object_part_content_set() instead
 159  *
 160  */
 161 EINA_DEPRECATED EAPI void         elm_bubble_icon_set(Evas_Object *obj, Evas_Object *icon) EINA_ARG_NONNULL(1);
 162
 163 /**
 164  * Get the icon of the bubble
 165  *
 166  * @param obj The bubble object
 167  * @return The icon for the bubble
 168  *
 169  * This function gets the icon shown on the top left of bubble.
 170  *
 171  * @deprecated use elm_object_part_content_get() instead
 172  *
 173  */
 174 EINA_DEPRECATED EAPI Evas_Object *elm_bubble_icon_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
 175
 176 /**
 177  * Unset the icon of the bubble
 178  *
 179  * Unparent and return the icon object which was set for this widget.
 180  *
 181  * @param obj The bubble object
 182  * @return The icon that was being used
 183  *
 184  * @deprecated use elm_object_part_content_unset() instead
 185  *
 186  */
 187 EINA_DEPRECATED EAPI Evas_Object *elm_bubble_icon_unset(Evas_Object *obj) EINA_ARG_NONNULL(1);
 188
 189 /**
 190  * Set the corner of the bubble
 191  *
 192  * @param obj The bubble object.
 193  * @param corner The given corner for the bubble.
 194  *
 195  * This function sets the corner of the bubble. The corner will be used to
 196  * determine where the arrow in the frame points to and where label, icon and
 197  * info are shown.
 198  *
 199  * Possible values for corner are:
 200  * @li "top_left" - Default
 201  * @li "top_right"
 202  * @li "bottom_left"
 203  * @li "bottom_right"
 204  */
 205 EAPI void                         elm_bubble_corner_set(Evas_Object *obj, const char *corner) EINA_ARG_NONNULL(1, 2);
 206
 207 /**
 208  * Get the corner of the bubble
 209  *
 210  * @param obj The bubble object.
 211  * @return The given corner for the bubble.
 212  *
 213  * This function gets the selected corner of the bubble.
 214  */
 215 EAPI const char                  *elm_bubble_corner_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
 216
 217 /**
 218  * @}
 219  */