Tizen Native API  4.0
Classes | Public Types | Public Member Functions | Static Public Member Functions
Dali::Toolkit::Control Class Reference
Controls

Control is the base class for all controls. More...

Inheritance diagram for Dali::Toolkit::Control:
Dali::CustomActor Dali::Actor Dali::Handle Dali::BaseHandle Dali::Toolkit::Alignment Dali::Toolkit::Button Dali::Toolkit::FlexContainer Dali::Toolkit::ImageView Dali::Toolkit::Model3dView Dali::Toolkit::ProgressBar Dali::Toolkit::Scrollable Dali::Toolkit::ScrollBar Dali::Toolkit::Slider Dali::Toolkit::TableView Dali::Toolkit::TextEditor Dali::Toolkit::TextField Dali::Toolkit::TextLabel Dali::Toolkit::VideoView Dali::WidgetView::WidgetView

Classes

struct  KeyboardFocus
 Describes the direction to move the keyboard focus towards. More...
struct  Property
 Enumeration for the instance of properties belonging to the Control class. More...

Public Types

enum  PropertyRange
 Enumeration for the start and end property ranges for control. More...
typedef Signal< bool(Control,
const KeyEvent &) > 		KeyEventSignalType
 Key Event signal type.
typedef Signal< void(Control) > KeyInputFocusSignalType
 Key InputFocusType signal type.
typedef Signal< void(Control) > ResourceReadySignalType
 ResourceReady signal type.

Public Member Functions

 Control ()
 Creates an uninitialized Control handle.
 Control (const Control &uiControl)
 Copy constructor.
 ~Control ()
 Dali::Control is intended as a base class.
Control & operator= (const Control &handle)
 Assignment operator.
void SetKeyInputFocus ()
 This sets the control to receive key events.
bool HasKeyInputFocus ()
 Quries whether the control has key input focus.
void ClearKeyInputFocus ()
 Once an actor is Set to receive key input focus this function is called to stop it receiving key events.
PinchGestureDetector GetPinchGestureDetector () const
 Retrieves the pinch gesture detector of the control.
PanGestureDetector GetPanGestureDetector () const
 Retrieves the pan gesture detector of the control.
TapGestureDetector GetTapGestureDetector () const
 Retrieves the tap gesture detector of the control.
LongPressGestureDetector GetLongPressGestureDetector () const
 Retrieves the long press gesture detector of the control.
void SetStyleName (const std::string &styleName)
 Sets the name of the style to be applied to the control.
const std::string & GetStyleName () const
 Retrieves the name of the style to be applied to the control (if any).
void SetBackgroundColor (const Vector4 &color)
 Sets the background color of the control.
Vector4 GetBackgroundColor () const DALI_DEPRECATED_API
 Retrieves the background color of the control.
void SetBackgroundImage (Image image) DALI_DEPRECATED_API
 Sets an image as the background of the control.
void ClearBackground ()
 Clears the background.
bool IsResourceReady () const
 Query if all resources required by a control are loaded and ready.
Visual::ResourceStatus GetVisualResourceStatus (const Dali::Property::Index index)
 Get the loading state of the visual resource.
KeyEventSignalType & KeyEventSignal ()
 This signal is emitted when key event is received.
KeyInputFocusSignalType & KeyInputFocusGainedSignal ()
 This signal is emitted when the control gets Key Input Focus.
KeyInputFocusSignalType & KeyInputFocusLostSignal ()
 This signal is emitted when the control loses Key Input Focus.
ResourceReadySignalType & ResourceReadySignal ()
 This signal is emitted after all resources required by a control are loaded and ready.
 Control (Internal::Control &implementation)
 Creates an initialized Control.
 Control (Dali::Internal::CustomActor *internal)
 This constructor is used by CustomActor within Dali core to create additional Control handles using an Internal CustomActor pointer.
template<typename I >
void VerifyCustomActorPointer (Dali::Internal::CustomActor *internal)
 Template to allow deriving controls to verify whether the Internal::CustomActor* is actually an implementation of their class.

Static Public Member Functions

static Control New ()
 Creates a new instance of a Control.
static Control DownCast (BaseHandle handle)
 Downcasts a handle to Control handle.
template<typename T , typename I >
static T DownCast (BaseHandle handle)
 Template to allow deriving controls to DownCast handles to deriving handle classes.

Detailed Description

Control is the base class for all controls.

The implementation of the control must be supplied; see Internal::Control for more details.

Since:
2.4, DALi version 1.0.0
See also:
Internal::Control

