Gustavo Lima Chaves
parent
b684a2ccf7
commit
62c915ba06
|
|
@ -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 <b>all be controlled by the theme</b>. 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);
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue