Layers provide a mechanism for overlaying groups of actors on top of each other. More...

Inheritance diagram for Dali::Layer:

Classes
struct	Property
	An enumeration of properties belonging to the Layer class. More...
Public Types
enum	Behavior
	Enumeration for the behavior of the layer. More...
enum	TreeDepthMultiplier
	TREE_DEPTH_MULTIPLIER is used by the rendering sorting algorithm to decide which actors to render first. More...
typedef float(*	SortFunctionType )(const Vector3 &position)
	The sort function type.
Public Member Functions
	Layer ()
	Create an empty Layer handle.
	~Layer ()
	Destructor.
	Layer (const Layer &copy)
	Copy constructor.
Layer &	operator= (const Layer &rhs)
	Assignment operator.
unsigned int	GetDepth () const
	Query the depth of the layer.
void	Raise ()
	Increment the depth of the layer.
void	Lower ()
	Decrement the depth of the layer.
void	RaiseAbove (Layer target)
	Ensures the layers depth is greater than the target layer.
void	LowerBelow (Layer target)
	Ensures the layers depth is less than the target layer.
void	RaiseToTop ()
	Raises the layer to the top.
void	LowerToBottom ()
	Lowers the layer to the bottom.
void	MoveAbove (Layer target)
	Moves the layer directly above the given layer.
void	MoveBelow (Layer target)
	Moves the layer directly below the given layer.
void	SetBehavior (Behavior behavior)
	Set the behavior of the layer.
Behavior	GetBehavior () const
	Get the behavior of the layer.
void	SetClipping (bool enabled)
	Sets whether clipping is enabled for a layer.
bool	IsClipping () const
	Query whether clipping is enabled for a layer.
void	SetClippingBox (int x, int y, int width, int height)
	Sets the clipping box of a layer, in window coordinates.
void	SetClippingBox (ClippingBox box)
	Sets the clipping box of a layer, in window coordinates.
ClippingBox	GetClippingBox () const
	Retrieves the clipping box of a layer, in window coordinates.
void	SetDepthTestDisabled (bool disable)
	Whether to disable the depth test.
bool	IsDepthTestDisabled () const
	Retrieves whether depth test is disabled.
void	SetSortFunction (SortFunctionType function)
	This allows the user to specify the sort function that the layer should use.
void	SetTouchConsumed (bool consume)
	This allows the user to specify whether this layer should consume touch (including gestures).
bool	IsTouchConsumed () const
	Retrieves whether the layer consumes touch (including gestures).
void	SetHoverConsumed (bool consume)
	This allows the user to specify whether this layer should consume hover.
bool	IsHoverConsumed () const
	Retrieves whether the layer consumes hover.
Static Public Member Functions
static Layer	New ()
	Create a Layer object.
static Layer	DownCast (BaseHandle handle)
	Downcast a handle to Layer handle.

Detailed Description

Layers provide a mechanism for overlaying groups of actors on top of each other.

When added to the stage, a layer can be ordered relative to other layers. The bottom layer is at depth zero. The stage provides a default layer for it's children (see Stage::GetRootLayer()).

Layered actors inherit position etc. as normal, but are drawn in an order determined by the layers. In case of LAYER_3D, the depth buffer is cleared before each layer is rendered unless depth test is disabled or there's no need for it based on the layers contents; actors in lower layers cannot obscure actors in higher layers.

A layer has either LAYER_2D or LAYER_3D mode. LAYER_2D has better performance, the depth test is disabled, and a child actor hides its parent actor. LAYER_3D uses the depth test, thus a close actor hides a farther one. LAYER_2D is the default mode and recommended for general cases. See Layer::Behavior and SetBehavior() for more information.

Layer is a type of Actor, thus can have parent or children actors. A layer influences rendering of its all descendant actors, until another layer appears in the actor tree and manages its own subtree.

If depth test is disabled, there is no performance overhead from clearing the depth buffer.

Since :: 2.4

Member Typedef Documentation

typedef float(* Dali::Layer::SortFunctionType)(const Vector3 &position)

The sort function type.

Since :: 2.4

Parameters:

[in] position This is the actor translation from camera.

Member Enumeration Documentation

enum Dali::Layer::Behavior

Enumeration for the behavior of the layer.

Check each value to see how it affects the layer.

Since :: 2.4

Enumerator:

LAYER_2D

Layer doesn't make use of the depth test (default mode).

This mode is expected to have better performance than the 3D mode. When using this mode any ordering would be with respect to tree level of each Actor.

