SplitContainer
A SplitContainer is two panels with a draggable bar between them: a file list next to an editor, a navigation tree next to a grid, a form next to a preview. It is the control a form reaches for when two regions must share the window, and its difficulty is all in the arithmetic of the splitter.
Two panels and a splitter
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 = "Notes";
ClientSize = new Size(640, 360);
var split = new SplitContainer
{
Dock = DockStyle.Fill,
Orientation = Orientation.Vertical,
SplitterDistance = 200,
SplitterWidth = 6,
Panel1MinSize = 120,
Panel2MinSize = 240,
FixedPanel = FixedPanel.Panel1,
};
var files = new ListBox { Dock = DockStyle.Fill, BorderStyle = BorderStyle.None };
files.Items.AddRange(new object[] { "notes.txt", "ideas.txt" });
var editor = new RichTextBox { Dock = DockStyle.Fill, BorderStyle = BorderStyle.None };
split.Panel1.Controls.Add(files);
split.Panel2.Controls.Add(editor);
Controls.Add(split);
}
}
dotnet build app.csproj
Build succeeded.
0 Warning(s)
0 Error(s)
The listing is built and not run. The splitter stands between the panels and is dragged with the mouse. Orientation.Vertical means the splitter is vertical and the panels sit side by side; the name is about the bar, not about the arrangement, which is the first thing everyone gets wrong. A child goes into Panel1 or Panel2, never into the SplitContainer itself: those two are the real containers, and a control added to the split container directly is laid out over both.
The properties
- Orientation: Vertical (a vertical bar, panels side by side) or Horizontal (a horizontal bar, panels stacked).
- SplitterDistance: how far the bar is from the left (or the top) edge, in pixels. Setting it outside the allowed range is clamped or throws, depending on the moment of the layout.
- SplitterWidth: the thickness of the bar, and the width of the grab area. Windows draws no handle of its own, so a value under four is hard to grab.
- Panel1MinSize and Panel2MinSize: the smallest each side may become. They are what keeps a user from dragging a pane to nothing.
- FixedPanel: which side keeps its size when the whole control is resized. None shares the change between the two, which is the default.
- IsSplitterFixed: freezes the bar. The split can still be changed from code.
- SplitterMoved: raised with a SplitterEventArgs that carries the new position, which is the event a form uses to save the layout.
The two minimums are the part that makes the control usable, and the part a form usually forgets. With no minimum a user can drag the splitter against the edge and lose a pane entirely; with a minimum, the drag stops, and the control has a rule that the code can rely on too.
Collapsing and fixing
A side panel that can be hidden is a Panel1Collapsed or Panel2Collapsed flag, and the control redraws the remaining panel to fill the space. That is the whole mechanism behind a View menu item that hides the navigation column:
using System;
using System.Drawing;
using System.Windows.Forms;
internal sealed class Form1 : Form
{
private readonly SplitContainer _split = new()
{
Dock = DockStyle.Fill,
Orientation = Orientation.Vertical,
SplitterDistance = 200,
};
public Form1()
{
Text = "A hidden side";
ClientSize = new Size(600, 320);
var toggle = new Button { Text = "Hide navigation", Dock = DockStyle.Top };
toggle.Click += (sender, e) =>
{
_split.Panel1Collapsed = !_split.Panel1Collapsed;
toggle.Text = _split.Panel1Collapsed ? "Show navigation" : "Hide navigation";
};
_split.Panel1.Controls.Add(new TreeView { Dock = DockStyle.Fill });
_split.Panel2.Controls.Add(new TextBox { Dock = DockStyle.Fill, Multiline = true });
Controls.Add(_split);
Controls.Add(toggle);
}
}
That block is a fragment: a form with no Main, so the checker counts it and does not build it. The button keeps its own caption in step with the flag, which is the small rule that makes a toggle understandable: the label says what the click will do, not what the current state is.
The arithmetic that runs
The splitter is a number between two bounds, and the bounds change with the window. That arithmetic decides whether a drag is possible at all, and it runs here:
using System;
var widths = new[] { 200, 600, 1200 };
foreach (var width in widths)
{
Console.WriteLine($"window {width,4}: {Place(width, 700, 160, 120)}");
}
Console.WriteLine($"smallest workable width: {Array.Find(widths, width => width >= 160 + 120)}");
static string Place(int width, int wanted, int minLeft, int minRight)
{
var room = width - minRight;
if (room < minLeft)
{
return $"too narrow for both panels ({room} < {minLeft})";
}
return Math.Clamp(wanted, minLeft, room).ToString();
}
dotnet run
window 200: too narrow for both panels (80 < 160)
window 600: 480
window 1200: 700
smallest workable width: 600
The output is the real run. At 200 pixels the two minimums add up to more than the control has, and the third line is what the control cannot do: it has no splitter position that satisfies both panels. Math.Clamp would have thrown an ArgumentException there, which is exactly what a call to SplitterDistance with a value the control refuses does at run time; the guard is the honest version. At 600 the wanted 700 is clamped to 480, because the right panel keeps its 120 minimum. At 1200 nothing is clamped and the bar stays where it was asked to be. The last line asks the array which of the widths a form must refuse, which is the check a form makes when it restores a saved layout.
In a form the same rule is why SplitterDistance is set after the size of the control is known, and why a layout restored from a settings file is applied in Shown rather than in the constructor: before the control has its final width, the clamp has nothing to work with.
Exercises
- Add a row for a window of 300 pixels and run the program.
- Change Place to return the smaller of the two panels' sizes as well, and print both.
- Explain from the documentation what FixedPanel = Panel1 does when the window is made wider.
Questions
A new set of questions in a new order every time. Choose one answer for each, then check.
-
What does Orientation.Vertical mean on a SplitContainer?
Answer
The splitter bar is vertical, so the panels sit side by side
The name is about the bar, which is the mistake everyone makes first.
-
Where does a control go in a SplitContainer?
Answer
Into Panel1 or Panel2
The two panels are the containers; a child of the split container itself covers both.
-
What does SplitterDistance measure?
Answer
The pixels from the left or top edge to the bar
SplitterWidth is the bar's own thickness.
-
What do Panel1MinSize and Panel2MinSize prevent?
Answer
Dragging a panel to nothing
They are the lower bounds of the two panels during a drag.
-
What does FixedPanel = Panel1 do on a resize?
Answer
Panel1 keeps its size and Panel2 takes the change
None shares the change between the two panels.
-
Which property hides one panel and lets the other fill the space?
Answer
Panel1Collapsed
The collapse flags redraw the remaining panel to fill the control.
-
Which event reports a drag of the splitter?
Answer
SplitterMoved
It carries the new position and is where a layout is saved.
-
What did the run print for a 600-pixel window?
Answer
480
The wanted 700 was clamped to 600 minus the right minimum of 120.
-
Why does the 200-pixel window have no answer?
Answer
The two minimums add up to more than the width
160 + 120 is 280, which does not fit in 200.
-
When is SplitterDistance restored from settings safely?
Answer
In Shown, after the control has its final size
Before the final size the values are clamped against the wrong bounds.
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