LayoutControl included with DotNetBar for WinForms helps you create resolution and DPI independent user interface data entry forms. Its built-in layout logic will re-flow its content to fit available bounds and size constraints.

LayoutControl allows for fixed and relative sizing of controls added to it and you can create both flow and table like layouts easily. In simple terms to understand the essence of layout this control provides imagine that LayoutControl will place items it contains from left to right and switch to new line as container boundaries are reached.

Each item added to LayoutControl will have its own textual caption with text-markup support so when you add controls to LayoutControl you do not have to create labels for them. Additionally, by default all items will automatically share the largest label width so they line up visually inside of the control for clean layout presentation.

Please note that LayoutControl content cannot be modified on inherited forms due to limitation of VS.NET WinForms designer and nature of inheritance used.

Basics

LayoutControl works with its own items that derive from LayoutItemBase type. LayoutItemBase describes an item that participates in layout. It specifies the item’s text-label, image or symbol, width and height including the type of units used, pixel or percentage, minimum size for the item, its styling and more. However, note that you do not use LayoutItemBase directly rather you always works with descendents.

LayoutControlItem inherits from LayoutItemBase and is used to host an Windows Forms control in LayoutControl. When you use VS.NET designer and drag & drop controls onto the LayoutControl, our designer automatically creates LayoutControlItem for the control that is added. It also performs default setup of LayoutControlItem depending on the control that was added. Note that LayoutControl does not work with the Windows Forms controls added to it, rather all its layout work is performed on the LayoutControlItem objects that are created for each Windows Forms control it contains.

To start using LayoutControl simply drag & drop the controls into it. Each control added to LayoutControl using VS.NET designer will receive corresponding host LayoutControlItem which is responsible for actual layout properties of the control. LayoutControlItem provides a text-label with text-markup support for the control as well as properties to control the layout logic. LayoutControlItem is the object which you change when you need to affect the size, position and layout rules of the control inside of LayoutControl.

Selecting Layout Items

When  you click on control inside LayoutControl you will select the actual control not its corresponding host layout item which controls layout behavior. If label for the item is visible then you can click the label to select the layout item as shown in image below:

LayoutControl6

In cases where text label is not visible, like for brown and green panels above you can click the area around the panel to select its layout item:

LayoutControl5

Another way to get access to all layout items is through VS.NET Document Outline window. You can open it from View->Other Windows->Document Outline menu in VS.NET or using Ctrl+W, U keyboard shortcut. Document outline shows all controls and items on the form and allows you to select them:

LayoutControl7

Sizing

As explained above when you drag & drop controls onto the LayoutControl, the control added gets automatically wrapped into LayoutControlItem which is what LayoutControl works with directly to perform its layout.

To set the size of the item, you use Width and Height properties on LayoutControlItem. WidthType and HeightType properties specify the type of the unit that Width and Height properties hold. When WidthType=eLayoutSizeType.Absolute it means that Width property contains fixed width of the item in pixels. When WidthType=eLayoutSizeType.Relative, it indicates that Width property contains percentage value of available container width, meaning if it is set to 50, that means item will be 50% in width of available container size.

Width and Height specified are for whole item, including its text-label. Using MinSize property you can specify the explicit minimum size of the item in pixels, including its text-label. MinSize property is of Size type and you can specify either width or height or both as minimum sizes. Note that when LayoutControl cannot fit the items due to minimum size constraints it will automatically show scroll-bars.

Text Labels and Images, Symbols

Each item automatically provides the text label through Text property. Text-markup is also supported. TextVisible property controls whether text label is visible or not. TextSize property allows you to set explicit size of the textual label. In most use cases this is not necessary since size is automatically calculated. TextPadding property specifies the amount of empty space in pixels around the text. TextAlignment property specifies the text horizontal alignment within the text-bounds and TextPosition property specifies text position in relation to the other parts of the layout item, in most cases the WinForms Control item is hosting.

