Elementary: Conformant Documentation

SVN revision: 61479

legacy/elementary/doc/examples.dox

@@ -2188,6 +2188,79 @@
  * @example hoversel_example_01.c
  */
 
+/**
+ * @page conformant_example Conformant Example.
+ *
+ * In this example we'll explain how to create applications to work
+ * with illume, considering space required for virtual keyboards.
+ *
+ * Illume is a module for Enlightenment that modifies the user interface
+ * to work cleanly and nicely on a mobile device. It has support for
+ * virtual keyboard, among other nice features.
+ *
+ * Let's start creating a very simple window with a vertical box
+ * with multi-line entry between two buttons.
+ * This entry will expand filling all space on window not used by buttons.
+ *
+ * @dontinclude conformant_example_01.c
+ * @skipline elm_main
+ * @until }
+ *
+ * For information about how to create windows, boxes, buttons or entries,
+ * look for documentation for these widgets.
+ *
+ * It will looks fine when you don't need a virtual keyboard, as you
+ * can see on the following image:
+ *
+ * @image html screenshots/conformant_example_01.png
+ * @image latex screenshots/conformant_example_01.eps
+ *
+ * But if you call a virtual keyboard, the window will resize, changing
+ * widgets size and position. All the content will shrink.
+ * The window will look like this:
+ *
+ * @image html screenshots/conformant_example_02.png
+ * @image latex screenshots/conformant_example_02.eps
+ *
+ * If you don't want such behaviour, you
+ * will need a conformant to account for space taken up by the indicator,
+ * virtual keyboard and softkey windows.
+ *
+ * In this case, using the conformant in a proper way, you will have
+ * a window like the following when the virtual keyboard is hidden:
+ *
+ * @image html screenshots/conformant_example_03.png
+ * @image latex screenshots/conformant_example_03.eps
+ *
+ * As you can see, it guess the space that will be required by the keyboard.
+ * Verify how perfectly it fits when keyboard is visible:
+ *
+ * @image html screenshots/conformant_example_04.png
+ * @image latex screenshots/conformant_example_04.eps
+ *
+ * So, let's study each step required to transform our initial example on
+ * the second one.
+ *
+ * First of all, we need to set the window as an illume conformant window:
+ * @dontinclude conformant_example_02.c
+ * @skipline elm_win_conformant_set
+ *
+ * Next, we'll add a conformant widget, and set it to resize with the window,
+ * instead of the box.
+ * @skipline conform
+ * @until evas_object_show
+ *
+ * Finally, we'll set the box as conformant's content, just like this:
+ * @skipline elm_conformant_content_set
+ *
+ * Compare both examples code:
+ * @ref conformant_example_01.c "conformant_example_01.c"
+ * @ref conformant_example_02.c "conformant_example_02.c"
+ *
+ * @example conformant_example_01.c
+ * @example conformant_example_02.c
+ */
+
 /**
  * @page bg_example_01_c bg_example_01.c
  * @include bg_example_01.c

legacy/elementary/src/examples/Makefile.am

@@ -57,6 +57,8 @@ SRCS = \
 	calendar_example_05.c \
 	calendar_example_06.c \
 	clock_example.c \
+	conformant_example_01.c \
+	conformant_example_02.c \
 	image_example_01.c \
 	flipselector_example.c \
 	fileselector_example.c \
@@ -113,6 +115,8 @@ pkglib_PROGRAMS += \
 	calendar_example_05 \
 	calendar_example_06 \
 	clock_example \
+	conformant_example_01 \
+	conformant_example_02 \
 	image_example_01 \
 	diskselector_example_01 \
 	diskselector_example_02 \

legacy/elementary/src/examples/conformant_example_01.c

@@ -0,0 +1,78 @@
+/**
+ * Simple Elementary's <b>conformant widget</b> example, illustrating its
+ * usage and API.
+ *
+ * See stdout/stderr for output. Compile with:
+ *
+ * @verbatim
+ * gcc -g `pkg-config --cflags --libs elementary` conformant_example_01.c -o conformant_example_01
+ * @endverbatim
+ */
+
+#include <Elementary.h>
+#ifdef HAVE_CONFIG_H
+# include "elementary_config.h"
+#else
+# define __UNUSED__
+#endif
+
+EAPI int
+elm_main(int argc __UNUSED__, char **argv __UNUSED__)
+{
+   Evas_Object *win, *bg, *btn, *bx, *en;
+
+   win = elm_win_add(NULL, "conformant", ELM_WIN_BASIC);
+   elm_win_title_set(win, "Conformant Example");
+   elm_win_autodel_set(win, EINA_TRUE);
+
+   bg = elm_bg_add(win);
+   elm_win_resize_object_add(win, bg);
+   evas_object_size_hint_weight_set(bg, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND);
+   evas_object_show(bg);
+
+   bx = elm_box_add(win);
+   elm_win_resize_object_add(win, bx);
+   evas_object_size_hint_weight_set(bx, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND);
+   evas_object_size_hint_align_set(bx, EVAS_HINT_FILL, EVAS_HINT_FILL);
+
+   btn = elm_button_add(win);
+   elm_object_text_set(btn, "Test Conformant");
+   evas_object_size_hint_weight_set(btn, EVAS_HINT_EXPAND, 0);
+   evas_object_size_hint_align_set(btn, EVAS_HINT_FILL, 0);
+   elm_box_pack_end(bx, btn);
+   evas_object_show(btn);
+
+   en = elm_entry_add(win);
+   elm_entry_scrollable_set(en, EINA_TRUE);
+   elm_entry_entry_set(en,
+                       "This is a multi-line entry at the bottom<br>"
+                       "This can contain more than 1 line of text and be "
+                       "scrolled around to allow for entering of lots of "
+                       "content. It is also to test to see that autoscroll "
+                       "moves to the right part of a larger multi-line "
+                       "text entry that is inside of a scroller than can be "
+                       "scrolled around, thus changing the expected position "
+                       "as well as cursor changes updating auto-scroll when "
+                       "it is enabled.");
+
+   evas_object_size_hint_weight_set(en, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND);
+   evas_object_size_hint_align_set(en, EVAS_HINT_FILL, EVAS_HINT_FILL);
+   evas_object_show(en);
+   elm_box_pack_end(bx, en);
+
+   btn = elm_button_add(win);
+   elm_object_text_set(btn, "Test Conformant");
+   evas_object_size_hint_weight_set(btn, EVAS_HINT_EXPAND, 0);
+   evas_object_size_hint_align_set(btn, EVAS_HINT_FILL, 0);
+   elm_box_pack_end(bx, btn);
+   evas_object_show(btn);
+
+   evas_object_show(bx);
+
+   evas_object_resize(win, 240, 480);
+   evas_object_show(win);
+
+   elm_run();
+   return 0;
+}
+ELM_MAIN()

