Layouts

Wisej.NET includes several built-in layout engines and allows developers to easily build custom layout engines. This enables implementing layouts of any complexity, beyond what's available using plain CSS in browsers.

Traditional web frameworks using HTML string concatenation and CSS layouts (Blazor, Angular, PHP, ASP.NET, JSP, etc.) support only a fraction of the layouts available in Wisej.NET applications.

Layout engines handle arranging controls in their container. Every control's LayoutEngine property returns the current engine and can be overridden in derived classes. The engine measures preferred size for AutoSize controls and arranges position/size of container's direct children.

Layout Engines

Default

All controls use the DefaultLayout engine, which supports:

• Absolute positions: Each child sets its own Location and Size

• Docking: Children can dock to the parent using DockStyles

• Anchoring: Children can anchor their sides to the parent using AnchorStyles

Docking

Docking applies to child controls in inverse order "away from the viewer". The child control order affects how docking uses available space and intersections between horizontal/vertical docked controls.

Docking demonstration

Controls dock using the container's DisplayRectangle area, reduced by the Padding property.

The DefaultLayout engine doesn't use margins. To increase distance between docked controls, add docked Spacers.

Anchoring

Anchoring styles can be applied to any of the four sides of a control, or none.

When a control has no anchoring (AnchorStyles.None), it will "float" within its container, preserving its relative location. Likewise, if anchoring is not set only for the vertical sides or horizontal sides, the control "floats" vertically or horizontally.

To keep a control centered in its parent, center it and remove the anchoring.

The default initial value of the Anchor property is Top + Left.

Anchor demonstration

Padding and Margins are irrelevant to anchoring.

Flow

The flow layout engine is implemented for the FlowLayoutPanel. Child controls are arranged horizontally or vertically next to each other.

When using a FlowLayoutPanel in the designer, it extends all its children and adds several extension properties relevant only for flow layout:

• FillWeight: An arbitrary integer determining whether the child control grows horizontally or vertically (depending on FlowDirection) to use remaining space. Default is 0, preserving control size. ⚠️ When using FillWeight, set the control's MinimumSize to prevent shrinking to 0.
• FlowBreak: When true, causes a flow break, wrapping to the next line/column depending on the panel's FlowDirection.

Set these values programmatically using flowLayoutPanel.SetFlowBreak(child, value) or flowLayoutPanel.SetFillWeight(child, value).

In the animation below, green buttons have FillWeight set to 1. Left panel flows horizontally, right panel flows vertically:

Flow layout demonstration

The FlowLayout engine enforces margins. Changing a child control's Margin property increases distance to adjacent controls.

Table

The table layout engine is implemented for the TableLayoutPanel. Child controls are arranged in cells in a grid.

When using the TableLayoutPanel in the designer, it extends its children and adds several extension properties relevant only for table layout:

• Row, Column, Cell: Determine the grid cell placement for the control. Only one control can occupy a specific cell.

• RowSpan: Determines how many rows are occupied by the cell.

• ColumnSpan: Determines how many columns are occupied by the cell.

This layout engine doesn't allow wrapping but supports growing. When adding a child programmatically, you can control whether to add a new row or column when all cells are assigned by setting the GrowStyle property.

Use the RowStyles and ColumnStyles collections to determine cell sizing modes. Cells can:

• Resize proportionally using percentage

• Auto-size to fit content

• Have fixed pixel size

Additionally, controls can dock or anchor inside their assigned cell.

The animation below shows a TableLayoutPanel where button3 spans 2 columns and is anchored left and right while vertically centered in the cell. Adding new controls using this code automatically adds new rows when the last row's cells are occupied:

private void button1_Click(object sender, EventArgs e)
{
	this.tableLayoutPanel1.Controls.Add(new Button { 
		Text = "New Button"
	});
}

Table layout demonstration

The TableLayout engine enforces margins. Changing a child control's Margin property affects distance to adjacent controls.

Flex

The flex layout engine is implemented for the FlexLayoutPanel. It comprises two layout engines: HBoxLayout and VBoxLayout. This container arranges its children horizontally or vertically, always filling the client area.

