TableLayoutPanel
A TableLayoutPanel arranges its children in a grid. It is the container for a form that is mostly fields: a label in one column and a field in the next, a row per line, and the whole grid resizable without a single Location. It is more work to set up than an anchored form and the only layout that keeps a two-column form aligned when the labels change length.
A grid that lays out
using System;
using System.Drawing;
using System.Windows.Forms;
internal static class Program
{
[STAThread]
private static void Main()
{
ApplicationConfiguration.Initialize();
Application.Run(new Form1());
}
}
internal sealed class Form1 : Form
{
public Form1()
{
Text = "A table of fields";
ClientSize = new Size(480, 220);
var table = new TableLayoutPanel
{
Dock = DockStyle.Fill,
ColumnCount = 2,
RowCount = 4,
Padding = new Padding(12),
};
table.ColumnStyles.Add(new ColumnStyle(SizeType.Absolute, 120F));
table.ColumnStyles.Add(new ColumnStyle(SizeType.Percent, 100F));
table.RowStyles.Add(new RowStyle(SizeType.AutoSize));
table.RowStyles.Add(new RowStyle(SizeType.AutoSize));
table.RowStyles.Add(new RowStyle(SizeType.Percent, 100F));
table.RowStyles.Add(new RowStyle(SizeType.AutoSize));
var nameLabel = new Label { Text = "&Name:", AutoSize = true, Anchor = AnchorStyles.Left };
var nameBox = new TextBox { Anchor = AnchorStyles.Left | AnchorStyles.Right };
var notesLabel = new Label { Text = "&Notes:", AutoSize = true, Anchor = AnchorStyles.Left };
var notes = new TextBox { Multiline = true, Dock = DockStyle.Fill };
var save = new Button { Text = "&Save", AutoSize = true, Anchor = AnchorStyles.Right };
table.Controls.Add(nameLabel, 0, 0);
table.Controls.Add(nameBox, 1, 0);
table.Controls.Add(notesLabel, 0, 1);
table.Controls.Add(notes, 1, 1);
table.SetRowSpan(notes, 2);
table.Controls.Add(save, 1, 3);
Controls.Add(table);
}
}
dotnet build app.csproj
Build succeeded.
0 Warning(s)
0 Error(s)
The listing is built and not run. The first column is 120 pixels wide whatever the labels say; the second takes the rest. The notes field spans two rows and stretches, because a control in a table cell can be anchored or docked like any other and the cell is the parent area it works in. Controls.Add(control, column, row) places a control in its cell, and SetRowSpan and SetColumnSpan make it cover more than one.
Column and row styles
The sizes are not numbers on the columns but style objects in two collections:
- SizeType.Absolute: a fixed number of pixels. new ColumnStyle(SizeType.Absolute, 120F).
- SizeType.Percent: a share of the panel. Percentages are normalised, so 50F and 50F give two equal halves and 100F alone gives everything that is left.
- SizeType.AutoSize: the size the content needs, which is what a row of labels wants.
- GrowStyle: what happens when a control is added at a column or row the styles do not cover, AddRows (the default), AddColumns or FixedSize.
- CellBorderStyle: a grid of lines, which is a debugging aid and occasionally a table.
A table layout panel with Dock = Fill and a percent column is the layout that survives a resize and a different font. The absolute column is the one number in the form that a translation or a high-DPI monitor can make too small, which is why the labels of a translated form are measured rather than fixed.
Spans and placement
A cell is addressed by column and row, counted from zero, and a control placed without an address takes the next free cell. The span is set after the add:
using System;
using System.Drawing;
using System.Windows.Forms;
internal sealed class Form1 : Form
{
public Form1()
{
Text = "A spanned header";
ClientSize = new Size(420, 200);
var table = new TableLayoutPanel { Dock = DockStyle.Fill, ColumnCount = 2, RowCount = 3 };
table.ColumnStyles.Add(new ColumnStyle(SizeType.Percent, 40F));
table.ColumnStyles.Add(new ColumnStyle(SizeType.Percent, 60F));
var title = new Label
{
Text = "Invoice 2026-0041",
Dock = DockStyle.Fill,
TextAlign = ContentAlignment.MiddleCenter,
BackColor = SystemColors.ControlLight,
};
table.Controls.Add(title, 0, 0);
table.SetColumnSpan(title, 2);
table.Controls.Add(new Label { Text = "Net", AutoSize = true }, 0, 1);
table.Controls.Add(new Label { Text = "1 250.00", AutoSize = true }, 1, 1);
Controls.Add(table);
}
}
That block is a fragment: a form with no Main, so the checker counts it and does not build it. A spanned control covers the cells it crosses, and the cells it covers are not available to another control; the style of the first cell in the span decides the size in the direction of the span only when the span has no percent to work with.
The cell arithmetic that runs
Whichever style produced the sizes, the grid is a set of edges, and finding the rectangle of a cell or the cell under a point is a running sum. That arithmetic runs here:
using System;
var columns = new[] { 120, 200, 80 };
var rows = new[] { 32, 32, 90 };
foreach (var cell in new[] { (Column: 0, Row: 0), (Column: 1, Row: 1), (Column: 2, Row: 2) })
{
var rect = Cell(columns, rows, cell.Column, cell.Row);
Console.WriteLine($"cell {cell.Column},{cell.Row}: x={rect.X} y={rect.Y} w={rect.Width} h={rect.Height}");
}
Console.WriteLine($"hit 150,40 -> {Hit(columns, rows, 150, 40)}");
Console.WriteLine($"hit 450,10 -> {Hit(columns, rows, 450, 10)}");
static (int X, int Y, int Width, int Height) Cell(int[] columns, int[] rows, int column, int row)
{
var x = 0;
for (var i = 0; i < column; i++)
{
x += columns[i];
}
var y = 0;
for (var i = 0; i < row; i++)
{
y += rows[i];
}
return (x, y, columns[column], rows[row]);
}
static string Hit(int[] columns, int[] rows, int x, int y)
{
var column = -1;
var left = 0;
for (var i = 0; i < columns.Length; i++)
{
if (x < left + columns[i])
{
column = i;
break;
}
left += columns[i];
}
var row = -1;
var top = 0;
for (var i = 0; i < rows.Length; i++)
{
if (y < top + rows[i])
{
row = i;
break;
}
top += rows[i];
}
return column < 0 || row < 0 ? "outside" : $"{column},{row}";
}
dotnet run
cell 0,0: x=0 y=0 w=120 h=32
cell 1,1: x=120 y=32 w=200 h=32
cell 2,2: x=320 y=64 w=80 h=90
hit 150,40 -> 1,1
hit 450,10 -> outside
The output is the real run. The origin of a cell is the sum of the sizes before it, which is why the third column starts at 320 and the third row at 64. The hit test is the same sums in the other direction, and it is the part of a grid a program needs when it draws its own cells or accepts a click on one: 450,10 is past the right edge of the 400-pixel grid, so it belongs to no cell at all.
Exercises
- Add a fourth column of 60 pixels and run the program. Which coordinates change?
- Change the hit test to return the cell of a point on the border between two columns, and say which side wins.
- Explain from the documentation what GrowStyle does when a control is added at row 4 of a table with three rows.
Questions
A new set of questions in a new order every time. Choose one answer for each, then check.
-
How is a control placed in a TableLayoutPanel?
Answer
Controls.Add(control, column, row)
The table places the control in the cell it is given, and the cell is the layout area.
-
Which SizeType gives a column a share of the panel?
Answer
Percent
Absolute is pixels and AutoSize fits the content.
-
Which SizeType sizes a row to its content?
Answer
AutoSize
A row of labels is AutoSize; a row that must fill uses Percent.
-
How does a control cover two columns?
Answer
SetColumnSpan(control, 2)
The span is set on the control after it is added.
-
What does GrowStyle decide?
Answer
What happens when a control is added outside the declared rows or columns
AddRows is the default; FixedSize refuses the extra cell.
-
Where does the third column of widths 120, 200 and 80 start?
Answer
At x = 320
The origin is the sum of the sizes before it, which the run printed.
-
What does the run print for the point (450, 10)?
Answer
outside, because the grid is 400 pixels wide
The horizontal sum stops at 400, so no column contains the point.
-
Why does a table layout survive a translation better than absolute positions?
Answer
The columns are measured or proportional, not pinned to pixel positions
A longer label needs a wider column, and Percent or AutoSize gives it one.
-
What does CellBorderStyle do?
Answer
Draws a grid of lines between the cells
It is a debugging aid and occasionally a table look.
-
What happens to a cell covered by a span?
Answer
It is not available to another control
The spanned control occupies every cell it crosses.
Every listing on this page was built with the .NET SDK 10.0.303 for net10.0-windows against the targeting pack Microsoft.WindowsDesktop.App.Ref 10.0.15 from the offline feed, in a Docker container on Alpine Linux 3.24.3 (x86_64). The programs were built, not run on Linux: WinForms needs Windows. The logic that draws nothing was also run headless on the same machine, and its output is the run output printed below each of those programs.
Article author: Arthur Isaev