From cbff250f77c0744fd8e991f2b520cd638fdb8209 Mon Sep 17 00:00:00 2001 From: "Jonas M. Gastal" Date: Thu, 23 Feb 2012 18:14:30 +0000 Subject: [PATCH] Better evas rectangle docs. SVN revision: 68356 --- legacy/evas/src/lib/Evas.h | 98 +++++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 92 insertions(+), 6 deletions(-) diff --git a/legacy/evas/src/lib/Evas.h b/legacy/evas/src/lib/Evas.h index bfb1d48..82ec1ac 100644 --- a/legacy/evas/src/lib/Evas.h +++ b/legacy/evas/src/lib/Evas.h @@ -6124,13 +6124,99 @@ EAPI void *evas_object_intercept_move_callback_del (Evas_Obje * * @brief Function to create evas rectangle objects. * - * This function may seem useless given there are no functions to manipulate - * the created rectangle, however the rectangle is actually very useful and can - * be manipulate using the generic @ref Evas_Object_Group - * "evas object functions". + * There is only one function to deal with rectangle objects, this may make this + * function seem useless given there are no functions to manipulate the created + * rectangle, however the rectangle is actually very useful and should be + * manipulated using the generic @ref Evas_Object_Group "evas object functions". * - * For an example of use of an evas_object_rectangle see @ref - * Example_Evas_Object_Manipulation "here". + * The evas rectangle server a number of key functions when working on evas + * programs: + * @li Background + * @li Debugging + * @li Clipper + * + * @section Background + * + * One extremely common requirement of evas programs is to have a solid color + * background, this can be accomplished with the following very simple code: + * @code + * Evas_Object *bg = evas_object_rectangle_add(evas_canvas); + * //Here we set the rectangles red, green, blue and opacity levels + * evas_object_color_set(bg, 255, 255, 255, 255); // opaque white background + * evas_object_resize(bg, WIDTH, HEIGHT); // covers full canvas + * evas_object_show(bg); + * @endcode + * + * This however will have issues if the @c evas_canvas is resized, however most + * windows are created using ecore evas and that has a solution to using the + * rectangle as a background: + * @code + * Evas_Object *bg = evas_object_rectangle_add(ecore_evas_get(ee)); + * //Here we set the rectangles red, green, blue and opacity levels + * evas_object_color_set(bg, 255, 255, 255, 255); // opaque white background + * evas_object_resize(bg, WIDTH, HEIGHT); // covers full canvas + * evas_object_show(bg); + * ecore_evas_object_associate(ee, bg, ECORE_EVAS_OBJECT_ASSOCIATE_BASE); + * @endcode + * So this gives us a white background to our window that will be resized + * together with it. + * + * @section Debugging + * + * Debugging is a major part of any programmers task and when debugging visual + * issues with evas programs the rectangle is an extremely useful tool. The + * rectangle's simplicity means that it's easier to pinpoint issues with it than + * with more complex objects. Therefore a common technique to use when writing + * an evas program and not getting the desired visual result is to replace the + * misbehaving object for a solid color rectangle and seeing how it interacts + * with the other elements, this often allows us to notice clipping, parenting + * or positioning issues. Once the issues have been identified and corrected the + * rectangle can be replaced for the original part and in all likelihood any + * remaining issues will be specific to that object's type. + * + * @section clipping Clipping + * + * Clipping serves two main functions: + * @li Limiting visibility(i.e. hiding portions of an object). + * @li Applying a layer of color to an object. + * + * @subsection hiding Limiting visibility + * + * It is often necessary to show only parts of an object, while it may be + * possible to create an object that corresponds only to the part that must be + * shown(and it isn't always possible) it's usually easier to use a a clipper. A + * clipper is a rectangle that defines what's visible and what is not. The way + * to do this is to create a solid white rectangle(which is the default, no need + * to call evas_object_color_set()) and give it a position and size of what + * should be visible. The following code exemplifies showing the center half of + * @c my_evas_object: + * @code + * Evas_Object *clipper = evas_object_rectangle_add(evas_canvas); + * evas_object_move(clipper, my_evas_object_x / 4, my_evas_object_y / 4); + * evas_object_resize(clipper, my_evas_object_width / 2, my_evas_object_height / 2); + * evas_object_clip_set(my_evas_object, clipper); + * evas_object_show(clipper); + * @endcode + * + * @subsection color Layer of color + * + * In the @ref clipping section we used a solid white clipper, which produced no + * change in the color of the clipped object, it just hid what was outside the + * clippers area. It is however sometimes desirable to change the of color an + * object, this can be accomplished using a clipper that has a non-white color. + * Clippers with color work by multiplying the colors of clipped object. The + * following code will show how to remove all the red from an object: + * @code + * Evas_Object *clipper = evas_object_rectangle_add(evas); + * evas_object_move(clipper, my_evas_object_x, my_evas_object_y); + * evas_object_resize(clipper, my_evas_object_width, my_evas_object_height); + * evas_object_color_set(clipper, 0, 255, 255, 255); + * evas_object_clip_set(obj, clipper); + * evas_object_show(clipper); + * @endcode + * + * For an example that more fully exercise the use of an evas object rectangle + * see @ref Example_Evas_Object_Manipulation. * * @ingroup Evas_Object_Specific */ -- 2.7.4