legacy/elementary/src/examples/conformant_example_02.c

@@ -0,0 +1,85 @@
+/**
+ * Simple Elementary's <b>conformant widget</b> example, illustrating its
+ * usage and API.
+ *
+ * See stdout/stderr for output. Compile with:
+ *
+ * @verbatim
+ * gcc -g `pkg-config --cflags --libs elementary` conformant_example_02.c -o conformant_example_02
+ * @endverbatim
+ */
+
+#include <Elementary.h>
+#ifdef HAVE_CONFIG_H
+# include "elementary_config.h"
+#else
+# define __UNUSED__
+#endif
+
+EAPI int
+elm_main(int argc __UNUSED__, char **argv __UNUSED__)
+{
+   Evas_Object *win, *bg, *conform, *btn, *bx, *en;
+
+   win = elm_win_add(NULL, "conformant", ELM_WIN_BASIC);
+   elm_win_title_set(win, "Conformant Example");
+   elm_win_autodel_set(win, EINA_TRUE);
+
+   elm_win_conformant_set(win, EINA_TRUE);
+
+   bg = elm_bg_add(win);
+   elm_win_resize_object_add(win, bg);
+   evas_object_size_hint_weight_set(bg, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND);
+   evas_object_show(bg);
+
+   conform = elm_conformant_add(win);
+   elm_win_resize_object_add(win, conform);
+   evas_object_size_hint_weight_set(conform, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND);
+   evas_object_show(conform);
+
+   bx = elm_box_add(win);
+   evas_object_size_hint_weight_set(bx, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND);
+   evas_object_size_hint_align_set(bx, EVAS_HINT_FILL, EVAS_HINT_FILL);
+
+   btn = elm_button_add(win);
+   elm_object_text_set(btn, "Test Conformant");
+   evas_object_size_hint_weight_set(btn, EVAS_HINT_EXPAND, 0);
+   evas_object_size_hint_align_set(btn, EVAS_HINT_FILL, 0);
+   elm_box_pack_end(bx, btn);
+   evas_object_show(btn);
+
+   en = elm_entry_add(win);
+   elm_entry_scrollable_set(en, EINA_TRUE);
+   elm_entry_entry_set(en,
+                       "This is a multi-line entry at the bottom<br>"
+                       "This can contain more than 1 line of text and be "
+                       "scrolled around to allow for entering of lots of "
+                       "content. It is also to test to see that autoscroll "
+                       "moves to the right part of a larger multi-line "
+                       "text entry that is inside of a scroller than can be "
+                       "scrolled around, thus changing the expected position "
+                       "as well as cursor changes updating auto-scroll when "
+                       "it is enabled.");
+
+   evas_object_size_hint_weight_set(en, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND);
+   evas_object_size_hint_align_set(en, EVAS_HINT_FILL, EVAS_HINT_FILL);
+   evas_object_show(en);
+   elm_box_pack_end(bx, en);
+
+   btn = elm_button_add(win);
+   elm_object_text_set(btn, "Test Conformant");
+   evas_object_size_hint_weight_set(btn, EVAS_HINT_EXPAND, 0);
+   evas_object_size_hint_align_set(btn, EVAS_HINT_FILL, 0);
+   elm_box_pack_end(bx, btn);
+   evas_object_show(btn);
+
+   elm_conformant_content_set(conform, bx);
+   evas_object_show(bx);
+
+   evas_object_resize(win, 240, 480);
+   evas_object_show(win);
+
+   elm_run();
+   return 0;
+}
+ELM_MAIN()

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

