From 06912fa3c51ea137042854e5600cf7e664a1bbc6 Mon Sep 17 00:00:00 2001 From: Yoonsang Lee Date: Fri, 17 Jul 2015 16:05:17 +0900 Subject: [PATCH] [DALi][DOC-213] Add Property, Update Handle/Body Signed-off-by: Yoonsang Lee Change-Id: I4bc79e44198a2661c082d9a2a41646bfe4e3c93d --- org.tizen.ui.guides/html/native/dali/actors_n.htm | 3 +- org.tizen.ui.guides/html/native/dali/handle_n.htm | 202 ++++++++++++++++ .../html/native/dali/properties_n.htm | 257 +++++++++++++++++++++ org.tizen.ui.guides/html/native/dali/threads_n.htm | 182 +++++++++++++++ 4 files changed, 643 insertions(+), 1 deletion(-) create mode 100755 org.tizen.ui.guides/html/native/dali/handle_n.htm create mode 100755 org.tizen.ui.guides/html/native/dali/properties_n.htm create mode 100755 org.tizen.ui.guides/html/native/dali/threads_n.htm diff --git a/org.tizen.ui.guides/html/native/dali/actors_n.htm b/org.tizen.ui.guides/html/native/dali/actors_n.htm index dd6e416..7aab77f 100755 --- a/org.tizen.ui.guides/html/native/dali/actors_n.htm +++ b/org.tizen.ui.guides/html/native/dali/actors_n.htm @@ -154,7 +154,8 @@ Stage::GetCurrent().Add(actor);

For example, a touch event can be handled as follows:

