From: Adeel Kazmi Date: Thu, 23 Apr 2015 16:45:10 +0000 (+0100) Subject: (Doxygen) Added constraints documentation & some clean up X-Git-Tag: accepted/tizen/common/20150512.125104~14 X-Git-Url: http://review.tizen.org/git/?p=platform%2Fcore%2Fuifw%2Fdali-toolkit.git;a=commitdiff_plain;h=bf219d48e3a22c8fb7b7b8702f898392480f3c45 (Doxygen) Added constraints documentation & some clean up Change-Id: I226252305a1a2129c5fbe6691440a6422d54fb91 --- diff --git a/docs/content/main-page.h b/docs/content/main-page.h index 3802d3d..f74e830 100644 --- a/docs/content/main-page.h +++ b/docs/content/main-page.h @@ -28,7 +28,7 @@ * - \link animation-multi-threading-notes Multi-threading Notes \endlink * * \section Constraints - * - \link constraints-intro Introduction to Constraints \endlink + * - \link constraints Constraints \endlink * * \section SizeNegotiation Size Negotiation * - \link size-negotiation Size Negotiation \endlink @@ -51,9 +51,7 @@ * * \section Scripting * - \link script-overview Overview \endlink - * - \link script-howto How to Add a Custom Control \endlink * - \link script-hello Hello World in script \endlink - * * - \link handle-body-idiom Handle – body idiom \endlink * * \section Rendering diff --git a/docs/content/programming-guide/constraints-intro.h b/docs/content/programming-guide/constraints-intro.h deleted file mode 100644 index fb8752d..0000000 --- a/docs/content/programming-guide/constraints-intro.h +++ /dev/null @@ -1,32 +0,0 @@ -/*! \page constraints-intro Constraints - * - -

Introduction

- -Constraints can be used to modify the property of an actor, based on the properties of another actor. Custom a functions or functors can be supplied, to describe the relationship between these properties. A common example is alignment e.g. modifying an actor's position, when the size of the parent actor changes. Multiple constraints can be applied to the same actor at the same time. - -Constraints are applied in the dedicated render thread, after animations have been applied. This means that Constraints override the values set by Animations. Constraints may behave in a similar way to animations, since they can be applied or removed gradually. By default the apply-time is zero, meaning that the constraint will be applied immediately. - -

Local Constraints

- -A local constraint is based on the local properties (i.e. size, position, scale, rotation, color) of an actor. For example you could change the color of an actor, based its rotation. - -

Parent Constraints

- -A parent constraint is based on properties of the actor's parent. The following example shows how to constrain an actor to be 80% of its parent's size: - -@code -Actor actor = Actor::New(); -Vector3 scale(0.8f, 0.8f, 0.8f); // Set width/height/depth at 80% of parent -Constraint constraint = ParentConstraint::Size::New(Dali::ParentSize(scale)); -actor.ApplyConstraint(constraint); -@endcode - -The actor's constraints can later be removed: - -@code - actor.RemoveConstraints(); -@endcode - -* -*/ diff --git a/docs/content/programming-guide/constraints.h b/docs/content/programming-guide/constraints.h new file mode 100644 index 0000000..9394b3c --- /dev/null +++ b/docs/content/programming-guide/constraints.h @@ -0,0 +1,232 @@ +/*! \page constraints Constraints + * + +

Introduction

+ +Constraints are used to modify the property of an actor, based on other properties of the same actor; properties of the actor's parent; or properties of another actor altogether, when the modification needs to be at run-time. +Custom functions or functors can be supplied, where the desired value of the property can be calculated. +These functions (or functors) are called in every frame so should be fast and not too complex otherwise it will hit performance. + +Multiple constraints can be applied to the same actor at the same time. +The order in which constraints are applied is important as this is the order in which they are processed in the update thread. + +Constraints are applied after animations have been applied. +This means that Constraints override the values set by Animations. + +Not all properties can be used as a constraint input, please see Dali::Handle::IsPropertyAConstraintInput() for more details. + +

When to use a Constraint

