From 86da228bb20ee8d9dc88663818a2905c383e0a8f Mon Sep 17 00:00:00 2001 From: gastal Date: Wed, 29 Jun 2011 20:47:41 +0000 Subject: [PATCH] Elementary: elm_bubble documentation. git-svn-id: https://svn.enlightenment.org/svn/e/trunk/elementary@60842 7cbeb6ba-43b4-40fd-8cce-4c39aea84d33 --- doc/examples.dox | 49 ++++++++++++ src/examples/Makefile.am | 2 + src/examples/bubble_example_01.c | 72 +++++++++++++++++ src/lib/Elementary.h.in | 158 +++++++++++++++++++++++++++++++++++++- src/lib/elm_bubble.c | 162 --------------------------------------- 5 files changed, 277 insertions(+), 166 deletions(-) create mode 100644 src/examples/bubble_example_01.c diff --git a/doc/examples.dox b/doc/examples.dox index 9368b83..6d8a449 100644 --- a/doc/examples.dox +++ b/doc/examples.dox @@ -877,6 +877,55 @@ */ /** + * @page bubble_01_example_page elm_bubble - Simple use. + * @dontinclude bubble_example_01.c + * + * This example shows a bubble with all fields set(label, info, content and + * icon) and the selected corner changing when the bubble is clicked. To be + * able use a bubble we need to do some setup and create a window, for this + * example we are going to ignore that part of the code since it isn't + * relevant to the bubble. + * + * To have the selected corner change in a clockwise motion we are going to + * use the following callback: + * @skip static + * @until } + * @until } + * + * Here we are creating an elm_label that is going to be used as the content + * for our bubble: + * @skipline elm_label + * @until show + * @note You could use any evas_object for this, we are using an elm_label + * for simplicity. + * + * Despite it's name the bubble's icon doesn't have to be an icon, it can be + * any evas_object. For this example we are going to make the icon a simple + * blue rectangle: + * @until show + * + * And finally we have the actual bubble creation and the setting of it's + * label, info and content: + * @until content + * @skipline show + * @note Because we didn't set a corner, the default("top_left") will be + * used. + * + * Now that we have our bubble all that is left is connecting the "clicked" + * signals to our callback: + * @line smart_callback + * + * This last bubble we created was very complete, so it's pertinent to show + * that most of that stuff is optional a bubble can be created with nothing + * but content: + * @until content + * @skipline show + * + * See the full source code @ref bubble_example_01.c here. + * @example bubble_example_01.c + */ + +/** * @page bg_example_01_c bg_example_01.c * @include bg_example_01.c * @example bg_example_01.c diff --git a/src/examples/Makefile.am b/src/examples/Makefile.am index 3833b71..4820e75 100644 --- a/src/examples/Makefile.am +++ b/src/examples/Makefile.am @@ -30,6 +30,7 @@ SRCS = \ actionslider_example_01.c \ anchorblock_example_01.c \ animator_example_01.c \ + bubble_example_01.c \ button_example_01.c \ transit_example_01.c \ transit_example_02.c \ @@ -63,6 +64,7 @@ pkglib_PROGRAMS += \ actionslider_example_01 \ anchorblock_example_01 \ animator_example_01 \ + bubble_example_01 \ button_example_01 \ transit_example_01 \ transit_example_02 \ diff --git a/src/examples/bubble_example_01.c b/src/examples/bubble_example_01.c new file mode 100644 index 0000000..0bd559d --- /dev/null +++ b/src/examples/bubble_example_01.c @@ -0,0 +1,72 @@ +//Compile with: +//gcc -g `pkg-config --cflags --libs elementary` -DPACKAGE_DATA_DIR="\"\"" bubble_example_01.c -o bubble_example_01 + +#include +#ifdef HAVE_CONFIG_H +# include "elementary_config.h" +#endif + +static const char *corners[] = {"top_left", "top_right", + "bottom_right", "bottom_left"}; + +void +_bla(void *data, Evas_Object *obj, void *event_info) +{ + static unsigned char corner = 0; + elm_bubble_corner_set(obj, corners[++corner > 3 ? corner = 0 : corner]); +} + +EAPI int +elm_main(int argc, char **argv) +{ + Evas_Object *win, *bg, *bubble, *label, *icon; + Elm_Animator *animator; + char buf[256]; + + win = elm_win_add(NULL, "bubble", ELM_WIN_BASIC); + elm_win_title_set(win, "Bubble"); + elm_win_autodel_set(win, EINA_TRUE); + elm_policy_set(ELM_POLICY_QUIT, ELM_POLICY_QUIT_LAST_WINDOW_CLOSED); + + bg = elm_bg_add(win); + elm_win_resize_object_add(win, bg); + evas_object_show(bg); + + label = elm_label_add(win); + elm_object_text_set(label, "This is the CONTENT of our bubble"); + evas_object_show(label); + + icon = evas_object_rectangle_add(evas_object_evas_get(win)); + evas_object_color_set(icon, 0, 0, 255, 255); + evas_object_show(icon); + + bubble = elm_bubble_add(win); + elm_bubble_icon_set(bubble, icon); + elm_bubble_info_set(bubble, "INFO"); + elm_bubble_label_set(bubble, "LABEL"); + elm_bubble_content_set(bubble, label); + evas_object_resize(bubble, 300, 100); + evas_object_show(bubble); + + evas_object_smart_callback_add(bubble, "clicked", _bla, NULL); + + label = elm_label_add(win); + elm_object_text_set(label, "Bubble with no icon, info or label"); + evas_object_show(label); + + bubble = elm_bubble_add(win); + elm_bubble_content_set(bubble, label); + evas_object_resize(bubble, 200, 50); + evas_object_move(bubble, 0, 110); + evas_object_show(bubble); + + evas_object_resize(win, 300, 200); + evas_object_show(win); + + elm_run(); + + evas_object_del(icon); + + return 0; +} +ELM_MAIN() diff --git a/src/lib/Elementary.h.in b/src/lib/Elementary.h.in index aeec6f7..06c432d 100644 --- a/src/lib/Elementary.h.in +++ b/src/lib/Elementary.h.in @@ -3657,23 +3657,173 @@ extern "C" { * @} */ - /* bubble */ + /** + * @defgroup Bubble Bubble + * + * @brief The Bubble is a widget to show text similarly to how speech is + * represented in comics. + * + * The bubble widget contains 5 important visual elements: + * @li The frame is a rectangle with rounded rectangles and an "arrow". + * @li The @p icon is an image to which the frame's arrow points to. + * @li The @p label is a text which appears to the right of the icon if the + * corner is "top_left" or "bottom_left" and is right aligned to the frame + * otherwise. + * @li The @p info is a text which appears to the right of the label. Info's + * font is of a ligther color than label. + * @li The @p content is an evas object that is shown inside the frame. + * + * The position of the arrow, icon, label and info depends on which corner is + * selected. The four available corners are: + * @li "top_left" - Default + * @li "top_right" + * @li "bottom_left" + * @li "bottom_right" + * + * Signals that you can add callbacks for are: + * @li "clicked" - This is called when a user has clicked the bubble. + * + * For an example of using a buble see @ref bubble_01_example_page "this + * example". + * + * @{ + */ + /** + * Add a new bubble to the parent + * + * @param parent The parent object + * @return The new object or NULL if it cannot be created + * + * This function adds a text bubble to the given parent evas object. + */ EAPI Evas_Object *elm_bubble_add(Evas_Object *parent) EINA_ARG_NONNULL(1); + /** + * Set the label of the bubble + * + * @param obj The bubble object + * @param label The string to set in the label + * + * This function sets the title of the bubble. Where this appears depends on + * the selected corner. + */ EAPI void elm_bubble_label_set(Evas_Object *obj, const char *label) EINA_ARG_NONNULL(1); + /** + * Get the label of the bubble + * + * @param obj The bubble object + * @return The string of set in the label + * + * This function gets the title of the bubble. + */ EAPI const char *elm_bubble_label_get(const Evas_Object *obj) EINA_ARG_NONNULL(1); + /** + * Set the info of the bubble + * + * @param obj The bubble object + * @param info The given info about the bubble + * + * This function sets the info of the bubble. Where this appears depends on + * the selected corner. + */ EAPI void elm_bubble_info_set(Evas_Object *obj, const char *info) EINA_ARG_NONNULL(1); + /** + * Get the info of the bubble + * + * @param obj The bubble object + * + * @return The "info" string of the bubble + * + * This function gets the info text. + */ EAPI const char *elm_bubble_info_get(const Evas_Object *obj) EINA_ARG_NONNULL(1); - + /** + * Set the content to be shown in the bubble + * + * Once the content object is set, a previously set one will be deleted. + * If you want to keep the old content object, use the + * elm_bubble_content_unset() function. + * + * @param obj The bubble object + * @param content The given content of the bubble + * + * This function sets the content shown on the middle of the bubble. + */ EAPI void elm_bubble_content_set(Evas_Object *obj, Evas_Object *content) EINA_ARG_NONNULL(1); + /** + * Get the content shown in the bubble + * + * Return the content object which is set for this widget. + * + * @param obj The bubble object + * @return The content that is being used + */ EAPI Evas_Object *elm_bubble_content_get(const Evas_Object *obj) EINA_ARG_NONNULL(1); + /** + * Unset the content shown in the bubble + * + * Unparent and return the content object which was set for this widget. + * + * @param obj The bubble object + * @return The content that was being used + */ EAPI Evas_Object *elm_bubble_content_unset(Evas_Object *obj) EINA_ARG_NONNULL(1); + /** + * Set the icon of the bubble + * + * Once the icon object is set, a previously set one will be deleted. + * If you want to keep the old content object, use the + * elm_icon_content_unset() function. + * + * @param obj The bubble object + * @param icon The given icon for the bubble + */ EAPI void elm_bubble_icon_set(Evas_Object *obj, Evas_Object *icon) EINA_ARG_NONNULL(1); + /** + * Get the icon of the bubble + * + * @param obj The bubble object + * @return The icon for the bubble + * + * This function gets the icon shown on the top left of bubble. + */ EAPI Evas_Object *elm_bubble_icon_get(const Evas_Object *obj) EINA_ARG_NONNULL(1); + /** + * Unset the icon of the bubble + * + * Unparent and return the icon object which was set for this widget. + * + * @param obj The bubble object + * @return The icon that was being used + */ EAPI Evas_Object *elm_bubble_icon_unset(Evas_Object *obj) EINA_ARG_NONNULL(1); + /** + * Set the corner of the bubble + * + * @param obj The bubble object. + * @param corner The given corner for the bubble. + * + * This function sets the corner of the bubble. The corner will be used to + * determine where the arrow in the frame points to and where label, icon and + * info arre shown. + * + * Possible values for corner are: + * @li "top_left" - Default + * @li "top_right" + * @li "bottom_left" + * @li "bottom_right" + */ EAPI void elm_bubble_corner_set(Evas_Object *obj, const char *corner) EINA_ARG_NONNULL(1, 2); + /** + * Get the corner of the bubble + * + * @param obj The bubble object. + * @return The given corner for the bubble. + * + * This function gets the selected corner of the bubble. + */ EAPI const char *elm_bubble_corner_get(const Evas_Object *obj) EINA_ARG_NONNULL(1); - /* smart callbacks called: - * "clicked" - the user clicked the bubble + /** + * @} */ /* photo */ diff --git a/src/lib/elm_bubble.c b/src/lib/elm_bubble.c index 2ee7a2e..cbc2b45 100644 --- a/src/lib/elm_bubble.c +++ b/src/lib/elm_bubble.c @@ -1,17 +1,6 @@ #include #include "elm_priv.h" -/** - * @defgroup Bubble Bubble - * - * The Bubble is an widget used to show a text in a frame as speech is - * represented in comics. - * - * Signals that you can add callbacks for are: - * - * "clicked" - This is called when a user has clicked the bubble. - */ - typedef struct _Widget_Data Widget_Data; struct _Widget_Data @@ -147,16 +136,6 @@ _mouse_up(void *data, Evas *e __UNUSED__, Evas_Object *obj __UNUSED__, void *eve evas_object_smart_callback_call(data, SIG_CLICKED, NULL); } -/** - * Add a new bubble to the parent - * - * @param parent The parent object - * @return The new object or NULL if it cannot be created - * - * This function adds a text bubble to the given parent evas object. - * - * @ingroup Bubble - */ EAPI Evas_Object * elm_bubble_add(Evas_Object *parent) { @@ -192,17 +171,6 @@ elm_bubble_add(Evas_Object *parent) return obj; } -/** - * Set the label of the bubble - * - * @param obj The bubble object - * @param label The string to set in the label - * - * This function sets the title of the bubble that is shown on top of - * the bubble. - * - * @ingroup Bubble - */ EAPI void elm_bubble_label_set(Evas_Object *obj, const char *label) { @@ -216,17 +184,6 @@ elm_bubble_label_set(Evas_Object *obj, const char *label) _sizing_eval(obj); } -/** - * Get the label of the bubble - * - * @param obj The bubble object - * @return The string of set in the label - * - * This function gets the title of the bubble that is shown on top of - * the bubble. - * - * @ingroup Bubble - */ EAPI const char* elm_bubble_label_get(const Evas_Object *obj) { @@ -236,19 +193,6 @@ elm_bubble_label_get(const Evas_Object *obj) return wd->label; } -/** - * Set the info of the bubble - * - * @param obj The bubble object - * @param info The given info about the bubble - * - * This function sets the text shown on the top right of bubble. - * In the Anchorblock example of the Elementary tests application it - * shows time. - * - * @ingroup Bubble - * - */ EAPI void elm_bubble_info_set(Evas_Object *obj, const char *info) { @@ -262,19 +206,6 @@ elm_bubble_info_set(Evas_Object *obj, const char *info) _sizing_eval(obj); } -/** - * Get the info of the bubble - * - * @param obj The bubble object - * - * @return The "info" string of the bubble - * - * This function gets the text set to be displayed at the top right of - * the bubble. - * - * @ingroup Bubble - * - */ EAPI const char * elm_bubble_info_get(const Evas_Object *obj) { @@ -284,22 +215,6 @@ elm_bubble_info_get(const Evas_Object *obj) return wd->info; } -/** - * Set the content to be shown in the bubble - * - * Once the content object is set, a previously set one will be deleted. - * If you want to keep the old content object, use the - * elm_bubble_content_unset() function. - * - * @param obj The bubble object - * @param content The given content of the bubble - * - * This function sets the content shown on the middle of the bubble. - * In the Anchorblock example of the Elementary tests application it - * shows time. - * - * @ingroup Bubble - */ EAPI void elm_bubble_content_set(Evas_Object *obj, Evas_Object *content) { @@ -319,16 +234,6 @@ elm_bubble_content_set(Evas_Object *obj, Evas_Object *content) _sizing_eval(obj); } -/** - * Get the content shown in the bubble - * - * Return the content object which is set for this widget. - * - * @param obj The bubble object - * @return The content that is being used - * - * @ingroup Bubble - */ EAPI Evas_Object * elm_bubble_content_get(const Evas_Object *obj) { @@ -338,16 +243,6 @@ elm_bubble_content_get(const Evas_Object *obj) return wd->content; } -/** - * Unset the content shown in the bubble - * - * Unparent and return the content object which was set for this widget. - * - * @param obj The bubble object - * @return The content that was being used - * - * @ingroup Bubble - */ EAPI Evas_Object * elm_bubble_content_unset(Evas_Object *obj) { @@ -363,18 +258,6 @@ elm_bubble_content_unset(Evas_Object *obj) return content; } -/** - * Set the icon of the bubble - * - * Once the icon object is set, a previously set one will be deleted. - * If you want to keep the old content object, use the - * elm_icon_content_unset() function. - * - * @param obj The bubble object - * @param icon The given icon for the bubble - * - * @ingroup Bubble - */ EAPI void elm_bubble_icon_set(Evas_Object *obj, Evas_Object *icon) { @@ -396,16 +279,6 @@ elm_bubble_icon_set(Evas_Object *obj, Evas_Object *icon) _sizing_eval(obj); } -/** - * Get the icon of the bubble - * - * @param obj The bubble object - * @return The icon for the bubble - * - * This function gets the icon shown on the top left of bubble. - * - * @ingroup Bubble - */ EAPI Evas_Object * elm_bubble_icon_get(const Evas_Object *obj) { @@ -415,16 +288,6 @@ elm_bubble_icon_get(const Evas_Object *obj) return wd->icon; } -/** - * Unset the icon of the bubble - * - * Unparent and return the icon object which was set for this widget. - * - * @param obj The bubble object - * @return The icon that was being used - * - * @ingroup Bubble - */ EAPI Evas_Object * elm_bubble_icon_unset(Evas_Object *obj) { @@ -440,21 +303,6 @@ elm_bubble_icon_unset(Evas_Object *obj) return icon; } -/** - * Set the corner of the bubble - * - * @param obj The bubble object. - * @param corner The given corner for the bubble. - * - * This function sets the corner of the bubble. - * The corner will be used to find the group in the theme - * For example, if you set the corner to "bottom_right", - * the following group will be searched: - * "elm/bubble/bottom_right/default", - * considering default style. - * - * @ingroup Bubble - */ EAPI void elm_bubble_corner_set(Evas_Object *obj, const char *corner) { @@ -466,16 +314,6 @@ elm_bubble_corner_set(Evas_Object *obj, const char *corner) _theme_hook(obj); } -/** - * Get the corner of the bubble - * - * @param obj The bubble object. - * @return The given corner for the bubble. - * - * This function gets the corner of the bubble. - * - * @ingroup Bubble - */ EAPI const char* elm_bubble_corner_get(const Evas_Object *obj) { -- 2.7.4