Actors: Working with Basic DALi Components

Actor is the primary object in DALi application.

- -

Actor Basics

Actor is the basic component that composes the entire scene. It can have visible (for example, UI components, image actor) or invisible (for example, camera actor or layer) forms.

Actor is also the primary object with which DALi applications interact. Multiple types of event signals provided by actors can be handled in a application through user-defined callback functions.

Actors and Stage

Stage is a top-level object that represents the entire scene or screen. It is used for displaying a hierarchy of actors managed by the scene graph structure. An actor inherits a position relative to its parent, and can be moved in relation to this point.

@@ -60,7 +55,7 @@ Stage::GetCurrent().Add(actor); -

Coordinate System

The stage has a 2D size that matches the size of the application window. The default unit 1 is 1 pixel with default camera.

@@ -70,7 +65,7 @@ Stage::GetCurrent().Add(actor);

DALi coordinate system

Positioning Actors

An actor inherits its parent's position. The relative position between the actor & parent is determined by the following properties:

Parent origin @@ -103,7 +98,7 @@ Stage::GetCurrent().Add(actor);

Event Handling for Actors

The Dali::Actor class provides following event signals:

@@ -173,202 +168,6 @@ actor.TouchedSignal().Connect(&OnTouch);

For more information, see Event Handling.

Layout Management

- -

DALi provides rule-based layout management, size negotiation, which is used to allocate the sizes of the actors on the stage based on rules of dependency between the actors.

- -

Dimensions

The notion of width and height is generalized into the concept of a dimension. Several methods take the Dimension parameter. The Dimension enum specifies the available dimensions as bit fields:

Dimension::WIDTH
Dimension::HEIGHT

If a method can process width and height at the same time, the Dimension::ALL_DIMENSIONS mask can be specified.

- -

Resize Policies

- -

The ResizePolicy enum specifies a range of options for controlling the way actors resize. These rules enable automatic resizing.

- -

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

- Table: Resizing rules -
Resize policy	Description	Illustration
ResizePolicy::FIXED	Use this option to maintain a specific size as set by the SetSize() function. This is the default for all actors.
ResizePolicy::USE_NATURAL_SIZE	Use this option for objects, such as images or text to get their natural size. This can mean the dimensions of an image or the size of text with no wrapping. You can also use this option with table views when the size of the table depends on its children.
ResizePolicy::FILL_TO_PARENT	The size of the actor is similar to its parent's size with proportionate filling considered.
ResizePolicy::SIZE_RELATIVE_TO_PARENT	The size of the actor is similar to its parent's size with a relative scale. Use the SetSizeModeFactor() function to specify the ratio.
ResizePolicy::SIZE_FIXED_OFFSET_FROM_PARENT	The size of the actor is similar to its parent's size with a fixed offset using the SetSizeModeFactor function.
ResizePolicy::FIT_TO_CHILDREN	The size of the actor is scaled around the size of the its children. For example, the height of a pop-up can be resized according to its contents.
ResizePolicy::DIMENSION_DEPENDENCY	This option covers rules, such as width-for-height and height-for-width. You can specify that one dimension depends on another.

- - -

Example with Actors

- -

This section describes a layout example with a actor.

- -

Enabling Size Negotiation

- -

Text and image actors have relayout enabled by default, while plain actors are disabled unless the SetResizePolicy() function is called.

- -

Specifying Size Policies

- -

Actors have different size policies by default. For example, the image actor is set to USE_NATURAL_SIZE. This ensures that an image actor uses its natural size by default when it is placed on the stage. However, if the SetSize() function is used with sizes other than 0 on the image actor, the current resize policy is overridden by the FIXED policy and the actor takes the specified size.

- -

You can specify how an actor is size-negotiated:

- -

void SetResizePolicy(ResizePolicy::Type policy, Dimension::Type dimension) @endcode

- -

It is possible to specify different policies for the different dimensions of width and height to archive different layouts. Different actors have different resize policies specified. For example, image actors are set to USE_NATURAL_SIZE by default.

- -

