Background Knowledge: Using DALi More Effectively

+ +

This section describes useful background knowledge that enables you to use DALi more effectively. + +

Handle/Body Pattern

+ +

DALi widely adopts the handle/body pattern (a.k.a. pimpl pattern) which seperates implementation details (the body class) from its interface (the handle class). In DALi, Dali::Handle represents the interface part and hides internal implementation classes. It additionally provides smart-pointer semantics which manages internal objects with reference counts. +

+ +

This structure is benificial for both users and developers of DALi:

Easier memory management +
Each internal Dali::Object class (the body class) contains a single reference count object which can be intitialized with the static "New" methods in the DALi public API. This means that C++ new/delete operators do not have to be used in the user code.
+
Better encapsulation +
The danger of API/ABI breaks is reduced since the implementation of a class can be changed without modifying the public API, thus without recompiling code using the public API. This also can reduce the build time.
+

+ +

Guide for Handles

+ +

No need to call destructors +

+class HandleTest
+{
+  HandleTest()
+  {
+    mActor = Actor::New();
+  }
+
+  ~HandleTest() {} // Actor object is destroyed automatically
+
+  Actor mActor;
+};
+

Can be stored in STL containers +

+class HandleTest
+{
+  HandleTest()
+  {
+    mActors.push_back( Actor::New() );
+    mActors.push_back( Actor::New() );
+    ...
+  }
+
+  ~HandleTest() {} // Actors are destroyed automatically
+
+  std::vector<Actor> mActors;
+};
+

Passing by value is encouraged +

+void SomeFunction( Actor actor )
+{
+  if( actor )
+  {
+    actor.SomeMethod();
+  }
+}
+

Validity check +

+{
+  ...
+  Actor actor;  // Create a NULL object
+
+  // At this stage we cannot call any of the Actor methods
+  if( !actor )  // This test is will pass, since the actor is NULL
+  {
+    actor = Actor::New();
+    ...
+  }
+  ...
+}
+

Equality operators +

+{
+  Actor handle1;
+  Actor handle2;
+  cout << handle1 == handle2 << endl; // "true", both handles are empty
+
+  handle2 = Actor::New();
+  cout << handle1 == handle2 << endl; // "false", one handle is empty
+
+  handle1 = Actor::New();
+  cout << handle1 == handle2 << endl; // "false", handles to different objects
+
+  handle1 = handle2;
+  cout << handle1 == handle2 << endl; // "true", handles to same object
+}
+

Reference counting examples +

+class AnimationTest
+{
+...
+private:
+  Animation mAnimation; // animation handle
+};
+void AnimationTest::Initialize ()
+{
+  mAnimation = Animation::New( 10.0f ); // reference count will be 1, animation object stays alive when method returns
+  ...
+}
+void AnimationTest::SetAnimation( Animation anim )
+{
+  mAnimation = anim; // reference count of original animation decreased, 'anim' is referenced instead
+                     // if nobody else had a reference on the initial animation, the object is destroyed
+}
+

+ +

+// At this point we own a Dali::Actor named "container"
+// Enter a code block
+{
+  // Create an text label
+  TextLabel actor = TextLabel::New("test");
+  // Add the text label to a container
+  container.Add(actor);
+}
+// Exit the code block
+// At this stage the text label is still alive
+// We don't keep the handle to the text label, but it can be retrieved from the container
+

+ +

+ + + + + +