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       *elm_layout_add(Evas_Object *parent) EINA_ARG_NONNULL(1);
 156
 157    /**
 158     * Set the file that will be used as layout
 159     *
 160     * @param obj The layout object
 161     * @param file The path to file (edj) that will be used as layout
 162     * @param group The group that the layout belongs in edje file
 163     *
 164     * @return (1 = success, 0 = error)
 165     *
 166     * @ingroup Layout
 167     */
 168    EAPI Eina_Bool          elm_layout_file_set(Evas_Object *obj, const char *file, const char *group) EINA_ARG_NONNULL(1);
 169
 170    /**
 171     * Set the edje group from the elementary theme that will be used as layout
 172     *
 173     * @param obj The layout object
 174     * @param clas the clas of the group
 175     * @param group the group
 176     * @param style the style to used
 177     *
 178     * @return (1 = success, 0 = error)
 179     *
 180     * @ingroup Layout
 181     */
 182    EAPI Eina_Bool          elm_layout_theme_set(Evas_Object *obj, const char *clas, const char *group, const char *style) EINA_ARG_NONNULL(1);
 183
 184    /**
 185     * Set the layout content.
 186     *
 187     * @param obj The layout object
 188     * @param swallow The swallow part name in the edje file
 189     * @param content The child that will be added in this layout object
 190     *
 191     * Once the content object is set, a previously set one will be deleted.
 192     * If you want to keep that old content object, use the
 193     * elm_object_part_content_unset() function.
 194     *
 195     * @note In an Edje theme, the part used as a content container is called @c
 196     * SWALLOW. This is why the parameter name is called @p swallow, but it is
 197     * expected to be a part name just like the second parameter of
 198     * elm_layout_box_append().
 199     *
 200     * @see elm_layout_box_append()
 201     * @see elm_object_part_content_get()
 202     * @see elm_object_part_content_unset()
 203     * @see @ref secBox
 204     * @deprecated use elm_object_part_content_set() instead
 205     *
 206     * @ingroup Layout
 207     */
 208    EINA_DEPRECATED EAPI void               elm_layout_content_set(Evas_Object *obj, const char *swallow, Evas_Object *content) EINA_ARG_NONNULL(1);
 209
 210    /**
 211     * Get the child object in the given content part.
 212     *
 213     * @param obj The layout object
 214     * @param swallow The SWALLOW part to get its content
 215     *
 216     * @return The swallowed object or NULL if none or an error occurred
 217     *
 218     * @deprecated use elm_object_part_content_get() instead
 219     *
 220     * @ingroup Layout
 221     */
 222    EINA_DEPRECATED EAPI Evas_Object       *elm_layout_content_get(const Evas_Object *obj, const char *swallow) EINA_ARG_NONNULL(1);
 223
 224    /**
 225     * Unset the layout content.
 226     *
 227     * @param obj The layout object
 228     * @param swallow The swallow part name in the edje file
 229     * @return The content that was being used
 230     *
 231     * Unparent and return the content object which was set for this part.
 232     *
 233     * @deprecated use elm_object_part_content_unset() instead
 234     *
 235     * @ingroup Layout
 236     */
 237    EINA_DEPRECATED EAPI Evas_Object       *elm_layout_content_unset(Evas_Object *obj, const char *swallow) EINA_ARG_NONNULL(1);
 238
 239    /**
 240     * Set the text of the given part
 241     *
 242     * @param obj The layout object
 243     * @param part The TEXT part where to set the text
 244     * @param text The text to set
 245     *
 246     * @ingroup Layout
 247     * @deprecated use elm_object_part_text_set() instead.
 248     */
 249    EINA_DEPRECATED EAPI void               elm_layout_text_set(Evas_Object *obj, const char *part, const char *text) EINA_ARG_NONNULL(1);
 250
 251    /**
 252     * Get the text set in the given part
 253     *
 254     * @param obj The layout object
 255     * @param part The TEXT part to retrieve the text off
 256     *
 257     * @return The text set in @p part
 258     *
 259     * @ingroup Layout
 260     * @deprecated use elm_object_part_text_get() instead.
 261     */
 262    EINA_DEPRECATED EAPI const char        *elm_layout_text_get(const Evas_Object *obj, const char *part) EINA_ARG_NONNULL(1);
 263
 264    /**
 265     * Append child to layout box part.
 266     *
 267     * @param obj the layout object
 268     * @param part the box part to which the object will be appended.
 269     * @param child the child object to append to box.
 270     *
 271     * Once the object is appended, it will become child of the layout. Its
 272     * lifetime will be bound to the layout, whenever the layout dies the child
 273     * will be deleted automatically. One should use elm_layout_box_remove() to
 274     * make this layout forget about the object.
 275     *
 276     * @see elm_layout_box_prepend()
 277     * @see elm_layout_box_insert_before()
 278     * @see elm_layout_box_insert_at()
 279     * @see elm_layout_box_remove()
 280     *
 281     * @ingroup Layout
 282     */
 283    EAPI void               elm_layout_box_append(Evas_Object *obj, const char *part, Evas_Object *child) EINA_ARG_NONNULL(1);
 284
 285    /**
 286     * Prepend child to layout box part.
 287     *
 288     * @param obj the layout object
 289     * @param part the box part to prepend.
 290     * @param child the child object to prepend to box.
 291     *
 292     * Once the object is prepended, it will become child of the layout. Its
 293     * lifetime will be bound to the layout, whenever the layout dies the child
 294     * will be deleted automatically. One should use elm_layout_box_remove() to
 295     * make this layout forget about the object.
 296     *
 297     * @see elm_layout_box_append()
 298     * @see elm_layout_box_insert_before()
 299     * @see elm_layout_box_insert_at()
 300     * @see elm_layout_box_remove()
 301     *
 302     * @ingroup Layout
 303     */
 304    EAPI void               elm_layout_box_prepend(Evas_Object *obj, const char *part, Evas_Object *child) EINA_ARG_NONNULL(1);
 305
 306    /**
 307     * Insert child to layout box part before a reference object.
 308     *
 309     * @param obj the layout object
 310     * @param part the box part to insert.
 311     * @param child the child object to insert into box.
 312     * @param reference another reference object to insert before in box.
 313     *
 314     * Once the object is inserted, it will become child of the layout. Its
 315     * lifetime will be bound to the layout, whenever the layout dies the child
 316     * will be deleted automatically. One should use elm_layout_box_remove() to
 317     * make this layout forget about the object.
 318     *
 319     * @see elm_layout_box_append()
 320     * @see elm_layout_box_prepend()
 321     * @see elm_layout_box_insert_before()
 322     * @see elm_layout_box_remove()
 323     *
 324     * @ingroup Layout
 325     */
 326    EAPI void               elm_layout_box_insert_before(Evas_Object *obj, const char *part, Evas_Object *child, const Evas_Object *reference) EINA_ARG_NONNULL(1);
 327
 328    /**
 329     * Insert child to layout box part at a given position.
 330     *
 331     * @param obj the layout object
 332     * @param part the box part to insert.
 333     * @param child the child object to insert into box.
 334     * @param pos the numeric position >=0 to insert the child.
 335     *
 336     * Once the object is inserted, it will become child of the layout. Its
 337     * lifetime will be bound to the layout, whenever the layout dies the child
 338     * will be deleted automatically. One should use elm_layout_box_remove() to
 339     * make this layout forget about the object.
 340     *
 341     * @see elm_layout_box_append()
 342     * @see elm_layout_box_prepend()
 343     * @see elm_layout_box_insert_before()
 344     * @see elm_layout_box_remove()
 345     *
 346     * @ingroup Layout
 347     */
 348    EAPI void               elm_layout_box_insert_at(Evas_Object *obj, const char *part, Evas_Object *child, unsigned int pos) EINA_ARG_NONNULL(1);
 349
 350    /**
 351     * Remove a child of the given part box.
 352     *
 353     * @param obj The layout object
 354     * @param part The box part name to remove child.
 355     * @param child The object to remove from box.
 356     * @return The object that was being used, or NULL if not found.
 357     *
 358     * The object will be removed from the box part and its lifetime will
 359     * not be handled by the layout anymore. This is equivalent to
 360     * elm_object_part_content_unset() for box.
 361     *
 362     * @see elm_layout_box_append()
 363     * @see elm_layout_box_remove_all()
 364     *
 365     * @ingroup Layout
 366     */
 367    EAPI Evas_Object       *elm_layout_box_remove(Evas_Object *obj, const char *part, Evas_Object *child) EINA_ARG_NONNULL(1, 2, 3);
 368
 369    /**
 370     * Remove all children of the given part box.
 371     *
 372     * @param obj The layout object
 373     * @param part The box part name to remove child.
 374     * @param clear If EINA_TRUE, then all objects will be deleted as
 375     *        well, otherwise they will just be removed and will be
 376     *        dangling on the canvas.
 377     *
 378     * The objects will be removed from the box part and their lifetime will
 379     * not be handled by the layout anymore. This is equivalent to
 380     * elm_layout_box_remove() for all box children.
 381     *
 382     * @see elm_layout_box_append()
 383     * @see elm_layout_box_remove()
 384     *
 385     * @ingroup Layout
 386     */
 387    EAPI void               elm_layout_box_remove_all(Evas_Object *obj, const char *part, Eina_Bool clear) EINA_ARG_NONNULL(1, 2);
 388
 389    /**
 390     * Insert child to layout table part.
 391     *
 392     * @param obj the layout object
 393     * @param part the box part to pack child.
 394     * @param child_obj the child object to pack into table.
 395     * @param col the column to which the child should be added. (>= 0)
 396     * @param row the row to which the child should be added. (>= 0)
 397     * @param colspan how many columns should be used to store this object. (>=
 398     *        1)
 399     * @param rowspan how many rows should be used to store this object. (>= 1)
 400     *
 401     * Once the object is inserted, it will become child of the table. Its
 402     * lifetime will be bound to the layout, and whenever the layout dies the
 403     * child will be deleted automatically. One should use
 404     * elm_layout_table_remove() to make this layout forget about the object.
 405     *
 406     * If @p colspan or @p rowspan are bigger than 1, that object will occupy
 407     * more space than a single cell. For instance, the following code:
 408     * @code
 409     * elm_layout_table_pack(layout, "table_part", child, 0, 1, 3, 1);
 410     * @endcode
 411     *
 412     * Would result in an object being added like the following picture:
 413     *
 414     * @image html layout_colspan.png
 415     * @image latex layout_colspan.eps width=\textwidth
 416     *
 417     * @see elm_layout_table_unpack()
 418     * @see elm_layout_table_clear()
 419     *
 420     * @ingroup Layout
 421     */
 422    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);
 423
 424    /**
 425     * Unpack (remove) a child of the given part table.
 426     *
 427     * @param obj The layout object
 428     * @param part The table part name to remove child.
 429     * @param child_obj The object to remove from table.
 430     * @return The object that was being used, or NULL if not found.
 431     *
 432     * The object will be unpacked from the table part and its lifetime
 433     * will not be handled by the layout anymore. This is equivalent to
 434     * elm_object_part_content_unset() for table.
 435     *
 436     * @see elm_layout_table_pack()
 437     * @see elm_layout_table_clear()
 438     *
 439     * @ingroup Layout
 440     */
 441    EAPI Evas_Object       *elm_layout_table_unpack(Evas_Object *obj, const char *part, Evas_Object *child_obj) EINA_ARG_NONNULL(1, 2, 3);
 442
 443    /**
 444     * Remove all the child objects of the given part table.
 445     *
 446     * @param obj The layout object
 447     * @param part The table part name to remove child.
 448     * @param clear If EINA_TRUE, then all objects will be deleted as
 449     *        well, otherwise they will just be removed and will be
 450     *        dangling on the canvas.
 451     *
 452     * The objects will be removed from the table part and their lifetime will
 453     * not be handled by the layout anymore. This is equivalent to
 454     * elm_layout_table_unpack() for all table children.
 455     *
 456     * @see elm_layout_table_pack()
 457     * @see elm_layout_table_unpack()
 458     *
 459     * @ingroup Layout
 460     */
 461    EAPI void               elm_layout_table_clear(Evas_Object *obj, const char *part, Eina_Bool clear) EINA_ARG_NONNULL(1, 2);
 462
 463    /**
 464     * Get the edje layout
 465     *
 466     * @param obj The layout object
 467     *
 468     * @return A Evas_Object with the edje layout settings loaded
 469     * with function elm_layout_file_set
 470     *
 471     * This returns the edje object. It is not expected to be used to then
 472     * swallow objects via edje_object_part_swallow() for example. Use
 473     * elm_object_part_content_set() instead so child object handling and sizing is
 474     * done properly.
 475     *
 476     * @note This function should only be used if you really need to call some
 477     * low level Edje function on this edje object. All the common stuff (setting
 478     * text, emitting signals, hooking callbacks to signals, etc.) can be done
 479     * with proper elementary functions.
 480     *
 481     * @see elm_object_signal_callback_add()
 482     * @see elm_object_signal_emit()
 483     * @see elm_object_part_text_set()
 484     * @see elm_object_part_content_set()
 485     * @see elm_layout_box_append()
 486     * @see elm_layout_table_pack()
 487     * @see elm_layout_data_get()
 488     *
 489     * @ingroup Layout
 490     */
 491    EAPI Evas_Object       *elm_layout_edje_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
 492
 493    /**
 494     * Get the edje data from the given layout
 495     *
 496     * @param obj The layout object
 497     * @param key The data key
 498     *
 499     * @return The edje data string
 500     *
 501     * This function fetches data specified inside the edje theme of this layout.
 502     * This function return NULL if data is not found.
 503     *
 504     * In EDC this comes from a data block within the group block that @p
 505     * obj was loaded from. E.g.
 506     *
 507     * @code
 508     * collections {
 509     *   group {
 510     *     name: "a_group";
 511     *     data {
 512     *       item: "key1" "value1";
 513     *       item: "key2" "value2";
 514     *     }
 515     *   }
 516     * }
 517     * @endcode
 518     *
 519     * @ingroup Layout
 520     */
 521    EAPI const char        *elm_layout_data_get(const Evas_Object *obj, const char *key) EINA_ARG_NONNULL(1, 2);
 522
 523    /**
 524     * Eval sizing
 525     *
 526     * @param obj The layout object
 527     *
 528     * Manually forces a sizing re-evaluation. This is useful when the minimum
 529     * size required by the edje theme of this layout has changed. The change on
 530     * the minimum size required by the edje theme is not immediately reported to
 531     * the elementary layout, so one needs to call this function in order to tell
 532     * the widget (layout) that it needs to reevaluate its own size.
 533     *
 534     * The minimum size of the theme is calculated based on minimum size of
 535     * parts, the size of elements inside containers like box and table, etc. All
 536     * of this can change due to state changes, and that's when this function
 537     * should be called.
 538     *
 539     * Also note that a standard signal of "size,eval" "elm" emitted from the
 540     * edje object will cause this to happen too.
 541     *
 542     * @ingroup Layout
 543     */
 544    EAPI void               elm_layout_sizing_eval(Evas_Object *obj) EINA_ARG_NONNULL(1);
 545
 546    /**
 547     * Sets a specific cursor for an edje part.
 548     *
 549     * @param obj The layout object.
 550     * @param part_name a part from loaded edje group.
 551     * @param cursor cursor name to use, see Elementary_Cursor.h
 552     *
 553     * @return EINA_TRUE on success or EINA_FALSE on failure, that may be
 554     *         part not exists or it has "mouse_events: 0".
 555     *
 556     * @ingroup Layout
 557     */
 558    EAPI Eina_Bool          elm_layout_part_cursor_set(Evas_Object *obj, const char *part_name, const char *cursor) EINA_ARG_NONNULL(1, 2);
 559
 560    /**
 561     * Get the cursor to be shown when mouse is over an edje part
 562     *
 563     * @param obj The layout object.
 564     * @param part_name a part from loaded edje group.
 565     * @return the cursor name.
 566     *
 567     * @ingroup Layout
 568     */
 569    EAPI const char        *elm_layout_part_cursor_get(const Evas_Object *obj, const char *part_name) EINA_ARG_NONNULL(1, 2);
 570
 571    /**
 572     * Unsets a cursor previously set with elm_layout_part_cursor_set().
 573     *
 574     * @param obj The layout object.
 575     * @param part_name a part from loaded edje group, that had a cursor set
 576     *        with elm_layout_part_cursor_set().
 577     *
 578     * @ingroup Layout
 579     */
 580    EAPI void               elm_layout_part_cursor_unset(Evas_Object *obj, const char *part_name) EINA_ARG_NONNULL(1, 2);
 581
 582    /**
 583     * Sets a specific cursor style for an edje part.
 584     *
 585     * @param obj The layout object.
 586     * @param part_name a part from loaded edje group.
 587     * @param style the theme style to use (default, transparent, ...)
 588     *
 589     * @return EINA_TRUE on success or EINA_FALSE on failure, that may be
 590     *         part not exists or it did not had a cursor set.
 591     *
 592     * @ingroup Layout
 593     */
 594    EAPI Eina_Bool          elm_layout_part_cursor_style_set(Evas_Object *obj, const char *part_name, const char *style) EINA_ARG_NONNULL(1, 2);
 595
 596    /**
 597     * Gets a specific cursor style for an edje part.
 598     *
 599     * @param obj The layout object.
 600     * @param part_name a part from loaded edje group.
 601     *
 602     * @return the theme style in use, defaults to "default". If the
 603     *         object does not have a cursor set, then NULL is returned.
 604     *
 605     * @ingroup Layout
 606     */
 607    EAPI const char        *elm_layout_part_cursor_style_get(const Evas_Object *obj, const char *part_name) EINA_ARG_NONNULL(1, 2);
 608
 609    /**
 610     * Sets if the cursor set should be searched on the theme or should use
 611     * the provided by the engine, only.
 612     *
 613     * @note before you set if should look on theme you should define a
 614     * cursor with elm_layout_part_cursor_set(). By default it will only
 615     * look for cursors provided by the engine.
 616     *
 617     * @param obj The layout object.
 618     * @param part_name a part from loaded edje group.
 619     * @param engine_only if cursors should be just provided by the engine (EINA_TRUE)
 620     *        or should also search on widget's theme as well (EINA_FALSE)
 621     *
 622     * @return EINA_TRUE on success or EINA_FALSE on failure, that may be
 623     *         part not exists or it did not had a cursor set.
 624     *
 625     * @ingroup Layout
 626     */
 627    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);
 628
 629    /**
 630     * Gets a specific cursor engine_only for an edje part.
 631     *
 632     * @param obj The layout object.
 633     * @param part_name a part from loaded edje group.
 634     *
 635     * @return whenever the cursor is just provided by engine or also from theme.
 636     *
 637     * @ingroup Layout
 638     */
 639    EAPI Eina_Bool          elm_layout_part_cursor_engine_only_get(const Evas_Object *obj, const char *part_name) EINA_ARG_NONNULL(1, 2);
 640
 641 /**
 642  * @def elm_layout_icon_set
 643  * Convenience macro to set the icon object in a layout that follows the
 644  * Elementary naming convention for its parts.
 645  *
 646  * @ingroup Layout
 647  */
 648 #define elm_layout_icon_set(_ly, _obj) \
 649   do { \
 650     const char *sig; \
 651     elm_object_part_content_set((_ly), "elm.swallow.icon", (_obj)); \
 652     if ((_obj)) sig = "elm,state,icon,visible"; \
 653     else sig = "elm,state,icon,hidden"; \
 654     elm_object_signal_emit((_ly), sig, "elm"); \
 655   } while (0)
 656
 657 /**
 658  * @def elm_layout_icon_get
 659  * Convienience macro to get the icon object from a layout that follows the
 660  * Elementary naming convention for its parts.
 661  *
 662  * @ingroup Layout
 663  */
 664 #define elm_layout_icon_get(_ly) \
 665   elm_object_part_content_get((_ly), "elm.swallow.icon")
 666
 667 /**
 668  * @def elm_layout_end_set
 669  * Convienience macro to set the end object in a layout that follows the
 670  * Elementary naming convention for its parts.
 671  *
 672  * @ingroup Layout
 673  */
 674 #define elm_layout_end_set(_ly, _obj) \
 675   do { \
 676     const char *sig; \
 677     elm_object_part_content_set((_ly), "elm.swallow.end", (_obj)); \
 678     if ((_obj)) sig = "elm,state,end,visible"; \
 679     else sig = "elm,state,end,hidden"; \
 680     elm_object_signal_emit((_ly), sig, "elm"); \
 681   } while (0)
 682
 683 /**
 684  * @def elm_layout_end_get
 685  * Convienience macro to get the end object in a layout that follows the
 686  * Elementary naming convention for its parts.
 687  *
 688  * @ingroup Layout
 689  */
 690 #define elm_layout_end_get(_ly) \
 691   elm_object_part_content_get((_ly), "elm.swallow.end")
 692
 693 /**
 694  * @def elm_layout_label_set
 695  * Convienience macro to set the label in a layout that follows the
 696  * Elementary naming convention for its parts.
 697  *
 698  * @ingroup Layout
 699  * @deprecated use elm_object_text_set() instead.
 700  */
 701 #define elm_layout_label_set(_ly, _txt) \
 702   elm_layout_text_set((_ly), "elm.text", (_txt))
 703
 704 /**
 705  * @def elm_layout_label_get
 706  * Convenience macro to get the label in a layout that follows the
 707  * Elementary naming convention for its parts.
 708  *
 709  * @ingroup Layout
 710  * @deprecated use elm_object_text_set() instead.
 711  */
 712 #define elm_layout_label_get(_ly) \
 713   elm_layout_text_get((_ly), "elm.text")
 714
 715    /* smart callbacks called:
 716     * "theme,changed" - when elm theme is changed.
 717     */
 718
 719    /**
 720     * @}
 721     */