From 401f53e23f8d23954fd905a196f669c6acc7449b Mon Sep 17 00:00:00 2001 From: "Jonas M. Gastal" Date: Thu, 28 Jul 2011 16:51:39 +0000 Subject: [PATCH] Elementary: table documentation. SVN revision: 61865 --- legacy/elementary/doc/Makefile.am | 3 +- legacy/elementary/doc/examples.dox | 55 +++++++++ legacy/elementary/doc/index.doxy | 3 + legacy/elementary/doc/widgets/Makefile.am | 4 +- .../doc/widgets/widget_preview_table.c | 32 +++++ legacy/elementary/src/examples/Makefile.am | 12 +- .../src/examples/table_example_01.c | 55 +++++++++ .../src/examples/table_example_02.c | 58 +++++++++ legacy/elementary/src/lib/Elementary.h.in | 111 +++++++++++++++++- legacy/elementary/src/lib/elm_table.c | 103 ---------------- 10 files changed, 327 insertions(+), 109 deletions(-) create mode 100644 legacy/elementary/doc/widgets/widget_preview_table.c create mode 100644 legacy/elementary/src/examples/table_example_01.c create mode 100644 legacy/elementary/src/examples/table_example_02.c diff --git a/legacy/elementary/doc/Makefile.am b/legacy/elementary/doc/Makefile.am index 70a04d00b8..8b5c364fff 100644 --- a/legacy/elementary/doc/Makefile.am +++ b/legacy/elementary/doc/Makefile.am @@ -66,7 +66,8 @@ WGT_PREVIEW = \ inwin:preview-00.png:widget_preview_inwin1:200:160 \ inwin:preview-01.png:widget_preview_inwin2:200:160 \ inwin:preview-02.png:widget_preview_inwin3:200:160 \ - scroller:preview-00.png:widget_preview_scroller:100:30 + scroller:preview-00.png:widget_preview_scroller:100:30 \ + table::preview-00.png:widget_preview_table:100:100 widget-build: @$(MAKE) -C widgets diff --git a/legacy/elementary/doc/examples.dox b/legacy/elementary/doc/examples.dox index 88eba4bdf1..51d0582234 100644 --- a/legacy/elementary/doc/examples.dox +++ b/legacy/elementary/doc/examples.dox @@ -4884,6 +4884,61 @@ * @example scroller_example_01.c */ +/** + * @page tutorial_table_01 + * + * In this example we add four labels to a homogeneous table that has a padding + * of 5px between cells. + * + * The interesting bits from this example are: + * @li Where we set the table as homogeneous and the padding: + * @dontinclude table_example_01.c + * @skip padding_set + * @until homogeneous_set + * @li Where we add each label to the table: + * @skipline elm_table_pack + * @skipline elm_table_pack + * @skipline elm_table_pack + * @skipline elm_table_pack + * + * Here you can see the full source: + * @include table_example_01.c + * + * Our example will look like this: + * + * @image html screenshots/table_example_01.png + * @image latex screenshots/table_example_01.eps width=\textwidth + * + * @example table_example_01.c + */ + +/** + * @page tutorial_table_02 + * + * For our second example we'll create a table with 4 rectangles in it. Since + * our rectangles are of different sizes our table won't be homogeneous. + * + * The interesting bits from this example are: + * @li Where we set the table as not homogeneous: + * @dontinclude table_example_02.c + * @skipline homogeneous_set + * @li Where we add each rectangle to the table: + * @skipline elm_table_pack + * @skipline elm_table_pack + * @skipline elm_table_pack + * @skipline elm_table_pack + * + * Here you can see the full source: + * @include table_example_02.c + * + * Our example will look like this: + * + * @image html screenshots/table_example_02.png + * @image latex screenshots/table_example_02.eps width=\textwidth + * + * @example table_example_02.c + */ + /** * @page bg_example_01_c bg_example_01.c * @include bg_example_01.c diff --git a/legacy/elementary/doc/index.doxy b/legacy/elementary/doc/index.doxy index 2828c7e255..3ae3adf3a8 100644 --- a/legacy/elementary/doc/index.doxy +++ b/legacy/elementary/doc/index.doxy @@ -237,4 +237,7 @@ * @image html img/widget/scroller/preview-00.png * @image latex img/widget/scroller/preview-00.eps * @li @ref Table + * + * @image html img/widget/table/preview-00.png + * @image latex img/widget/table/preview-00.eps */ diff --git a/legacy/elementary/doc/widgets/Makefile.am b/legacy/elementary/doc/widgets/Makefile.am index 76c2720d94..2e39ede540 100644 --- a/legacy/elementary/doc/widgets/Makefile.am +++ b/legacy/elementary/doc/widgets/Makefile.am @@ -82,7 +82,8 @@ widget_preview_photocam \ widget_preview_inwin1 \ widget_preview_inwin2 \ widget_preview_inwin3 \ -widget_preview_scroller +widget_preview_scroller \ +widget_preview_table LDADD = $(top_builddir)/src/lib/libelementary.la @ELEMENTARY_EWEATHER_LIBS@ @ELEMENTARY_EDBUS_LIBS@ @ELEMENTARY_EFREET_LIBS@ @ELEMENTARY_EMAP_LIBS@ @ELEMENTARY_LIBS@ @EIO_LIBS@ @my_libs@ @@ -146,5 +147,6 @@ EXTRA_DIST = \ widget_preview_inwin2.c \ widget_preview_inwin3.c \ widget_preview_scroller.c \ + widget_preview_table.c \ widget_preview_tmpl_foot.c \ widget_preview_tmpl_head.c diff --git a/legacy/elementary/doc/widgets/widget_preview_table.c b/legacy/elementary/doc/widgets/widget_preview_table.c new file mode 100644 index 0000000000..f37d52b80b --- /dev/null +++ b/legacy/elementary/doc/widgets/widget_preview_table.c @@ -0,0 +1,32 @@ +#include "widget_preview_tmpl_head.c" + +Evas_Object *o = elm_table_add(win); +evas_object_size_hint_weight_set(o, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND); +elm_win_resize_object_add(win, o); +evas_object_show(o); + +Evas_Object *o2 = evas_object_rectangle_add(evas_object_evas_get(win)); +evas_object_color_set(o2, 255, 0, 0, 255); +evas_object_size_hint_min_set(o2, 50, 50); +evas_object_show(o2); +elm_table_pack(o, o2, 0, 0, 1, 1); + +o2 = evas_object_rectangle_add(evas_object_evas_get(win)); +evas_object_color_set(o2, 0, 255, 0, 255); +evas_object_size_hint_min_set(o2, 50, 50); +evas_object_show(o2); +elm_table_pack(o, o2, 1, 0, 1, 1); + +o2 = evas_object_rectangle_add(evas_object_evas_get(win)); +evas_object_color_set(o2, 0, 0, 255, 255); +evas_object_size_hint_min_set(o2, 50, 50); +evas_object_show(o2); +elm_table_pack(o, o2, 0, 1, 1, 1); + +o2 = evas_object_rectangle_add(evas_object_evas_get(win)); +evas_object_color_set(o2, 255, 255, 0, 255); +evas_object_size_hint_min_set(o2, 50, 50); +evas_object_show(o2); +elm_table_pack(o, o2, 1, 1, 1, 1); + +#include "widget_preview_tmpl_foot.c" diff --git a/legacy/elementary/src/examples/Makefile.am b/legacy/elementary/src/examples/Makefile.am index f4a3e71fbc..bd22620b4f 100644 --- a/legacy/elementary/src/examples/Makefile.am +++ b/legacy/elementary/src/examples/Makefile.am @@ -98,7 +98,9 @@ SRCS = \ notify_example_01.c \ photocam_example_01.c \ inwin_example.c \ - scroller_example_01.c + scroller_example_01.c \ + table_example_01.c \ + table_example_02.c pkglib_PROGRAMS = @@ -186,7 +188,9 @@ pkglib_PROGRAMS += \ notify_example_01 \ photocam_example_01 \ inwin_example \ - scroller_example_01 + scroller_example_01 \ + table_example_01 \ + table_example_02 # This variable will hold the list of screenshots that will be made # by "make screenshots". Each item in the list is of the form: @@ -248,7 +252,9 @@ SCREENSHOTS = \ photocam_example_01:photocam_example_01.png:3 \ scroller_example_01:scroller_example_01.png:0.0 \ inwin_example:inwin_example.png:0.0 \ - inwin_example:inwin_example_a.png:0.2 + inwin_example:inwin_example_a.png:0.2 \ + table_example_01:table_example_01.png:0.0 \ + table_example_02:table_example_02.png:0.0 HTML_SS_DIR=$(top_builddir)/doc/html/screenshots LATEX_SS_DIR=$(top_builddir)/doc/latex/screenshots diff --git a/legacy/elementary/src/examples/table_example_01.c b/legacy/elementary/src/examples/table_example_01.c new file mode 100644 index 0000000000..13318ba12f --- /dev/null +++ b/legacy/elementary/src/examples/table_example_01.c @@ -0,0 +1,55 @@ +//Compile with: +//gcc -g `pkg-config --cflags --libs elementary` table_example_01.c -o table_example_01 + +#include +#ifdef HAVE_CONFIG_H +# include "elementary_config.h" +#endif + +EAPI int +elm_main(int argc, char **argv) +{ + Evas_Object *win, *bg, *label, *table; + + win = elm_win_add(NULL, "table", ELM_WIN_BASIC); + elm_win_title_set(win, "Table"); + 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); + + table = elm_table_add(win); + elm_win_resize_object_add(win, table); + evas_object_show(table); + elm_table_padding_set(table, 5, 5); + elm_table_homogeneous_set(table, EINA_TRUE); + + label = elm_label_add(win); + elm_object_text_set(label, "label 0"); + evas_object_show(label); + elm_table_pack(table, label, 0, 0, 1, 1); + + label = elm_label_add(win); + elm_object_text_set(label, "label 1"); + evas_object_show(label); + elm_table_pack(table, label, 1, 0, 1, 1); + + label = elm_label_add(win); + elm_object_text_set(label, "label 2"); + evas_object_show(label); + elm_table_pack(table, label, 0, 1, 1, 1); + + label = elm_label_add(win); + elm_object_text_set(label, "label 3"); + evas_object_show(label); + elm_table_pack(table, label, 1, 1, 1, 1); + + evas_object_show(win); + + elm_run(); + + return 0; +} +ELM_MAIN() diff --git a/legacy/elementary/src/examples/table_example_02.c b/legacy/elementary/src/examples/table_example_02.c new file mode 100644 index 0000000000..fe103d5ee1 --- /dev/null +++ b/legacy/elementary/src/examples/table_example_02.c @@ -0,0 +1,58 @@ +//Compile with: +//gcc -g `pkg-config --cflags --libs elementary` table_example_02.c -o table_example_02 + +#include +#ifdef HAVE_CONFIG_H +# include "elementary_config.h" +#endif + +EAPI int +elm_main(int argc, char **argv) +{ + Evas_Object *win, *bg, *rect, *table; + + win = elm_win_add(NULL, "table", ELM_WIN_BASIC); + elm_win_title_set(win, "Table"); + 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); + + table = elm_table_add(win); + elm_win_resize_object_add(win, table); + evas_object_show(table); + elm_table_homogeneous_set(table, EINA_FALSE); + + rect = evas_object_rectangle_add(evas_object_evas_get(win)); + evas_object_color_set(rect, 255, 0, 0, 255); + evas_object_size_hint_min_set(rect, 100, 50); + evas_object_show(rect); + elm_table_pack(table, rect, 0, 0, 2, 1); + + rect = evas_object_rectangle_add(evas_object_evas_get(win)); + evas_object_color_set(rect, 0, 255, 0, 255); + evas_object_size_hint_min_set(rect, 50, 100); + evas_object_show(rect); + elm_table_pack(table, rect, 0, 1, 1, 2); + + rect = evas_object_rectangle_add(evas_object_evas_get(win)); + evas_object_color_set(rect, 0, 0, 255, 255); + evas_object_size_hint_min_set(rect, 50, 50); + evas_object_show(rect); + elm_table_pack(table, rect, 1, 1, 1, 1); + + rect = evas_object_rectangle_add(evas_object_evas_get(win)); + evas_object_color_set(rect, 255, 255, 0, 255); + evas_object_size_hint_min_set(rect, 50, 50); + evas_object_show(rect); + elm_table_pack(table, rect, 1, 2, 1, 1); + + evas_object_show(win); + + elm_run(); + + return 0; +} +ELM_MAIN() diff --git a/legacy/elementary/src/lib/Elementary.h.in b/legacy/elementary/src/lib/Elementary.h.in index d721d7ed7d..307ec6d47e 100644 --- a/legacy/elementary/src/lib/Elementary.h.in +++ b/legacy/elementary/src/lib/Elementary.h.in @@ -4777,19 +4777,128 @@ extern "C" { * @} */ - /* table */ + /** + * @defgroup Table Table + * + * A container widget to arrange other widgets in a table where items can + * also span multiple columns or rows - even overlap (and then be raised or + * lowered accordingly to adjust stacking if they do overlap). + * + * The followin are examples of how to use a table: + * @li @ref tutorial_table_01 + * @li @ref tutorial_table_02 + * + * @{ + */ + /** + * @brief Add a new table to the parent + * + * @param parent The parent object + * @return The new object or NULL if it cannot be created + */ EAPI Evas_Object *elm_table_add(Evas_Object *parent) EINA_ARG_NONNULL(1); + /** + * @brief Set the homogeneous layout in the table + * + * @param obj The layout object + * @param homogeneous A boolean to set if the layout is homogeneous in the + * table (EINA_TRUE = homogeneous, EINA_FALSE = no homogeneous) + */ EAPI void elm_table_homogeneous_set(Evas_Object *obj, Eina_Bool homogeneous) EINA_ARG_NONNULL(1); + /** + * @brief Get the current table homogeneous mode. + * + * @param obj The table object + * @return A boolean to indicating if the layout is homogeneous in the table + * (EINA_TRUE = homogeneous, EINA_FALSE = no homogeneous) + */ EAPI Eina_Bool elm_table_homogeneous_get(const Evas_Object *obj) EINA_ARG_NONNULL(1); + /** + * @warning Use elm_table_homogeneous_set() instead + */ EINA_DEPRECATED EAPI void elm_table_homogenous_set(Evas_Object *obj, Eina_Bool homogenous) EINA_ARG_NONNULL(1); + /** + * @warning Use elm_table_homogeneous_get() instead + */ EINA_DEPRECATED EAPI Eina_Bool elm_table_homogenous_get(const Evas_Object *obj) EINA_ARG_NONNULL(1); + /** + * @brief Set padding between cells. + * + * @param obj The layout object. + * @param horizontal set the horizontal padding. + * @param vertical set the vertical padding. + * + * Default value is 0. + */ EAPI void elm_table_padding_set(Evas_Object *obj, Evas_Coord horizontal, Evas_Coord vertical) EINA_ARG_NONNULL(1); + /** + * @brief Get padding between cells. + * + * @param obj The layout object. + * @param horizontal set the horizontal padding. + * @param vertical set the vertical padding. + */ EAPI void elm_table_padding_get(const Evas_Object *obj, Evas_Coord *horizontal, Evas_Coord *vertical) EINA_ARG_NONNULL(1); + /** + * @brief Add a subobject on the table with the coordinates passed + * + * @param obj The table object + * @param subobj The subobject to be added to the table + * @param x Row number + * @param y Column number + * @param w rowspan + * @param h colspan + * + * @note All positioning inside the table is relative to rows and columns, so + * a value of 0 for x and y, means the top left cell of the table, and a + * value of 1 for w and h means @p subobj only takes that 1 cell. + */ EAPI void elm_table_pack(Evas_Object *obj, Evas_Object *subobj, int x, int y, int w, int h) EINA_ARG_NONNULL(1); + /** + * @brief Remove child from table. + * + * @param obj The table object + * @param subobj The subobject + */ EAPI void elm_table_unpack(Evas_Object *obj, Evas_Object *subobj) EINA_ARG_NONNULL(1); + /** + * @brief Faster way to remove all child objects from a table object. + * + * @param obj The table object + * @param clear If true, will delete children, else just remove from table. + */ EAPI void elm_table_clear(Evas_Object *obj, Eina_Bool clear) EINA_ARG_NONNULL(1); + /** + * @brief Set the packing location of an existing child of the table + * + * @param subobj The subobject to be modified in the table + * @param x Row number + * @param y Column number + * @param w rowspan + * @param h colspan + * + * Modifies the position of an object already in the table. + * + * @note All positioning inside the table is relative to rows and columns, so + * a value of 0 for x and y, means the top left cell of the table, and a + * value of 1 for w and h means @p subobj only takes that 1 cell. + */ EAPI void elm_table_pack_set(Evas_Object *subobj, int x, int y, int w, int h) EINA_ARG_NONNULL(1); + /** + * @brief Get the packing location of an existing child of the table + * + * @param subobj The subobject to be modified in the table + * @param x Row number + * @param y Column number + * @param w rowspan + * @param h colspan + * + * @see elm_table_pack_set() + */ EAPI void elm_table_pack_get(Evas_Object *subobj, int *x, int *y, int *w, int *h) EINA_ARG_NONNULL(1); + /** + * @} + */ /** * @defgroup Gengrid Gengrid (Generic grid) diff --git a/legacy/elementary/src/lib/elm_table.c b/legacy/elementary/src/lib/elm_table.c index 884de9b255..49b3c0f5ba 100644 --- a/legacy/elementary/src/lib/elm_table.c +++ b/legacy/elementary/src/lib/elm_table.c @@ -1,14 +1,6 @@ #include #include "elm_priv.h" -/** - * @defgroup Table Table - * - * Arranges widgets in a table where items can also span multiple - * columns or rows - even overlap (and then be raised or lowered - * accordingly to adjust stacking if they do overlap). - */ - typedef struct _Widget_Data Widget_Data; struct _Widget_Data @@ -125,14 +117,6 @@ _sub_del(void *data __UNUSED__, Evas_Object *obj, void *event_info __UNUSED__) _sizing_eval(obj); } -/** - * Add a new table to the parent - * - * @param parent The parent object - * @return The new object or NULL if it cannot be created - * - * @ingroup Table - */ EAPI Evas_Object * elm_table_add(Evas_Object *parent) { @@ -164,16 +148,6 @@ elm_table_add(Evas_Object *parent) return obj; } -/** - * Set the homogeneous layout in the table - * - * @param obj The layout object - * @param homogeneous A boolean to set (or no) layout homogeneous - * in the table - * (1 = homogeneous, 0 = no homogeneous) - * - * @ingroup Table - */ EAPI void elm_table_homogeneous_set(Evas_Object *obj, Eina_Bool homogeneous) { @@ -189,15 +163,6 @@ elm_table_homogenous_set(Evas_Object *obj, Eina_Bool homogenous) elm_table_homogeneous_set(obj, homogenous); } -/** - * Get the current table homogeneous mode. - * - * @param obj The table object - * @return a boolean to set (or no) layout homogeneous in the table - * (1 = homogeneous, 0 = no homogeneous) - * - * @ingroup Table - */ EAPI Eina_Bool elm_table_homogeneous_get(const Evas_Object *obj) { @@ -213,15 +178,6 @@ elm_table_homogenous_get(const Evas_Object *obj) return elm_table_homogeneous_get(obj); } -/** - * Set padding between cells. - * - * @param obj The layout object. - * @param horizontal set the horizontal padding. - * @param vertical set the vertical padding. - * - * @ingroup Table - */ EAPI void elm_table_padding_set(Evas_Object *obj, Evas_Coord horizontal, Evas_Coord vertical) { @@ -231,15 +187,6 @@ elm_table_padding_set(Evas_Object *obj, Evas_Coord horizontal, Evas_Coord vertic evas_object_table_padding_set(wd->tbl, horizontal, vertical); } -/** - * Get padding between cells. - * - * @param obj The layout object. - * @param horizontal set the horizontal padding. - * @param vertical set the vertical padding. - * - * @ingroup Table - */ EAPI void elm_table_padding_get(const Evas_Object *obj, Evas_Coord *horizontal, Evas_Coord *vertical) { @@ -249,18 +196,6 @@ elm_table_padding_get(const Evas_Object *obj, Evas_Coord *horizontal, Evas_Coord evas_object_table_padding_get(wd->tbl, horizontal, vertical); } -/** - * Add a subobject on the table with the coordinates passed - * - * @param obj The table object - * @param subobj The subobject to be added to the table - * @param x Coordinate to X axis - * @param y Coordinate to Y axis - * @param w Horizontal length - * @param h Vertical length - * - * @ingroup Table - */ EAPI void elm_table_pack(Evas_Object *obj, Evas_Object *subobj, int x, int y, int w, int h) { @@ -271,14 +206,6 @@ elm_table_pack(Evas_Object *obj, Evas_Object *subobj, int x, int y, int w, int h evas_object_table_pack(wd->tbl, subobj, x, y, w, h); } -/** - * Remove child from table. - * - * @param obj The table object - * @param subobj The subobject - * - * @ingroup Table - */ EAPI void elm_table_unpack(Evas_Object *obj, Evas_Object *subobj) { @@ -289,17 +216,6 @@ elm_table_unpack(Evas_Object *obj, Evas_Object *subobj) evas_object_table_unpack(wd->tbl, subobj); } -/** - * Set the packing location of an existing child of the table - * - * @param subobj The subobject to be modified in the table - * @param x Coordinate to X axis - * @param y Coordinate to Y axis - * @param w Horizontal length - * @param h Vertical length - * - * @ingroup Table - */ EAPI void elm_table_pack_set(Evas_Object *subobj, int x, int y, int w, int h) { @@ -310,17 +226,6 @@ elm_table_pack_set(Evas_Object *subobj, int x, int y, int w, int h) evas_object_table_pack(wd->tbl, subobj, x, y, w, h); } -/** - * Set the packing location of an existing child of the table - * - * @param subobj The subobject to be modified in the table - * @param x Coordinate to X axis - * @param y Coordinate to Y axis - * @param w Horizontal length - * @param h Vertical length - * - * @ingroup Table - */ EAPI void elm_table_pack_get(Evas_Object *subobj, int *x, int *y, int *w, int *h) { @@ -336,14 +241,6 @@ elm_table_pack_get(Evas_Object *subobj, int *x, int *y, int *w, int *h) if (h) *h = ih; } -/** - * Faster way to remove all child objects from a table object. - * - * @param obj The table object - * @param clear If true, it will delete just removed children - * - * @ingroup Table - */ EAPI void elm_table_clear(Evas_Object *obj, Eina_Bool clear) {