Signals | Signal Name | Method | |------------------------|-----------------------------------------------------| | keyEvent | KeyEventSignal() | | keyInputFocusGained | KeyInputFocusGainedSignal() | | keyInputFocusLost | KeyInputFocusLostSignal() | | resourceReady | ResourceReadySignal() | | tapped | GetTapGestureDetector().DetectedSignal() | | panned | GetPanGestureDetector().DetectedSignal() | | pinched | GetPinchGestureDetector().DetectedSignal() | | longPressed | GetLongPressGestureDetector().DetectedSignal() |

Actions | Action Name | Control method called | |------------------------|----------------------------------------------------| | accessibilityActivated | OnAccessibilityActivated() |

Member Typedef Documentation

typedef Signal<bool ( Control, const KeyEvent& ) > Dali::Toolkit::Control::KeyEventSignalType

Key Event signal type.

Since:
2.4, DALi version 1.0.0
typedef Signal<void ( Control ) > Dali::Toolkit::Control::KeyInputFocusSignalType

Key InputFocusType signal type.

Since:
2.4, DALi version 1.0.0
typedef Signal<void ( Control ) > Dali::Toolkit::Control::ResourceReadySignalType

ResourceReady signal type.

Since:
4.0, DALi version 1.2.60

Member Enumeration Documentation

enum Dali::Toolkit::Control::PropertyRange

Enumeration for the start and end property ranges for control.

Since:
2.4, DALi version 1.0.0
Enumerator:
PROPERTY_START_INDEX 

Start index is used by the property registration macro.

Since:
2.4, DALi version 1.0.0
CONTROL_PROPERTY_START_INDEX 

Start index of Control properties.

Since:
2.4, DALi version 1.0.0
CONTROL_PROPERTY_END_INDEX 

Reserving 1000 property indices.

Since:
2.4, DALi version 1.0.0

Reimplemented in Dali::Toolkit::ScrollView, Dali::Toolkit::FlexContainer, Dali::Toolkit::Button, Dali::Toolkit::PushButton, Dali::Toolkit::TableView, Dali::Toolkit::ImageView, Dali::Toolkit::ItemView, Dali::Toolkit::VideoView, Dali::Toolkit::TextLabel, Dali::WidgetView::WidgetView, Dali::Toolkit::ScrollBar, Dali::Toolkit::Scrollable, Dali::Toolkit::ProgressBar, Dali::Toolkit::Slider, Dali::Toolkit::TextEditor, Dali::Toolkit::TextField, and Dali::Toolkit::Model3dView.

Constructor & Destructor Documentation

Dali::Toolkit::Control::Control ( )

Creates an uninitialized Control handle.

Only derived versions can be instantiated. Calling member functions with an uninitialized Dali::Object is not allowed.

Since:
2.4, DALi version 1.0.0
Dali::Toolkit::Control::Control ( const Control &  uiControl)

Copy constructor.

Creates another handle that points to the same real object.

Since:
2.4, DALi version 1.0.0
Parameters:
[in]uiControlHandle to copy
Dali::Toolkit::Control::~Control ( )

Dali::Control is intended as a base class.

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

Since:
2.4, DALi version 1.0.0
Dali::Toolkit::Control::Control ( Internal::Control &  implementation) [explicit]

Creates an initialized Control.

Since:
2.4, DALi version 1.0.0
Parameters:
[in]implementationThe implementation for this control
Returns:
A handle to a newly allocated Dali resource
Note:
Should NOT be called to create a handle from the implementation. As stated, this allocates a NEW Dali resource.
Dali::Toolkit::Control::Control ( Dali::Internal::CustomActor *  internal) [explicit]

This constructor is used by CustomActor within Dali core to create additional Control handles using an Internal CustomActor pointer.

Since:
2.4, DALi version 1.0.0
Parameters:
[in]internalA pointer to a newly allocated Dali resource

Member Function Documentation

void Dali::Toolkit::Control::ClearBackground ( )

Clears the background.

Since:
2.4, DALi version 1.0.0
void Dali::Toolkit::Control::ClearKeyInputFocus ( )

Once an actor is Set to receive key input focus this function is called to stop it receiving key events.

A check is performed to ensure it was previously set, if this check fails then nothing is done.

Since:
2.4, DALi version 1.0.0
Precondition:
The Actor has been initialized.
static Control Dali::Toolkit::Control::DownCast ( BaseHandle  handle) [static]

Downcasts a handle to Control handle.

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

Since:
2.4, DALi version 1.0.0
Parameters:
[in]handleHandle to an object
Returns:
A handle to a Control or an uninitialized handle

Reimplemented from Dali::CustomActor.

