From 5280246cde290e81c93b88b14820e7197b8db12a Mon Sep 17 00:00:00 2001 From: gastal Date: Tue, 2 Aug 2011 17:02:07 +0000 Subject: [PATCH] Ecore: ecore_evas_object documentation. git-svn-id: svn+ssh://svn.enlightenment.org/var/svn/e/trunk/ecore@62016 7cbeb6ba-43b4-40fd-8cce-4c39aea84d33 --- doc/examples.dox | 33 ++++++++++ src/examples/Makefile.am | 7 +- src/examples/ecore_evas_object_example.c | 52 +++++++++++++++ src/lib/ecore_evas/Ecore_Evas.h | 107 ++++++++++++++++++++++++++++++- src/lib/ecore_evas/ecore_evas.c | 36 ----------- src/lib/ecore_evas/ecore_evas_util.c | 48 -------------- 6 files changed, 195 insertions(+), 88 deletions(-) create mode 100644 src/examples/ecore_evas_object_example.c diff --git a/doc/examples.dox b/doc/examples.dox index 9ac9131..cb63847 100644 --- a/doc/examples.dox +++ b/doc/examples.dox @@ -15,6 +15,7 @@ * @li @ref ecore_con_server_simple_example_c * @li @ref ecore_con_client_simple_example_c * @li @ref ecore_evas_callbacks_example_c + * @li @ref ecore_evas_object_example_c * */ @@ -1292,3 +1293,35 @@ * @include ecore_evas_window_sizes_example.c * @example ecore_evas_window_sizes_example.c */ + +/** + * @page ecore_evas_object_example_c Ecore Evas Object example + * @dontinclude ecore_evas_object_example.c + * + * This example creates an Ecore_Evas(a window) and associates a background and + * a custom cursor for it. + * + * We'll start looking at the association, which is quite simple. We choose to + * associate using ECORE_EVAS_OBJECT_ASSOCIATE_BASE to have it be resized with + * the window, since for a background that is what's most useful: + * @skipline ecore_evas_object_associate + * @note If we didn't associate the background we'd need to listen to resize of + * Ecore_Evas and manually resize the background or have artifacts on our + * window. + * + * We then check that the association worked: + * @until printf + * + * Next we are going to set a custom cursor, for our cursor we are going to use + * a small green rectangle. Our cursor is going to be on layer 0(any lower and + * it would be below the background and thus invisible) and clicks will be + * computed as happening on pixel 1, 1 of the image: + * @until cursor_set + * + * We then check every one of those parameters: + * @until printf + * + * Here you have the full-source of the code: + * @include ecore_evas_object_example.c + * @example ecore_evas_object_example.c + */ diff --git a/src/examples/Makefile.am b/src/examples/Makefile.am index df13e74..27d05b1 100644 --- a/src/examples/Makefile.am +++ b/src/examples/Makefile.am @@ -45,7 +45,8 @@ SRCS = \ ecore_pipe_gstreamer_example.c \ ecore_thread_example.c \ ecore_evas_callbacks.c \ - ecore_evas_window_sizes_example.c + ecore_evas_window_sizes_example.c \ + ecore_evas_object_example.c EXTRA_DIST = $(SRCS) @@ -76,9 +77,9 @@ pkglib_PROGRAMS += \ ecore_con_client_simple_example \ ecore_thread_example \ ecore_evas_callbacks \ - ecore_evas_window_sizes_example + ecore_evas_window_sizes_example \ + ecore_evas_object_example -ecore_animator_example_LDADD = $(ECOREBASELDADD) @EVAS_LIBS@ $(top_builddir)/src/lib/ecore_evas/libecore_evas.la ecore_con_lookup_example_LDADD = $(ECOREBASELDADD) $(top_builddir)/src/lib/ecore_con/libecore_con.la ecore_con_url_headers_example_LDADD = $(ECOREBASELDADD) $(top_builddir)/src/lib/ecore_con/libecore_con.la ecore_con_url_download_example_LDADD = $(ECOREBASELDADD) $(top_builddir)/src/lib/ecore_con/libecore_con.la diff --git a/src/examples/ecore_evas_object_example.c b/src/examples/ecore_evas_object_example.c new file mode 100644 index 0000000..33da234 --- /dev/null +++ b/src/examples/ecore_evas_object_example.c @@ -0,0 +1,52 @@ +/** + * Ecore example illustrating ecore evas object usage. + * + * You'll need at least one Evas engine built for it (excluding the + * buffer one). See stdout/stderr for output. + * + * @verbatim + * gcc -o ecore_evas_object_example ecore_evas_object_example.c `pkg-config --libs --cflags ecore-evas` + * @endverbatim + */ + +#include +#include + +int +main(void) +{ + Ecore_Evas *ee; + Evas_Object *bg, *cursor, *obj; + int layer, x, y; + + ecore_evas_init(); + + ee = ecore_evas_new(NULL, 0, 0, 200, 200, NULL); + ecore_evas_title_set(ee, "Ecore Evas Object Example"); + ecore_evas_show(ee); + + bg = evas_object_rectangle_add(ecore_evas_get(ee)); + evas_object_color_set(bg, 0, 0, 255, 255); + evas_object_resize(bg, 200, 200); + evas_object_show(bg); + ecore_evas_object_associate(ee, bg, ECORE_EVAS_OBJECT_ASSOCIATE_BASE); + + if(bg == ecore_evas_object_associate_get(ee)) + printf("Association worked!\n"); + + cursor = evas_object_rectangle_add(ecore_evas_get(ee)); + evas_object_color_set(cursor, 0, 255, 0, 255); + evas_object_resize(cursor, 5, 10); + ecore_evas_object_cursor_set(ee, cursor, 0, 1, 1); + + ecore_evas_cursor_get(ee, &obj, &layer, &x, &y); + if(obj == cursor && layer == 0 && x == 1 && y == 1) + printf("Set cursor worked!\n"); + + ecore_main_loop_begin(); + + ecore_evas_free(ee); + ecore_evas_shutdown(); + + return 0; +} diff --git a/src/lib/ecore_evas/Ecore_Evas.h b/src/lib/ecore_evas/Ecore_Evas.h index 9a88477..d602e4a 100644 --- a/src/lib/ecore_evas/Ecore_Evas.h +++ b/src/lib/ecore_evas/Ecore_Evas.h @@ -37,6 +37,7 @@ * * The following is a list of example that partially exemplify Ecore_Evas's API: * @li @ref ecore_evas_callbacks_example_c + * @li @ref ecore_evas_object_example_c */ /* FIXME: @@ -604,9 +605,59 @@ EAPI void ecore_evas_size_step_set(Ecore_Evas *ee, int w, int h); */ EAPI void ecore_evas_size_step_get(const Ecore_Evas *ee, int *w, int *h); +/** + * @brief Set the cursor of an Ecore_Evas. + * + * @param ee The Ecore_Evas + * @param file The path to an image file for the cursor. + * @param layer The layer in which the cursor will appear. + * @param hot_x The x coordinate of the cursor's hot spot. + * @param hot_y The y coordinate of the cursor's hot spot. + * + * This function makes the mouse cursor over @p ee be the image specified by + * @p file. The actual point within the image that the mouse is at is specified + * by @p hot_x and @p hot_y, which are coordinates with respect to the top left + * corner of the cursor image. + * + * @note This function creates an object from the image and uses + * ecore_evas_object_cursor_set(). + * + * @see ecore_evas_object_cursor_set() + */ EAPI void ecore_evas_cursor_set(Ecore_Evas *ee, const char *file, int layer, int hot_x, int hot_y); -EAPI void ecore_evas_object_cursor_set(Ecore_Evas *ee, Evas_Object *obj, int layer, int hot_x, int hot_y); +/** + * @brief Get information about an Ecore_Evas' cursor + * + * @param ee The Ecore_Evas to set + * @param obj A pointer to an Evas_Object to place the cursor Evas_Object. + * @param layer A pointer to an int to place the cursor's layer in. + * @param hot_x A pointer to an int to place the cursor's hot_x coordinate in. + * @param hot_y A pointer to an int to place the cursor's hot_y coordinate in. + * + * This function queries information about an Ecore_Evas' cursor. + * + * @see ecore_evas_cursor_set() + * @see ecore_evas_object_cursor_set() + */ EAPI void ecore_evas_cursor_get(const Ecore_Evas *ee, Evas_Object **obj, int *layer, int *hot_x, int *hot_y); +/** + * @brief Set the cursor of an Ecore_Evas + * + * @param ee The Ecore_Evas + * + * @param obj The Evas_Object which will be the cursor. + * @param layer The layer in which the cursor will appear. + * @param hot_x The x coordinate of the cursor's hot spot. + * @param hot_y The y coordinate of the cursor's hot spot. + * + * This function makes the mouse cursor over @p ee be the object specified by + * @p obj. The actual point within the object that the mouse is at is specified + * by @p hot_x and @p hot_y, which are coordinates with respect to the top left + * corner of the cursor object. + * + * @see ecore_evas_cursor_set() + */ +EAPI void ecore_evas_object_cursor_set(Ecore_Evas *ee, Evas_Object *obj, int layer, int hot_x, int hot_y); EAPI void ecore_evas_layer_set(Ecore_Evas *ee, int layer); EAPI int ecore_evas_layer_get(const Ecore_Evas *ee); EAPI void ecore_evas_focus_set(Ecore_Evas *ee, Eina_Bool on); @@ -639,8 +690,62 @@ EAPI Ecore_Window ecore_evas_window_get(const Ecore_Evas *ee); EAPI void ecore_evas_screen_geometry_get(const Ecore_Evas *ee, int *x, int *y, int *w, int *h); +/** + * @brief Associate the given object to this ecore evas. + * + * @param ee The Ecore_Evas to associate to @a obj + * @param obj The object to associate to @a ee + * @param flags The association flags. + * @return EINA_TRUE on success, EINA_FALSE otherwise. + * + * Association means that operations on one will affect the other, for + * example moving the object will move the window, resize the object will + * also affect the ecore evas window, hide and show applies as well. + * + * This is meant to simplify development, since you often need to associate + * these events with your "base" objects, background or bottom-most object. + * + * Be aware that some methods might not be what you would like, deleting + * either the window or the object will delete the other. If you want to + * change that behavior, let's say to hide window when it's closed, you + * must use ecore_evas_callback_delete_request_set() and set your own code, + * like ecore_evas_hide(). Just remember that if you override delete_request + * and still want to delete the window/object, you must do that yourself. + * + * Since we now define delete_request, deleting windows will not quit + * main loop, if you wish to do so, you should listen for EVAS_CALLBACK_FREE + * on the object, that way you get notified and you can call + * ecore_main_loop_quit(). + * + * Flags can be OR'ed of: + * @li ECORE_EVAS_OBJECT_ASSOCIATE_BASE (or 0): to listen to basic events + * like delete, resize and move, but no stacking or layer are used. + * @li ECORE_EVAS_OBJECT_ASSOCIATE_STACK: stacking operations will act + * on the Ecore_Evas, not the object. So evas_object_raise() will + * call ecore_evas_raise(). Relative operations (stack_above, stack_below) + * are still not implemented. + * @li ECORE_EVAS_OBJECT_ASSOCIATE_LAYER: stacking operations will act + * on the Ecore_Evas, not the object. So evas_object_layer_set() will + * call ecore_evas_layer_set(). + * @li ECORE_EVAS_OBJECT_ASSOCIATE_DEL: the object delete will delete the + * ecore_evas as well as delete_requests on the ecore_evas will delete + * etc. + */ EAPI Eina_Bool ecore_evas_object_associate(Ecore_Evas *ee, Evas_Object *obj, Ecore_Evas_Object_Associate_Flags flags); +/** + * @brief Cancel the association set with ecore_evas_object_associate(). + * + * @param ee The Ecore_Evas to dissociate from @a obj + * @param obj The object to dissociate from @a ee + * @return EINA_TRUE on success, EINA_FALSE otherwise. + */ EAPI Eina_Bool ecore_evas_object_dissociate(Ecore_Evas *ee, Evas_Object *obj); +/** + * @brief Get the object associated with @p ee + * + * @param ee The Ecore_Evas to get the object from. + * @return The associated object, or NULL if there is no associated object. + */ EAPI Evas_Object *ecore_evas_object_associate_get(const Ecore_Evas *ee); /* helper function to be used with ECORE_GETOPT_CALLBACK_*() */ diff --git a/src/lib/ecore_evas/ecore_evas.c b/src/lib/ecore_evas/ecore_evas.c index d2883c1..7404a3c 100644 --- a/src/lib/ecore_evas/ecore_evas.c +++ b/src/lib/ecore_evas/ecore_evas.c @@ -1870,19 +1870,6 @@ ecore_evas_size_step_get(const Ecore_Evas *ee, int *w, int *h) } } -/** - * Set the cursor of an Ecore_Evas - * @param ee The Ecore_Evas - * @param file The path to an image file for the cursor - * @param layer - * @param hot_x The x coordinate of the cursor's hot spot - * @param hot_y The y coordinate of the cursor's hot spot - * - * This function makes the mouse cursor over @p ee be the image specified by - * @p file. The actual point within the image that the mouse is at is specified - * by @p hot_x and @p hot_y, which are coordinates with respect to the top left - * corner of the cursor image. - */ EAPI void ecore_evas_cursor_set(Ecore_Evas *ee, const char *file, int layer, int hot_x, int hot_y) { @@ -1910,19 +1897,6 @@ ecore_evas_cursor_set(Ecore_Evas *ee, const char *file, int layer, int hot_x, in IFE; } -/** - * Set the cursor of an Ecore_Evas - * @param ee The Ecore_Evas - * @param obj The Evas_Object for the cursor - * @param layer - * @param hot_x The x coordinate of the cursor's hot spot - * @param hot_y The y coordinate of the cursor's hot spot - * - * This function makes the mouse cursor over @p ee be the image specified by - * @p file. The actual point within the image that the mouse is at is specified - * by @p hot_x and @p hot_y, which are coordinates with respect to the top left - * corner of the cursor image. - */ EAPI void ecore_evas_object_cursor_set(Ecore_Evas *ee, Evas_Object *obj, int layer, int hot_x, int hot_y) { @@ -1936,16 +1910,6 @@ ecore_evas_object_cursor_set(Ecore_Evas *ee, Evas_Object *obj, int layer, int ho IFE; } -/** - * Get information about an Ecore_Evas' cursor - * @param ee The Ecore_Evas to set - * @param obj A pointer to an Evas_Object to place the cursor Evas_Object. - * @param layer A pointer to an int to place the cursor's layer in.. - * @param hot_x A pointer to an int to place the cursor's hot_x coordinate in. - * @param hot_y A pointer to an int to place the cursor's hot_y coordinate in. - * - * This function queries information about an Ecore_Evas' cursor. - */ EAPI void ecore_evas_cursor_get(const Ecore_Evas *ee, Evas_Object **obj, int *layer, int *hot_x, int *hot_y) { diff --git a/src/lib/ecore_evas/ecore_evas_util.c b/src/lib/ecore_evas/ecore_evas_util.c index 4db59b2..96ccae3 100644 --- a/src/lib/ecore_evas/ecore_evas_util.c +++ b/src/lib/ecore_evas/ecore_evas_util.c @@ -217,47 +217,6 @@ _ecore_evas_object_evas_check(const char *function, const Ecore_Evas *ee, const return 0; } -/** - * Associate the given object to this ecore evas. - * - * Association means that operations on one will affect the other, for - * example moving the object will move the window, resize the object will - * also affect the ecore evas window, hide and show applies as well. - * - * This is meant to simplify development, since you often need to associate - * these events with your "base" objects, background or bottom-most object. - * - * Be aware that some methods might not be what you would like, deleting - * either the window or the object will delete the other. If you want to - * change that behavior, let's say to hide window when it's closed, you - * must use ecore_evas_callback_delete_request_set() and set your own code, - * like ecore_evas_hide(). Just remember that if you override delete_request - * and still want to delete the window/object, you must do that yourself. - * - * Since we now define delete_request, deleting windows will not quit - * main loop, if you wish to do so, you should listen for EVAS_CALLBACK_FREE - * on the object, that way you get notified and you can call - * ecore_main_loop_quit(). - * - * Flags can be OR'ed of: - * - ECORE_EVAS_OBJECT_ASSOCIATE_BASE (or 0): to listen to basic events - * like delete, resize and move, but no stacking or layer are used. - * - ECORE_EVAS_OBJECT_ASSOCIATE_STACK: stacking operations will act - * on the Ecore_Evas, not the object. So evas_object_raise() will - * call ecore_evas_raise(). Relative operations (stack_above, stack_below) - * are still not implemented. - * - ECORE_EVAS_OBJECT_ASSOCIATE_LAYER: stacking operations will act - * on the Ecore_Evas, not the object. So evas_object_layer_set() will - * call ecore_evas_layer_set(). - * - ECORE_EVAS_OBJECT_ASSOCIATE_DEL: the object delete will delete the - * ecore_evas as well as delete_requests on the ecore_evas will delete - * etc. - * - * @param ee The Ecore_Evas to associate to @a obj - * @param obj The object to associate to @a ee - * @param flags The association flags. - * @return EINA_TRUE on success, EINA_FALSE otherwise. - */ EAPI Eina_Bool ecore_evas_object_associate(Ecore_Evas *ee, Evas_Object *obj, Ecore_Evas_Object_Associate_Flags flags) { @@ -286,13 +245,6 @@ ecore_evas_object_associate(Ecore_Evas *ee, Evas_Object *obj, Ecore_Evas_Object_ return EINA_TRUE; } -/** - * Cancel the association set with ecore_evas_object_associate(). - * - * @param ee The Ecore_Evas to dissociate from @a obj - * @param obj The object to dissociate from @a ee - * @return EINA_TRUE on success, EINA_FALSE otherwise. - */ EAPI Eina_Bool ecore_evas_object_dissociate(Ecore_Evas *ee, Evas_Object *obj) { -- 2.7.4