diff --git a/legacy/elementary/src/lib/elm_layout.h b/legacy/elementary/src/lib/elm_layout.h index 0f367d4981..d4f8d6427f 100644 --- a/legacy/elementary/src/lib/elm_layout.h +++ b/legacy/elementary/src/lib/elm_layout.h @@ -13,139 +13,141 @@ * * A Layout is a direct realization of @ref elm-layout-class. * - * This is a container widget that takes a standard Edje design file and - * wraps it very thinly in a widget. + * This is a container widget that takes a standard Edje design file + * and wraps it very thinly in a widget. * - * An Edje design (theme) file has a very wide range of possibilities to - * describe the behavior of elements added to the Layout. Check out the Edje - * documentation and the EDC reference to get more information about what can - * be done with Edje. + * An Edje design (theme) file has a very wide range of possibilities + * to describe the behavior of elements forming a layout. Check out + * the Edje documentation and the EDC reference to get more + * information about what can be done with Edje. * * Just like @ref List, @ref Box, and other container widgets, any - * object added to the Layout will become its child, meaning that it will be - * deleted if the Layout is deleted, move if the Layout is moved, and so on. + * object added to the Layout will become its child, meaning that it + * will be deleted if the Layout is deleted, moved if the Layout is + * moved, and so on. * - * The Layout widget can contain as many Contents, Boxes or Tables as - * described in its theme file. For instance, objects can be added to - * different Tables by specifying the respective Table part names. The same - * is valid for Content and Box. + * The layout widget may contain as many parts/children as described + * in its theme file. Some of these children can have special types, + * such as content holder ones (swallow spots), boxes or tables. These + * are parts meant to contain others. For instance, objects can be + * added to different table parts by specifying the respective table + * part names. The same is valid for swallows and boxes. * - * The objects added as child of the Layout will behave as described in the - * part description where they were added. There are 3 possible types of - * parts where a child can be added: + * The objects added as children of a layout will behave as described + * in the part description where they were added. There are 3 possible + * types of parts where a child can be added: * - * @section secContent Content (SWALLOW part) + * @section secContent Content (@c SWALLOW part) * - * Only one object can be added to the @c SWALLOW part (but you still can - * have many @c SWALLOW parts and one object on each of them). Use the @c - * elm_object_content_set/get/unset functions to set, retrieve and unset - * objects as content of the @c SWALLOW. After being set to this part, the - * object size, position, visibility, clipping and other description - * properties will be totally controlled by the description of the given part - * (inside the Edje theme file). + * Only one object can be added to the @c SWALLOW part at a time (but + * you still can have many @c SWALLOW parts and one object on each of + * them). Use the @c elm_layout_content_set()/get/unset functions to + * set, retrieve and unset objects as content of the @c SWALLOW. After + * being set to this part, the object's size, position, visibility, + * clipping and other description properties will be totally + * controlled by the description of the given part (inside the Edje + * theme file). * - * One can use @c evas_object_size_hint_* functions on the child to have some - * kind of control over its behavior, but the resulting behavior will still - * depend heavily on the @c SWALLOW part description. + * One can use @c evas_object_size_hint_* functions on the child to + * have some kind of control over its behavior, but the resulting + * behavior will still depend heavily on the @c SWALLOW part's + * description. * - * The Edje theme also can change the part description, based on signals or - * scripts running inside the theme. This change can also be animated. All of - * this will affect the child object set as content accordingly. The object - * size will be changed if the part size is changed, it will animate move if - * the part is moving, and so on. + * The Edje theme also can change the part description, based on + * signals or scripts running inside the theme. This change can also + * be animated. All of this will affect the child object set as + * content accordingly. The object's size will be changed if the part + * size is changed, it will animate moving accordingly if the part is + * moving, and so on. * - * The following picture demonstrates a Layout widget with a child object - * added to its @c SWALLOW: + * The following picture demonstrates a layout widget with a child + * object added to its @c SWALLOW: * * @image html layout_swallow.png * @image latex layout_swallow.eps width=\textwidth * - * @section secBox Box (BOX part) + * @section secBox Box (@c BOX part) * - * An Edje @c BOX part is very similar to the Elementary @ref Box widget. It - * allows one to add objects to the box and have them distributed along its - * area, accordingly to the specified @a layout property (now by @a layout we - * mean the chosen layouting design of the Box, not the Layout widget - * itself). + * An Edje @c BOX part is very similar to the Elementary @ref Box + * widget. It allows one to add objects to the box and have them + * distributed along its area, accordingly to the specified @c layout + * property (now by @c layout we mean the chosen layouting design of + * the Box, not the layout widget itself). * - * A similar effect for having a box with its position, size and other things - * controlled by the Layout theme would be to create an Elementary @ref Box - * widget and add it as a Content in the @c SWALLOW part. + * A similar effect for having a box with its position, size and other + * things controlled by the layout theme would be to create an + * Elementary @ref Box widget and add it as content in a @c SWALLOW part. * - * The main difference of using the Layout Box is that its behavior, the box - * properties like layouting format, padding, align, etc. will be all - * controlled by the theme. This means, for example, that a signal could be - * sent to the Layout theme (with elm_object_signal_emit()) and the theme - * handled the signal by changing the box padding, or align, or both. Using - * the Elementary @ref Box widget is not necessarily harder or easier, it - * just depends on the circumstances and requirements. + * The main difference to that, by using the layout box instead, is + * that its behavior, like layouting format, padding, align, etc., + * will all be controlled by the theme. This means, for + * example, that a signal could be sent to the layout's theme (with + * elm_layout_signal_emit()) and the signal be handled by changing the + * box's padding, or alignment, or both. Using the Elementary @ref Box + * widget is not necessarily harder or easier, it just depends on the + * circumstances and requirements. * - * The Layout Box can be used through the @c elm_layout_box_* set of + * The layout box can be used through the @c elm_layout_box_* set of * functions. * - * The following picture demonstrates a Layout widget with many child objects - * added to its @c BOX part: + * The following picture demonstrates a Layout widget with many child + * objects added to its @c BOX part: * * @image html layout_box.png * @image latex layout_box.eps width=\textwidth * - * @section secTable Table (TABLE part) + * @section secTable Table (@c TABLE part) * - * Just like the @ref secBox, the Layout Table is very similar to the - * Elementary @ref Table widget. It allows one to add objects to the Table - * specifying the row and column where the object should be added, and any - * column or row span if necessary. + * Just like the @ref secBox, the layout table is very similar to the + * Elementary @ref Table widget. It allows one to add objects to the + * table by specifying the row and column where the object should be + * added, and any column or row span, if necessary. * - * Again, we could have this design by adding a @ref Table widget to the @c - * SWALLOW part using elm_object_part_content_set(). The same difference happens - * here when choosing to use the Layout Table (a @c TABLE part) instead of - * the @ref Table plus @c SWALLOW part. It's just a matter of convenience. + * Again, we could have this design by adding a @ref table widget to a + * @c SWALLOW part, using elm_layout_content_set(). The same + * difference happens here when choosing to use the layout table (a + * @c TABLE part) instead of the @ref table in a @c SWALLOW part. It's + * just a matter of convenience. * - * The Layout Table can be used through the @c elm_layout_table_* set of + * The layout table can be used through the @c elm_layout_table_* set of * functions. * - * The following picture demonstrates a Layout widget with many child objects - * added to its @c TABLE part: + * The following picture demonstrates a layout widget with many child + * objects added to its @c TABLE part: * * @image html layout_table.png * @image latex layout_table.eps width=\textwidth * * @section secPredef Predefined Layouts * - * Another interesting thing about the Layout widget is that it offers some - * predefined themes that come with the default Elementary theme. These - * themes can be set by the call elm_layout_theme_set(), and provide some - * basic functionality depending on the theme used. + * Another interesting thing about the layout widget is that it offers + * some predefined themes that come with the default Elementary + * theme. These themes can be set by the call elm_layout_theme_set(), + * and provide some basic functionality depending on the theme used. * - * Most of them already send some signals, some already provide a toolbar or - * back and next buttons. + * Most of them already send some signals, some already provide a + * toolbar or back and next buttons. * - * These are available predefined theme layouts. All of them have class = @c - * layout, group = @c application, and style = one of the following options: + * These are the available predefined theme layouts. All of them have + * class = @c layout, group = @c application, and style = one of the + * following options: * - * @li @c toolbar-content - application with toolbar and main content area - * @li @c toolbar-content-back - application with toolbar and main content - * area with a back button and title area - * @li @c toolbar-content-back-next - application with toolbar and main - * content area with a back and next buttons and title area - * @li @c content-back - application with a main content area with a back - * button and title area - * @li @c content-back-next - application with a main content area with a - * back and next buttons and title area - * @li @c toolbar-vbox - application with toolbar and main content area as a - * vertical box - * @li @c toolbar-table - application with toolbar and main content area as a - * table - * - * Supported elm_object common APIs. - * @li @ref elm_object_signal_emit - * @li @ref elm_object_signal_callback_add - * @li @ref elm_object_signal_callback_del - * @li @ref elm_object_part_text_set - * @li @ref elm_object_part_text_get - * @li @ref elm_object_part_content_set - * @li @ref elm_object_part_content_get - * @li @ref elm_object_part_content_unset + * @li @c toolbar-content - for applications with a toolbar and main + * content area + * @li @c toolbar-content-back - for applications with a toolbar and + * main content (with a back button) + * and title areas + * @li @c toolbar-content-back-next - for applications with a toolbar + * and main content (with back and + * next buttons) and title areas + * @li @c content-back - for application with main content (with a + * back button) and title areas + * @li @c content-back-next - for applications with main content (with + * back and next buttons) and title areas + * @li @c toolbar-vbox - for applications with a toolbar and main + * content area as a vertical box + * @li @c toolbar-table - for applications with a toolbar and main + * content area as a table * * @section layout-signals Emitted signals * @@ -284,7 +286,7 @@ EAPI void elm_layout_signal_callback_add(Evas_Object *obj, const char *emission, * This function removes the @b last callback attached to a signal * emitted by the undelying Edje object of @a obj, with parameters @a * emission, @a source and @c func matching exactly those passed to a - * previous call to elm_object_signal_callback_add(). The data pointer + * previous call to elm_layout_signal_callback_add(). The data pointer * that was passed to this call will be returned. * * @ingroup Layout @@ -391,7 +393,7 @@ EAPI Eina_Bool elm_layout_box_insert_at(Evas_Object *obj, con * * The object will be removed from the box part and its lifetime will * not be handled by the layout anymore. This is equivalent to - * elm_object_part_content_unset() for box. + * elm_layout_content_unset() for box. * * @see elm_layout_box_append() * @see elm_layout_box_remove_all() @@ -467,7 +469,7 @@ EAPI Eina_Bool elm_layout_table_pack(Evas_Object *obj, const * * The object will be unpacked from the table part and its lifetime * will not be handled by the layout anymore. This is equivalent to - * elm_object_part_content_unset() for table. + * elm_layout_content_unset() for table. * * @see elm_layout_table_pack() * @see elm_layout_table_clear() @@ -507,7 +509,7 @@ EAPI Eina_Bool elm_layout_table_clear(Evas_Object *obj, const * * This returns the edje object. It is not expected to be used to then * swallow objects via edje_object_part_swallow() for example. Use - * elm_object_part_content_set() instead so child object handling and sizing is + * elm_layout_content_set() instead so child object handling and sizing is * done properly. * * @note This function should only be used if you really need to call some @@ -515,10 +517,10 @@ EAPI Eina_Bool elm_layout_table_clear(Evas_Object *obj, const * text, emitting signals, hooking callbacks to signals, etc.) can be done * with proper elementary functions. * - * @see elm_object_signal_callback_add() - * @see elm_object_signal_emit() - * @see elm_object_part_text_set() - * @see elm_object_part_content_set() + * @see elm_layout_signal_callback_add() + * @see elm_layout_signal_emit() + * @see elm_layout_text_set() + * @see elm_layout_content_set() * @see elm_layout_box_append() * @see elm_layout_table_pack() * @see elm_layout_data_get() @@ -719,17 +721,20 @@ EAPI Eina_Bool elm_layout_part_cursor_engine_only_get(const E * * 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_object_part_content_unset() function. + * elm_layout_content_unset() function. * - * @note In an Edje theme, the part used as a content container is called @c - * SWALLOW. This is why the parameter name is called @p swallow, but it is + * @note In an Edje theme, the part used as a content container is called + * @c SWALLOW. This is why the parameter name is called @p swallow, but it is * expected to be a part name just like the second parameter of * elm_layout_box_append(). * * @see elm_layout_box_append() - * @see elm_object_part_content_get() - * @see elm_object_part_content_unset() + * @see elm_layout_content_get() + * @see elm_layout_content_unset() + * * @see @ref secBox + * + * @ingroup Layout */ EAPI Eina_Bool elm_layout_content_set(Evas_Object *obj, const char *swallow, Evas_Object *content); @@ -740,6 +745,8 @@ EAPI Eina_Bool elm_layout_content_set(Evas_Object *obj, const * @param swallow The SWALLOW part to get its content * * @return The swallowed object or NULL if none or an error occurred + * + * @ingroup Layout */ EAPI Evas_Object *elm_layout_content_get(const Evas_Object *obj, const char *swallow); @@ -751,6 +758,8 @@ EAPI Evas_Object *elm_layout_content_get(const Evas_Object *obj, * @return The content that was being used * * Unparent and return the content object which was set for this part. + * + * @ingroup Layout */ EAPI Evas_Object *elm_layout_content_unset(Evas_Object *obj, const char *swallow);