Rectangle Object Functions
Evas » Specific 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.

## 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);
evas_object_show
EVAS_API void evas_object_show(Evas_Object *eo_obj)
Makes the given Evas object visible.
Definition evas_object_main.c:1814
evas_object_color_set
EVAS_API void evas_object_color_set(Evas_Object *obj, int r, int g, int b, int a)
Sets the general/main color of the given Evas object to the given one.
Definition evas_object_main.c:2024
Evas_Object
Efl_Canvas_Object Evas_Object
An Evas Object handle.
Definition Evas_Common.h:185
evas_object_resize
EVAS_API void evas_object_resize(Evas_Object *obj, Evas_Coord w, Evas_Coord h)
Changes the size of the given Evas object.
Definition evas_object_main.c:1236
evas_object_rectangle_add
EVAS_API Evas_Object * evas_object_rectangle_add(Evas *e)
Adds a rectangle to the given evas.
Definition evas_object_rectangle.c:78

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);
ecore_evas_get
EAPI Evas * ecore_evas_get(const Ecore_Evas *ee)
Gets an Ecore_Evas's Evas.
Definition ecore_evas.c:1314
ecore_evas_object_associate
EAPI Eina_Bool ecore_evas_object_associate(Ecore_Evas *ee, Evas_Object *obj, Ecore_Evas_Object_Associate_Flags flags)
Associates the given object to this ecore evas.
Definition ecore_evas_util.c:223

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);
evas_object_move
EVAS_API void evas_object_move(Evas_Object *obj, Evas_Coord x, Evas_Coord y)
Move the given Evas object to the given location inside its canvas' viewport.
Definition evas_object_main.c:1171
evas_object_clip_set
EVAS_API void evas_object_clip_set(Efl_Canvas_Object *obj, Efl_Canvas_Object *clipper)
Clip one object to another.
Definition efl_canvas_object_eo.legacy.c:15

## 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().