-
bool OnTouch(Actor actor, const TouchEvent& touch)
+
+bool OnTouch(Actor actor, const TouchEvent& touch)
 {
    bool handled = false;
 
diff --git a/org.tizen.ui.guides/html/native/dali/handle_n.htm b/org.tizen.ui.guides/html/native/dali/handle_n.htm
new file mode 100755
index 0000000..41da6eb
--- /dev/null
+++ b/org.tizen.ui.guides/html/native/dali/handle_n.htm
@@ -0,0 +1,202 @@
+
+
+
+	
+	
+	
+	
+		
+	
+	
+	
+	
+
+	Handle/Body Pattern: Basic Way of Using DALi Objects  
+
+
+
+
+	
+
+

+
Handle/Body Pattern: Basic Way of Using DALi Objects

+
+
DALi widely adopts the handle/body pattern (a.k.a. pimpl pattern) which seperates implementation details (the body classes) from their interfaces (the handle classes).

+
Dali::BaseHandle (in mobile and wearable) is a base class of these handle classes in DALi. It additionally provides smart-pointer semantics which manages internal objects with reference counts. Most of classes in DALi public API are handle classes, which means they inherit from Dali::BaseHandle.
+

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

+
    
+	
  • Easier memory management
+	
    Each internal implementation 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.
+(For your information, these internal body class inherit from Dali::BaseObject, but you don't need to use this class directly).
+
    
+	
    • 
+	
  • 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
+
    
+
+

+
+
+    
+
+
+

+
+Go to top
+
+
+
+
+
+
+
+
diff --git a/org.tizen.ui.guides/html/native/dali/properties_n.htm b/org.tizen.ui.guides/html/native/dali/properties_n.htm
new file mode 100755
index 0000000..766e586
--- /dev/null
+++ b/org.tizen.ui.guides/html/native/dali/properties_n.htm
@@ -0,0 +1,257 @@
+
+
+
+	
+	
+	
+	
+		
+	
+	
+	
+	
+
+	Properties: Accessing to Properties of DALi Objects  
+
+
+
+
+	
+
+

+
Properties: Accessing to Properties of DALi Objects

+
+
A property is a value used by an object that can be modified or read via Dali::Handle::GetProperty() / SetProperty() API.

+
+
The difference between properties and ordinary C++ member variables is that a property can be dynamically added to or removed from an existing object in runtime, which enables more flexible, script-like programming with DALi.

+
+
Dali::Handle (in mobile and wearable) provides methods to manage properties, thus the DALi classes that inherit from Dali::Handle (most of classes that users would use) have a number of predefined properties and can have any number of user-defined custom properties.
+

+
+
Accessing to Property Values

+
+	
Property values of an object usually can be accessed via two ways: by its class member functions or by property getters/setters (Dali::Handle::GetProperty() / SetProperty()).

+	
For example, Dali::Actor has following predefined properties:

+
+	
+		
+		
+		
+			
+			
+		
+		
+			
+			
+		
+		
+			
+			
+		
+		
+			
+			
+		
+		
+			
+			
+		
+		
+			
+			
+		
+		
+			
+			
+		
+		
+	

+			Table: Properties of Dali::Actor
+		
Property Index (enumeration)Member Functions
Dali::Actor::POSITIONDali::Actor::GetCurrentPosition() / SetPosition()
Dali::Actor::ORIENTATIONDali::Actor::GetCurrentOrientation() / SetOrientation()
Dali::Actor::SIZEDali::Actor::GetCurrentSize() / SetSize()
Dali::Actor::COLORDali::Actor::GetCurrentColor() / SetColor()
Dali::Actor::NAMEDali::Actor::GetName() / SetName()
......

+
+	You can access them in both ways:
+
+	
+Actor actor = Actor::New();
+actor.SetName("test actor");
+std::cout << actor.GetName() << std::endl;  // "test actor"
+

+
+	
+Actor actor = Actor::New();
+actor.SetProperty( Actor::Property::NAME, "test actor" );
+std::cout << actor.GetProperty( Actor::Property::NAME ) << std::endl;  // "test actor"
+std::cout << actor.GetProperty<std::string>( Actor::Property::NAME ) << std::endl;  // "test actor"
+std::cout << actor.GetProperty( Actor::Property::NAME ).Get<std::string>() << std::endl;  // "test actor"
+

+
+
Please see API reference for Dali::Handle (in mobile and wearable) for more information.
+
+
Usages of Properties

+
+
Registering User-Defined Custom Properties to Objects

+
+
Properties can be registered / unregistered in runtime, which enables script-like programming of DALi application, for example, adding custom member data to an instance of a DALi class without subclassing the class or maintaining another pool of custom data.

+
For example, you can set your own custom data to PushButton objects and use them later when the buttons are clicked like:

+
+void Create( Application& application )
+{
+  for( int i=0; i<5; ++i )
+  {
+    Toolkit::PushButton button = Toolkit::PushButton::New();
+    button.SetSize( 100, 100 );
+    button.SetPosition( 100*i+50, 50 );
+    button.ClickedSignal().Connect( this, OnButtonClicked );
+
+    // Register a custom property having button index.
+    // Store the property index so you can look it up later.
+    // Note: This is much faster than looking the property up by property name and should always be used if possible.
+    // As all control types are the same (PushButtons) the indices to the unique custom property are all same.
+    Property::Value data( i );
+    mCustomDataIndex = button.RegisterProperty( "custom-data", data );
+
+    Stage::GetCurrent().Add(button);
+  }
+}
+
+bool OnButtonClicked(Toolkit::Button button)
+{
+  // Look up the custom property by the stored property index.
+  // Note: If the property belongs to a control in another library, or we do not know the index, we can look the index up first with:
+  // Property::Index index = button.GetPropertyIndex( "custom-data" );
+  cout << button.GetProperty( mCustomDataIndex ) << endl;
+  return true;
+}
+

+
+
Please see API reference for Dali::Handle (in mobile and wearable) for more information.
+
+
Animating Objects

+
+
DALi animation API is used to animate the properties of any number of objects.

+
+
For example, following code animates the value of the POSITION property of a radio button to (100.0, 200.0, 0.0) for 2 seconds:

+
+
+RadioButton actor = RadioButton::New();
+Stage::GetCurrent().Add(actor);
+Animation animation = Animation::New(2.0f); // duration 2 seconds
+animation.AnimateTo(Property(actor, Actor::Property::POSITION), Vector3(100.0f, 200.0f, 0.0f));
+animation.Play();
+

+
+
Please see Animation Basics for more information.

+
+
Imposing Constraints on Objects

+
+
DALi constraint API is used to modify the property of an object based on other properties of other objects.

+
+
For example, following code makes the value of the SIZE property of an actor same as the value of the SIZE property of its parent actor:

+
+
+Constraint constraint = Constraint::New( actor,
+                                                  Actor::Property::SIZE,
+                                                  EqualToConstraint() );
+constraint.AddSource( ParentSource( Actor::Property::SIZE ) );
+constraint.Apply();
+

+
+
Please see Constraints for more information.

+
+
Index, Type, and Name

+
+
A property has its own index, type, and name.

+
+
For example, predefined properties of Dali::Actor has following indices, types, and names:

+
+	
+		
+		
+		
+			
+			
+			
+		
+		
+			
+			
+			
+		
+		
+			
+			
+			
+		
+		
+			
+			
+			
+		
+		
+			
+			
+			
+		
+		
+			
+			
+			
+		
+		
+			
+			
+			
+		
+		
+	

+			Table: Indices, Names, and Types of Properties of Dali::Actor
+		
Property Index (enumeration)Property TypeProperty Name
Dali::Actor::POSITIONVector3"position"
Dali::Actor::ORIENTATIONQuaternion"orientation"
Dali::Actor::SIZEVector3"size"
Dali::Actor::COLORVector4"color"
Dali::Actor::NAMEstd::string"name"
.........

+
+
Proper index and type will be only used and property name is currently only for internal use. You can see these information at API reference for property of each class. For example for Dali::Actor, please see Dali::Actor::Property (in mobile and wearable).

+
+
To check all kinds of supported property types, please see Dali::Property::Type (in mobile and wearable) and Dali::PropertyTypes (in mobile and wearable).

+
+    
+
+
+

+
+Go to top
+
+
+
+
+
+
+
+
diff --git a/org.tizen.ui.guides/html/native/dali/threads_n.htm b/org.tizen.ui.guides/html/native/dali/threads_n.htm
new file mode 100755
index 0000000..e90ea6d
--- /dev/null
+++ b/org.tizen.ui.guides/html/native/dali/threads_n.htm
@@ -0,0 +1,182 @@
+
+
+
+	
+	
+	
+	
+		
+	
+	
+	
+	
+
+	Properties: Accessing to Properties of DALi Objects  
+
+
+
+
+	
+
+

+
Properties: Accessing to Properties of DALi Objects

+
+
GetCurrentPosition()

+
+
A property is a value used by an object that can be modified or read via Dali::Handle::GetProperty() / SetProperty() API.

+
+
The difference between properties and ordinary C++ member variables is that a property can be dynamically added to or removed from an existing object in runtime, which enables more flexible, script-like programming with DALi.

+
+
Dali::Handle (in mobile and wearable) provides methods to manage properties, thus the DALi classes that inherit from Dali::Handle (most of classes that users would use) have a number of predefined properties and can have any number of user-defined custom properties.
+

+
+
Accessing to Properties

+
+	
Properties of an object usually can be accessed via two ways: by its class member functions or by property getters/setters (Dali::Handle::GetProperty() / SetProperty()).

+	
For example, Dali::Actor has following predefined properties:

+
+	
+		
+		
+		
+			
+			
+		
+		
+			
+			
+		
+		
+			
+			
+		
+		
+			
+			
+		
+		
+			
+			
+		
+		
+			
+			
+		
+		
+			
+			
+		
+		
+	

+			Table: Properties of Dali::Actor
+		
Property Index (enumeration)Member Functions
Dali::Actor::POSITIONDali::Actor::GetCurrentPosition() / SetPosition()
Dali::Actor::ORIENTATIONDali::Actor::GetCurrentOrientation() / SetOrientation()
Dali::Actor::SIZEDali::Actor::GetCurrentSize() / SetSize()
Dali::Actor::COLORDali::Actor::GetCurrentColor() / SetColor()
Dali::Actor::NAMEDali::Actor::GetName() / SetName()
......

+
+	You can access them in both ways:
+
+	
+Actor actor = Actor::New();
+actor.SetName("test actor");
+std::cout << actor.GetName() << std::endl;  // "test actor"
+

+
+	
+Actor actor = Actor::New();
+actor.SetProperty( Actor::Property::NAME, "test actor" );
+std::cout << actor.GetProperty( Actor::Property::NAME ) << std::endl;  // "test actor"
+std::cout << actor.GetProperty<std::string>( Actor::Property::NAME ) << std::endl;  // "test actor"
+std::cout << actor.GetProperty( Actor::Property::NAME ).Get<std::string>() << std::endl;  // "test actor"
+

+
+
Usages of Properties

+
+
Registering User-Defined Custom Properties to an Object

+
+
Properties can be registered / unregistered in runtime, which enables script-like programming of DALi application, for example, adding custom member data to an instance of a DALi class without subclassing the class or maintaining another pool of custom data.

+
For example, you can set your own custom data to PushButton objects and use them later when the buttons are clicked like:

+
+  void Create( Application& application )
+  {
+    for( int i=0; i<5; ++i )
+    {
+      Toolkit::PushButton button = Toolkit::PushButton::New();
+      button.SetSize( 100, 100 );
+      button.SetPosition( 100*i+50, 50 );
+      button.ClickedSignal().Connect( this, OnButtonClicked );
+
+      // Register a custom property having button index.
+      // Store the property index so you can look it up later.
+      // Note: This is much faster than looking the property up by property name and should always be used if possible.
+      // As all control types are the same (PushButtons) the indices to the unique custom property are all same.
+      Property::Value data( i );
+      mCustomDataIndex = button.RegisterProperty( "custom-data", data );
+
+      Stage::GetCurrent().Add(button);
+    }
+  }
+
+  bool OnButtonClicked(Toolkit::Button button)
+  {
+    // Look up the custom property by the stored property index.
+    // Note: If the property belongs to a control in another library, or we do not know the index, we can look the index up first with:
+    // Property::Index index = button.GetPropertyIndex( "custom-data" );
+    cout << button.GetProperty( mCustomDataIndex ) << endl;
+    return true;
+  }
+

+
+
Animation

+
+
Constraint

+
+
+
+types
+
+set/get add/remove
+
+constraint animation
+
+
+
+
+    
+
+
+

+
+Go to top
+
+
+
+
+
+
+
+
-- 
2.7.4