By default all items within LayoutControl will use largest text-size, i.e. widest label, of item contained within. This ensures that text-labels and controls are neatly aligned inside control automatically. If you want to stop this for certain items you can set SharedTextSizeEnabled property on items where you want to disable this largest text-size sharing.

MnemonicsEnabled property indicates whether accelerator keys assigned through item Text property are processed by items which respond to them. LayoutControlItem which hosts WinForms control will focus the control when its accelerator key is pressed. Accelerator keys are set using amphersand character before the character which indicates the key, for example setting text to: &First indicates that F key is accelerator key and when Alt+F keys are pressed and LayoutControl has input focus, the WinForms control assigned to its LayoutControlItem will be focused.

LayoutControlItem also adds text related properties that deal with text-control relation. TextControlSpacing property specifies the spacing in pixels between text and control.

Image property specifies the image that is displayed next to item’s text. ImagePosition property indicates the position of the image in relation to the text label of item. ImageTextSpacing property specifies the distance between image and text in pixels.

LayoutControl also supports 361+ Symbols that are built into the DotNetBar. Using Symbol property you can set the symbol to use next to text instead of Image. Note that setting Symbol will cause Image not to be displayed even if set. SymbolColor property allows you to set color symbol is drawn with.

Control Positioning, Dock and Anchor properties

Each control that is added to LayoutControl must be hosted by LayoutControlItem. By default the control size will be set based on the size properties indicated on LayoutControlItem. However, using ControlSize property on LayoutControlItem you can suggest control size which is used when calculated layout size for the control is larger than ControlSize property value. Either width or height may be set or both. ControlSize property can be used in conjuction with Dock and Anchor properties on the Control. When available space for the Control exceeds ControlSize the Dock and Anchor properties will indicate the control position inside of the control box.

Here is an example where LayoutControlItem.Width is set to 80 pixels and Height is set to 100%. Area item occupies is yellow highlight below. The ControlSize is set to 40,40 pixels and you can see that brown panel control is positioned in top-left corner within items bounds:

LayoutControl8

If we set control’s Anchor property to Bottom, Right this happens:

LayoutControl9

As you can see Control is positioned to bottom, right corner of items bounds.

If we set control’s Dock property to Right following happens:

LayoutControl10

Spacers

In some layout scenarios use of empty items, spacer is required. LayoutControl includes LayoutSpacerItem just for this purpose. You can add it to LayoutControl using its task menu:

LayoutControl11

Here is an example where spacer is used to push down the text-box to the bottom of layout control:

LayoutControl12

Layout Rules

First layout rule used by LayoutControl is that relative, percentage size of the control is based on available width after the fixed sized width of controls is added up. To understand that, consider following screen-shot in which layout item which hosts text-box control has width set to 100% and brown panel has fixed width set to 100:

DotNetBar LayoutControl Layout Rules

If you add more fixed width controls the text-box will shrink unless its MinSize is set.

To indicate that you want layout item to consume all available width of the container, you set its width to 101%. Here is what happens when we set Width=101% on layout item hosting text-box:

DotNetBar LayoutControl Rules

So built-in layout rule is that when Width of layout item is set to 101% it will consume complete width of the container.

First and last layout item in container have special layout rules. If first or last item Height is set to 100% they will be aligned to left (first item) or to right (last item) consuming the height of container and other controls flowing in between them.

To visualize this, here is screen-shot in which first layout item, panel, has its Height=100%, notice how text-boxes that are added after panel are positioned next to it:

DotNetBar LayoutControl Rules

Now we will add another, green panel, to layout as last item and set its Height=100%, notice how its docked to the right and how text-boxes are arranged in between two panels:

DotNetBar LayoutControl Rules

Another layout rule comes into effect when using relative width size and fixed width size items on same line. For example having fixed size item followed by the relative sized item with Width set to 100% will cause next item to be presented on next line. When that is not desirable and you need relative width size item sandwiched between fixed size items you can set relative Width=99% which will indicate to layout engine that next item should be positioned on same line if possible. Here is image which shows this in action where Spacer is used to push button all the way to the right:

