From e851249db79d8c3a88876ba7e7824c34ade1e640 Mon Sep 17 00:00:00 2001 From: Tom Hacohen Date: Fri, 31 Jul 2015 15:19:33 +0100 Subject: [PATCH] Evas table: Migrate docs to new Eolian format. --- src/lib/evas/canvas/evas_table.eo | 231 +++++++++++++----------------- 1 file changed, 96 insertions(+), 135 deletions(-) diff --git a/src/lib/evas/canvas/evas_table.eo b/src/lib/evas/canvas/evas_table.eo index d9f9142e3e..a4019705b1 100644 --- a/src/lib/evas/canvas/evas_table.eo +++ b/src/lib/evas/canvas/evas_table.eo @@ -1,12 +1,8 @@ /* XXX: Remove the Object_ part once the relevant Eolian bugs are fixed. */ enum Evas.Object_Table.Homogeneous_Mode { - /** - * How to pack items into cells in a table. - * @ingroup Evas_Object_Table - * - * @see evas_object_table_homogeneous_set() for an explanation of the function of - * each one. - */ + [[How to pack items into cells in a table. + + See @Evas.Table.homogeneous for an explanation of the function of each one.]] legacy: Evas_Object_Table_Homogeneous; none = 0, table = 1, @@ -19,67 +15,59 @@ class Evas.Table (Evas.Smart_Clipped) eo_prefix: evas_obj_table; methods { @property homogeneous { + [[Set how this table should layout children. + + Todo: consider aspect hint and respect it. + + @Evas.Object_Table.Homogeneous_Mode.none + If table does not use homogeneous mode then columns and rows will + be calculated based on hints of individual cells. This operation + mode is more flexible, but more complex and heavy to calculate as + well. Weight properties are handled as a boolean expand. Negative + alignment will be considered as 0.5. This is the default. + + Todo: @Evas.Object_Table.Homogeneous_Mode.none should balance weight. + + @Evas.Object_Table.Homogeneous_Mode.table + When homogeneous is relative to table the own table size is divided + equally among children, filling the whole table area. That is, if + table has $WIDTH and $COLUMNS, each cell will get _WIDTH / + COLUMNS_ pixels. If children have minimum size that is larger + than this amount (including padding), then it will overflow and be + aligned respecting the alignment hint, possible overlapping sibling + cells. Weight hint is used as a boolean, if greater than zero it + will make the child expand in that axis, taking as much space as + possible (bounded to maximum size hint). Negative alignment will be + considered as 0.5. + + @Evas.Object_Table.Homogeneous_Mode.item + When homogeneous is relative to item it means the greatest minimum + cell size will be used. That is, if no element is set to expand, + the table will have its contents to a minimum size, the bounding + box of all these children will be aligned relatively to the table + object using evas_object_table_align_get(). If the table area is + too small to hold this minimum bounding box, then the objects will + keep their size and the bounding box will overflow the box area, + still respecting the alignment. Weight hint is used as a + boolean, if greater than zero it will make that cell expand in that + axis, toggling the *expand mode*, which makes the table behave + much like @Evas.Object_Table.Homogeneous_Mode.table, except that the + bounding box will overflow and items will not overlap siblings. If + no minimum size is provided at all then the table will fallback to + expand mode as well.]] set { - /*@ - @brief Set how this table should layout children. - - @todo consider aspect hint and respect it. - - @par EVAS_OBJECT_TABLE_HOMOGENEOUS_NONE - If table does not use homogeneous mode then columns and rows will - be calculated based on hints of individual cells. This operation - mode is more flexible, but more complex and heavy to calculate as - well. @b Weight properties are handled as a boolean expand. Negative - alignment will be considered as 0.5. This is the default. - - @todo @c EVAS_OBJECT_TABLE_HOMOGENEOUS_NONE should balance weight. - - @par EVAS_OBJECT_TABLE_HOMOGENEOUS_TABLE - When homogeneous is relative to table the own table size is divided - equally among children, filling the whole table area. That is, if - table has @c WIDTH and @c COLUMNS, each cell will get WIDTH / - COLUMNS pixels. If children have minimum size that is larger - than this amount (including padding), then it will overflow and be - aligned respecting the alignment hint, possible overlapping sibling - cells. @b Weight hint is used as a boolean, if greater than zero it - will make the child expand in that axis, taking as much space as - possible (bounded to maximum size hint). Negative alignment will be - considered as 0.5. - - @par EVAS_OBJECT_TABLE_HOMOGENEOUS_ITEM - When homogeneous is relative to item it means the greatest minimum - cell size will be used. That is, if no element is set to expand, - the table will have its contents to a minimum size, the bounding - box of all these children will be aligned relatively to the table - object using evas_object_table_align_get(). If the table area is - too small to hold this minimum bounding box, then the objects will - keep their size and the bounding box will overflow the box area, - still respecting the alignment. @b Weight hint is used as a - boolean, if greater than zero it will make that cell expand in that - axis, toggling the expand mode, which makes the table behave - much like @b EVAS_OBJECT_TABLE_HOMOGENEOUS_TABLE, except that the - bounding box will overflow and items will not overlap siblings. If - no minimum size is provided at all then the table will fallback to - expand mode as well. */ } get { - /*@ - Get the current layout homogeneous mode. - - @see evas_object_table_homogeneous_set() */ } values { homogeneous: Evas.Object_Table.Homogeneous_Mode; } } @property align { + [[Control the alignment of the whole bounding box of contents.]] set { - /*@ - Set the alignment of the whole bounding box of contents. */ } get { - /*@ - Get alignment of the whole bounding box of contents. */ } values { horizontal: double; @@ -87,13 +75,10 @@ class Evas.Table (Evas.Smart_Clipped) } } @property padding { + [[Control the padding between cells.]] set { - /*@ - Set padding between cells. */ } get { - /*@ - Get padding between cells. */ } values { horizontal: Evas.Coord; @@ -101,35 +86,27 @@ class Evas.Table (Evas.Smart_Clipped) } } @property mirrored { - set { - /*@ - Sets the mirrored mode of the table. In mirrored mode the table items go - from right to left instead of left to right. That is, 1,1 is top right, not - top left. + [[Control the mirrored mode of the table. In mirrored mode, the table items go + from right to left instead of left to right. That is, 1,1 is top right, not + top left. - @since 1.1 */ + @since 1.1]] + set { } get { - /*@ - Gets the mirrored mode of the table. - - @return @c EINA_TRUE if it's a mirrored table, @c EINA_FALSE otherwise. - @since 1.1 - @see evas_object_table_mirrored_set() */ } values { - mirrored: bool; /*@ the mirrored mode to set */ + mirrored: bool; [[$true if mirrored, $false otherwise]] } } @property col_row_size { get { - /*@ - Get the number of columns and rows this table takes. + [[Get the number of columns and rows this table takes. - @note columns and rows are virtual entities, one can specify a table - with a single object that takes 4 columns and 5 rows. The only - difference for a single cell table is that paddings will be - accounted proportionally. */ + Note: columns and rows are virtual entities, one can specify a table + with a single object that takes 4 columns and 5 rows. The only + difference for a single cell table is that paddings will be + accounted proportionally.]] } values { cols: int; @@ -138,22 +115,20 @@ class Evas.Table (Evas.Smart_Clipped) } @property children { get { - /*@ - Get the list of children for the table. + [[Get the list of children for the table. - @note This is a duplicate of the list kept by the table internally. - It's up to the user to destroy it when it no longer needs it. - It's possible to remove objects from the table when walking this - list, but these removals won't be reflected on it. */ + Note: This is a duplicate of the list kept by the table internally. + It's up to the user to destroy it when it no longer needs it. + It's possible to remove objects from the table when walking this + list, but these removals won't be reflected on it.]] return: free(own(list *), eina_list_free) @warn_unused; } } @property child { get { - /*@ - Get the child of the table at the given coordinates + [[Get the child of the table at the given coordinates - @note This does not take into account col/row spanning*/ + Note: This does not take into account col/row spanning]] } keys { col: ushort; @@ -164,91 +139,77 @@ class Evas.Table (Evas.Smart_Clipped) } } clear { - /*@ - Faster way to remove all child objects from a table object. */ + [[Faster way to remove all child objects from a table object.]] params { - @in clear: bool; /*@ if true, it will delete just removed children. */ + @in clear: bool; [[If $true, it will delete just removed children.]] } } accessor_new @const { - /*@ - Get an accessor to get random access to the list of children for the table. + [[Get an accessor to get random access to the list of children for the table. - @note Do not remove or delete objects while walking the list. */ + Note: Do not remove or delete objects while walking the list.]] return: free(own(accessor *), eina_accessor_free) @warn_unused; } iterator_new @const { - /*@ - Get an iterator to walk the list of children for the table. + [[Get an iterator to walk the list of children for the table. - @note Do not remove or delete objects while walking the list. */ + Note: Do not remove or delete objects while walking the list.]] return: free(own(iterator *), eina_iterator_free) @warn_unused; } add_to { - /*@ - @brief Create a table that is child of a given element @a parent. - - @see evas_object_table_add() */ + [[Create a table that is child of a given element $parent.]] return: Evas.Object * @warn_unused; } pack_get @const { - /*@ - Get packing location of a child of table + [[Get packing location of a child of table - @return 1 on success, 0 on failure. - @since 1.1 */ - return: bool; + @since 1.1]] + return: bool; [[$true on success, $false on failure.]] params { - @in child: Evas.Object *; /*@ The child object to add. */ - @out col: ushort; /*@ pointer to store relative-horizontal position to place child. */ - @out row: ushort; /*@ pointer to store relative-vertical position to place child. */ - @out colspan: ushort; /*@ pointer to store how many relative-horizontal position to use for this child. */ - @out rowspan: ushort; /*@ pointer to store how many relative-vertical position to use for this child. */ + @in child: Evas.Object *; [[The child object to add.]] + @out col: ushort; [[pointer to store relative-horizontal position to place child.]] + @out row: ushort; [[pointer to store relative-vertical position to place child.]] + @out colspan: ushort; [[pointer to store how many relative-horizontal position to use for this child.]] + @out rowspan: ushort; [[pointer to store how many relative-vertical position to use for this child.]] } } pack { - /*@ - Add a new child to a table object or set its current packing. + [[Add a new child to a table object or set its current packing. - Note that columns and rows only guarantee 16bit unsigned values at best. - That means that col + colspan AND row + rowspan must fit inside 16bit - unsigned values cleanly. You will be warned once values exceed 15bit - storage, and attempting to use values not able to fit in 16bits will - result in failure. + Note that columns and rows only guarantee 16bit unsigned values at best. + That means that col + colspan AND row + rowspan must fit inside 16bit + unsigned values cleanly. You will be warned once values exceed 15bit + storage, and attempting to use values not able to fit in 16bits will + result in failure.]] - @return 1 on success, 0 on failure. */ - - return: bool; + return: bool; [[$true on success, $false on failure.]] params { - @in child: Evas.Object * @nonull; /*@ The child object to add. */ - @in col: ushort; /*@ relative-horizontal position to place child. */ - @in row: ushort; /*@ relative-vertical position to place child. */ - @in colspan: ushort; /*@ how many relative-horizontal position to use for this child. */ - @in rowspan: ushort; /*@ how many relative-vertical position to use for this child. */ + @in child: Evas.Object * @nonull; [[The child object to add.]] + @in col: ushort; [[relative-horizontal position to place child.]] + @in row: ushort; [[relative-vertical position to place child.]] + @in colspan: ushort; [[how many relative-horizontal position to use for this child.]] + @in rowspan: ushort; [[how many relative-vertical position to use for this child.]] } } unpack { - /*@ - Remove child from table. + [[Remove child from table. - @note removing a child will immediately call a walk over children in order - to recalculate numbers of columns and rows. If you plan to remove - all children, use evas_object_table_clear() instead. + Note: removing a child will immediately call a walk over children in order + to recalculate numbers of columns and rows. If you plan to remove + all children, use @Evas.Table.clear instead.]] - @return 1 on success, 0 on failure. */ - - return: bool; + return: bool; [[$true on success, $false on failure.]] params { @in child: Evas.Object * @nonull; } } } implements { - class.constructor; + class.constructor; Eo.Base.constructor; Evas.Object_Smart.add; Evas.Object_Smart.del;