+ +Constraints are designed as a way of modifying properties that cannot be modified by any existing built in functionality; Like Animations, Size negotiation or Parent anchor, origin settings. +As they provide the ability for the application developer to execute their own code within the update thread, DALi can no-longer guarantee the timeliness of this code, or how optimised it may be. + +Generally, you should not use constraints with the SIZE property as constraining the size and size negotiation are mutually exclusive. +Consider the following use cases as an example of when and when not to use a constraint: + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Requirement:Desired Solution:
Need a child to be 50% the size of it's parent.Use Size negotiation.
Need to zoom an actor in to the screen via it's scale property.Use an Animation.
Need an actor to appear centered around the bottom-right corner of it's parent.Use ParentOrigin & AnchorPoint.
Need to lay out a series of controls with various alignment requirements.Use either Anchor & origin settings, or a TableView.
Need to automatically modify the position property of one actor based on the position property of another actor, that is neither a parent OR a child.Use a Constraint.
Need to position an actor relative to it's parent actor in a NON-UNIFORM way, IE. a non-linear calculation needs to be performed that requires a functor.Use a Constraint.
Need to modify an actor's property in real time based on some calculations that require additional data to be stored in-between frames.Use a Constraint. The constraint functor can hold any variables within it that need to be preserved frame-to-frame.
+ +For most general cases, the position and size requirements of a child or parent actor (from it's child or parent) can be calculated with Size Negotiation. + +

Constraint Sources

+ +These are properties of this (or another actor) that are used as inputs into the constraint. +The constraint will take these values, optionally perform a calculation on them (if using a custom functor) and write the result to the specified property of the target actor. +The source actor is specified as either the same actor, it's parent or another actor. + +

Local Source

+ +A local source is based on the local properties (i.e. size, position, scale, orientation, color) of an actor. +For example, the actor's orientation could be used as a constraint input source. + +@code +Dali::ConstraintSource source( Dali::LocalSource( Dali::Actor::Property::ORIENTATION ) ); +@endcode + +

Parent Source

+ +A parent source is based on properties of the actor's parent. +For example, a parent's position can be used as a constraint input source. + +@code +Dali::ConstraintSource source( Dali::ParentSource( Dali::Actor::Property::POSITION ) ); +@endcode + +

Source

+ +Finally, you can base your source on the properties of another handle altogether. +For example, a sibling actor's color could be used as a constraint input source. + +@code +Dali::ConstraintSource source( Dali::Source( anotherHandle, Dali::Actor::Property::COLOR ) ); +@endcode + +

The Constraint Function

+ +The signature of the constraint function is: + +@code +void Function( PropertyType& current, const Dali::PropertyInputContainer& inputs ); +@endcode + +Here 'current' is a reference to the target property type, e.g. float, Vector2, Vector3 etc. +This is an in/out parameter. +It represents the current value of the property and the expectation is that it will be modified by the function to the desired value. + +The 'inputs' parameter holds all the constraint input sources. +Each element is a pointer to the property-input and can be accessed using the indexing operator[]. +The order in which the sources are added is the order in which the property-inputs are sorted in the container. For example: + +@code +constraint.AddSource( Dali::LocalSource( Dali::Actor::Property::POSITION ) ); +constraint.AddSource( Dali::LocalSource( Dali::Actor::Property::SIZE ) ); +constraint.AddSource( Dali::ParentSource( Dali::Actor::Property::POSITION ) ); +constraint.AddSource( Dali::ParentSource( Dali::Actor::Property::SIZE ) ); +@endcode + +In the constraint function this equates to: +@code +const Dali::Vector3& position( inputs[0]->GetVector3() ); +const Dali::Vector3& size( inputs[1]->GetVector3() ); +const Dali::Vector3& parentPosition( inputs[2]->GetVector3() ); +const Dali::Vector3& parentSize( inputs[3]->GetVector3() ); +@endcode + +

Creating a Constraint

+ +

Using C Functions

+ +If you do not have any data that is changed at runtime, then C functions should be used. +For example, the color of an actor could be changed based on its position along the x-axis till a preset distance of 100, beyond which it is transparent. + +@code +Dali::Actor actor = Actor::New(); + +Dali::Constraint constraint = Dali::Constraint::New< Vector4 >( actor, Dali::Actor::Property::COLOR, MyConstraintFunction ); // Creates a constraint that targets actor +constraint.AddSource( Dali::LocalSource( Dali::Actor::Property::POSITION ) ); // Adds the POSITION property as a constraint input +constraint.Apply(); // The constraint is applied +@endcode + +And the actual C Function: + +@code +void MyConstraintFunction( Dali::Vector4& current, const Dali::PropertyInputContainer& inputs ) +{ + const Dali::Vector3& position( inputs[0]->GetVector3() ); + + float distance = fabs( position.x ); + + // More than 100.0f away, opacity is 0.0f + if ( distance > 100.0f ) + { + current.a = 0.0f; + } + else + { + // Otherwise it will blend between fully opaque and transparent + current.a = ( 100.0f - distance ) / 100.0f; + } +} +@endcode + +Please have a look at Dali::Constraint::New() for more details. + +

Using Functors

+ +If you need to store some data in a struct/class, then a functor can be used. +Reusing the last example, the color of an actor is changed based on its position along the x-axis, but the distance when it is transparent is different for each applied constraint. + +@code +Dali::Actor actor = Actor::New(); + +Dali::Constraint constraint = Dali::Constraint::New< Vector4 >( actor, Dali::Actor::Property::COLOR, MyFunctor( 200 ) ); // Creates a constraint that targets actor, and uses MyFunctor with a distance of 200 +constraint.AddSource( Dali::LocalSource( Dali::Actor::Property::POSITION ) ); // Adds the POSITION property as a constraint input +constraint.Apply(); // The constraint is applied +@endcode + +And the struct: + +@code +struct MyFunctor +{ + /// Constructor which takes the distance at which the actor will be fully transparent + MyFunctor( float distance ) + : mDistance( distance ) + { + } + + /// Functor + void operator()( Dali::Vector4& current, const Dali::PropertyInputContainer& inputs ) + { + const Dali::Vector3& position( inputs[0]->GetVector3() ); + + float distance = fabs( position.x ); + + // More than mDistance away, opacity is 0.0f + if ( distance > mDistance ) + { + current.a = 0.0f; + } + else + { + // Otherwise it will blend between fully opaque and transparent + current.a = ( 100.0f - mDistance ) / 100.0f; + } + } + + // Data + const float mDistance; +}; +@endcode + +MyFunctor could then be used with another constraint with a different distance. + +Please have a look at Dali::Constraint::New(Handle, Property::Index, const T&) for more details. + +Instead of using the default functor, another method can be declared in the class or struct and used as the constraint function. +Please have a look at appropriate Dali::Constraint::New() method for more details. + +

Removing Constraints

+ +The actor's constraints can later be removed in several ways: + +@code +mConstraint.Remove(); // mConstraint is a base-handle to a constraint +actor.RemoveConstraints(); // Removes ALL constraints applied to an actor +actor.RemoveConstraint( tag ); // All constraints with the tag are removed from the actor (tag can be set using SetTag) +@endcode + +* +*/ diff --git a/docs/content/programming-guide/script-howto.h b/docs/content/programming-guide/script-howto.h deleted file mode 100644 index b9d3da0..0000000 --- a/docs/content/programming-guide/script-howto.h +++ /dev/null @@ -1,101 +0,0 @@ -/*! \page script-howto Scripting HowTo - * - *

Scripting A Custom Control

- * - * These steps must be taken to provide scripting access for your control. - * - * - * -* - *

Registering your Type, Signals and Actions

- * - * As part of your my-actor.cpp a static "Dali::TypeRegistration" object is created to register MyActor for scripting. - * - * Functions for Creation, Signal Connection and Action are registered with this object. - * - * @code - * namespace // type registration - * { - * - * // Register MyActor with base actor CustomActor and creation function CreateCustom - * Dali::TypeRegistration mCustomType( typeid(MyActor), typeid(Dali::CustomActor), MyActor::Create ); - * - * // Add a signal to the type registration - * Dali::TypeSignalConnector signal1( mCustomType, "page-changed", MyActor::DoConnectSignalCustom); - * - * // Add an action to the type registration - * Dali::TypeAction action1( mCustomType, "SelectPage", MyActor::DoActionCustom); - * - * } - * @endcode - * - * The registered handling functions are also static. For example. - * - * @code - * BaseHandle MyActor::Create(void) - * { - * return MyActor::New(); - * } - * - * Dali::Connection MyActor::DoConnectSignalCustom(BaseObject* object, ConnectionTrackerInterface* tracker, const std::string& signalName, FunctorDelegate* functor) - * { - * Dali::Connection connection ; - * - * MyActor* actor = dynamic_cast(object); - * - * if(actor && "page-changed" == signalName) - * { - * connection = return actor->PageChangedSignal().Connect( tracker, functor ); - * } - * - * return connection ; - * } - * - * bool MyActor::DoActionCustom(BaseObject* object, const std::string& actionName, const PropertyValueContainer& attributes) - * { - * bool actioned = false ; - * - * MyActor* actor = dynamic_cast(object) ; - * - * if(actor && "SelectPage" == actionName) - * { - * actor->DoSelectPage() ; - * actioned = true; - * } - * - * return actioned ; - * } - * @endcode - * - *

Providing Properties for scripting

- * - * Properties can be registered by name to allow script access. - * - * A RegisterProperty() call with property attributes allows the custom class to register non animatable properties. - * - * @code - * void MyActor::Initialize() - * { - * // Register a non animatable and writeable property. - * mPropertyAlphaIndex = Self().RegisterProperty("alpha", 0.0f, Dali::Property::WRITEABLE); - * } - * @endcode - * - * If a non animatable property is set then the class is notified via the OnPropertySet virtual function. - * - * @code - * void MyActor::OnPropertySet(Property::Index index, Property::Value propertyValue) - * { - * if(index == mPropertyAlphaIndex) - * { - * SetAlpha(propertyValue.Get()); - * } - * } - * - * @endcode - * - */ diff --git a/docs/content/programming-guide/script-overview.h b/docs/content/programming-guide/script-overview.h index f9eb951..6224f60 100644 --- a/docs/content/programming-guide/script-overview.h +++ b/docs/content/programming-guide/script-overview.h @@ -33,7 +33,7 @@ * * The property system has non animatable properties that can be used by the scripting runtime to set actor attributes. * - * Custom controls can register properties for scripting access. The custom control is notified of a non animatable property value change. + * Custom controls can register properties for scripting access. * * *

A Javascript example

@@ -51,7 +51,6 @@ * * // Property access * // This line finds a property called "alpha" and Sets with SetProperty(index, Property::Value(2.0)) - * // If the property is non animatable it calls OnPropertySet(Property::Value(2.0)) * custom.alpha = 2.0; * * // NB: non animatable properties can be strings