(Touch) Updated programming guide, Automated Tests & KeyboardFocusManager to use...

[platform/core/uifw/dali-toolkit.git] / docs / content / shared-javascript-and-cpp-documentation / creating-custom-controls.md

diff --git a/docs/content/shared-javascript-and-cpp-documentation/creating-custom-controls.md b/docs/content/shared-javascript-and-cpp-documentation/creating-custom-controls.md
index b40262b..946b4f0 100644 (file)
--- a/docs/content/shared-javascript-and-cpp-documentation/creating-custom-controls.md
+++ b/docs/content/shared-javascript-and-cpp-documentation/creating-custom-controls.md
@@ -137,7 +137,6 @@ Dali::Toolkit::Internal::Control provides several behaviours which are specified
 | Behaviour                            | Description                                                             |
 |--------------------------------------|-------------------------------------------------------------------------|
 | ACTOR_BEHAVIOUR_NONE                 | No behaviour required.                                                  |
-| REQUIRES_TOUCH_EVENTS                | If our control requires [touch events](@ref creating-controls-events).  |
 | REQUIRES_HOVER_EVENTS                | If our control requires [hover events](@ref creating-controls-events).  |
 | REQUIRES_WHEEL_EVENTS                | If our control requires [wheel events](@ref creating-controls-events).  |
 | REQUIRES_STYLE_CHANGE_SIGNALS        | True if need to monitor style change signals such as Theme/Font change. |
@@ -146,25 +145,11 @@ ________________________________________________________________________________
 
 ### Touch, Hover & Wheel Events {#creating-controls-events}
 
-+ A **touch event** is when any touch occurs within the bounds of the custom actor.
++ A **touch** is when any touch occurs within the bounds of the custom actor. Connect to Dali::Actor::TouchSignal().
 + A **hover event** is when a pointer moves within the bounds of a custom actor (e.g. mouse pointer or hover pointer).
 + A **wheel event** is when the mouse wheel (or similar) is moved while hovering over an actor (via a mouse pointer or hover pointer).
  
-If the control should needs to utilise these events, then the correct behaviour flag should be used when constructing the control.
- 
-Then the appropriate method should be overridden.
-~~~{.cpp}
-// C++
-bool MyUIControlImpl::OnTouchEvent( const TouchEvent& event )
-{
-  bool consumed = false;
-
-  // Handle touch event
-
-  // Return true if handled/consumed, false otherwise
-  return consumed;
-}
-~~~
+If the control needs to utilise hover and wheel events, then the correct behaviour flag should be used when constructing the control and then the appropriate method should be overridden.
 ~~~{.cpp}
 // C++
 bool MyUIControlImpl::OnHoverEvent( const HoverEvent& event )
@@ -327,6 +312,93 @@ void AppFunction()
 
 customControl.MyCustomSignal.Connect( this, &AppFunction );
 ~~~
+ 
+___________________________________________________________________________________________________
+
+### Children Added/Removed {#creating-controls-children}
+
+Methods are provided that can be overridden if notification is required when a child is added or removed from our control.
+An up call to the Control class is necessary if these methods are overridden.
+ 
+~~~{.cpp}
+// C++
+void MyUIControlImpl::OnChildAdd( Actor& child );
+{
+  // Up call to Control first
+  Control::OnChildAdd( child );
+
+  // Do any other operations required upon child addition
+}
+~~~
+~~~{.cpp}
+// C++
+void MyUIControlImpl::OnChildRemove( Actor& child );
+{
+  // Do any other operations required upon child removal
+
+  // Up call to Control at the end
+  Control::OnChildRemove( child );
+}
+~~~
+ 
+Avoid adding or removing the child again within these methods.
+ 
+___________________________________________________________________________________________________
+
+### Stage Connection {#creating-controls-stage}
+
+Methods are provided that can be overridden if notification is required when our control is connected to or disconnected from the stage.
+An up call to the Control class is necessary if these methods are overridden.
+ 
+~~~{.cpp}
+// C++
+void MyUIControlImpl::OnStageConnection( int depth )
+{
+  // Up call to Control first
+  Control::OnStageConnection( depth );
+
+  // Do any other operations required upon stage connection
+}
+~~~
+~~~{.cpp}
+// C++
+void MyUIControlImpl::OnStageDisconnection()
+{
+  // Do any other operations required upon stage disconnection
+
+  // Up call to Control at the end
+  Control::OnStageDisconnection();
+}
+~~~
+ 
+___________________________________________________________________________________________________
+
+### Size {#creating-controls-size}
+
+Methods are provided that can be overridden if notification is required when our control's size is manipulated.
+An up call to the Control class is necessary if these methods are overridden.
+ 
+~~~{.cpp}
+// C++
+void MyUIControlImpl::OnSizeSet( const Vector3& targetSize )
+{
+  // Up call to Control
+  Control::OnSizeSet( targetSize );
+
+  // Do any other operations required upon size set
+}
+~~~
+~~~{.cpp}
+// C++
+void MyUIControlImpl::OnSizeAnimation( Animation& animation, const Vector3& targetSize )
+{
+  // Up call to Control
+  Control::OnSizeAnimation( animation, targetSize );
+
+  // Do any other operations required upon size animation
+}
+~~~
+ 
 ___________________________________________________________________________________________________
 
 ### Other Features {#creating-controls-other}