The following example shows the rootActor with its width set to ResizePolicy::FILL_TO_PARENT and its height set to ResizePolicy::FIT_TO_CHILDREN. It has an image actor added to it with an explicit call to USE_NATURAL_SIZE in both dimensions called on it. This creates an actor that fills the space of its parent in the width dimension and fits its child in the height dimension. As the image actor child is using its natural size, the height of the root actor fits the height of the child image.

- -

Actor rootActor = Actor::New();
-rootActor.SetResizePolicy(ResizePolicy::FILL_TO_PARENT, Dimension::WIDTH);
-rootActor.SetResizePolicy(ResizePolicy::FIT_TO_CHILDREN, Dimension::HEIGHT);
-ImageActor image = ImageActor::New(Image::New(MY_IMAGE_PATH));
-image.SetResizePolicy(ResizePolicy::USE_NATURAL_SIZE, Dimension::ALL_DIMENSIONS);
-rootActor.Add(image);

- -

The following images show the before and after layouts for this code example.

- -

Figure: Before and after setting the resize policy

Before and after setting the resize policy

- - -

This example shows a root actor set to expand to its parent's width and adjust around its child's height. The child image actor is set to its natural size.

- -

To specify that a dimension has a dependency on another dimension, use the ResizePolicy::DIMENSION_DEPENDENCY policy. For example, if the dimension is Dimension::HEIGHT and the dependency is Dimension::WIDTH, there is a height-for-width dependency in effect. You can use the policy in a text view that wraps its text. The following example shows a text view that expands its width according to the size of its parent, wraps its contents and then determines its height based on the width.

- -

TextLabel text = TextLabel::New("Example");
-text.SetResizePolicy(ResizePolicy::FILL_TO_PARENT, Dimension::WIDTH);
-text.SetResizePolicy(ResizePolicy::DIMENSION_DEPENDENCY, Dimension::HEIGHT);

- -

Specifying Sizes and Size Limits

- -

To specify a fixed size for an actor, use the FIXED resize policy and set the desired size using the SetSize function. If only 1 dimension is FIXED, the other value in the size parameter is ignored, so it is safe to set it to 0.

To constrain the final negotiated size of an actor, set the following minimum and maximum sizes, respectively:

- -

void SetMinimumSize(const Vector2& size)
-void SetMaximumSize(const Vector2& size)

- -

Adjusting the Negotiated Size

- -

When an actor must to maintain the aspect ratio of its natural size, use the SizeScalePolicy() function. This is useful to ensure that images maintain their aspect ratio while still fitting the bounds they have been allocated.

You can use the following resize policies:

SizeScalePolicy::USE_SIZE_SET -
This is the default policy.
SizeScalePolicy::FIT_WITH_ASPECT_RATIO -
Fits the actor within the bounds it has been allocated while maintaining the aspect ratio.
SizeScalePolicy::FILL_WITH_ASPECT_RATIO -
Fills all available space, potentially overflowing its bounds, while maintaining aspect ratio.

- -

void SetSizeScalePolicy(SizeScalePolicy::Type policy)

- -

Using Actors in Containers

- -

When using actors in containers, such as a table view, you can specify the padding surrounding the actor. The padding specifies the left, right, bottom, and top padding value.

- -

void SetPadding(const Padding& padding)

- - - - - - - - - - -

Note
Beware of infinite dependency loops! - The simplest form of this is shown when the resize policy of a parent actor is set to ResizePolicy::FIT_TO_CHILDREN with a child that has a resize policy of ResizePolicy::FILL_TO_PARENT. - A more complex loop occurs when a parent actor has a width policy of ResizePolicy::DIMENSION_DEPENDENCY with a height policy of ResizePolicy::FIT_TO_CHILDREN. The parent has a single child with a height policy ResizePolicy::DIMENSION_DEPENDENCY with width. If the child's width policy is ResizePolicy::FILL_TO_PARENT, a loop occurs. - Loops can occur over larger spreads of parent-child relationships. These loops are detected by the relayout algorithm, which allocates actors 0 sizes.

Note

Beware of infinite dependency loops!

The simplest form of this is shown when the resize policy of a parent actor is set to ResizePolicy::FIT_TO_CHILDREN with a child that has a resize policy of ResizePolicy::FILL_TO_PARENT.

