In this example, we illustrate how to create and handle Evas smart objects.

A smart object is one that provides custom functions to handle clipping, hiding, moving, resizing, color setting and more on child elements, automatically, for the smart object's user. They could be as simple as a group of objects that move together (see Evas_Smart_Object_Clipped) or implementations of whole complex UI widgets, providing some intelligence (thus the name) and extension to simple Evas objects.

Here, we create one as an example. What it does is to control (at maximum) 2 child objects, with regard to their geometries and colors. There can be a "left" child and a "right" one. The former will always occupy the top left quadrant of the smart object's area, while the latter will occupy the bottom right. The smart object will also contain an internal decorative border object, which will also be controlled by it, naturally.

Here is where we add it to the canvas:

The magic starts to happen in the evas_smart_example_add() function, which is one in the example smart object's defined interface. These should be the functions you would export to the users of your smart object. We made three for this one:

• evas_smart_example_add(): add a new instance of the example smart object to a canvas
• evas_smart_example_remove(): remove a given child of the smart object from it
• evas_smart_example_set_left(): set the left child of the smart object
• evas_smart_example_set_right(): set the right child of the smart object

The object's creation takes place as:

Smart objects are defined by smart classes, which are structs defining their interfaces, or smart functions (see Evas_Smart_Class, the base class for any smart object). As you see, one has to use the evas_object_smart_add() function to instantiate smart objects. Its second parameter is what matters -- an Evas_Smart struct, which contains all the smart class definitions (smart functions, smart callbacks, and the like). Note, however, that _evas_smart_example_smart_class_new() seems not to be defined in our example's code. That's because it came from a very handy helper macro:

The first argument to the macro,

The first function pointer's code will take place at an example smart object's creation time:

The #EVAS_SMART_DATA_ALLOC macro will take care of allocating our smart object data, which will be available on other contexts for us (mainly in our interface functions):

See that, as we're inheriting from the clipped smart object's class, we must have their data struct as our first member. Other data of interest for us is a child members array and the border object's handle. The latter is what is created in the last mentioned function. Note how to tell Evas the border will be managed by our smart object from that time on: evas_object_smart_member_add(priv->border, o);. The counterpart of this function is exemplified on the smart object's interface function to remove children:

At the end of that function we make use of an constant defined by the #EVAS_SMART_SUBCLASS_NEW: _evas_smart_example_parent_sc. It has the same prefix we passed to the macro, as you can see, and it holds a pointer to our parent smart class. Then, we can call the specialized method, itself, after our code. The del, hide, show and resize specializations are straightforward, we let the reader take a look at them below to check their behavior. What's interesting is the calculate one:

This code will take place whenever the smart object itself is flagged "dirty", i.e., must be recalculated for rendering (that could come from changes on its clipper, resizing, moving, etc). There, we make sure the decorative border lies on the edges of the smart object and the children, if any, lie on their respective quadrants.

After instantiating our smart object, we do some checks to exemplify some of the API on smart objects:

Other important things we also exemplify here are smart callbacks and smart callback introspection:

Here we declare our array of smart callback descriptions, which has one element only, in this case. That callback will take place, as the name indicates, whenever the number of member objects in our smart object example instance changes. That global array variable must be the last argument to #EVAS_SMART_SUBCLASS_NEW, so that it's registered as the smart class's callbacks description.

After we instantiate the smart object, we take a look on those descriptions and register a callback on that unique smart event:

The code of the callback will just print how many member objects we have, which is an integer argument of the callback itself, as flagged by its description:

One of the points at which we issue that callback is inside the evas_smart_example_remove(), code that was already shown.

As in other examples, to interact with this one there's a command line interface. A help string can be asked for with the 'h' key:

"Real life" examples of smart objects are Edje and Emotion objects: they both have independent libraries implementing their behavior. The full example follows.