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

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
.

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 onFlowDirection
) to use remaining space. Default is 0, preserving control size. ⚠️ When usingFillWeight
, set the control'sMinimumSize
to prevent shrinking to 0.FlowBreak
: Whentrue
, causes a flow break, wrapping to the next line/column depending on the panel'sFlowDirection
.
In the animation below, green buttons have FillWeight
set to 1. Left panel flows horizontally, right panel flows vertically:

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"
});
}

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 onLayoutStyle
) to use remaining space. Default is 0, preserving control size. ⚠️ When usingFillWeight
, set the control'sMinimumSize
to prevent shrinking to 0.AlignX
: Controls horizontal alignment of child controls that can't fill a verticalFlexLayoutPanel
due to width constraints. Overrides the defaultHorizontalAlign
for that control.AlignY
: Controls vertical alignment of child controls that can't fill a horizontalFlexLayoutPanel
due to height constraints. Overrides the defaultVerticalAlign
for that control.
The animation below shows two FlexLayoutPanel
s - first using HBox layout, second using VBox layout. Some buttons have FillWeight
set to 1, and button3
is set to align vertically:

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'sAutoSize
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 ownLocation
andSize
.
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:
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.
Last updated
Was this helpful?