DotNetBar LayoutControl Rule

Layout Groups

Layout Groups are almost like nested layout controls. LayoutGroup item type allows you to group certain controls together and create flexible layouts that are not possible otherwise. Additionally, you can use LayoutGroup styling through LayoutGroup.Style property to set background and border colors for the group or even change the group appearance so it is rendered as our PanelEx or GroupPanel control through LayoutGroup.Appearance property. Here is an example of layout that cannot be created unless you use LayoutGroup item:

DotNetBar LayoutControl LayoutGroup Item

Notice two groups that have Width=50% are displayed side by side with left group containing 3 text-boxes and right group containing the text-box and RichTextBox controls. Notice how group on the right has customized background and border through LayoutGroup.Style properties.

Each LayoutGroup can also display captions/headers. Setting LayoutGroup.Text will cause LayoutGroup to display caption. TextPosition property controls where caption is displayed, on top, on bottom to the left or right of the group content. When caption is displayed on left or right side it will be rotated 90 degrees. TextAlignment property will control caption alignment within the caption box. TextLineAlignment property will control vertical text alignment within the caption box. CaptionStyle property allows you to set the style specific for caption including background colors, border colors and type, font etc. By default caption height is automatically determined based on the current font height, but using CaptionHeight property you can set explicit caption height in pixels. Here is image which uses all properties described above to display custom caption for LayoutGroup:

DotNetBar LayoutControl LayoutGroup Custom Styling

Using Appearance property you can specify that LayoutGroup should be drawn using one of our predefined system appearances. You can set it to Panel or GroupPanel. Panel will cause the LayoutGroup to be rendered like our PanelEx control using current style set on StyleManager. That looks like this:

DotNetBar LayoutControl LayoutGroup with PanelEx appearance

Setting Appearance=GroupPanel would render same group like so:

DotNetBar LayoutControl LayoutGroup with GroupPanel Appearance

Note that when you set Appearance=Panel or GroupPanel any setting to CaptionStyle and Style will be overridden (and not used and visible) by the system group appearance.

Using Image or Symbol properties you can set the image or symbol that will be displayed next to caption. Note that setting Symbol overrides the image.

 

Setting up from code

LayoutControl is easily setup from code. It involves creating LayoutControlItem to host a control, then assigning the control to it and finally adding both to LayoutControl. Here is simple code which creates two text-boxes that are on the same line and third text-box below them consuming 100% of width of the container:

C#:

LayoutControlItem item = new LayoutControlItem();
TextBox tb = new TextBox();
// Connect layout item and control
item.Control = tb;
// This performs default setup as you see in designer
// It sets default width/height and Text
layoutControl2.SetupControlItem(item);
// Set item label
item.Text = "Text 1:";
item.Width = 50;
item.WidthType = eLayoutSizeType.Percent;
item.Height = 28;
// Control and item are added separately
// Add control
layoutControl2.Controls.Add(tb);
// Then add layout item
layoutControl2.RootGroup.Items.Add(item);
 
// Create second text-box
tb = new TextBox();
item = new LayoutControlItem();
// Connect layout item and control
item.Control = tb;
layoutControl2.SetupControlItem(item);
item.Text = "Text 2:";
item.Width = 50;
item.WidthType = eLayoutSizeType.Percent;
item.Height = 28;
layoutControl2.Controls.Add(tb);
layoutControl2.RootGroup.Items.Add(item);
 
// Create third text-box which consumes all container width
tb = new TextBox();
item = new LayoutControlItem();
// Connect layout item and control
item.Control = tb;
layoutControl2.SetupControlItem(item);
item.Text = "Text 3:";
item.Width = 101; // 101% indicates consume all container width
item.WidthType = eLayoutSizeType.Percent;
layoutControl2.Controls.Add(tb);
layoutControl2.RootGroup.Items.Add(item);
 
