src/lib/elm_layout.h

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