Reimplemented in Dali::Toolkit::ScrollView, Dali::Toolkit::TextField, Dali::Toolkit::TextEditor, Dali::Toolkit::TextLabel, Dali::Toolkit::FlexContainer, Dali::Toolkit::VideoView, Dali::Toolkit::ItemView, Dali::Toolkit::TableView, Dali::Toolkit::Button, Dali::Toolkit::ScrollBar, Dali::Toolkit::ImageView, Dali::Toolkit::Slider, Dali::Toolkit::ProgressBar, Dali::WidgetView::WidgetView, Dali::Toolkit::PushButton, Dali::Toolkit::Alignment, Dali::Toolkit::Model3dView, Dali::Toolkit::Scrollable, Dali::Toolkit::RadioButton, and Dali::Toolkit::CheckBoxButton.

template<typename T , typename I >
static T Dali::Toolkit::Control::DownCast ( BaseHandle  handle) [static]

Template to allow deriving controls to DownCast handles to deriving handle classes.

Template Parameters:
TThe handle class
IThe implementation class
Since:
2.4, DALi version 1.0.0
Parameters:
[in]handleHandle to an object
Returns:
Handle to a class T or an uninitialized handle
See also:
DownCast(BaseHandle)

Reimplemented from Dali::CustomActor.

Reimplemented in Dali::Toolkit::ScrollView, Dali::Toolkit::TextField, Dali::Toolkit::TextEditor, Dali::Toolkit::TextLabel, Dali::Toolkit::FlexContainer, Dali::Toolkit::VideoView, Dali::Toolkit::ItemView, Dali::Toolkit::TableView, Dali::Toolkit::Button, Dali::Toolkit::ScrollBar, Dali::Toolkit::ImageView, Dali::Toolkit::Slider, Dali::Toolkit::ProgressBar, Dali::WidgetView::WidgetView, Dali::Toolkit::PushButton, Dali::Toolkit::Alignment, Dali::Toolkit::Model3dView, Dali::Toolkit::Scrollable, Dali::Toolkit::RadioButton, and Dali::Toolkit::CheckBoxButton.

Vector4 Dali::Toolkit::Control::GetBackgroundColor ( ) const

Retrieves the background color of the control.

Deprecated:
Deprecated since 3.0, DALi version 1.1.3
Since:
2.4, DALi version 1.0.0
Returns:
The background color of the control
LongPressGestureDetector Dali::Toolkit::Control::GetLongPressGestureDetector ( ) const

Retrieves the long press gesture detector of the control.

Since:
2.4, DALi version 1.0.0
Returns:
The long press gesture detector
Note:
Will return an empty handle if the control does not handle the gesture itself.
PanGestureDetector Dali::Toolkit::Control::GetPanGestureDetector ( ) const

Retrieves the pan gesture detector of the control.

Since:
2.4, DALi version 1.0.0
Returns:
The pan gesture detector
Note:
Will return an empty handle if the control does not handle the gesture itself.
PinchGestureDetector Dali::Toolkit::Control::GetPinchGestureDetector ( ) const

Retrieves the pinch gesture detector of the control.

Since:
2.4, DALi version 1.0.0
Returns:
The pinch gesture detector
Note:
Will return an empty handle if the control does not handle the gesture itself.
const std::string& Dali::Toolkit::Control::GetStyleName ( ) const

Retrieves the name of the style to be applied to the control (if any).

Since:
2.4, DALi version 1.0.0
Returns:
A string matching a style, or an empty string
TapGestureDetector Dali::Toolkit::Control::GetTapGestureDetector ( ) const

Retrieves the tap gesture detector of the control.

Since:
2.4, DALi version 1.0.0
Returns:
The tap gesture detector
Note:
Will return an empty handle if the control does not handle the gesture itself.
Visual::ResourceStatus Dali::Toolkit::Control::GetVisualResourceStatus ( const Dali::Property::Index  index)

Get the loading state of the visual resource.

Since:
4.0, DALi version 1.3.5
Parameters:
[in]indexThe Property index of the visual
Returns:
Return the loading status (PREPARING, READY and FAILED) of visual resource
bool Dali::Toolkit::Control::HasKeyInputFocus ( )

Quries whether the control has key input focus.

Since:
2.4, DALi version 1.0.0
Returns:
true if this control has keyboard input focus
Precondition:
The Control has been initialized.
The Control should be on the stage before setting keyboard focus.
Note:
The control can be set to have the focus and still not receive all the key events if another control has over ridden it. As the key input focus mechanism works like a stack, the top most control receives all the key events, and passes on the unhandled events to the controls below in the stack. A control in the stack will regain key input focus when there are no more controls above it in the focus stack. To query for the control which is on top of the focus stack use Dali::Toolkit::KeyInputFocusManager::GetCurrentKeyboardFocusActor().
bool Dali::Toolkit::Control::IsResourceReady ( ) const

Query if all resources required by a control are loaded and ready.

Most resources are only loaded when the control is placed on stage.

Since:
4.0, DALi version 1.2.60
Returns:
true if the resources are loaded and ready, false otherwise
KeyEventSignalType& Dali::Toolkit::Control::KeyEventSignal ( )