@@ -7899,13 +7899,110 @@ extern "C" {
    EINA_DEPRECATED EAPI void         elm_scrolled_entry_cnp_textonly_set(Evas_Object *obj, Eina_Bool textonly) EINA_ARG_NONNULL(1);
    EINA_DEPRECATED EAPI Eina_Bool    elm_scrolled_entry_cnp_textonly_get(Evas_Object *obj) EINA_ARG_NONNULL(1);
 
-   /* conformant */
+   /**
+    * @defgroup Conformant Conformant
+    * @ingroup Elementary
+    *
+    * The aim is to provide a widget that can be used in elementary apps to
+    * account for space taken up by the indicator, virtual keypad & softkey
+    * windows when running the illume2 module of E17.
+    *
+    * So conformant content will be sized and positioned considering the
+    * space required for such stuff, and when they popup, as a keyboard
+    * shows when an entry is selected, conformant content won't change.
+    *
+    * Available styles for it:
+    * - @c "default"
+    *
+    * See how to use this widget in this example:
+    * @ref conformant_example
+    */
+
+   /**
+    * @addtogroup Conformant
+    * @{
+    */
+
+   /**
+    * Add a new conformant widget to the given parent Elementary
+    * (container) object.
+    *
+    * @param parent The parent object.
+    * @return A new conformant widget handle or @c NULL, on errors.
+    *
+    * This function inserts a new conformant widget on the canvas.
+    *
+    * @ingroup Conformant
+    */
    EAPI Evas_Object *elm_conformant_add(Evas_Object *parent) EINA_ARG_NONNULL(1);
+
+   /**
+    * Set the content of the conformant widget.
+    *
+    * @param obj The conformant object.
+    * @param content The content to be displayed by the conformant.
+    *
+    * Content will be sized and positioned considering the space required
+    * to display a virtual keyboard. So it won't fill all the conformant
+    * size. This way is possible to be sure that content won't resize
+    * or be re-positioned after the keyboard is displayed.
+    *
+    * 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_conformat_content_unset() function.
+    *
+    * @see elm_conformant_content_unset()
+    * @see elm_conformant_content_get()
+    *
+    * @ingroup Conformant
+    */
    EAPI void         elm_conformant_content_set(Evas_Object *obj, Evas_Object *content) EINA_ARG_NONNULL(1);
+
+   /**
+    * Get the content of the conformant widget.
+    *
+    * @param obj The conformant object.
+    * @return The content that is being used.
+    *
+    * Return the content object which is set for this widget.
+    * It won't be unparent from conformant. For that, use
+    * elm_conformant_content_unset().
+    *
+    * @see elm_conformant_content_set() for more details.
+    * @see elm_conformant_content_unset()
+    *
+    * @ingroup Conformant
+    */
    EAPI Evas_Object *elm_conformant_content_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
+
+   /**
+    * Unset the content of the conformant widget.
+    *
+    * @param obj The conformant object.
+    * @return The content that was being used.
+    *
+    * Unparent and return the content object which was set for this widget.
+    *
+    * @see elm_conformant_content_set() for more details.
+    *
+    * @ingroup Conformant
+    */
    EAPI Evas_Object *elm_conformant_content_unset(Evas_Object *obj) EINA_ARG_NONNULL(1);
+
+   /**
+    * Returns the Evas_Object that represents the content area.
+    *
+    * @param obj The conformant object.
+    * @return The content area of the widget.
+    *
+    * @ingroup Conformant
+    */
    EAPI Evas_Object *elm_conformant_content_area_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
 
+   /**
+    * @}
+    */
+
    /* mapbuf */
    EAPI Evas_Object *elm_mapbuf_add(Evas_Object *parent) EINA_ARG_NONNULL(1);
    EAPI void         elm_mapbuf_content_set(Evas_Object *obj, Evas_Object *content) EINA_ARG_NONNULL(1);

legacy/elementary/src/lib/elm_conform.c

@@ -9,14 +9,6 @@
 # define MAX(a,b) ((a) < (b)) ? (b) : (a)
 #endif
 
-/**
- * @defgroup Conformant Conformant
- *
- * The aim is to provide a widget that can be used in elementary apps to
- * account for space taken up by the indicator, virtual keypad & softkey windows when running
- * the illume2 module of E17.
- */
-
 typedef struct _Widget_Data Widget_Data;
 struct _Widget_Data
 {
@@ -444,14 +436,6 @@ _prop_change(void *data, int type __UNUSED__, void *event)
 }
 #endif
 
-/**
- * Add a new Conformant object
- *
- * @param parent The parent object
- * @return The new conformant object or NULL if it cannot be created
- *
- * @ingroup Conformant
- */
 EAPI Evas_Object *
 elm_conformant_add(Evas_Object *parent)
 {
@@ -499,18 +483,6 @@ elm_conformant_add(Evas_Object *parent)
    return obj;
 }
 
-/**
- * Set the content of the conformant 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_conformat_content_unset() function.
- *
- * @param obj The conformant object
- * @return The content that was being used
- *
- * @ingroup Conformant
- */
 EAPI void
 elm_conformant_content_set(Evas_Object *obj, Evas_Object *content)
 {
@@ -532,16 +504,6 @@ elm_conformant_content_set(Evas_Object *obj, Evas_Object *content)
    _sizing_eval(obj);
 }
 
-/**
- * Get the content of the conformant widget
- *
- * Return the content object which is set for this widget;
- *
- * @param obj The conformant object
- * @return The content that is being used
- *
- * @ingroup Conformant
- */
 EAPI Evas_Object *
 elm_conformant_content_get(const Evas_Object *obj)
 {
@@ -552,16 +514,6 @@ elm_conformant_content_get(const Evas_Object *obj)
    return wd->content;
 }
 
-/**
- * Unset the content of the conformant widget
- *
- * Unparent and return the content object which was set for this widget;
- *
- * @param obj The conformant object
- * @return The content that was being used
- *
- * @ingroup Conformant
- */
 EAPI Evas_Object *
 elm_conformant_content_unset(Evas_Object *obj)
 {
@@ -577,14 +529,7 @@ elm_conformant_content_unset(Evas_Object *obj)
    wd->content = NULL;
    return content;
 }
-/**
- * Returns the Evas_Object that represents the content area.
- *
- * @param obj The conformant object.
- * @return The content area of the widget.
- *
- * @ingroup Conformant
- */
+
 EAPI Evas_Object *
 elm_conformant_content_area_get(const Evas_Object *obj)
 {
@@ -596,4 +541,3 @@ elm_conformant_content_area_get(const Evas_Object *obj)
    _elm_dangerous_call_check(__FUNCTION__);
    return (Evas_Object *)edje_object_part_object_get(wd->base, "elm.swallow.content");
 }
-