A more complex loop occurs when a parent actor has a width policy of ResizePolicy::DIMENSION_DEPENDENCY with a height policy of ResizePolicy::FIT_TO_CHILDREN. The parent has a single child with a height policy ResizePolicy::DIMENSION_DEPENDENCY with width. If the child's width policy is ResizePolicy::FILL_TO_PARENT, a loop occurs.

Loops can occur over larger spreads of parent-child relationships. These loops are detected by the relayout algorithm, which allocates actors 0 sizes.

- -

Image Actor

An image can be displayed through an image actor. THe Dali::ImageActor class inherits from the Dali::Actor class and provides means to display resources, such as images on the stage.

- -

Construction

- -

The image actor is constructed by passing a Dali::Image object. The Dali::Image is an abstract base class with multiple derived classes, and the Dali::ResourceImage class is used for loading an image from a file.

- -

Dali::Image image = ResourceImage::New(myImageFilename);
-Dali::ImageActor myImageActor = ImageActor::New(image);

- -

Style

- -

The image actor can render an image in 2 different ways. Although the nine-patch feature is supported by the image actor, using 9-patch image (.9.png or .9.jpg) is encouraged.

STYLE_QUAD: A simple flat quad style for rendering images.
STYLE_NINE_PATCH: This style gives the flexibility to stretch images by dividing it into 9 sections. The corners are not scaled; the edges are scaled on 1 axis, and the middle is scaled in both axes.

- -

myImageActor.SetStyle (Dali::ImageActor::STYLE_NINE_PATCH);

- -

Border

- -

The border is used in the ImageActor::STYLE_NINE_PATCH. It defines the border values of the image for stretching.

- -

Dali::ImageActor::Border border(0.45,0.15,0.45,0.15);
-myImageActor.SetBorder(border);

- -

Pixel Area

- -

The area of the image to be displayed by the image actor can be set by setting the pixel area. The pixel area is relative to the top-left (0,0) coordinates of the image.

- -

Rect<int> pixel1(myX, myY, myWidth, myHeight);
-if(!myImageActor.IsPixelAreaSet())
-{
-   myImageActor.SetPixelArea(pixel1);
-}
-
-//Removes the pixel area setting
-myImageActor.ClearPixelArea();

- -

Changing an Image

- -

The image actor needs a reference to a Dali::Image object on creation. However the Image object can be later changed by calling DaliActor:SetImage() function.

- -

myImageActor.SetImage(newImage);

- diff --git a/org.tizen.ui.guides/html/native/dali/event_handling_n.htm b/org.tizen.ui.guides/html/native/dali/event_handling_n.htm index c91283d..fb86d62 100755 --- a/org.tizen.ui.guides/html/native/dali/event_handling_n.htm +++ b/org.tizen.ui.guides/html/native/dali/event_handling_n.htm @@ -67,10 +67,7 @@

The concept of signal and slots were introduced by Qt for communication between objects. The event mechanism of DALi is inspired by Qt.

Figure: A schematic example of signal-slot connections
- : Signal 1 is connected to slot 1,
- signal 2 is connected to slot 1 & slot 3,
- and signal 3 is connected to slot 2.

Figure: A schematic example of signal-slot connections: Signal 1 is connected to slot 1, signal 2 is connected to slot 1 and slot 3, and signal 3 is connected to slot 2.

Signal and slot event handling

The signal and slot system has following advantages:

diff --git a/org.tizen.ui.guides/html/native/dali/guides_dali_n.htm b/org.tizen.ui.guides/html/native/dali/guides_dali_n.htm index 9bfd3d7..178ce2e 100755 --- a/org.tizen.ui.guides/html/native/dali/guides_dali_n.htm +++ b/org.tizen.ui.guides/html/native/dali/guides_dali_n.htm @@ -41,6 +41,10 @@

Enables you to get started with the DALi UI programming.

Actors: Working with Basic DALi Components

Enables you to handle DALi actors.

Event Handling: Managing the Event Flow

Enables you to handle DALi events.