Controls can use Margin, MinimumSize, MaximumSize and several extension properties to customize the layout:

• FillWeight: An arbitrary integer determining whether the child control grows horizontally or vertically (based on LayoutStyle) to use remaining space. Default is 0, preserving control size. ⚠️ When using FillWeight, set the control's MinimumSize to prevent shrinking to 0.
• AlignX: Controls horizontal alignment of child controls that can't fill a vertical FlexLayoutPanel due to width constraints. Overrides the default HorizontalAlign for that control.
• AlignY: Controls vertical alignment of child controls that can't fill a horizontal FlexLayoutPanel due to height constraints. Overrides the default VerticalAlign for that control.

The animation below shows two FlexLayoutPanels - first using HBox layout, second using VBox layout. Some buttons have FillWeight set to 1, and button3 is set to align vertically:

Flex layout demonstration

The FlexLayout engine enforces margins. Changing a child control's Margin property affects distance to adjacent controls.

Custom

You can build a custom layout engine by deriving from the Wisej.Web.Layout.LayoutEngine class and overriding the Control.LayoutEngine property in your container class.

You can create a single instance (singleton) of your layout engine to reuse, rather than creating a new instance for each container instantiation.

A layout engine needs to implement three methods:

• InitLayout(child, specifiedBounds): Optional - can use base implementation. Since layout engines can be cached, this call refreshes any internal cache related to a child control.

• GetPreferredSize(container, proposedSize): Optional - can use base implementation. Used when the container's AutoSize property is enabled and needs to measure children for preferred size.

• Layout(container, args): Arranges child controls in their container. The simplest layout engine does nothing, letting controls use their own Location and Size.

This sample shows a basic custom layout that arranges child controls in a cascading pattern from top-left to bottom-right:

public class CascadeLayout : LayoutEngine
{
	private static CascadeLayout _instance;

	private CascadeLayout() { }

	public static LayoutEngine Instance
		=> _instance = _instance ?? new CascadeLayout();

	public override bool Layout(object container, LayoutEventArgs layoutEventArgs)
	{
		var panel = (CascadeLayoutPanel)container;

		var gap = panel.Gap;
		var size = panel.ClientSize;
		var count = panel.Controls.Count;
		size.Width = size.Width - gap * (count - 1);
		size.Height = size.Height - gap * (count - 1);

		var i = 0;
		var bounds = new Rectangle(Point.Empty, size);
		foreach (Control child in panel.Controls)
		{
			child.Bounds = bounds;

			bounds.X += gap;
			bounds.Y += gap;
		}

		return false;
	}
}

The CascadeLayout engine works with this CascadingLayoutPanel. It adds a Gap property used by the layout engine:

public class CascadeLayoutPanel : Panel
{
	public override LayoutEngine LayoutEngine 
		=> CascadeLayout.Instance;

	public int Gap
	{
		get { return _gap; }
		set
		{
			_gap = value;
			PerformLayout();
		}
	}
	private int _gap = 30;
}

Depending on the value of the Gap property and the size of the container, this is the result.

Design Time

AutoLayout

Since 3.0

The designer's toolbar has a new option to arrange child controls without setting the Dock or the Anchor properties.

Clicking the AutoLayout button opens the AutoLayout floating panel:

Button	Description
	Arranges the controls horizontally, using the available space proportionally.
	Arranges the controls vertically, using the available space proportionally.
	Docks the controls to the left of the containing area.
	Docks the controls to the right of the containing area.
	Docks the controls to the bottom of the containing area.
	Docks the controls to the top of the containing area.
	Resizes the controls to fill the containing area.
	Toggles using the controls' margin when applying the auto layout.
	Selects the horizontal alignment of the controls within the containing area.
	Selects the vertical alignment of the controls within the containing area.
	Sets the spacing between the controls in pixels.

Margins

Margins are used by the designer to create proximity snap lines.

When moving a control near another, proximity snap lines appear based on the controls' margins.

The vertical snap line between controls combines the top control's Margin.Bottom and bottom control's Margin.Top values. Using this feature correctly simplifies UI development and helps maintain UI/UX guidelines.