1 #ifndef _EVAS_CANVAS_EO_H_ 2 #define _EVAS_CANVAS_EO_H_ 3 4 #ifndef _EVAS_CANVAS_EO_CLASS_TYPE 5 #define _EVAS_CANVAS_EO_CLASS_TYPE 6 7 typedef Eo Evas_Canvas; 8 9 #endif 10 11 #ifndef _EVAS_CANVAS_EO_TYPES 12 #define _EVAS_CANVAS_EO_TYPES 13 14 15 #endif 16 /** Evas canvas class 17 * 18 * @ingroup Evas_Canvas 19 */ 20 #define EVAS_CANVAS_CLASS evas_canvas_class_get() 21 22 EWAPI const Efl_Class *evas_canvas_class_get(void) EINA_CONST; 23 24 /** 25 * @brief Set the image cache. 26 * 27 * This function sets the image cache of canvas in bytes. 28 * 29 * @param[in] obj The object. 30 * @param[in] size The cache size. 31 * 32 * @ingroup Evas_Canvas 33 */ 34 EOAPI void evas_canvas_image_cache_set(Eo *obj, int size); 35 36 /** 37 * @brief Get the image cache. 38 * 39 * This function returns the image cache size of canvas in bytes. 40 * 41 * @param[in] obj The object. 42 * 43 * @return The cache size. 44 * 45 * @ingroup Evas_Canvas 46 */ 47 EOAPI int evas_canvas_image_cache_get(const Eo *obj); 48 49 /** 50 * @brief Set the default set of flags an event begins with 51 * 52 * Events in evas can have an event_flags member. This starts out with an 53 * initial value (no flags). This lets you set the default flags that an event 54 * begins with to @c flags. 55 * 56 * @param[in] obj The object. 57 * @param[in] flags The default flags to use. 58 * 59 * @since 1.2 60 * 61 * @ingroup Evas_Canvas 62 */ 63 EOAPI void evas_canvas_event_default_flags_set(Eo *obj, Evas_Event_Flags flags); 64 65 /** 66 * @brief Get the default set of flags an event begins with 67 * 68 * This gets the default event flags events are produced with when fed in. 69 * 70 * @param[in] obj The object. 71 * 72 * @return The default flags to use. 73 * 74 * @since 1.2 75 * 76 * @ingroup Evas_Canvas 77 */ 78 EOAPI Evas_Event_Flags evas_canvas_event_default_flags_get(const Eo *obj); 79 80 /** 81 * @brief Changes the size of font cache of the given evas. 82 * 83 * @param[in] obj The object. 84 * @param[in] size The size in bytes. 85 * 86 * @ingroup Evas_Canvas 87 */ 88 EOAPI void evas_canvas_font_cache_set(Eo *obj, int size); 89 90 /** 91 * @brief Get the size of font cache of the given evas in bytes. 92 * 93 * @param[in] obj The object. 94 * 95 * @return The size in bytes. 96 * 97 * @ingroup Evas_Canvas 98 */ 99 EOAPI int evas_canvas_font_cache_get(const Eo *obj); 100 101 /** 102 * @brief Attaches a specific pointer to the evas for fetching later. 103 * 104 * @param[in] obj The object. 105 * @param[in] data The attached pointer. 106 * 107 * @ingroup Evas_Canvas 108 */ 109 EOAPI void evas_canvas_data_attach_set(Eo *obj, void *data); 110 111 /** 112 * @brief Returns the pointer attached by @ref evas_canvas_data_attach_set. 113 * 114 * @param[in] obj The object. 115 * 116 * @return The attached pointer. 117 * 118 * @ingroup Evas_Canvas 119 */ 120 EOAPI void *evas_canvas_data_attach_get(const Eo *obj); 121 122 /** 123 * @brief Retrieve the object focused by the default seat. 124 * 125 * Focused objects will be the ones having key events delivered to, which the 126 * programmer can act upon by means of @ref evas_object_event_callback_add 127 * usage. 128 * 129 * @note Most users wouldn't be dealing directly with Evas' focused objects. 130 * Instead, they would be using a higher level library for that (like a 131 * toolkit, as Elementary) to handle focus and who's receiving input for them. 132 * 133 * This call returns the object that currently has focus on the canvas @c e or 134 * @c null, if none. 135 * 136 * See also @ref evas_object_focus_set, @ref evas_object_focus_get, @ref 137 * evas_object_key_grab, @ref evas_object_key_ungrab, 138 * @ref evas_canvas_seat_focus_get 139 * 140 * @param[in] obj The object. 141 * 142 * @return The object that has focus or @c null if there is not one. 143 * 144 * @ingroup Evas_Canvas 145 */ 146 EOAPI Efl_Canvas_Object *evas_canvas_focus_get(const Eo *obj) EINA_WARN_UNUSED_RESULT; 147 148 /** 149 * @brief Return the focused object by a given seat. 150 * 151 * @param[in] obj The object. 152 * @param[in] seat The seat to fetch the focused object or @c null for the 153 * default seat. 154 * 155 * @return The object that has the focus or @c null if the seat has no focused 156 * object. 157 * 158 * @since 1.19 159 * 160 * @ingroup Evas_Canvas 161 */ 162 EOAPI Efl_Canvas_Object *evas_canvas_seat_focus_get(const Eo *obj, Evas_Device *seat); 163 164 /** 165 * @brief Get the highest (stacked) Evas object on the canvas @c e. 166 * 167 * This function will take all populated layers in the canvas into account, 168 * getting the highest object for the highest layer, naturally. 169 * 170 * @warning This function will skip objects parented by smart objects, acting 171 * only on the ones at the "top level", with regard to object parenting. 172 * 173 * See also @ref evas_object_layer_get, @ref evas_object_layer_set, @ref 174 * evas_object_below_get, @ref evas_object_above_get. 175 * 176 * @param[in] obj The object. 177 * 178 * @return A pointer to the highest object on it (if any) or @c null otherwise. 179 * 180 * @ingroup Evas_Canvas 181 */ 182 EOAPI Efl_Canvas_Object *evas_canvas_object_top_get(const Eo *obj) EINA_WARN_UNUSED_RESULT; 183 184 /** 185 * @brief This function returns the current known default pointer coordinates. 186 * 187 * @param[in] obj The object. 188 * @param[in] dev The pointer device. 189 * @param[out] x The pointer to a Evas_Coord to be filled in. 190 * @param[out] y The pointer to a Evas_Coord to be filled in. 191 * 192 * @since 1.19 193 * 194 * @ingroup Evas_Canvas 195 */ 196 EOAPI void evas_canvas_pointer_canvas_xy_by_device_get(const Eo *obj, Evas_Device *dev, int *x, int *y); 197 198 /** 199 * @brief This function returns the current known default pointer coordinates 200 * 201 * This function returns the current known canvas unit coordinates of the mouse 202 * pointer and sets the contents of the Evas_Coords pointed to by @c x and @c y 203 * to contain these coordinates. If @c e is not a valid canvas the results of 204 * this function are undefined. 205 * 206 * @param[in] obj The object. 207 * @param[out] x The pointer to a Evas_Coord to be filled in. 208 * @param[out] y The pointer to a Evas_Coord to be filled in. 209 * 210 * @ingroup Evas_Canvas 211 */ 212 EOAPI void evas_canvas_pointer_canvas_xy_get(const Eo *obj, int *x, int *y); 213 214 /** 215 * @brief Get the number of mouse or multi presses currently active. 216 * 217 * @param[in] obj The object. 218 * 219 * @return Mouse or multi presses currently active 220 * 221 * @since 1.2 222 * 223 * @ingroup Evas_Canvas 224 */ 225 EOAPI int evas_canvas_event_down_count_get(const Eo *obj); 226 227 /** 228 * @brief This gets the internal counter that counts the number of smart 229 * calculations. 230 * 231 * Whenever evas performs smart object calculations on the whole canvas it 232 * increments a counter by 1. This function returns the value of the smart 233 * object calculate counter. It starts with a value of 0 and will increase (and 234 * eventually wrap around to negative values and so on) by 1 every time objects 235 * are calculated. You can use this counter to ensure you don't re-do 236 * calculations withint the same calculation generation/run if the calculations 237 * maybe cause self-feeding effects. 238 * 239 * @param[in] obj The object. 240 * 241 * @return Number of smart calculations 242 * 243 * @since 1.1 244 * 245 * @ingroup Evas_Canvas 246 */ 247 EOAPI int evas_canvas_smart_objects_calculate_count_get(const Eo *obj); 248 249 /** 250 * @brief Get the focus state for the default seat. 251 * 252 * @param[in] obj The object. 253 * 254 * @return @c true if focused, @c false otherwise 255 * 256 * @ingroup Evas_Canvas 257 */ 258 EOAPI Eina_Bool evas_canvas_focus_state_get(const Eo *obj); 259 260 /** 261 * @brief Get the focus state by a given seat. 262 * 263 * @param[in] obj The object. 264 * @param[in] seat The seat to check the focus state. Use @c null for the 265 * default seat. 266 * 267 * @return @c true if the seat has the canvas focus, @c false otherwise. 268 * 269 * @ingroup Evas_Canvas 270 */ 271 EOAPI Eina_Bool evas_canvas_seat_focus_state_get(const Eo *obj, Evas_Device *seat); 272 273 /** 274 * @brief Get the changed marker for the canvas. 275 * 276 * @param[in] obj The object. 277 * 278 * @return @c true if changed, @c false otherwise 279 * 280 * @since 1.11 281 * 282 * @ingroup Evas_Canvas 283 */ 284 EOAPI Eina_Bool evas_canvas_changed_get(const Eo *obj); 285 286 /** 287 * @brief This function returns the current known pointer coordinates. 288 * 289 * @param[in] obj The object. 290 * @param[in] dev The mouse device. 291 * @param[out] x The pointer to an integer to be filled in. 292 * @param[out] y The pointer to an integer to be filled in. 293 * 294 * @since 1.19 295 * 296 * @ingroup Evas_Canvas 297 */ 298 EOAPI void evas_canvas_pointer_output_xy_by_device_get(const Eo *obj, Evas_Device *dev, int *x, int *y); 299 300 /** 301 * @brief This function returns the current known default pointer coordinates. 302 * 303 * This function returns the current known screen/output coordinates of the 304 * mouse pointer and sets the contents of the integers pointed to by @c x and 305 * @c y to contain these coordinates. If @c e is not a valid canvas the results 306 * of this function are undefined. 307 * 308 * @param[in] obj The object. 309 * @param[out] x The pointer to an integer to be filled in. 310 * @param[out] y The pointer to an integer to be filled in. 311 * 312 * @ingroup Evas_Canvas 313 */ 314 EOAPI void evas_canvas_pointer_output_xy_get(const Eo *obj, int *x, int *y); 315 316 /** 317 * @brief Get the lowest (stacked) Evas object on the canvas @c e. 318 * 319 * This function will take all populated layers in the canvas into account, 320 * getting the lowest object for the lowest layer, naturally. 321 * 322 * @warning This function will skip objects parented by smart objects, acting 323 * only on the ones at the "top level", with regard to object parenting. 324 * 325 * See also @ref evas_object_layer_get, @ref evas_object_layer_set, @ref 326 * evas_object_below_get. 327 * 328 * @param[in] obj The object. 329 * 330 * @return A pointer to the lowest object on it, if any, or @c null otherwise. 331 * 332 * @ingroup Evas_Canvas 333 */ 334 EOAPI Efl_Canvas_Object *evas_canvas_object_bottom_get(const Eo *obj) EINA_WARN_UNUSED_RESULT; 335 336 /** 337 * @brief Returns a bitmask with the mouse buttons currently pressed, set to 1. 338 * 339 * @param[in] obj The object. 340 * @param[in] dev The mouse device. 341 * 342 * @return A bitmask of the currently depressed buttons on the canvas. 343 * 344 * @ingroup Evas_Canvas 345 */ 346 EOAPI unsigned int evas_canvas_pointer_button_down_mask_by_device_get(const Eo *obj, Evas_Device *dev); 347 348 /** 349 * @brief Returns a bitmask with the default mouse buttons currently pressed, 350 * set to 1. 351 * 352 * Calling this function will return a 32-bit integer with the appropriate bits 353 * set to 1, which correspond to a mouse button being depressed. This limits 354 * Evas to a mouse devices with a maximum of 32 buttons, but that is generally 355 * in excess of any host system's pointing device abilities. 356 * 357 * A canvas by default begins with no mouse buttons being pressed and only 358 * pointer move events can alter that. 359 * 360 * The least significant bit corresponds to the first mouse button (button 1) 361 * and the most significant bit corresponds to the last mouse button (button 362 * 32). 363 * 364 * If @c e is not a valid canvas, the return value is undefined. 365 * 366 * @param[in] obj The object. 367 * 368 * @return A bitmask of the currently depressed buttons on the canvas. 369 * 370 * @ingroup Evas_Canvas 371 */ 372 EOAPI unsigned int evas_canvas_pointer_button_down_mask_get(const Eo *obj) EINA_WARN_UNUSED_RESULT; 373 374 /** 375 * @brief Retrieve a list of Evas objects lying over a given position in a 376 * canvas. 377 * 378 * This function will traverse all the layers of the given canvas, from top to 379 * bottom, querying for objects with areas covering the given position. It will 380 * enter the smart objects. It will not append to the list pass events as 381 * hidden objects. Call eina_list_free on the returned list after usage. 382 * 383 * @param[in] obj The object. 384 * @param[in] stop An Evas Object where to stop searching. 385 * @param[in] x The horizontal coordinate of the position. 386 * @param[in] y The vertical coordinate of the position. 387 * 388 * @return List of objects 389 * 390 * @ingroup Evas_Canvas 391 */ 392 EOAPI Eina_List *evas_canvas_tree_objects_at_xy_get(Eo *obj, Efl_Canvas_Object *stop, int x, int y) EINA_WARN_UNUSED_RESULT; 393 394 /** 395 * @brief Enables or turns on programmatically the lock key with name 396 * @c keyname for the default seat. 397 * 398 * The effect will be as if the key was put on its active state after this 399 * call. 400 * 401 * See also @ref evas_canvas_key_lock_add, @ref evas_canvas_key_lock_del, 402 * @ref evas_canvas_key_lock_del, @ref evas_canvas_key_lock_off, 403 * @ref evas_canvas_seat_key_lock_on, @ref evas_canvas_seat_key_lock_off. 404 * 405 * @param[in] obj The object. 406 * @param[in] keyname The name of the lock to enable. 407 * 408 * @ingroup Evas_Canvas 409 */ 410 EOAPI void evas_canvas_key_lock_on(Eo *obj, const char *keyname) EINA_ARG_NONNULL(2); 411 412 /** 413 * @brief Enables or turns on programmatically the lock key with name 414 * @c keyname for a give seat. 415 * 416 * The effect will be as if the key was put on its active state after this 417 * call. 418 * 419 * See also @ref evas_canvas_key_lock_add, @ref evas_canvas_key_lock_del, 420 * @ref evas_canvas_key_lock_del, @ref evas_canvas_key_lock_off, 421 * @ref evas_canvas_key_lock_on, @ref evas_canvas_seat_key_lock_off. 422 * 423 * @param[in] obj The object. 424 * @param[in] keyname The name of the lock to enable. 425 * @param[in] seat The seat to enable the keylock. A @c null seat repesents the 426 * default seat. 427 * 428 * @since 1.19 429 * 430 * @ingroup Evas_Canvas 431 */ 432 EOAPI void evas_canvas_seat_key_lock_on(Eo *obj, const char *keyname, Evas_Device *seat) EINA_ARG_NONNULL(2); 433 434 /** 435 * @brief Disables or turns off programmatically the lock key with name 436 * @c keyname for a given seat. 437 * 438 * The effect will be as if the key was put on its inactive state after this 439 * call. 440 * 441 * See also @ref evas_canvas_key_lock_on, @ref evas_canvas_seat_key_lock_on, 442 * @ref evas_canvas_key_lock_off. 443 * 444 * @param[in] obj The object. 445 * @param[in] keyname The name of the lock to enable. 446 * @param[in] seat The seat to disable the keylock. A @c null seat repesents 447 * the default seat. 448 * 449 * @since 1.19 450 * 451 * @ingroup Evas_Canvas 452 */ 453 EOAPI void evas_canvas_seat_key_lock_off(Eo *obj, const char *keyname, Evas_Device *seat) EINA_ARG_NONNULL(2); 454 455 /** 456 * @brief Adds the @c keyname key to the current list of modifier keys. 457 * 458 * Modifiers are keys like shift, alt and ctrl, i.e. keys which are meant to be 459 * pressed together with others, altering the behavior of the second keys 460 * pressed. Evas is so that these keys can be user defined. 461 * 462 * This call allows custom modifiers to be added to the Evas system at run 463 * time. It is then possible to set and unset modifier keys programmatically 464 * for other parts of the program to check and act on. Programmers using Evas 465 * would check for modifier keys on key event callbacks using @ref 466 * evas_key_modifier_is_set. 467 * 468 * @note If the programmer instantiates the canvas by means of the @ref 469 * ecore_evas_new family of helper functions, Ecore will take care of 470 * registering on it all standard modifiers: "Shift", "Control", "Alt", "Meta", 471 * "Hyper", "Super". 472 * 473 * @param[in] obj The object. 474 * @param[in] keyname The name of the modifier key to add to the list of Evas 475 * modifiers. 476 * 477 * @ingroup Evas_Canvas 478 */ 479 EOAPI void evas_canvas_key_modifier_add(Eo *obj, const char *keyname) EINA_ARG_NONNULL(2); 480 481 /** 482 * @brief Disables or turns off programmatically the modifier key with name 483 * @c keyname for the default seat. 484 * 485 * See also @ref evas_canvas_key_modifier_add, @ref evas_key_modifier_get, 486 * @ref evas_canvas_key_modifier_on, @ref evas_canvas_seat_key_modifier_off, 487 * @ref evas_canvas_seat_key_modifier_off, @ref evas_key_modifier_is_set, @ref 488 * evas_seat_key_modifier_is_set. 489 * 490 * @param[in] obj The object. 491 * @param[in] keyname The name of the modifier to disable. 492 * 493 * @ingroup Evas_Canvas 494 */ 495 EOAPI void evas_canvas_key_modifier_off(Eo *obj, const char *keyname) EINA_ARG_NONNULL(2); 496 497 /** 498 * @brief Render the given Evas canvas asynchronously. 499 * 500 * This function only returns @c true when a frame will be rendered. If the 501 * previous frame is still rendering, @c false will be returned so the users 502 * know not to wait for the updates callback and just return to their main 503 * loop. 504 * 505 * If a @c func callback is given, a list of updated areas will be generated 506 * and the function will be called from the main thread after the rendered 507 * frame is flushed to the screen. The resulting list should be freed with @ref 508 * evas_render_updates_free. 509 * 510 * The list is given in the @c event_info parameter of the callback function. 511 * 512 * @param[in] obj The object. 513 * 514 * @return @c true if the canvas will render, @c false otherwise. 515 * 516 * @since 1.8 517 * 518 * @ingroup Evas_Canvas 519 */ 520 EOAPI Eina_Bool evas_canvas_render_async(Eo *obj); 521 522 /** Inform the evas that it lost the focus from the default seat. 523 * 524 * @ingroup Evas_Canvas 525 */ 526 EOAPI void evas_canvas_focus_out(Eo *obj); 527 528 /** 529 * @brief Update the canvas internal objects but not triggering immediate 530 * renderization. 531 * 532 * This function updates the canvas internal objects not triggering 533 * renderization. To force renderization function @ref evas_canvas_render 534 * should be used. 535 * @param[in] obj The object. 536 * 537 * @ingroup Evas_Canvas 538 */ 539 EOAPI void evas_canvas_norender(Eo *obj); 540 541 /** 542 * @brief Pop the nochange flag down 1. 543 * 544 * This tells evas, that while the nochange flag is greater than 0, do not mark 545 * objects as "changed" when making changes. 546 * 547 * @warning Do not use this function unless you know what Evas exactly works 548 * with "changed" state. 549 * @param[in] obj The object. 550 * 551 * @ingroup Evas_Canvas 552 */ 553 EOAPI void evas_canvas_nochange_pop(Eo *obj); 554 555 /** 556 * @brief Disables or turns off programmatically the lock key with name 557 * @c keyname for the default seat. 558 * 559 * The effect will be as if the key was put on its inactive state after this 560 * call. 561 * 562 * See also @ref evas_canvas_key_lock_on, @ref evas_canvas_seat_key_lock_on, 563 * @ref evas_canvas_seat_key_lock_off. 564 * 565 * @param[in] obj The object. 566 * @param[in] keyname The name of the lock to disable. 567 * 568 * @ingroup Evas_Canvas 569 */ 570 EOAPI void evas_canvas_key_lock_off(Eo *obj, const char *keyname) EINA_ARG_NONNULL(2); 571 572 /** 573 * @brief Push the nochange flag up 1 574 * 575 * This tells evas, that while the nochange flag is greater than 0, do not mark 576 * objects as "changed" when making changes. 577 * 578 * @warning Do not use this function unless you know what Evas exactly works 579 * with "changed" state. 580 * @param[in] obj The object. 581 * 582 * @ingroup Evas_Canvas 583 */ 584 EOAPI void evas_canvas_nochange_push(Eo *obj); 585 586 /** Force the given evas and associated engine to flush its font cache. 587 * 588 * @ingroup Evas_Canvas 589 */ 590 EOAPI void evas_canvas_font_cache_flush(Eo *obj); 591 592 /** 593 * @brief Enables or turns on programmatically the modifier key with name 594 * @c keyname for the default seat. 595 * 596 * The effect will be as if the key was pressed for the whole time between this 597 * call and a matching evas_key_modifier_off(). 598 * 599 * See also @ref evas_canvas_key_modifier_off, 600 * @ref evas_canvas_seat_key_modifier_on, 601 * @ref evas_canvas_seat_key_modifier_off. 602 * 603 * @param[in] obj The object. 604 * @param[in] keyname The name of the modifier to enable. 605 * 606 * @ingroup Evas_Canvas 607 */ 608 EOAPI void evas_canvas_key_modifier_on(Eo *obj, const char *keyname) EINA_ARG_NONNULL(2); 609 610 /** 611 * @brief Enables or turns on programmatically the modifier key with name 612 * @c keyname for a given seat. 613 * 614 * The effect will be as if the key was pressed for the whole time between this 615 * call and a matching @ref evas_canvas_seat_key_modifier_off. 616 * 617 * See also @ref evas_canvas_key_modifier_off, 618 * @ref evas_canvas_seat_key_modifier_on, 619 * @ref evas_canvas_seat_key_modifier_off. 620 * 621 * @param[in] obj The object. 622 * @param[in] keyname The name of the lock to enable. 623 * @param[in] seat The seat to enable the modifier. A @c null seat repesents 624 * the default seat. 625 * 626 * @since 1.19 627 * 628 * @ingroup Evas_Canvas 629 */ 630 EOAPI void evas_canvas_seat_key_modifier_on(Eo *obj, const char *keyname, Evas_Device *seat) EINA_ARG_NONNULL(2); 631 632 /** 633 * @brief Disables or turns off programmatically the modifier key with name 634 * @c keyname for a given seat. 635 * 636 * See also @ref evas_canvas_key_modifier_add, @ref evas_key_modifier_get, 637 * @ref evas_canvas_key_modifier_on, @ref evas_canvas_seat_key_modifier_off, 638 * @ref evas_canvas_seat_key_modifier_off, @ref evas_key_modifier_is_set, @ref 639 * evas_seat_key_modifier_is_set. 640 * 641 * @param[in] obj The object. 642 * @param[in] keyname The name of the lock to enable. 643 * @param[in] seat The seat to disable the modifier. A @c null seat repesents 644 * the default seat. 645 * 646 * @since 1.19 647 * 648 * @ingroup Evas_Canvas 649 */ 650 EOAPI void evas_canvas_seat_key_modifier_off(Eo *obj, const char *keyname, Evas_Device *seat) EINA_ARG_NONNULL(2); 651 652 /** 653 * @brief List of available font descriptions known or found by this evas. 654 * 655 * The list depends on Evas compile time configuration, such as fontconfig 656 * support, and the paths provided at runtime as explained in @ref 657 * Evas_Font_Path_Group. 658 * 659 * @param[in] obj The object. 660 * 661 * @return A newly allocated list of strings. Do not change the strings. Be 662 * sure to call @ref evas_font_available_list_free after you're done. 663 * 664 * @ingroup Evas_Canvas 665 */ 666 EOAPI Eina_List *evas_canvas_font_available_list(const Eo *obj) EINA_WARN_UNUSED_RESULT; 667 668 /** 669 * @brief Retrieves the object on the given evas with the given name. 670 * 671 * This looks for the evas object given a name by @ref evas_object_name_set. If 672 * the name is not unique canvas-wide, then which one of the many objects with 673 * that name is returned is undefined, so only use this if you can ensure the 674 * object name is unique. 675 * 676 * @param[in] obj The object. 677 * @param[in] name The given name. 678 * 679 * @return If successful, the Evas object with the given name. Otherwise, 680 * @c null. 681 * 682 * @ingroup Evas_Canvas 683 */ 684 EOAPI Efl_Canvas_Object *evas_canvas_object_name_find(const Eo *obj, const char *name) EINA_WARN_UNUSED_RESULT; 685 686 /** 687 * @brief Appends a font path to the list of font paths used by the given evas. 688 * 689 * @param[in] obj The object. 690 * @param[in] path The new font path. 691 * 692 * @ingroup Evas_Canvas 693 */ 694 EOAPI void evas_canvas_font_path_append(Eo *obj, const char *path) EINA_ARG_NONNULL(2); 695 696 /** Removes all font paths loaded into memory for the given evas. 697 * 698 * @ingroup Evas_Canvas 699 */ 700 EOAPI void evas_canvas_font_path_clear(Eo *obj); 701 702 /** 703 * @brief This function returns the nth touch point's coordinates. 704 * 705 * Touch point's coordinates is updated whenever moving that point on the 706 * canvas. 707 * 708 * @param[in] obj The object. 709 * @param[in] n The number of the touched point (0 being the first). 710 * @param[out] x Last known X position in window coordinates 711 * @param[out] y Last known Y position in window coordinates 712 * 713 * @ingroup Evas_Canvas 714 */ 715 EOAPI void evas_canvas_touch_point_list_nth_xy_get(Eo *obj, unsigned int n, double *x, double *y); 716 717 /** 718 * @brief Removes the @c keyname key from the current list of lock keys on 719 * canvas @c e. 720 * 721 * @param[in] obj The object. 722 * @param[in] keyname The name of the key to remove from the locks list. 723 * 724 * @ingroup Evas_Canvas 725 */ 726 EOAPI void evas_canvas_key_lock_del(Eo *obj, const char *keyname) EINA_ARG_NONNULL(2); 727 728 /** 729 * @brief Add a damage rectangle. 730 * 731 * This is the function by which one tells evas that a part of the canvas has 732 * to be repainted. 733 * 734 * @note All newly created Evas rectangles get the default color values of 255 735 * 255 255 255 (opaque white). 736 * 737 * @param[in] obj The object. 738 * @param[in] x The rectangle's left position. 739 * @param[in] y The rectangle's top position. 740 * @param[in] w The rectangle's width. 741 * @param[in] h The rectangle's height. 742 * 743 * @ingroup Evas_Canvas 744 */ 745 EOAPI void evas_canvas_damage_rectangle_add(Eo *obj, int x, int y, int w, int h); 746 747 /** Sync evas canvas 748 * 749 * @ingroup Evas_Canvas 750 */ 751 EOAPI void evas_canvas_sync(Eo *obj); 752 753 /** 754 * @brief Retrieves the list of font paths used by the given evas. 755 * 756 * @param[in] obj The object. 757 * 758 * @return The list of font paths used. 759 * 760 * @ingroup Evas_Canvas 761 */ 762 EOAPI const Eina_List *evas_canvas_font_path_list(const Eo *obj) EINA_WARN_UNUSED_RESULT; 763 764 /** 765 * @brief Reload the image cache. 766 * 767 * This function reloads the image cache of canvas. 768 * @param[in] obj The object. 769 * 770 * @ingroup Evas_Canvas 771 */ 772 EOAPI void evas_canvas_image_cache_reload(Eo *obj); 773 774 /** 775 * @brief Convert/scale a canvas coordinate into output screen coordinates. 776 * 777 * This function takes in a horizontal coordinate as the @c x parameter and 778 * converts it into output units, accounting for output size, viewport size and 779 * location, returning it as the function return value. If @c e is invalid, 780 * the results are undefined. 781 * 782 * @param[in] obj The object. 783 * @param[in] x The canvas X coordinate. 784 * 785 * @return The output/screen coordinate translated to output coordinates. 786 * 787 * @ingroup Evas_Canvas 788 */ 789 EOAPI int evas_canvas_coord_world_x_to_screen(const Eo *obj, int x) EINA_WARN_UNUSED_RESULT; 790 791 /** 792 * @brief Force immediate renderization of the given Evas canvas. 793 * 794 * This function forces an immediate renderization update of the given canvas 795 * @c e. 796 * 797 * @note This is a very low level function, which most of Evas' users wouldn't 798 * care about. You might use it, for instance, to grab an Evas' canvas update 799 * regions and paint them back, using the canvas' pixmap, on a displaying 800 * system working below Evas. 801 * 802 * @note Evas is a stateful canvas. If no operations changing its state took 803 * place since the last rendering action, you won't see any changes and this 804 * call will be a no-op. 805 * 806 * @param[in] obj The object. 807 * 808 * @return A newly allocated list of updated rectangles of the canvas 809 * (@ref Eina_Rect structs). Free this list with @ref evas_render_updates_free. 810 * 811 * @ingroup Evas_Canvas 812 */ 813 EOAPI Eina_List *evas_canvas_render_updates(Eo *obj) EINA_WARN_UNUSED_RESULT; 814 815 /** 816 * @brief Flush the image cache of the canvas. 817 * 818 * This function flushes image cache of canvas. 819 * @param[in] obj The object. 820 * 821 * @ingroup Evas_Canvas 822 */ 823 EOAPI void evas_canvas_image_cache_flush(Eo *obj); 824 825 /** 826 * @brief Convert/scale an output screen coordinate into canvas coordinates. 827 * 828 * This function takes in a vertical coordinate as the @c y parameter and 829 * converts it into canvas units, accounting for output size, viewport size and 830 * location, returning it as the function return value. If @c e is invalid, the 831 * results are undefined. 832 * 833 * @param[in] obj The object. 834 * @param[in] y The screen/output y coordinate. 835 * 836 * @return The screen coordinate translated to canvas unit coordinates. 837 * 838 * @ingroup Evas_Canvas 839 */ 840 EOAPI int evas_canvas_coord_screen_y_to_world(const Eo *obj, int y) EINA_WARN_UNUSED_RESULT; 841 842 /** 843 * @brief Removes the @c keyname key from the current list of modifier keys on 844 * canvas @c e. 845 * 846 * See also @ref evas_canvas_key_modifier_add. 847 * 848 * @param[in] obj The object. 849 * @param[in] keyname The name of the key to remove from the modifiers list. 850 * 851 * @ingroup Evas_Canvas 852 */ 853 EOAPI void evas_canvas_key_modifier_del(Eo *obj, const char *keyname) EINA_ARG_NONNULL(2); 854 855 /** Inform to the evas that it got the focus from the default seat. 856 * 857 * @ingroup Evas_Canvas 858 */ 859 EOAPI void evas_canvas_focus_in(Eo *obj); 860 861 /** 862 * @brief Inform to the evas that it got the focus from a given seat. 863 * 864 * @param[in] obj The object. 865 * @param[in] seat The seat or @c null for the default seat. 866 * 867 * @since 1.19 868 * 869 * @ingroup Evas_Canvas 870 */ 871 EOAPI void evas_canvas_seat_focus_in(Eo *obj, Evas_Device *seat); 872 873 /** 874 * @brief Inform to the evas that it lost the focus from a given seat. 875 * 876 * @param[in] obj The object. 877 * @param[in] seat The seat or @c null for the default seat. 878 * 879 * @since 1.19 880 * 881 * @ingroup Evas_Canvas 882 */ 883 EOAPI void evas_canvas_seat_focus_out(Eo *obj, Evas_Device *seat); 884 885 /** 886 * @brief Add an "obscured region" to an Evas canvas. 887 * 888 * This is the function by which one tells an Evas canvas that a part of it 889 * must not be repainted. The region must be rectangular and its coordinates 890 * inside the canvas viewport are passed in the call. After this call, the 891 * region specified won't participate in any form in Evas' calculations and 892 * actions during its rendering updates, having its displaying content frozen 893 * as it was just after this function took place. 894 * 895 * We call it "obscured region" because the most common use case for this 896 * rendering (partial) freeze is something else (most probably other canvas) 897 * being on top of the specified rectangular region, thus shading it completely 898 * from the user's final scene in a display. To avoid unnecessary processing, 899 * one should indicate to the obscured canvas not to bother about the 900 * non-important area. 901 * 902 * The majority of users won't have to worry about this function, as they'll be 903 * using just one canvas in their applications, with nothing inset or on top of 904 * it in any form. 905 * 906 * To make this region one that has to be repainted again, call the function 907 * @ref evas_obscured_clear. 908 * 909 * @note This is a very low level function, which most of Evas' users wouldn't 910 * care about. 911 * 912 * @note This function does not flag the canvas as having its state changed. If 913 * you want to re-render it afterwards expecting new contents, you have to add 914 * "damage" regions yourself (see @ref evas_damage_rectangle_add). 915 * 916 * @param[in] obj The object. 917 * @param[in] x The rectangle's top left corner's horizontal coordinate. 918 * @param[in] y The rectangle's top left corner's vertical coordinate. 919 * @param[in] w The rectangle's width. 920 * @param[in] h The rectangle's height. 921 * 922 * @ingroup Evas_Canvas 923 */ 924 EOAPI void evas_canvas_obscured_rectangle_add(Eo *obj, int x, int y, int w, int h); 925 926 /** 927 * @brief Make the canvas discard as much data as possible used by the engine 928 * at runtime. 929 * 930 * This function will unload images, delete textures and much more where 931 * possible. You may also want to call @ref evas_canvas_render_idle_flush 932 * immediately prior to this to perhaps discard a little more, though this 933 * function should implicitly delete most of what 934 * @ref evas_canvas_render_idle_flush might discard too. 935 * @param[in] obj The object. 936 * 937 * @ingroup Evas_Canvas 938 */ 939 EOAPI void evas_canvas_render_dump(Eo *obj); 940 941 /** Force renderization of the given canvas. 942 * 943 * @ingroup Evas_Canvas 944 */ 945 EOAPI void evas_canvas_render(Eo *obj); 946 947 /** 948 * @brief Prepends a font path to the list of font paths used by the given 949 * evas. 950 * 951 * @param[in] obj The object. 952 * @param[in] path The new font path. 953 * 954 * @ingroup Evas_Canvas 955 */ 956 EOAPI void evas_canvas_font_path_prepend(Eo *obj, const char *path) EINA_ARG_NONNULL(2); 957 958 /** 959 * @brief Remove all "obscured regions" from an Evas canvas. 960 * 961 * This function removes all the rectangles from the obscured regions list of 962 * the canvas @c e. It takes obscured areas added with 963 * @ref evas_canvas_obscured_rectangle_add and make them again a regions that 964 * have to be repainted on rendering updates. 965 * 966 * @note This is a very low level function, which most of Evas' users wouldn't 967 * care about. 968 * 969 * @note This function does not flag the canvas as having its state changed. If 970 * you want to re-render it afterwards expecting new contents, you have to add 971 * "damage" regions yourself (see @ref evas_canvas_damage_rectangle_add). 972 * @param[in] obj The object. 973 * 974 * @ingroup Evas_Canvas 975 */ 976 EOAPI void evas_canvas_obscured_clear(Eo *obj); 977 978 /** 979 * @brief Convert/scale an output screen coordinate into canvas coordinates. 980 * 981 * This function takes in a horizontal coordinate as the @c x parameter and 982 * converts it into canvas units, accounting for output size, viewport size and 983 * location, returning it as the function return value. If @c e is invalid, the 984 * results are undefined. 985 * 986 * @param[in] obj The object. 987 * @param[in] x The screen/output x coordinate. 988 * 989 * @return The screen coordinate translated to canvas unit coordinates. 990 * 991 * @ingroup Evas_Canvas 992 */ 993 EOAPI int evas_canvas_coord_screen_x_to_world(const Eo *obj, int x) EINA_WARN_UNUSED_RESULT; 994 995 /** 996 * @brief Adds the @c keyname key to the current list of lock keys. 997 * 998 * Locks are keys like caps lock, num lock or scroll lock, i.e., keys which are 999 * meant to be pressed once -- toggling a binary state which is bound to it -- 1000 * and thus altering the behavior of all subsequently pressed keys somehow, 1001 * depending on its state. Evas is so that these keys can be defined by the 1002 * user. 1003 * 1004 * This allows custom locks to be added to the evas system at run time. It is 1005 * then possible to set and unset lock keys programmatically for other parts of 1006 * the program to check and act on. Programmers using Evas would check for lock 1007 * keys on key event callbacks using @ref evas_key_lock_is_set. 1008 * 1009 * @note If the programmer instantiates the canvas by means of the 1010 * ecore_evas_new() family of helper functions, Ecore will take care of 1011 * registering on it all standard lock keys: "Caps_Lock", "Num_Lock", 1012 * "Scroll_Lock". 1013 * 1014 * @param[in] obj The object. 1015 * @param[in] keyname The name of the key to add to the locks list. 1016 * 1017 * @ingroup Evas_Canvas 1018 */ 1019 EOAPI void evas_canvas_key_lock_add(Eo *obj, const char *keyname) EINA_ARG_NONNULL(2); 1020 1021 /** 1022 * @brief Make the canvas discard internally cached data used for rendering. 1023 * 1024 * This function flushes the arrays of delete, active and render objects. Other 1025 * things it may also discard are: shared memory segments, temporary scratch 1026 * buffers, cached data to avoid re-compute of that data etc. 1027 * @param[in] obj The object. 1028 * 1029 * @ingroup Evas_Canvas 1030 */ 1031 EOAPI void evas_canvas_render_idle_flush(Eo *obj); 1032 1033 /** 1034 * @brief Return the default device of a given type. 1035 * 1036 * @note Currently EFL only creates a seat, mouse and keyboard. 1037 * 1038 * @param[in] obj The object. 1039 * @param[in] type The class of the default device to fetch. 1040 * 1041 * @return The default device or @c null on error. 1042 * 1043 * @since 1.19 1044 * 1045 * @ingroup Evas_Canvas 1046 */ 1047 EOAPI Evas_Device *evas_canvas_default_device_get(const Eo *obj, Evas_Device_Class type); 1048 1049 /** 1050 * @brief Convert/scale a canvas coordinate into output screen coordinates. 1051 * 1052 * This function takes in a vertical coordinate as the @c x parameter and 1053 * converts it into output units, accounting for output size, viewport size and 1054 * location, returning it as the function return value. If @c e is invalid, the 1055 * results are undefined. 1056 * 1057 * @param[in] obj The object. 1058 * @param[in] y The canvas y coordinate. 1059 * 1060 * @return The output/screen coordinate translated to output coordinates. 1061 * 1062 * @ingroup Evas_Canvas 1063 */ 1064 EOAPI int evas_canvas_coord_world_y_to_screen(const Eo *obj, int y) EINA_WARN_UNUSED_RESULT; 1065 1066 #endif 1067