Rectangle Object Functions

Function to create evas rectangle objects. More...

EVAS_API Evas_Object *	evas_object_rectangle_add (Evas *e)
	Adds a rectangle to the given evas. More...

Detailed Description

Function to create evas rectangle objects.

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 evas object functions.

The evas rectangle serves a number of key functions when working on evas programs:

• Background
• Debugging
• Clipper

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:

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);

This will have issues if the evas_canvas is resized, however most windows are created using ecore evas and that has a solution to using the rectangle as a background:

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);

So this gives us a white background to our window that will be resized together with it.

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.

Clipping

Clipping serves two main functions:

• Limiting visibility(i.e. hiding portions of an object).
• Applying a layer of color to an object.

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 my_evas_object:

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);

Layer of color

In the Clipping section we used a solid white clipper that 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 color of 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:

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);

Warning

We don't guarantee any proper results if you create a Rectangle object without setting the evas engine.

For an example that more fully exercise the use of an evas object rectangle see Evas objects basic manipulation example.

Function Documentation

evas_object_rectangle_add()

EVAS_API Evas_Object * evas_object_rectangle_add

(

Evas *

e

)

Adds a rectangle to the given evas.

Parameters

e	The given evas.

Returns

The new rectangle object.

References EINA_SAFETY_ON_FALSE_RETURN_VAL, and EVAS_CANVAS_CLASS.

Referenced by edje_perspective_new().