For the following actor tree of the Layer1 object, D and E hide B, B and C hides A, and F hides C, regardless of their Z positions. Rendering order between siblings, such as D & E or B & C, is not determined. If you have two overlapped actors, just make them parent-child, not siblings.

     Layer1 (parent)
       |
       A
      / \
     B   C
    / \   \
   D   E   F

Since :: 2.4

LAYER_3D

Layer will use depth test and do several clears.

When using this mode depth test will be used. A depth clear will happen for each layer, which means actors in a layer "above" other layers will be rendered in front of actors in those layers regardless of their Z positions (see Layer::Raise() and Layer::Lower()). Opaque renderers are drawn first and write to the depth buffer. Then transparent renderers are drawn with depth test enabled but depth write switched off. Unlike LAYER_2D, parent-child relationship does not affect rendering order at all.

Since :: 2.4

Remarks:: This is an experimental feature. Using 2D UI components of DALi Toolkit in LAYER_3D mode has not been enoughly tested yet because they are orginally designed for 2D use cases. Simple controls such as Toolkit::Control or Toolkit::ImageView might not have any problem with LAYER_3D, but more complex one like Toolkit::PushButton, you might get unexpected rendered order in LAYER_3D. Although we'll support 2D controls in LAYER_3D soon, we recommend to use 2D controls with LAYER_2D only at this moment. Of course, controls rendered in 3D space, such as SpiralLayout of Toolkit::ItemView (see Toolkit::DefaultItemLayout::New), should be used with LAYER_3D.

enum Dali::Layer::TreeDepthMultiplier

TREE_DEPTH_MULTIPLIER is used by the rendering sorting algorithm to decide which actors to render first.

Since :: 2.4

Constructor & Destructor Documentation

Dali::Layer::Layer ( )

Create an empty Layer handle.

This can be initialised with Layer::New(...).

Since :: 2.4

Dali::Layer::~Layer ( )

Destructor.

This is non-virtual since derived Handle types must not contain data or virtual methods.

Since :: 2.4

Dali::Layer::Layer ( const Layer & copy )

Copy constructor.

Since :: 2.4

Parameters:

[in] copy The actor to copy

Member Function Documentation

static Layer Dali::Layer::DownCast ( BaseHandle handle ) [static]

Downcast a handle to Layer handle.

If handle points to a Layer the downcast produces valid handle. If not the returned handle is left uninitialized.

Since :: 2.4

Parameters:

[in] handle Handle to An object

Returns:: Handle to a Layer or an uninitialized handle

Reimplemented from Dali::Actor.

Behavior Dali::Layer::GetBehavior ( ) const

Get the behavior of the layer.

Since :: 2.4

Returns:: The behavior of the layer

ClippingBox Dali::Layer::GetClippingBox ( ) const

Retrieves the clipping box of a layer, in window coordinates.

Since :: 2.4

Returns:: The clipping box

unsigned int Dali::Layer::GetDepth ( ) const

Query the depth of the layer.

0 is bottom most layer, higher number is on top.

Since :: 2.4

Returns:: The current depth of the layer

Precondition:: Layer is on the stage. If layer is not added to the stage, returns 0.

bool Dali::Layer::IsClipping ( ) const

Query whether clipping is enabled for a layer.

Since :: 2.4

Returns:: True if clipping is enabled.

bool Dali::Layer::IsDepthTestDisabled ( ) const

Retrieves whether depth test is disabled.

Since :: 2.4

Returns:: True if depth test is disabled.

bool Dali::Layer::IsHoverConsumed ( ) const

Retrieves whether the layer consumes hover.

Since :: 2.4

Returns:: True if consuming hover, false otherwise.

bool Dali::Layer::IsTouchConsumed ( ) const

Retrieves whether the layer consumes touch (including gestures).

Since :: 2.4

Returns:: True if consuming touch, false otherwise.

void Dali::Layer::Lower ( )

Decrement the depth of the layer.

Since :: 2.4

Precondition:: Layer is on the stage.

void Dali::Layer::LowerBelow ( Layer target )

Ensures the layers depth is less than the target layer.

If the layer already is below the target layer its depth is not changed. If the layer was above target, its new depth will be immediately below target.

Since :: 2.4

Parameters:

target Layer to get below of

Precondition:: Layer is on the stage.; Target layer is on the stage.

Note:: All layers between this layer and target get new depth values.

void Dali::Layer::LowerToBottom ( )

Lowers the layer to the bottom.

Since :: 2.4

Precondition:: layer is on the stage.

void Dali::Layer::MoveAbove ( Layer target )

Moves the layer directly above the given layer.

After the call this layers depth will be immediately above target.

