Layout Model

XWT has a layout model based on containers. A container is a widget that can contain other widgets, and which defines a specific way of laying out those widgets. For example, the VBox container (Vertical Box), places widgets in sequence in a single column. The most important containers are:

• HBox: a row column of widgets packed horizontally
• VBox: a single column of widgets packed vertically
• Table: widgets are placed in a grid that can have several columns and rows. Widgets can span several cells.
• HPaned, VPaned: It can contain two widgets. Widgets are placed side by side. The division between the widgets can be moved by the user using a handle. Widgets can be arranged horizontally (HPaned) or vertically (VPaned).
• Canvas: widgets are placed at absolute positions. This is a good base class for creating custom containers.

Here is a simple example for VBox and HBox:

class MainWindow : Window
{
  VBox topPanel;
  public MainWindow() {
            this.Content = topPanel = new VBox();

            topPanel.PackStart(new Label("First Label"));
            topPanel.PackStart(new Label("Second Label"));            
        }
}

Margin

Widgets can have a margin at the left, top, right or bottom of the content they display. The margin can be set using the Margin property (to set all margins at once) or using the MarginLeft, MarginTop, MarginRight or MarginBottom properties. Here are some examples:

    var label = new Label ("Foo");
    label.Margin = 4;  // Sets the left, top, right and bottom margins to 4
    label.Margin = new WidgetSpacing (1,2,3,4); // Sets the margin to left:1, top:2, right:3, bottom:4
    label.MarginBottom = 5; // Sets the bottom margin to 5

The margin can be used to add spacing between widgets, or between the widget and the window borders. The margin area is not considered to be part of the widget, so for example if you set the background color of the widget, the area of the margin will not change color.

Placement

The VerticalPlacement and HorizontalPlacement properties define how the widget is aligned when the space assigned to it is larger than the space it needs. The placement can have one of the following values:

• Start: the widget is aligned to the left (for HorizontalPlacement) or to the top (for VerticalAlignment)
• Center: the widget is centered, either horizontally (for HorizontalPlacement) or vertically (for VerticalAlignment).
• End: the widget is aligned to the right (for HorizontalPlacement) or to the bottom (for VerticalAlignment)
• Fill: the widget is expanded to fill all the assigned space, either horizontally (for HorizontalPlacement) or vertically (for VerticalAlignment).

Expand

The ExpandHorizontal and ExpandVertical properties define wether the widget should take all available space or not.

Preferred Size of a Widget

Widgets have a preferred size, which is the optimal size required to render the widget. This size can be obtained by calling the GetPreferredSize method:

    var label = new Label ("Hi World");
    var ps = label.Surface.GetPreferredSize ();

In this example, GetPreferredSize() will return the width and height required to render the label with the text "Hi World". GetPreferredSize() can take a width and/or height constraint as argument. A constraint specifies the available width or height, so that the size calculation method can return a size adapted to it. For example:

    var label = new Label ("Hi World");
    var ps = label.Surface.GetPreferredSize (10, SizeConstraint.Unconstrained);

In this example, GetPreferredSize() will return the size of the label, taking into account that it can't be wider than 10 pixels, and there is no limit on the height.

Widget subclasses can provide a custom implementation of the GetPreferredSize method:

    class Foo: Widget
    {
        protected override Size OnGetPreferredSize (SizeConstraint widthConstraint, SizeConstraint heightConstraint)
        {
            return new Size (10, 20);
        }
    }

Minimum Size

The MinWidth and MinHeight properties define the minimum size that a widget can have. This size has preference over the preferred size.

Requested Size

The WidthRequest and HeightRequest properties define the a specific size to be used to render the widget. This size has preference over the preferred size and the minimum size.