-Size negotiation provides the ability for controls to be resized without the application having to set a size.
-A parent control can resize itself according to its children. Each control can provide hints to using policies for the width and height.
-Controls will be relaid just once and only when requested to, rather than relaid out several times when different properties are set.
-Using size negotiation avoids the need for using size constraints to resize children, which would need to be calculated in the update
-thread every time even minor changes occur.
-
-This topic covers size policies, deriving from ControlImpl, size policy examples and the size negotiation algorithm.
-
-<h2 class="pg">Size Policies</h2>
-
-Each control has a policy for both width and height:
-- <b>Fixed:</b> The size is fixed to the size set by the application. If no size is set, then the size is fixed to the <i>natural</i> size of the control.
-- <b>Mininum:</b> The size can grow and shrink but cannot be smaller than the <i>minimum</i> size specified.
-- <b>Maximum:</b> The size can grow and shrink but cannot be larger than the <i>maximum</i> size specified.
-- <b>Range:</b> The size can grow or shrink but within the <i>minimum</i> and <i>maximum</i> sizes specified.
-- <b>Flexible:</b> The size of the control can grow or shrink as required without any limits.
-
-Currently, by default, controls use a fixed size policy for width and height. If one dimension is set, and the other dimension is set to zero, then the latter
-dimension is assumed to have a non fixed policy.
-
-<h2 class="pg">Deriving from ControlImpl</h2>
-
-The size negotiation utilises several methods to work out the best size of a control. The default behaviour is in the ControlImpl class.
-The following methods can be overridden.
-@code Vector3 GetNaturalSize() @endcode
-This method should return the natural size of the control. This can be dependent on the control's children or the control may decide to have a fixed size.
-
-@code float GetHeightForWidth( float width ) @endcode
-This method should return the height it needs to be when given a certain width.
-
-@code float GetWidthForHeight( float height ) @endcode
-This method should return the width it needs to be when given a certain height.
-
-All these methods can be overridden by deriving classes. This allows each control to dictate what size it would like to be. If you want the default behaviour,
-then you do not have to override these methods. A parent control can call the child's methods to determine its size if it needs to.
-
-<h2 class="pg">Size Policies and Virtual Methods</h2>
-
-The table below shows the methods that are called when certain width and height policies are in place.
-
-<table>
- <tr>
- <td></td>
- <td><b>Fixed Height</b></td>
- <td><b>Height Not Fixed (All other policies)</b></td>
- </tr>
- <tr>
- <td><b>Fixed Width</b></td>
- <td>
- - Use size set by application
- - If only height set by application
- - Use height set by application
- - Use <b>GetWidthForHeight()</b> for width
- - If only width set by application
- - Use width set by application
- - Use <b>GetHeightForWidth()</b> for height
- - If not set, then get size by calling <b>GetNaturalSize()</b>
- </td>
- <td>
- - Use width set by application
- - Use allocated width if not set
- - Ensure it satisfies our width policy
- - Adjust if required
- - Use <b>GetHeightForWidth()</b> for height
- - Ensure height satisfies our height policy
- - Adjust if required
- </td>
- </tr>
- <tr>
- <td><b>Width Not Fixed (All other policies)</b></td>
- <td>
- - Use height set by application
- - Use allocated height if not set
- - Ensure it satisfies our height policy
- - Adjust if required
- - Use <b>GetWidthForHeight()</b> for width
- - Ensure width satisfies our width policy
- - Adjust if required
- </td>
- <td>
- - Constrain the allocated width and height according to the two policies
- </td>
- </tr>
-</table>
-
-<h2 class="pg">Size Policy Examples</h2>
-
-<h3 class="pg">Policy: Fixed Width and Height (1)</h3>
-
-<table border=0 cellpadding=10><tr>
-<td>
-\image html FixedWidthHeight.png
-</td>
-<td>
-The application/control has set the following settings:
-- <b>SetSize:</b> 200 x 300
-- <b>Natural Size:</b> 400 x 400
-- <b>Width To Height Ratio:</b> 1 to 1
-- <b>Width Policy:</b> Fixed
-- <b>Height Policy:</b> Fixed
-- <b>ParentOrigin:</b> TopLeft
-- <b>AnchorPoint:</b> TopLeft
-
-Control methods called:
-- None
-
-Result
-- <b>Allocated size:</b> 200 x 300
-</td>
-</tr></table>
-
-<h3 class="pg">Policy: Fixed Width and Height (2)</h3>
-
-<table border=0 cellpadding=10><tr>
-<td>
-\image html FixedWidthHeight2.png
-</td>
-<td>
-The application/control has set the following settings:
-- <b>SetSize:</b> 0 x 0 (No size set)
-- <b>Natural Size:</b> 400 x 400
-- <b>Width To Height Ratio:</b> 1 to 1
-- <b>Width Policy:</b> Fixed
-- <b>Height Policy:</b> Fixed
-- <b>ParentOrigin:</b> TopLeft
-- <b>AnchorPoint:</b> TopLeft
-
-Control methods called:
-- GetNaturalSize() = 400 x 400
-
-Result
-- <b>Allocated size:</b> 400 x 400
-</td>
-</tr></table>
-
-<h3 class="pg">Policy: Flexible Width and Height</h3>
-
-<table border=0 cellpadding=10><tr>
-<td>
-\image html FlexibleWidthHeight.png
-</td>
-<td>
-The application/control has set the following settings:
-- <b>SetSize:</b> 200 x 300
-- <b>Natural Size:</b> 400 x 400
-- <b>Width To Height Ratio:</b> 1 to 1
-- <b>Width Policy:</b> Flexible
-- <b>Height Policy:</b> Flexible
-- <b>ParentOrigin:</b> TopLeft
-- <b>AnchorPoint:</b> TopLeft
-
-Control methods called:
-- None
-
-Result
-- <b>Allocated size:</b> 480 x 800 (Assume stage size 480 x 800)
-</td>
-</tr></table>
-
-<h3 class="pg">Policy: Fixed Width and Flexible Height (1)</h3>
-
-<table border=0 cellpadding=10><tr>
-<td>
-\image html FixedWidthFlexibleHeight.png
-</td>
-<td>
-The application/control has set the following settings:
-- <b>SetSize:</b> 200 x 300
-- <b>Natural Size:</b> 400 x 400
-- <b>Width To Height Ratio:</b> 1 to 1
-- <b>Width Policy:</b> Fixed
-- <b>Height Policy:</b> Flexible
-- <b>ParentOrigin:</b> TopLeft
-- <b>AnchorPoint:</b> TopLeft
-
-Control methods called:
-- GetHeightForWidth( 200 ) = 200
-
-Result
-- <b>Allocated size:</b> 200 x 200
-</td>
-</tr></table>
-
-<h3 class="pg">Policy: Fixed Width and Flexible Height (2)</h3>
-
-<table border=0 cellpadding=10><tr>
-<td>
-\image html FixedWidthFlexibleHeight.png
-</td>
-<td>
-The application/control has set the following settings:
-- <b>SetSize:</b> 200 x 0 (No height set)
-- <b>Natural Size:</b> 400 x 400
-- <b>Width To Height Ratio:</b> 1 to 1
-- <b>Width Policy:</b> Fixed
-- <b>Height Policy:</b> Flexible
-- <b>ParentOrigin:</b> TopLeft
-- <b>AnchorPoint:</b> TopLeft
-
-Control methods called:
-- GetHeightForWidth( 200 ) = 200
-
-Result
-- <b>Allocated size:</b> 200 x 200
-</td>
-</tr></table>
-
-<h3 class="pg">Policy: Fixed Width and Flexible Height (3)</h3>
-
-If the control did not have the GetHeightForWidth() method, then the <i>size set</i> is used to calculate the ratio.
-
-<table border=0 cellpadding=10><tr>
-<td>
-\image html FixedWidthFlexibleHeight2.png
-</td>
-<td>
-The application/control has set the following settings:
-- <b>SetSize:</b> 200 x 0 (No height set)
-- <b>Natural Size:</b> 400 x 400
-- <b>Width To Height Ratio:</b> Not set
-- <b>Width Policy:</b> Fixed
-- <b>Height Policy:</b> Flexible
-- <b>ParentOrigin:</b> TopLeft
-- <b>AnchorPoint:</b> TopLeft
-
-Control methods called:
-- GetHeightForWidth( 200 ) = 200 <i>(Unable to calculate ratio using size set)</i>
-
-Result
-- <b>Allocated size:</b> 200 x 800 <i>(Allocate entire height)</i>
-</td>
-</tr></table>
-
-<h3 class="pg">Policy: Fixed Width and Flexible Height (4)</h3>
-
-<table border=0 cellpadding=10><tr>
-<td>
-\image html FlexibleWidthHeight.png
-</td>
-<td>
-The application/control has set the following settings:
-- <b>SetSize:</b> 0 x 0 (No size set)
-- <b>Natural Size:</b> 400 x 400
-- <b>Width To Height Ratio:</b> 1 to 1
-- <b>Width Policy:</b> Fixed
-- <b>Height Policy:</b> Flexible
-- <b>ParentOrigin:</b> TopLeft
-- <b>AnchorPoint:</b> TopLeft
-
-Control methods called:
-- GetHeightForWidth( 0 ) = 0
-
-Result
-- <b>Allocated size:</b> 480 x 800 <i>(Allocate entire size)</i>
-</td>
-</tr></table>
-
-<h3 class="pg">Policy: Flexible Width and Fixed Height (1)</h3>
-
-<table border=0 cellpadding=10><tr>
-<td>
-\image html FlexibleWidthFixedHeight.png
-</td>
-<td>
-The application/control has set the following settings:
-- <b>SetSize:</b> 0 x 300 (No width set)
-- <b>Natural Size:</b> 400 x 400
-- <b>Width To Height Ratio:</b> 1 to 1
-- <b>Width Policy:</b> Flexible
-- <b>Height Policy:</b> Fixed
-- <b>ParentOrigin:</b> TopLeft
-- <b>AnchorPoint:</b> TopLeft
-
-Control methods called:
-- GetWidthForHeight( 300 ) = 300
-
-Result
-- <b>Allocated size:</b> 300 x 300
-</td>
-</tr></table>
-
-<h3 class="pg">Policy: Flexible Width and Fixed Height (2)</h3>
-
-If the control did not have the GetWidthForHeight() method, then the <i>size set</i> is used to calculate the ratio.
-
-<table border=0 cellpadding=10><tr>
-<td>
-\image html FlexibleWidthFixedHeight2.png
-</td>
-<td>
-The application/control has set the following settings:
-- <b>SetSize:</b> 0 x 300 (No width set)
-- <b>Natural Size:</b> 400 x 400
-- <b>Width To Height Ratio:</b> Not set
-- <b>Width Policy:</b> Flexible
-- <b>Height Policy:</b> Fixed
-- <b>ParentOrigin:</b> TopLeft
-- <b>AnchorPoint:</b> TopLeft
-
-Control methods called:
-- GetWidthForHeight( 300 ) = 0 <i>(Unable to calculate ratio using size set)</i>
-
-Result
-- <b>Allocated size:</b> 480 x 300 <i>(Allocate entire width)</i>
-</td>
-</tr></table>
-
-<h2 class="pg">The Size Negotiation Algorithm</h2>
-
-<h3 class="pg">The Algorithm</h3>
-
--# The algorithm starts at the stage
- - All top level controls are found and offered the size of the stage
- - The control negotiates the size offered by using the policy rules to determine the size that it should be allocated
- - The control is then set to that allocated size
--# The control is responsible for setting the sizes of all its children
- - Can set a size on an Actor
- - Or can call relayout on a Control directly
--# Children that a control does not handle, the control can add to a container so that the top-level algorithm delas with it instead
- - The control should call Relayout with the child and size of itself as parameters
-
-<table border=0 cellpadding=10><tr>
-<td>
-\image html Algorithm1.png
-</td>
-<td>
-\image html Algorithm2.png
-</td>
-</tr></table>
-
-<h3 class="pg">A closer look at Control A</h3>
-
-Taking a closer look at Control A we see in this example that children should share the width equally and that the height of Control A
-is the maximum height of the children.
-
-<table border=0 cellpadding=10><tr>
-<td>
-\image html Algorithm3.png
-</td>
-<td>
-<table border=0 cellpadding=10><tr>
-<td>
-\image html Algorithm4.png
-</td>
-</tr></table>
-</td>
-</tr></table>
+Size negotiation, also known as layout management, is responsible for allocating sizes to all actors on the stage based on rules of dependency between
+the actors. Requests for relayout on actors are collected during the frame with the actual relayout performed at the end of the frame.
+
+This document details how to use the size negotiation API and is intended for application writters.
+
+The topics covered are:
+- Dimensions
+- Resize policies
+- Actor
+- Debugging
+
+<h2 class="pg">Dimensions</h2>
+
+The notion of width and height is generalised into the concept of a Dimension. Several methods take a Dimension parameter.
+
+The Dimension enum specifies the available dimensions as bitfields:
+- WIDTH
+- HEIGHT
+
+If a method can process width and height at the same time then the ALL_DIMENSIONS mask can be specified.
+
+<h2 class="pg">Resize Policies</h2>
+
+<h3>Policies</h3>
+The ResizePolicy enum specifies a range of options for controlling the way actors resize. These are powerful rules that enable much automatic
+resizing behaviour. They are as following:
+
+- FIXED: This is the option to use when you want the specific definite size as set by SetPreferredSize
+- USE_NATURAL_SIZE: Use this option for objects such as images or text to get their natural size e.g. The dimensions of the image, or the size of the text without wrapping. Also use this on TableViews when the size of the table is dependent on its children.
+- FILL_TO_PARENT: Size will fill up to the size of its parent's size, taking a size factor into account to allow proportionate filling
+- FIT_TO_CHILDREN: Size will scale around the size of the actor's children. E.g. A popup's height may resize itself around it's contents.
+- DIMENSION_DEPENDENCY: This covers rules such as width-for-height and height-for-width. You specify that one dimension depends on another.
+
+\image html size-negotiation/ResizePolicies.png
+
+<h2 class="pg">Actor</h2>
+
+This section details how an actor may be used with size negotiation.
+
+<h3>Enabling Size Negotiation</h3>
+
+The first thing to do is to specify whether you want an actor to be included or excluded from the relayout process. The following method is used to enable or disable the relayout
+for an individual actor.
+@code void SetRelayoutEnabled( bool enabled ) @endcode
+Text and image actors have relayout enabled by default, while a plain Actor is disabled. Be aware that if desiring to use an Actor in relayout
+then relayout needs to be explicitly enabled first.
+
+<h3>Specifying Size Policies</h3>
+
+The next step is to specify how an actor will be size negotiated. The resize policies for an actor may be specified by the following method:
+@code void SetResizePolicy( ResizePolicy policy, Dimension dimension ) @endcode
+It is common to specifiy different policies for the different dimensions of width and height to achive different layouts. Different actors have
+different resize policies specified by default. For example ImageActors are set to use USE_NATURAL_SIZE.
+
+The following example code snippet shows rootActor having its width policy set to FILL_TO_PARENT and its height policy set to FIT_TO_CHILDREN.
+It has an ImageActor added to it with an explicit call to USE_NATURAL_SIZE in both dimensions called on it. This will make an actor that will
+fill up the space of its parent in the width dimension and fit to its child in the height dimension. As the image actor child is using natural size
+the height of the root actor will fit to the height of the child image.