Elementary: elm_bubble documentation.

git-svn-id: https://svn.enlightenment.org/svn/e/trunk/elementary@60842 7cbeb6ba-43b4-40fd-8cce-4c39aea84d33

diff --git a/doc/examples.dox b/doc/examples.dox
index 9368b83..6d8a449 100644 (file)
--- 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
  * @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 (file)
--- 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 \
        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 \
        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 \
        actionslider_example_01 \
        anchorblock_example_01 \
        animator_example_01 \

+       bubble_example_01 \

        button_example_01 \
        transit_example_01 \
        transit_example_02 \
        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 (file)
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="\"<directory>\"" bubble_example_01.c -o bubble_example_01
+
+#include <Elementary.h>
+#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 (file)
--- 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);
    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);
    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);
    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);
    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);
    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);
    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);
    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);
    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);
    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);
    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);
    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);
    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);
    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 */
     */
 
    /* photo */

diff --git a/src/lib/elm_bubble.c b/src/lib/elm_bubble.c
index 2ee7a2e..cbc2b45 100644 (file)
--- a/src/lib/elm_bubble.c
+++ b/src/lib/elm_bubble.c
@@ -1,17 +1,6 @@
 #include <Elementary.h>
 #include "elm_priv.h"
 
 #include <Elementary.h>
 #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
 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);
 }
 
    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)
 {
 EAPI Evas_Object *
 elm_bubble_add(Evas_Object *parent)
 {


@@ -192,17 +171,6 @@ elm_bubble_add(Evas_Object *parent)
    return obj;
 }
 
    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)
 {
 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);
 }
 
    _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)
 {
 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;
 }
 
    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)
 {
 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);
 }
 
    _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)
 {
 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;
 }
 
    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)
 {
 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);
 }
 
    _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)
 {
 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;
 }
 
    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)
 {
 EAPI Evas_Object *
 elm_bubble_content_unset(Evas_Object *obj)
 {


@@ -363,18 +258,6 @@ elm_bubble_content_unset(Evas_Object *obj)
    return content;
 }
 
    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)
 {
 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);
 }
 
    _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)
 {
 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;
 }
 
    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)
 {
 EAPI Evas_Object *
 elm_bubble_icon_unset(Evas_Object *obj)
 {


@@ -440,21 +303,6 @@ elm_bubble_icon_unset(Evas_Object *obj)
    return icon;
 }
 
    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)
 {
 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);
 }
 
    _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)
 {
 EAPI const char*
 elm_bubble_corner_get(const Evas_Object *obj)
 {