Elementary: elm_frame documentation.

SVN revision: 61157

legacy/elementary/src/examples/Makefile.am

@@ -33,6 +33,7 @@ SRCS = \
 	bubble_example_01.c \
 	button_example_01.c \
 	colorselector_example_01.c
+	frame_example_01.c \
 	transit_example_01.c \
 	transit_example_02.c \
 	transit_example_03.c \
@@ -69,6 +70,7 @@ pkglib_PROGRAMS += \
 	bubble_example_01 \
 	button_example_01 \
 	colorselector_example_01 \
+	frame_example_01 \
 	transit_example_01 \
 	transit_example_02 \
 	transit_example_03 \
@@ -95,6 +97,7 @@ SCREENSHOTS = \
 	animator_example_01:animator_example_01.png:0.2 \
 	animator_example_01:animator_example_02.png:0.5 \
 	animator_example_01:animator_example_03.png:0.9 \
+	frame_example_01:frame_example_01.png:0.0 \
 	theme_example_01:theme_example_01.png:0.0
 
 screenshots: all

legacy/elementary/src/examples/frame_example_01.c

@@ -0,0 +1,85 @@
+//Compile with:
+//gcc -g `pkg-config --cflags --libs elementary` frame_example_01.c -o frame_example_01
+
+#include <Elementary.h>
+#ifdef HAVE_CONFIG_H
+# include "elementary_config.h"
+#endif
+
+EAPI int
+elm_main(int argc, char **argv)
+{
+   Evas_Object *win, *bg;
+   Evas_Object *f1, *r1, *f2, *r2, *f3, *r3, *f4, *r4;
+   Elm_Animator *animator;
+   char buf[256];
+
+   win = elm_win_add(NULL, "frame", ELM_WIN_BASIC);
+   elm_win_title_set(win, "Frame");
+   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);
+
+   r1 = evas_object_rectangle_add(evas_object_evas_get(win));
+   evas_object_color_set(r1, 255, 0, 0, 255);
+   evas_object_show(r1);
+
+   f1= elm_frame_add(win);
+   elm_frame_content_set(f1, r1);
+   elm_object_text_set(f1, "Default frame");
+   evas_object_resize(f1, 100, 100);
+   evas_object_move(f1, 25, 25);
+   evas_object_show(f1);
+
+   r2 = evas_object_rectangle_add(evas_object_evas_get(win));
+   evas_object_color_set(r2, 0, 255, 0, 255);
+   evas_object_show(r2);
+
+   f2 = elm_frame_add(win);
+   elm_frame_content_set(f2, r2);
+   elm_object_text_set(f2, "Padding frame");
+   evas_object_resize(f2, 100, 100);
+   evas_object_move(f2, 150, 25);
+   elm_object_style_set(f2, "pad_small");
+   evas_object_show(f2);
+
+   r3 = evas_object_rectangle_add(evas_object_evas_get(win));
+   evas_object_color_set(r3, 0, 0, 255, 255);
+   evas_object_show(r3);
+
+   f3 = elm_frame_add(win);
+   elm_frame_content_set(f3, r3);
+   elm_object_text_set(f3, "Top outdent frame");
+   evas_object_resize(f3, 100, 100);
+   evas_object_move(f3, 25, 150);
+   elm_object_style_set(f3, "outdent_top");
+   evas_object_show(f3);
+
+   r4 = evas_object_rectangle_add(evas_object_evas_get(win));
+   evas_object_color_set(r4, 0, 0, 0, 255);
+   evas_object_show(r4);
+
+   f4 = elm_frame_add(win);
+   elm_frame_content_set(f4, r4);
+   elm_object_text_set(f4, "Bottom outdent frame");
+   evas_object_resize(f4, 100, 100);
+   evas_object_move(f4, 150, 150);
+   elm_object_style_set(f4, "outdent_bottom");
+   evas_object_show(f4);
+
+   evas_object_resize(win, 275, 275);
+   evas_object_show(win);
+
+   elm_run();
+
+   evas_object_del(r1);
+   evas_object_del(r2);
+   evas_object_del(r3);
+   evas_object_del(r4);
+
+   return 0;
+}
+ELM_MAIN()