This signal is emitted when key event is received.

A callback of the following type may be connected: 

   bool YourCallbackName(Control control, const KeyEvent& event);

The return value of True, indicates that the event should be consumed. Otherwise the signal will be emitted on the next parent of the actor.

Since:
2.4, DALi version 1.0.0
Returns:
The signal to connect to
Precondition:
The Control has been initialized.
KeyInputFocusSignalType& Dali::Toolkit::Control::KeyInputFocusGainedSignal ( )

This signal is emitted when the control gets Key Input Focus.

A callback of the following type may be connected: 

   bool YourCallbackName( Control control );

The return value of True, indicates that the event should be consumed. Otherwise the signal will be emitted on the next parent of the actor.

Since:
2.4, DALi version 1.0.0
Returns:
The signal to connect to
Precondition:
The Control has been initialized.
KeyInputFocusSignalType& Dali::Toolkit::Control::KeyInputFocusLostSignal ( )

This signal is emitted when the control loses Key Input Focus.

This could be due to it being gained by another Control or Actor or just cleared from this control as no longer required.

A callback of the following type may be connected: 

   bool YourCallbackName( Control control );

The return value of True, indicates that the event should be consumed. Otherwise the signal will be emitted on the next parent of the actor.

Since:
2.4, DALi version 1.0.0
Returns:
The signal to connect to
Precondition:
The Control has been initialized.
static Control Dali::Toolkit::Control::New ( ) [static]

Creates a new instance of a Control.

Since:
2.4, DALi version 1.0.0
Returns:
A handle to a new Control

Reimplemented from Dali::Actor.

Reimplemented in Dali::Toolkit::ScrollView, Dali::Toolkit::TextField, Dali::Toolkit::TextEditor, Dali::Toolkit::TextLabel, Dali::Toolkit::FlexContainer, Dali::Toolkit::VideoView, Dali::Toolkit::Slider, Dali::Toolkit::ProgressBar, Dali::Toolkit::PushButton, Dali::Toolkit::ImageView, Dali::Toolkit::RadioButton, Dali::Toolkit::CheckBoxButton, and Dali::Toolkit::Model3dView.

Control& Dali::Toolkit::Control::operator= ( const Control &  handle)

Assignment operator.

Changes this handle to point to another real object.

Since:
2.4, DALi version 1.0.0
Parameters:
[in]handleObject to assign this to
Returns:
Reference to this
ResourceReadySignalType& Dali::Toolkit::Control::ResourceReadySignal ( )

This signal is emitted after all resources required by a control are loaded and ready.

Most resources are only loaded when the control is placed on stage.

If resources are shared between ImageViews, they are cached. In this case, the ResourceReady signal may be sent before there is an object to connect to. To protect against this, IsResourceReady() can be checked first.

    auto newControl = Control::New();
    newControl.SetResource( resourceUrl );
    if ( newControl.IsResourceReady() )
    {
       // do something
    }
    else
    {
      newControl.ResourceReadySignal.Connect( .... )
    }

A callback of the following type may be connected: 

   void YourCallbackName( Control control );
Since:
4.0, DALi version 1.2.60
Returns:
The signal to connect to
Note:
A RelayoutRequest is queued by Control before this signal is emitted
void Dali::Toolkit::Control::SetBackgroundColor ( const Vector4 &  color)

Sets the background color of the control.

Since:
2.4, DALi version 1.0.0
Parameters:
[in]colorThe required background color of the control
Note:
If SetBackgroundImage is called later, this background color is removed.
The background color fully blends with the actor color.
void Dali::Toolkit::Control::SetBackgroundImage ( Image  image)

Sets an image as the background of the control.

Deprecated:
Deprecated since 3.0, DALi version 1.2.8, use Property::BACKGROUND instead
Since:
2.4, DALi version 1.0.0
Parameters:
[in]imageThe image to set as the background
void Dali::Toolkit::Control::SetKeyInputFocus ( )

This sets the control to receive key events.

The key event can originate from a virtual or physical keyboard.

Since:
2.4, DALi version 1.0.0
Precondition:
The Control has been initialized.
The Control should be on the stage before setting keyboard focus.
void Dali::Toolkit::Control::SetStyleName ( const std::string &  styleName)

Sets the name of the style to be applied to the control.

Since:
2.4, DALi version 1.0.0
Parameters:
[in]styleNameA string matching a style described in a stylesheet
template<typename I >
void Dali::Toolkit::Control::VerifyCustomActorPointer ( Dali::Internal::CustomActor *  internal)

Template to allow deriving controls to verify whether the Internal::CustomActor* is actually an implementation of their class.

Template Parameters:
IThe implementation class
Since:
2.4, DALi version 1.0.0
Parameters:
[in]internalPointer to the Internal::CustomActor