src/lib/elm_layout.h

   1 /**
   2  * @defgroup Layout Layout
   3  *
   4  * @image html img/widget/layout/preview-00.png
   5  * @image latex img/widget/layout/preview-00.eps width=\textwidth
   6  *
   7  * @image html img/layout-predefined.png
   8  * @image latex img/layout-predefined.eps width=\textwidth
   9  *
  10  * This is a container widget that takes a standard Edje design file and
  11  * wraps it very thinly in a widget.
  12  *
  13  * An Edje design (theme) file has a very wide range of possibilities to
  14  * describe the behavior of elements added to the Layout. Check out the Edje
  15  * documentation and the EDC reference to get more information about what can
  16  * be done with Edje.
  17  *
  18  * Just like @ref List, @ref Box, and other container widgets, any
  19  * object added to the Layout will become its child, meaning that it will be
  20  * deleted if the Layout is deleted, move if the Layout is moved, and so on.
  21  *
  22  * The Layout widget can contain as many Contents, Boxes or Tables as
  23  * described in its theme file. For instance, objects can be added to
  24  * different Tables by specifying the respective Table part names. The same
  25  * is valid for Content and Box.
  26  *
  27  * The objects added as child of the Layout will behave as described in the
  28  * part description where they were added. There are 3 possible types of
  29  * parts where a child can be added:
  30  *
  31  * @section secContent Content (SWALLOW part)
  32  *
  33  * Only one object can be added to the @c SWALLOW part (but you still can
  34  * have many @c SWALLOW parts and one object on each of them). Use the @c
  35  * elm_object_content_set/get/unset functions to set, retrieve and unset
  36  * objects as content of the @c SWALLOW. After being set to this part, the
  37  * object size, position, visibility, clipping and other description
  38  * properties will be totally controlled by the description of the given part
  39  * (inside the Edje theme file).
  40  *
  41  * One can use @c evas_object_size_hint_* functions on the child to have some
  42  * kind of control over its behavior, but the resulting behavior will still
  43  * depend heavily on the @c SWALLOW part description.
  44  *
  45  * The Edje theme also can change the part description, based on signals or
  46  * scripts running inside the theme. This change can also be animated. All of
  47  * this will affect the child object set as content accordingly. The object
  48  * size will be changed if the part size is changed, it will animate move if
  49  * the part is moving, and so on.
  50  *
  51  * The following picture demonstrates a Layout widget with a child object
  52  * added to its @c SWALLOW:
  53  *
  54  * @image html layout_swallow.png
  55  * @image latex layout_swallow.eps width=\textwidth
  56  *
  57  * @section secBox Box (BOX part)
  58  *
  59  * An Edje @c BOX part is very similar to the Elementary @ref Box widget. It
  60  * allows one to add objects to the box and have them distributed along its
  61  * area, accordingly to the specified @a layout property (now by @a layout we
  62  * mean the chosen layouting design of the Box, not the Layout widget
  63  * itself).
  64  *
  65  * A similar effect for having a box with its position, size and other things
  66  * controlled by the Layout theme would be to create an Elementary @ref Box
  67  * widget and add it as a Content in the @c SWALLOW part.
  68  *
  69  * The main difference of using the Layout Box is that its behavior, the box
  70  * properties like layouting format, padding, align, etc. will be all
  71  * controlled by the theme. This means, for example, that a signal could be
  72  * sent to the Layout theme (with elm_object_signal_emit()) and the theme
  73  * handled the signal by changing the box padding, or align, or both. Using
  74  * the Elementary @ref Box widget is not necessarily harder or easier, it
  75  * just depends on the circunstances and requirements.
  76  *
  77  * The Layout Box can be used through the @c elm_layout_box_* set of
  78  * functions.
  79  *
  80  * The following picture demonstrates a Layout widget with many child objects
  81  * added to its @c BOX part:
  82  *
  83  * @image html layout_box.png
  84  * @image latex layout_box.eps width=\textwidth
  85  *
  86  * @section secTable Table (TABLE part)
  87  *
  88  * Just like the @ref secBox, the Layout Table is very similar to the
  89  * Elementary @ref Table widget. It allows one to add objects to the Table
  90  * specifying the row and column where the object should be added, and any
  91  * column or row span if necessary.
  92  *
  93  * Again, we could have this design by adding a @ref Table widget to the @c
  94  * SWALLOW part using elm_object_part_content_set(). The same difference happens
  95  * here when choosing to use the Layout Table (a @c TABLE part) instead of
  96  * the @ref Table plus @c SWALLOW part. It's just a matter of convenience.
  97  *
  98  * The Layout Table can be used through the @c elm_layout_table_* set of
  99  * functions.
 100  *
 101  * The following picture demonstrates a Layout widget with many child objects
 102  * added to its @c TABLE part:
 103  *
 104  * @image html layout_table.png
 105  * @image latex layout_table.eps width=\textwidth
 106  *
 107  * @section secPredef Predefined Layouts
 108  *
 109  * Another interesting thing about the Layout widget is that it offers some
 110  * predefined themes that come with the default Elementary theme. These
 111  * themes can be set by the call elm_layout_theme_set(), and provide some
 112  * basic functionality depending on the theme used.
 113  *
 114  * Most of them already send some signals, some already provide a toolbar or
 115  * back and next buttons.
 116  *
 117  * These are available predefined theme layouts. All of them have class = @c
 118  * layout, group = @c application, and style = one of the following options:
 119  *
 120  * @li @c toolbar-content - application with toolbar and main content area
 121  * @li @c toolbar-content-back - application with toolbar and main content
 122  * area with a back button and title area
 123  * @li @c toolbar-content-back-next - application with toolbar and main
 124  * content area with a back and next buttons and title area
 125  * @li @c content-back - application with a main content area with a back
 126  * button and title area
 127  * @li @c content-back-next - application with a main content area with a
 128  * back and next buttons and title area
 129  * @li @c toolbar-vbox - application with toolbar and main content area as a
 130  * vertical box
 131  * @li @c toolbar-table - application with toolbar and main content area as a
 132  * table
 133  *
 134  * @section secExamples Examples
 135  *
 136  * Some examples of the Layout widget can be found here:
 137  * @li @ref layout_example_01
 138  * @li @ref layout_example_02
 139  * @li @ref layout_example_03
 140  * @li @ref layout_example_edc
 141  *
 142  */
 143
 144 /**
 145  * Add a new layout to the parent
 146  *
 147  * @param parent The parent object
 148  * @return The new object or NULL if it cannot be created
 149  *
 150  * @see elm_layout_file_set()
 151  * @see elm_layout_theme_set()
 152  *
 153  * @ingroup Layout
 154  */
 155 EAPI Evas_Object *
 156                                   elm_layout_add(Evas_Object *parent)
 157 EINA_ARG_NONNULL(1);
 158
 159 /**
 160  * Set the file that will be used as layout
 161  *
 162  * @param obj The layout object
 163  * @param file The path to file (edj) that will be used as layout
 164  * @param group The group that the layout belongs in edje file
 165  *
 166  * @return (1 = success, 0 = error)
 167  *
 168  * @ingroup Layout
 169  */
 170 EAPI Eina_Bool                    elm_layout_file_set(Evas_Object *obj, const char *file, const char *group) EINA_ARG_NONNULL(1);
 171
 172 /**
 173  * Set the edje group from the elementary theme that will be used as layout
 174  *
 175  * @param obj The layout object
 176  * @param clas the clas of the group
 177  * @param group the group
 178  * @param style the style to used
 179  *
 180  * @return (1 = success, 0 = error)
 181  *
 182  * @ingroup Layout
 183  */
 184 EAPI Eina_Bool                    elm_layout_theme_set(Evas_Object *obj, const char *clas, const char *group, const char *style) EINA_ARG_NONNULL(1);
 185
 186 /**
 187  * Set the layout content.
 188  *
 189  * @param obj The layout object
 190  * @param swallow The swallow part name in the edje file
 191  * @param content The child that will be added in this layout object
 192  *
 193  * Once the content object is set, a previously set one will be deleted.
 194  * If you want to keep that old content object, use the
 195  * elm_object_part_content_unset() function.
 196  *
 197  * @note In an Edje theme, the part used as a content container is called @c
 198  * SWALLOW. This is why the parameter name is called @p swallow, but it is
 199  * expected to be a part name just like the second parameter of
 200  * elm_layout_box_append().
 201  *
 202  * @see elm_layout_box_append()
 203  * @see elm_object_part_content_get()
 204  * @see elm_object_part_content_unset()
 205  * @see @ref secBox
 206  * @deprecated use elm_object_part_content_set() instead
 207  *
 208  * @ingroup Layout
 209  */
 210 EINA_DEPRECATED EAPI void         elm_layout_content_set(Evas_Object *obj, const char *swallow, Evas_Object *content) EINA_ARG_NONNULL(1);
 211
 212 /**
 213  * Get the child object in the given content part.
 214  *
 215  * @param obj The layout object
 216  * @param swallow The SWALLOW part to get its content
 217  *
 218  * @return The swallowed object or NULL if none or an error occurred
 219  *
 220  * @deprecated use elm_object_part_content_get() instead
 221  *
 222  * @ingroup Layout
 223  */
 224 EINA_DEPRECATED EAPI Evas_Object *elm_layout_content_get(const Evas_Object *obj, const char *swallow) EINA_ARG_NONNULL(1);
 225
 226 /**
 227  * Unset the layout content.
 228  *
 229  * @param obj The layout object
 230  * @param swallow The swallow part name in the edje file
 231  * @return The content that was being used
 232  *
 233  * Unparent and return the content object which was set for this part.
 234  *
 235  * @deprecated use elm_object_part_content_unset() instead
 236  *
 237  * @ingroup Layout
 238  */
 239 EINA_DEPRECATED EAPI Evas_Object *elm_layout_content_unset(Evas_Object *obj, const char *swallow) EINA_ARG_NONNULL(1);
 240
 241 /**
 242  * Set the text of the given part
 243  *
 244  * @param obj The layout object
 245  * @param part The TEXT part where to set the text
 246  * @param text The text to set
 247  *
 248  * @ingroup Layout
 249  * @deprecated use elm_object_part_text_set() instead.
 250  */
 251 EINA_DEPRECATED EAPI void         elm_layout_text_set(Evas_Object *obj, const char *part, const char *text) EINA_ARG_NONNULL(1);
 252
 253 /**
 254  * Get the text set in the given part
 255  *
 256  * @param obj The layout object
 257  * @param part The TEXT part to retrieve the text off
 258  *
 259  * @return The text set in @p part
 260  *
 261  * @ingroup Layout
 262  * @deprecated use elm_object_part_text_get() instead.
 263  */
 264 EINA_DEPRECATED EAPI const char  *elm_layout_text_get(const Evas_Object *obj, const char *part) EINA_ARG_NONNULL(1);
 265
 266 /**
 267  * Append child to layout box part.
 268  *
 269  * @param obj the layout object
 270  * @param part the box part to which the object will be appended.
 271  * @param child the child object to append to box.
 272  *
 273  * Once the object is appended, it will become child of the layout. Its
 274  * lifetime will be bound to the layout, whenever the layout dies the child
 275  * will be deleted automatically. One should use elm_layout_box_remove() to
 276  * make this layout forget about the object.
 277  *
 278  * @see elm_layout_box_prepend()
 279  * @see elm_layout_box_insert_before()
 280  * @see elm_layout_box_insert_at()
 281  * @see elm_layout_box_remove()
 282  *
 283  * @ingroup Layout
 284  */
 285 EAPI void                         elm_layout_box_append(Evas_Object *obj, const char *part, Evas_Object *child) EINA_ARG_NONNULL(1);
 286
 287 /**
 288  * Prepend child to layout box part.
 289  *
 290  * @param obj the layout object
 291  * @param part the box part to prepend.
 292  * @param child the child object to prepend to box.
 293  *
 294  * Once the object is prepended, it will become child of the layout. Its
 295  * lifetime will be bound to the layout, whenever the layout dies the child
 296  * will be deleted automatically. One should use elm_layout_box_remove() to
 297  * make this layout forget about the object.
 298  *
 299  * @see elm_layout_box_append()
 300  * @see elm_layout_box_insert_before()
 301  * @see elm_layout_box_insert_at()
 302  * @see elm_layout_box_remove()
 303  *
 304  * @ingroup Layout
 305  */
 306 EAPI void                         elm_layout_box_prepend(Evas_Object *obj, const char *part, Evas_Object *child) EINA_ARG_NONNULL(1);
 307
 308 /**
 309  * Insert child to layout box part before a reference object.
 310  *
 311  * @param obj the layout object
 312  * @param part the box part to insert.
 313  * @param child the child object to insert into box.
 314  * @param reference another reference object to insert before in box.
 315  *
 316  * Once the object is inserted, it will become child of the layout. Its
 317  * lifetime will be bound to the layout, whenever the layout dies the child
 318  * will be deleted automatically. One should use elm_layout_box_remove() to
 319  * make this layout forget about the object.
 320  *
 321  * @see elm_layout_box_append()
 322  * @see elm_layout_box_prepend()
 323  * @see elm_layout_box_insert_before()
 324  * @see elm_layout_box_remove()
 325  *
 326  * @ingroup Layout
 327  */
 328 EAPI void                         elm_layout_box_insert_before(Evas_Object *obj, const char *part, Evas_Object *child, const Evas_Object *reference) EINA_ARG_NONNULL(1);
 329
 330 /**
 331  * Insert child to layout box part at a given position.
 332  *
 333  * @param obj the layout object
 334  * @param part the box part to insert.
 335  * @param child the child object to insert into box.
 336  * @param pos the numeric position >=0 to insert the child.
 337  *
 338  * Once the object is inserted, it will become child of the layout. Its
 339  * lifetime will be bound to the layout, whenever the layout dies the child
 340  * will be deleted automatically. One should use elm_layout_box_remove() to
 341  * make this layout forget about the object.
 342  *
 343  * @see elm_layout_box_append()
 344  * @see elm_layout_box_prepend()
 345  * @see elm_layout_box_insert_before()
 346  * @see elm_layout_box_remove()
 347  *
 348  * @ingroup Layout
 349  */
 350 EAPI void                         elm_layout_box_insert_at(Evas_Object *obj, const char *part, Evas_Object *child, unsigned int pos) EINA_ARG_NONNULL(1);
 351
 352 /**
 353  * Remove a child of the given part box.
 354  *
 355  * @param obj The layout object
 356  * @param part The box part name to remove child.
 357  * @param child The object to remove from box.
 358  * @return The object that was being used, or NULL if not found.
 359  *
 360  * The object will be removed from the box part and its lifetime will
 361  * not be handled by the layout anymore. This is equivalent to
 362  * elm_object_part_content_unset() for box.
 363  *
 364  * @see elm_layout_box_append()
 365  * @see elm_layout_box_remove_all()
 366  *
 367  * @ingroup Layout
 368  */
 369 EAPI Evas_Object                 *elm_layout_box_remove(Evas_Object *obj, const char *part, Evas_Object *child) EINA_ARG_NONNULL(1, 2, 3);
 370
 371 /**
 372  * Remove all children of the given part box.
 373  *
 374  * @param obj The layout object
 375  * @param part The box part name to remove child.
 376  * @param clear If EINA_TRUE, then all objects will be deleted as
 377  *        well, otherwise they will just be removed and will be
 378  *        dangling on the canvas.
 379  *
 380  * The objects will be removed from the box part and their lifetime will
 381  * not be handled by the layout anymore. This is equivalent to
 382  * elm_layout_box_remove() for all box children.
 383  *
 384  * @see elm_layout_box_append()
 385  * @see elm_layout_box_remove()
 386  *
 387  * @ingroup Layout
 388  */
 389 EAPI void                         elm_layout_box_remove_all(Evas_Object *obj, const char *part, Eina_Bool clear) EINA_ARG_NONNULL(1, 2);
 390
 391 /**
 392  * Insert child to layout table part.
 393  *
 394  * @param obj the layout object
 395  * @param part the box part to pack child.
 396  * @param child_obj the child object to pack into table.
 397  * @param col the column to which the child should be added. (>= 0)
 398  * @param row the row to which the child should be added. (>= 0)
 399  * @param colspan how many columns should be used to store this object. (>=
 400  *        1)
 401  * @param rowspan how many rows should be used to store this object. (>= 1)
 402  *
 403  * Once the object is inserted, it will become child of the table. Its
 404  * lifetime will be bound to the layout, and whenever the layout dies the
 405  * child will be deleted automatically. One should use
 406  * elm_layout_table_remove() to make this layout forget about the object.
 407  *
 408  * If @p colspan or @p rowspan are bigger than 1, that object will occupy
 409  * more space than a single cell. For instance, the following code:
 410  * @code
 411  * elm_layout_table_pack(layout, "table_part", child, 0, 1, 3, 1);
 412  * @endcode
 413  *
 414  * Would result in an object being added like the following picture:
 415  *
 416  * @image html layout_colspan.png
 417  * @image latex layout_colspan.eps width=\textwidth
 418  *
 419  * @see elm_layout_table_unpack()
 420  * @see elm_layout_table_clear()
 421  *
 422  * @ingroup Layout
 423  */
 424 EAPI void                         elm_layout_table_pack(Evas_Object *obj, const char *part, Evas_Object *child_obj, unsigned short col, unsigned short row, unsigned short colspan, unsigned short rowspan) EINA_ARG_NONNULL(1);
 425
 426 /**
 427  * Unpack (remove) a child of the given part table.
 428  *
 429  * @param obj The layout object
 430  * @param part The table part name to remove child.
 431  * @param child_obj The object to remove from table.
 432  * @return The object that was being used, or NULL if not found.
 433  *
 434  * The object will be unpacked from the table part and its lifetime
 435  * will not be handled by the layout anymore. This is equivalent to
 436  * elm_object_part_content_unset() for table.
 437  *
 438  * @see elm_layout_table_pack()
 439  * @see elm_layout_table_clear()
 440  *
 441  * @ingroup Layout
 442  */
 443 EAPI Evas_Object                 *elm_layout_table_unpack(Evas_Object *obj, const char *part, Evas_Object *child_obj) EINA_ARG_NONNULL(1, 2, 3);
 444
 445 /**
 446  * Remove all the child objects of the given part table.
 447  *
 448  * @param obj The layout object
 449  * @param part The table part name to remove child.
 450  * @param clear If EINA_TRUE, then all objects will be deleted as
 451  *        well, otherwise they will just be removed and will be
 452  *        dangling on the canvas.
 453  *
 454  * The objects will be removed from the table part and their lifetime will
 455  * not be handled by the layout anymore. This is equivalent to
 456  * elm_layout_table_unpack() for all table children.
 457  *
 458  * @see elm_layout_table_pack()
 459  * @see elm_layout_table_unpack()
 460  *
 461  * @ingroup Layout
 462  */
 463 EAPI void                         elm_layout_table_clear(Evas_Object *obj, const char *part, Eina_Bool clear) EINA_ARG_NONNULL(1, 2);
 464
 465 /**
 466  * Get the edje layout
 467  *
 468  * @param obj The layout object
 469  *
 470  * @return A Evas_Object with the edje layout settings loaded
 471  * with function elm_layout_file_set
 472  *
 473  * This returns the edje object. It is not expected to be used to then
 474  * swallow objects via edje_object_part_swallow() for example. Use
 475  * elm_object_part_content_set() instead so child object handling and sizing is
 476  * done properly.
 477  *
 478  * @note This function should only be used if you really need to call some
 479  * low level Edje function on this edje object. All the common stuff (setting
 480  * text, emitting signals, hooking callbacks to signals, etc.) can be done
 481  * with proper elementary functions.
 482  *
 483  * @see elm_object_signal_callback_add()
 484  * @see elm_object_signal_emit()
 485  * @see elm_object_part_text_set()
 486  * @see elm_object_part_content_set()
 487  * @see elm_layout_box_append()
 488  * @see elm_layout_table_pack()
 489  * @see elm_layout_data_get()
 490  *
 491  * @ingroup Layout
 492  */
 493 EAPI Evas_Object                 *elm_layout_edje_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
 494
 495 /**
 496  * Get the edje data from the given layout
 497  *
 498  * @param obj The layout object
 499  * @param key The data key
 500  *
 501  * @return The edje data string
 502  *
 503  * This function fetches data specified inside the edje theme of this layout.
 504  * This function return NULL if data is not found.
 505  *
 506  * In EDC this comes from a data block within the group block that @p
 507  * obj was loaded from. E.g.
 508  *
 509  * @code
 510  * collections {
 511  *   group {
 512  *     name: "a_group";
 513  *     data {
 514  *       item: "key1" "value1";
 515  *       item: "key2" "value2";
 516  *     }
 517  *   }
 518  * }
 519  * @endcode
 520  *
 521  * @ingroup Layout
 522  */
 523 EAPI const char                  *elm_layout_data_get(const Evas_Object *obj, const char *key) EINA_ARG_NONNULL(1, 2);
 524
 525 /**
 526  * Eval sizing
 527  *
 528  * @param obj The layout object
 529  *
 530  * Manually forces a sizing re-evaluation. This is useful when the minimum
 531  * size required by the edje theme of this layout has changed. The change on
 532  * the minimum size required by the edje theme is not immediately reported to
 533  * the elementary layout, so one needs to call this function in order to tell
 534  * the widget (layout) that it needs to reevaluate its own size.
 535  *
 536  * The minimum size of the theme is calculated based on minimum size of
 537  * parts, the size of elements inside containers like box and table, etc. All
 538  * of this can change due to state changes, and that's when this function
 539  * should be called.
 540  *
 541  * Also note that a standard signal of "size,eval" "elm" emitted from the
 542  * edje object will cause this to happen too.
 543  *
 544  * @ingroup Layout
 545  */
 546 EAPI void                         elm_layout_sizing_eval(Evas_Object *obj) EINA_ARG_NONNULL(1);
 547
 548 /**
 549  * Sets a specific cursor for an edje part.
 550  *
 551  * @param obj The layout object.
 552  * @param part_name a part from loaded edje group.
 553  * @param cursor cursor name to use, see Elementary_Cursor.h
 554  *
 555  * @return EINA_TRUE on success or EINA_FALSE on failure, that may be
 556  *         part not exists or it has "mouse_events: 0".
 557  *
 558  * @ingroup Layout
 559  */
 560 EAPI Eina_Bool                    elm_layout_part_cursor_set(Evas_Object *obj, const char *part_name, const char *cursor) EINA_ARG_NONNULL(1, 2);
 561
 562 /**
 563  * Get the cursor to be shown when mouse is over an edje part
 564  *
 565  * @param obj The layout object.
 566  * @param part_name a part from loaded edje group.
 567  * @return the cursor name.
 568  *
 569  * @ingroup Layout
 570  */
 571 EAPI const char                  *elm_layout_part_cursor_get(const Evas_Object *obj, const char *part_name) EINA_ARG_NONNULL(1, 2);
 572
 573 /**
 574  * Unsets a cursor previously set with elm_layout_part_cursor_set().
 575  *
 576  * @param obj The layout object.
 577  * @param part_name a part from loaded edje group, that had a cursor set
 578  *        with elm_layout_part_cursor_set().
 579  *
 580  * @ingroup Layout
 581  */
 582 EAPI void                         elm_layout_part_cursor_unset(Evas_Object *obj, const char *part_name) EINA_ARG_NONNULL(1, 2);
 583
 584 /**
 585  * Sets a specific cursor style for an edje part.
 586  *
 587  * @param obj The layout object.
 588  * @param part_name a part from loaded edje group.
 589  * @param style the theme style to use (default, transparent, ...)
 590  *
 591  * @return EINA_TRUE on success or EINA_FALSE on failure, that may be
 592  *         part not exists or it did not had a cursor set.
 593  *
 594  * @ingroup Layout
 595  */
 596 EAPI Eina_Bool                    elm_layout_part_cursor_style_set(Evas_Object *obj, const char *part_name, const char *style) EINA_ARG_NONNULL(1, 2);
 597
 598 /**
 599  * Gets a specific cursor style for an edje part.
 600  *
 601  * @param obj The layout object.
 602  * @param part_name a part from loaded edje group.
 603  *
 604  * @return the theme style in use, defaults to "default". If the
 605  *         object does not have a cursor set, then NULL is returned.
 606  *
 607  * @ingroup Layout
 608  */
 609 EAPI const char                  *elm_layout_part_cursor_style_get(const Evas_Object *obj, const char *part_name) EINA_ARG_NONNULL(1, 2);
 610
 611 /**
 612  * Sets if the cursor set should be searched on the theme or should use
 613  * the provided by the engine, only.
 614  *
 615  * @note before you set if should look on theme you should define a
 616  * cursor with elm_layout_part_cursor_set(). By default it will only
 617  * look for cursors provided by the engine.
 618  *
 619  * @param obj The layout object.
 620  * @param part_name a part from loaded edje group.
 621  * @param engine_only if cursors should be just provided by the engine (EINA_TRUE)
 622  *        or should also search on widget's theme as well (EINA_FALSE)
 623  *
 624  * @return EINA_TRUE on success or EINA_FALSE on failure, that may be
 625  *         part not exists or it did not had a cursor set.
 626  *
 627  * @ingroup Layout
 628  */
 629 EAPI Eina_Bool                    elm_layout_part_cursor_engine_only_set(Evas_Object *obj, const char *part_name, Eina_Bool engine_only) EINA_ARG_NONNULL(1, 2);
 630
 631 /**
 632  * Gets a specific cursor engine_only for an edje part.
 633  *
 634  * @param obj The layout object.
 635  * @param part_name a part from loaded edje group.
 636  *
 637  * @return whenever the cursor is just provided by engine or also from theme.
 638  *
 639  * @ingroup Layout
 640  */
 641 EAPI Eina_Bool                    elm_layout_part_cursor_engine_only_get(const Evas_Object *obj, const char *part_name) EINA_ARG_NONNULL(1, 2);
 642
 643 /**
 644  * @def elm_layout_icon_set
 645  * Convenience macro to set the icon object in a layout that follows the
 646  * Elementary naming convention for its parts.
 647  *
 648  * @ingroup Layout
 649  */
 650 #define elm_layout_icon_set(_ly, _obj)                                 \
 651   do {                                                                 \
 652        const char *sig;                                                \
 653        elm_object_part_content_set((_ly), "elm.swallow.icon", (_obj)); \
 654        if ((_obj)) sig = "elm,state,icon,visible";                     \
 655        else sig = "elm,state,icon,hidden";                             \
 656        elm_object_signal_emit((_ly), sig, "elm");                      \
 657     } while (0)
 658
 659 /**
 660  * @def elm_layout_icon_get
 661  * Convienience macro to get the icon object from a layout that follows the
 662  * Elementary naming convention for its parts.
 663  *
 664  * @ingroup Layout
 665  */
 666 #define elm_layout_icon_get(_ly) \
 667   elm_object_part_content_get((_ly), "elm.swallow.icon")
 668
 669 /**
 670  * @def elm_layout_end_set
 671  * Convienience macro to set the end object in a layout that follows the
 672  * Elementary naming convention for its parts.
 673  *
 674  * @ingroup Layout
 675  */
 676 #define elm_layout_end_set(_ly, _obj)                                 \
 677   do {                                                                \
 678        const char *sig;                                               \
 679        elm_object_part_content_set((_ly), "elm.swallow.end", (_obj)); \
 680        if ((_obj)) sig = "elm,state,end,visible";                     \
 681        else sig = "elm,state,end,hidden";                             \
 682        elm_object_signal_emit((_ly), sig, "elm");                     \
 683     } while (0)
 684
 685 /**
 686  * @def elm_layout_end_get
 687  * Convienience macro to get the end object in a layout that follows the
 688  * Elementary naming convention for its parts.
 689  *
 690  * @ingroup Layout
 691  */
 692 #define elm_layout_end_get(_ly) \
 693   elm_object_part_content_get((_ly), "elm.swallow.end")
 694
 695 /**
 696  * @def elm_layout_label_set
 697  * Convienience macro to set the label in a layout that follows the
 698  * Elementary naming convention for its parts.
 699  *
 700  * @ingroup Layout
 701  * @deprecated use elm_object_text_set() instead.
 702  */
 703 #define elm_layout_label_set(_ly, _txt) \
 704   elm_layout_text_set((_ly), "elm.text", (_txt))
 705
 706 /**
 707  * @def elm_layout_label_get
 708  * Convenience macro to get the label in a layout that follows the
 709  * Elementary naming convention for its parts.
 710  *
 711  * @ingroup Layout
 712  * @deprecated use elm_object_text_set() instead.
 713  */
 714 #define elm_layout_label_get(_ly) \
 715   elm_layout_text_get((_ly), "elm.text")
 716
 717 /* smart callbacks called:
 718  * "theme,changed" - when elm theme is changed.
 719  */
 720
 721 /**
 722  * @}
 723  */