legacy/elementary/src/lib/Elementary.h.in

@@ -2663,23 +2663,137 @@ extern "C" {
     *             by the cursor in the first place).
     */
 
-   /* frame */
-   EAPI Evas_Object *elm_frame_add(Evas_Object *parent) EINA_ARG_NONNULL(1);
-   EINA_DEPRECATED EAPI void         elm_frame_label_set(Evas_Object *obj, const char *label) EINA_ARG_NONNULL(1);
-   EINA_DEPRECATED EAPI const char  *elm_frame_label_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
-   EAPI void         elm_frame_content_set(Evas_Object *obj, Evas_Object *content) EINA_ARG_NONNULL(1);
-   EAPI Evas_Object *elm_frame_content_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
-   EAPI Evas_Object *elm_frame_content_unset(Evas_Object *obj) EINA_ARG_NONNULL(1);
-   /* available styles:
-    * default
-    * pad_small
-    * pad_medium
-    * pad_large
-    * pad_huge
-    * outdent_top
-    * outdent_bottom
+   /**
+    * @page tutorial_frame Frame example
+    * @dontinclude frame_example_01.c
+    *
+    * In this example we are going to create 4 Frames with different styles and
+    * add a rectangle of different color in each.
+    *
+    * We start we the usual setup code:
+    * @until show(bg)
+    *
+    * And then create one rectangle:
+    * @until show
+    *
+    * To add it in our first frame, which since it doesn't have it's style
+    * specifically set uses the default style:
+    * @until show
+    *
+    * And then create another rectangle:
+    * @until show
+    *
+    * To add it in our second frame, which uses the "pad_small" style, note that
+    * even tough we are setting a text for this frame it won't be show, only the
+    * default style shows the Frame's title:
+    * @until show
+    * @note The "pad_small", "pad_medium", "pad_large" and "pad_huge" styles are
+    * very similar, their only difference is the size of the empty area around
+    * the content of the frame.
+    *
+    * And then create yet another rectangle:
+    * @until show
+    *
+    * To add it in our third frame, which uses the "outdent_top" style, note
+    * that even tough we are setting a text for this frame it won't be show,
+    * only the default style shows the Frame's title:
+    * @until show
+    *
+    * And then create one last rectangle:
+    * @until show
+    *
+    * To add it in our fourth and final frame, which uses the "outdent_bottom"
+    * style, note that even tough we are setting a text for this frame it won't
+    * be show, only the default style shows the Frame's title:
+    * @until show
+    *
+    * And now we are left with just some more setup code:
+    * @until ELM_MAIN()
+    *
+    * Our example will look like this:
+    * @image html screenshots/frame_example_01.png
+    * @image latex screenshots/frame_example_01.eps
+    *
+    * @example frame_example_01.c
     */
-   /* smart callbacks called:
+   /**
+    * @defgroup Frame Frame
+    *
+    * @brief Frame is a widget that holds some content and has a title.
+    *
+    * The default look is a frame with a title, but Frame supports multple
+    * styles:
+    * @li default
+    * @li pad_small
+    * @li pad_medium
+    * @li pad_large
+    * @li pad_huge
+    * @li outdent_top
+    * @li outdent_bottom
+    *
+    * Of all this styles only default shows the title. Frame emits no signals.
+    *
+    * For a detailed example see the @ref tutorial_frame.
+    *
+    * @{
+    */
+   /**
+    * @brief Add a new frame to the parent
+    *
+    * @param parent The parent object
+    * @return The new object or NULL if it cannot be created
+    */
+   EAPI Evas_Object *elm_frame_add(Evas_Object *parent) EINA_ARG_NONNULL(1);
+   /**
+    * @brief Set the frame label
+    *
+    * @param obj The frame object
+    * @param label The label of this frame object
+    *
+    * @deprecated use elm_object_text_set() instead.
+    */
+   EINA_DEPRECATED EAPI void         elm_frame_label_set(Evas_Object *obj, const char *label) EINA_ARG_NONNULL(1);
+   /**
+    * @brief Get the frame label
+    *
+    * @param obj The frame object
+    *
+    * @return The label of this frame objet or NULL if unable to get frame
+    *
+    * @deprecated use elm_object_text_get() instead.
+    */
+   EINA_DEPRECATED EAPI const char  *elm_frame_label_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
+   /**
+    * @brief Set the content of the frame widget
+    *
+    * Once the content object is set, a previously set one will be deleted.
+    * If you want to keep that old content object, use the
+    * elm_frame_content_unset() function.
+    *
+    * @param obj The frame object
+    * @param content The content will be filled in this frame object
+    */
+   EAPI void         elm_frame_content_set(Evas_Object *obj, Evas_Object *content) EINA_ARG_NONNULL(1);
+   /**
+    * @brief Get the content of the frame widget
+    *
+    * Return the content object which is set for this widget
+    *
+    * @param obj The frame object
+    * @return The content that is being used
+    */
+   EAPI Evas_Object *elm_frame_content_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
+   /**
+    * @brief Unset the content of the frame widget
+    *
+    * Unparent and return the content object which was set for this widget
+    *
+    * @param obj The frame object
+    * @return The content that was being used
+    */
+   EAPI Evas_Object *elm_frame_content_unset(Evas_Object *obj) EINA_ARG_NONNULL(1);
+   /**
+    * @}
     */
 
    /* table */

legacy/elementary/src/lib/elm_frame.c

@@ -1,13 +1,6 @@
 #include <Elementary.h>
 #include "elm_priv.h"
 
-/**
- * @defgroup Frame Frame
- *
- * This holds some content and has a title. Looks like a frame, but
- * supports styles so multple frames are avaible
- */
-
 typedef struct _Widget_Data Widget_Data;
 
 struct _Widget_Data
@@ -131,14 +124,6 @@ _elm_frame_label_get(const Evas_Object *obj, const char *item)
    return wd->label;
 }
 
-/**
- * Add a new frame to the parent
- *
- * @param parent The parent object
- * @return The new object or NULL if it cannot be created
- *
- * @ingroup Frame
- */
 EAPI Evas_Object *
 elm_frame_add(Evas_Object *parent)
 {
@@ -170,49 +155,18 @@ elm_frame_add(Evas_Object *parent)
    return obj;
 }
 
-/**
- * Set the frame label
- *
- * @param obj The frame object
- * @param label The label of this frame object
- *
- * @ingroup Frame
- * @deprecate use elm_object_text_* instead.
- */
 EAPI void
 elm_frame_label_set(Evas_Object *obj, const char *label)
 {
    _elm_frame_label_set(obj, NULL, label);
 }
 
-/**
- * Get the frame label
- *
- * @param obj The frame object
- *
- * @return The label of this frame objet or NULL if unable to get frame
- *
- * @ingroup Frame
- * @deprecate use elm_object_text_* instead.
- */
 EAPI const char *
 elm_frame_label_get(const Evas_Object *obj)
 {
    return _elm_frame_label_get(obj, NULL);
 }
 
-/**
- * Set the content of the frame widget
- *
- * Once the content object is set, a previously set one will be deleted.
- * If you want to keep that old content object, use the
- * elm_frame_content_unset() function.
- *
- * @param obj The frame object
- * @param content The content will be filled in this frame object
- *
- * @ingroup Frame
- */
 EAPI void
 elm_frame_content_set(Evas_Object *obj, Evas_Object *content)
 {
@@ -232,16 +186,6 @@ elm_frame_content_set(Evas_Object *obj, Evas_Object *content)
    _sizing_eval(obj);
 }
 
-/**
- * Get the content of the frame widget
- *
- * Return the content object which is set for this widget
- *
- * @param obj The frame object
- * @return The content that is being used
- *
- * @ingroup Frame
- */
 EAPI Evas_Object *
 elm_frame_content_get(const Evas_Object *obj)
 {
@@ -251,16 +195,6 @@ elm_frame_content_get(const Evas_Object *obj)
    return wd->content;
 }
 
-/**
- * Unset the content of the frame widget
- *
- * Unparent and return the content object which was set for this widget
- *
- * @param obj The frame object
- * @return The content that was being used
- *
- * @ingroup Frame
- */
 EAPI Evas_Object *
 elm_frame_content_unset(Evas_Object *obj)
 {