+
+___________________________________________________________________________________________________
+
+### 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 Internal::MyUIControl::OnChildAdd( Actor& child );
+{
+ // Do any other operations required upon child addition
+
+ // Up call to Control at the end
+ Control::OnChildAdd( child );
+}
+~~~
+~~~{.cpp}
+// C++
+void Internal::MyUIControl::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 Internal::MyUIControl::OnStageConnection( int depth )
+{
+ // Do any other operations required upon stage connection
+
+ // Up call to Control at the end
+ Control::OnStageConnection( depth );
+}
+~~~
+~~~{.cpp}
+// C++
+void Internal::MyUIControl::OnStageDisconnection()
+{
+ // Do any other operations required upon stage disconnection
+
+ // Up call to Control at the end
+ Control::OnStageDisconnection();
+}
+~~~
+
+___________________________________________________________________________________________________
+
+### Size Negotiation {#creating-controls-size-negotiation}
+
+The following methods must be overridden for size negotiation to work correctly with a custom control.
+
+~~~{.cpp}
+// C++
+Vector3 Internal::MyUIControl::GetNaturalSize()
+{
+ // Return the natural size of the control
+ // This depends on our layout
+ // If we have one visual, then we can return the natural size of that
+ // If we have more visuals, then we need to calculate their positions within our control and work out the overall size we would like our control to be
+
+ // After working out the natural size of visuals that belong to this control,
+ // should also chain up to ensure other visuals belonging to the base class are
+ // also taken into account:
+ Vector2 baseSize = Control::GetNaturalSize(); // returns the size of the background.
+}
+~~~
+~~~{.cpp}
+// C++
+float Internal::MyUIControl::GetHeightForWidth( float width )
+{
+ // Called by the size negotiation algorithm if we have a fixed width
+ // We should calculate the height we would like our control to be for that width
+
+ // Should also chain up to determine the base class's preferred height:
+ float baseHeight = Control::GetHeightForWidth( width );
+
+}
+~~~
+~~~{.cpp}
+// C++
+float Internal::MyUIControl::GetWidthForHeight( float height )
+{
+ // Called by the size negotiation algorithm if we have a fixed height
+ // We should calculate the width we would like our control to be for that height
+
+ // Should also chain up to determine the base class's preferred width:
+ float baseWidth = Control::GetWidth( height );
+}
+~~~
+~~~{.cpp}
+// C++
+void Internal::MyUIControl::OnRelayout( const Vector2& size, RelayoutContainer& container )
+{
+ // The size is what we have been given and what our control needs to fit into
+ // Here, we need to set the position and the size of our visuals
+ // If we have other controls/actors as children
+ // - Add the control/actor to the container paired with the size required
+ // - To ensure this works, you need to set up the control with a relayout policy of USE_ASSIGNED_SIZE
+ // - DO NOT CALL SetSize on this control: This will trigger another size negotiation calculation
+ // DO NOT chain up to base class.
+}
+~~~
+More information on size negotiation can be found [here](@ref size-negotiation-controls).
+
+___________________________________________________________________________________________________
+
+### Clipping Support {#creating-controls-clipping}
+
+When an Actor is set to clip its children, the renderers have to be added manually in order to specify what its children need to clip to.
+The Control base class automates the creation of the visuals when it is set to clip its children.
+
+This is only done if the application or custom control writer has not
+added any Renderers to the Control or registered any visuals
+(regardless of whether these visuals are enabled or not).
+
+If custom control writers want to define the clipping visuals themselves, then they should register all required visuals before the control is staged.
+