UI Components: Creating the Application Layout diff --git a/org.tizen.ui.guides/html/native/dali/imageactor_n.htm b/org.tizen.ui.guides/html/native/dali/imageactor_n.htm new file mode 100644 index 0000000..3986a10 --- /dev/null +++ b/org.tizen.ui.guides/html/native/dali/imageactor_n.htm @@ -0,0 +1,111 @@ + + + + + + + + + + + + + + Actors: Working with Basic DALi Components + + + + + + +

Image Actor: Displaying Images

+ +

An image can be displayed through an image actor. THe Dali::ImageActor class inherits from the Dali::Actor class and provides means to display resources, such as images on the stage.

+ +

Construction

+ +

Dali::Image image = ResourceImage::New(myImageFilename);
+Dali::ImageActor myImageActor = ImageActor::New(image);

+ +

Style

+ +

The image actor can render an image in 2 different ways. Although the nine-patch feature is supported by the image actor, using 9-patch image (.9.png or .9.jpg) is encouraged.

STYLE_QUAD: A simple flat quad style for rendering images.
STYLE_NINE_PATCH: This style gives the flexibility to stretch images by dividing it into 9 sections. The corners are not scaled; the edges are scaled on 1 axis, and the middle is scaled in both axes.

+ +

myImageActor.SetStyle (Dali::ImageActor::STYLE_NINE_PATCH);

+ +

Border

+ +

The border is used in the ImageActor::STYLE_NINE_PATCH. It defines the border values of the image for stretching.

+ +

Dali::ImageActor::Border border(0.45,0.15,0.45,0.15);
+myImageActor.SetBorder(border);

+ +

Pixel Area

+ +

The area of the image to be displayed by the image actor can be set by setting the pixel area. The pixel area is relative to the top-left (0,0) coordinates of the image.

+ +

Rect<int> pixel1(myX, myY, myWidth, myHeight);
+if(!myImageActor.IsPixelAreaSet())
+{
+   myImageActor.SetPixelArea(pixel1);
+}
+
+//Removes the pixel area setting
+myImageActor.ClearPixelArea();

+ +

Changing an Image

+ +

The image actor needs a reference to a Dali::Image object on creation. However the Image object can be later changed by calling DaliActor:SetImage() function.

+ +

myImageActor.SetImage(newImage);

+ + + + +

+ +

+ + + + + + + + diff --git a/org.tizen.ui.guides/html/native/dali/layout_n.htm b/org.tizen.ui.guides/html/native/dali/layout_n.htm new file mode 100644 index 0000000..c4c7d8e --- /dev/null +++ b/org.tizen.ui.guides/html/native/dali/layout_n.htm @@ -0,0 +1,213 @@ + + + + + + + + + + + + + + Actors: Working with Basic DALi Components + + + + + + +

Layout Management: Allocating the Sizes of the Actors

+ +

DALi provides rule-based layout management, size negotiation, which is used to allocate the sizes of the actors on the stage based on rules of dependency between the actors.

+ +

Dimensions

The notion of width and height is generalized into the concept of a dimension. Several methods take the Dimension parameter. The Dimension enum specifies the available dimensions as bit fields:

Dimension::WIDTH
Dimension::HEIGHT

If a method can process width and height at the same time, the Dimension::ALL_DIMENSIONS mask can be specified.

+ +

Resize Policies

+ +

The ResizePolicy enum specifies a range of options for controlling the way actors resize. These rules enable automatic resizing.

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

+ Table: Resizing rules +
Resize policy	Description	Illustration
ResizePolicy::FIXED	Use this option to maintain a specific size as set by the SetSize() function. This is the default for all actors.
ResizePolicy::USE_NATURAL_SIZE	Use this option for objects, such as images or text to get their natural size. This can mean the dimensions of an image or the size of text with no wrapping. You can also use this option with table views when the size of the table depends on its children.
ResizePolicy::FILL_TO_PARENT	The size of the actor is similar to its parent's size with proportionate filling considered.
ResizePolicy::SIZE_RELATIVE_TO_PARENT	The size of the actor is similar to its parent's size with a relative scale. Use the SetSizeModeFactor() function to specify the ratio.
ResizePolicy::SIZE_FIXED_OFFSET_FROM_PARENT	The size of the actor is similar to its parent's size with a fixed offset using the SetSizeModeFactor function.
ResizePolicy::FIT_TO_CHILDREN	The size of the actor is scaled around the size of the its children. For example, the height of a pop-up can be resized according to its contents.
ResizePolicy::DIMENSION_DEPENDENCY	This option covers rules, such as width-for-height and height-for-width. You can specify that one dimension depends on another.