Since :: 2.4

Parameters:

target Layer to get on top of

Precondition:: Layer is on the stage.; Target layer is on the stage.

Note:: All layers between this layer and target get new depth values.

void Dali::Layer::MoveBelow ( Layer target )

Moves the layer directly below the given layer.

After the call this layers depth will be immediately below target.

Since :: 2.4

Parameters:

target Layer to get below of

Precondition:: Layer is on the stage.; Target layer is on the stage.

Note:: All layers between this layer and target get new depth values.

static Layer Dali::Layer::New ( ) [static]

Create a Layer object.

Since :: 2.4

Returns:: A handle to a newly allocated Layer

Reimplemented from Dali::Actor.

Layer& Dali::Layer::operator= ( const Layer & rhs )

Assignment operator.

Since :: 2.4

Parameters:

[in] rhs The actor to copy

Returns:: A reference to this

void Dali::Layer::Raise ( )

Increment the depth of the layer.

Since :: 2.4

Precondition:: Layer is on the stage.

void Dali::Layer::RaiseAbove ( Layer target )

Ensures the layers depth is greater than the target layer.

If the layer already is above the target layer its depth is not changed. If the layer was below target, its new depth will be immediately above target.

Since :: 2.4

Parameters:

target Layer to get above of

Precondition:: Layer is on the stage.; Target layer is on the stage.

Note:: All layers between this layer and target get new depth values.

void Dali::Layer::RaiseToTop ( )

Raises the layer to the top.

Since :: 2.4

Precondition:: Layer is on the stage.

void Dali::Layer::SetBehavior ( Behavior behavior )

Set the behavior of the layer.

Since :: 2.4

Parameters:

[in] behavior The desired behavior

void Dali::Layer::SetClipping ( bool enabled )

Sets whether clipping is enabled for a layer.

Clipping is initially disabled; see also SetClippingBox().

Since :: 2.4

Parameters:

[in] enabled True if clipping is enabled.

Note:: When clipping is enabled, the default clipping box is empty (0,0,0,0) which means everything is clipped.

void Dali::Layer::SetClippingBox	(	int	x,
		int	y,
		int	width,
		int	height
	)

Sets the clipping box of a layer, in window coordinates.

The contents of the layer will not be visible outside this box, when clipping is enabled. The default clipping box is empty (0,0,0,0) which means everything is clipped. You can only do rectangular clipping using this API in window coordinates. For other kinds of clipping, see Dali::Actor::SetDrawMode().

Since :: 2.4

Parameters:

[in]	x	The X-coordinate of the top-left corner of the box
[in]	y	The Y-coordinate of the top-left corner of the box
[in]	width	The width of the box
[in]	height	The height of the box

void Dali::Layer::SetClippingBox ( ClippingBox box )

Sets the clipping box of a layer, in window coordinates.

The contents of the layer will not be visible outside this box, when clipping is enabled. The default clipping box is empty (0,0,0,0).

Since :: 2.4

Parameters:

[in] box The clipping box

void Dali::Layer::SetDepthTestDisabled ( bool disable )

Whether to disable the depth test.

By default a layer enables depth test if there is more than one opaque actor or if there is one opaque actor and one, or more, transparent actors in LAYER_3D mode. However, it's possible to disable the depth test by calling this method.

Since :: 2.4

Parameters:

[in] disable True disables depth test. false sets the default behavior.

void Dali::Layer::SetHoverConsumed ( bool consume )

This allows the user to specify whether this layer should consume hover.

If set, any layers behind this layer will not be hit-test.

Since :: 2.4

Parameters:

[in] consume Whether the layer should consume hover.

void Dali::Layer::SetSortFunction ( SortFunctionType function )

This allows the user to specify the sort function that the layer should use.

The sort function is used to determine the order in which the actors are drawn and input is processed on the actors in the layer.

A function of the following type should be used:

  float YourSortFunction(const Vector3& position);

Since :: 2.4

Parameters:

[in] function The sort function pointer

Note:: If the sort function returns a low number, the actor with the data will be drawn in front of an actor whose data yields a high value from the sort function.; All child layers use the same sort function. If a child layer is added to this layer then the sort function used by the child layer will also be the same.

void Dali::Layer::SetTouchConsumed ( bool consume )

This allows the user to specify whether this layer should consume touch (including gestures).

If set, any layers behind this layer will not be hit-test.

Since :: 2.4

Parameters:

[in] consume Whether the layer should consume touch (including gestures).

Classes

Public Types

Public Member Functions

Static Public Member Functions

Detailed Description

Member Typedef Documentation

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation