-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>