+ + +

Example with Actors

+ +

This section describes a layout example with a actor.

+ +

Enabling Size Negotiation

+ +

Text and image actors have relayout enabled by default, while plain actors are disabled unless the SetResizePolicy() function is called.

+ +

Specifying Size Policies

+ +

You can specify how an actor is size-negotiated:

+ +

void SetResizePolicy(ResizePolicy::Type policy, Dimension::Type dimension) @endcode

+ +

Actor rootActor = Actor::New();
+rootActor.SetResizePolicy(ResizePolicy::FILL_TO_PARENT, Dimension::WIDTH);
+rootActor.SetResizePolicy(ResizePolicy::FIT_TO_CHILDREN, Dimension::HEIGHT);
+ImageActor image = ImageActor::New(Image::New(MY_IMAGE_PATH));
+image.SetResizePolicy(ResizePolicy::USE_NATURAL_SIZE, Dimension::ALL_DIMENSIONS);
+rootActor.Add(image);

+ +

The following images show the before and after layouts for this code example.

+ +

Figure: Before and after setting the resize policy

Before and after setting the resize policy

+ + +

This example shows a root actor set to expand to its parent's width and adjust around its child's height. The child image actor is set to its natural size.

+ +

TextLabel text = TextLabel::New("Example");
+text.SetResizePolicy(ResizePolicy::FILL_TO_PARENT, Dimension::WIDTH);
+text.SetResizePolicy(ResizePolicy::DIMENSION_DEPENDENCY, Dimension::HEIGHT);

+ +

Specifying Sizes and Size Limits

+ +

To constrain the final negotiated size of an actor, set the following minimum and maximum sizes, respectively:

+ +

void SetMinimumSize(const Vector2& size)
+void SetMaximumSize(const Vector2& size)

+ +

Adjusting the Negotiated Size

+ +

You can use the following resize policies:

SizeScalePolicy::USE_SIZE_SET +
This is the default policy.
SizeScalePolicy::FIT_WITH_ASPECT_RATIO +
Fits the actor within the bounds it has been allocated while maintaining the aspect ratio.
SizeScalePolicy::FILL_WITH_ASPECT_RATIO +
Fills all available space, potentially overflowing its bounds, while maintaining aspect ratio.

+ +

void SetSizeScalePolicy(SizeScalePolicy::Type policy)

+ +

Using Actors in Containers

+ +

When using actors in containers, such as a table view, you can specify the padding surrounding the actor. The padding specifies the left, right, bottom, and top padding value.

+ +

void SetPadding(const Padding& padding)

+ + + + + + + + + + +

Note
Beware of infinite dependency loops! + The simplest form of this is shown when the resize policy of a parent actor is set to ResizePolicy::FIT_TO_CHILDREN with a child that has a resize policy of ResizePolicy::FILL_TO_PARENT. + A more complex loop occurs when a parent actor has a width policy of ResizePolicy::DIMENSION_DEPENDENCY with a height policy of ResizePolicy::FIT_TO_CHILDREN. The parent has a single child with a height policy ResizePolicy::DIMENSION_DEPENDENCY with width. If the child's width policy is ResizePolicy::FILL_TO_PARENT, a loop occurs. + Loops can occur over larger spreads of parent-child relationships. These loops are detected by the relayout algorithm, which allocates actors 0 sizes.

Note

Beware of infinite dependency loops!

The simplest form of this is shown when the resize policy of a parent actor is set to ResizePolicy::FIT_TO_CHILDREN with a child that has a resize policy of ResizePolicy::FILL_TO_PARENT.

Loops can occur over larger spreads of parent-child relationships. These loops are detected by the relayout algorithm, which allocates actors 0 sizes.

+ + + + +

+ +

+ + + + + + + +