// Create spacer which will push button we will create to bottom of container
LayoutSpacerItem spacer = new LayoutSpacerItem();
spacer.Width = 100;
spacer.WidthType = eLayoutSizeType.Percent;
spacer.Height = 100;
spacer.HeightType = eLayoutSizeType.Percent;
spacer.MinSize = new Size(24, 24); // This ensures that spacer is at least 32 pixels in size
layoutControl2.RootGroup.Items.Add(spacer);
 
// Create the button which will be at the
// bottom of the control due to spacer pushing it down
Button button = new Button();
button.Text = "OK";
item = new LayoutControlItem();
// Connects button to layout item
item.Control = button;
layoutControl2.SetupControlItem(item);
item.ControlSize = new Size(72, 28); // This will specify explicit control size
// Button item will stretch over width of the container
item.Width = 101;
item.WidthType = eLayoutSizeType.Percent;
item.Height = 32;
// This will position button in right-bottom corner of item bounds
button.Anchor = AnchorStyles.Right | AnchorStyles.Bottom;
layoutControl2.Controls.Add(button);
layoutControl2.RootGroup.Items.Add(item);

VB:

Dim item As New LayoutControlItem()
Dim tb As New TextBox()
' Connect layout item and control
item.Control = tb
' This performs default setup as you see in designer
' It sets default width/height and Text
layoutControl2.SetupControlItem(item)
' Set item label
item.Text = "Text 1:"
item.Width = 50
item.WidthType = eLayoutSizeType.Percent
item.Height = 28
' Control and item are added separately
' Add control
layoutControl2.Controls.Add(tb)
' Then add layout item
layoutControl2.RootGroup.Items.Add(item)
 
' Create second text-box
tb = New TextBox()
item = New LayoutControlItem()
' Connect layout item and control
item.Control = tb
layoutControl2.SetupControlItem(item)
item.Text = "Text 2:"
item.Width = 50
item.WidthType = eLayoutSizeType.Percent
item.Height = 28
layoutControl2.Controls.Add(tb)
layoutControl2.RootGroup.Items.Add(item)
 
' Create third text-box which consumes all container width
tb = New TextBox()
item = New LayoutControlItem()
' Connect layout item and control
item.Control = tb
layoutControl2.SetupControlItem(item)
item.Text = "Text 3:"
item.Width = 101
' 101% indicates consume all container width
item.WidthType = eLayoutSizeType.Percent
layoutControl2.Controls.Add(tb)
layoutControl2.RootGroup.Items.Add(item)
 
' Create spacer which will push button we will create to bottom of container
Dim spacer As New LayoutSpacerItem()
spacer.Width = 100
spacer.WidthType = eLayoutSizeType.Percent
spacer.Height = 100
spacer.HeightType = eLayoutSizeType.Percent
spacer.MinSize = New Size(24, 24)
' This ensures that spacer is at least 32 pixels in size
layoutControl2.RootGroup.Items.Add(spacer)
 
' Create the button which will be at the
' bottom of the control due to spacer pushing it down
Dim button As New Button()
button.Text = "OK"
item = New LayoutControlItem()
' Connects button to layout item
item.Control = button
layoutControl2.SetupControlItem(item)
item.ControlSize = New Size(72, 28)
' This will specify explicit control size
' Button item will stretch over width of the container
item.Width = 101
item.WidthType = eLayoutSizeType.Percent
item.Height = 32
' This will position button in right-bottom corner of item bounds
button.Anchor = AnchorStyles.Right Or AnchorStyles.Bottom
layoutControl2.Controls.Add(button)
layoutControl2.RootGroup.Items.Add(item)

Related posts:

  1. Everything you need to know about RadialMenu control for WinForms
  2. Getting started with DotNetBar SideNav WinForms control
  3. Customizing Keyboard Control in DotNetBar for WinForms
  4. Working with DotNetBar from code.
  5. Getting started with DotNetBar TokenEditor WinForms control