Persistent Splitter control in Visual WebGui
Bogdan Zamfir
This article demonstrates how to implement a persistent splitter component, that is, a splitter that remembers its position set by user at runtime
The splitter is a great component. It allows splitting the workspace on one or more panels, each with their own controls.
However, one nice feature for splitters would be to allow users to customize the size of the panels, to widen / narrow them to meet various needs, and remember the size when the application is used next time
So I enhanced the build-in VWG splitter to implement this feature.
The things I faced when I tried to implement this were how to set the splitter position at runtime. After some tests I noticed the position of the splitter is actually determined not by some properties of the splitter itself, but by the size of the control the splitter is docked on.
To save / restore the splitter position, I use a cookie.
The Persistent Splitter component has design time support, and it has two properties that can be set at design time:
· CookieName - the name of the cookie used to save / load the splitter name
· DockedControl - the name of the control the splitter is docked on
The Persistent splitter has two main working private methods:
· SaveSplitterPosition – This is called from the Resize event handler for the control the splitter is docked on, and, depending on the dock style of the splitter, it saves in the cookie the value of the width (for vertical splitter) or height (for horizontal splitter) of the docking control.
· RestoreSplitterPosition – This is called from the SET accessor of the HostControlLoaded property. It tells the splitter that the component that hosts the splitter and related controls (particularly the control the splitter is docked on) was loaded, so their position can be manipulated in code).
The PersistentSplitter functionality is controlled by the HostControlLoaded property. This is write/only, and is used to notify the splitter when the component the splitter is docked on is available. In that moment the splitter can restore its position by adjusting the size of it’s docking component. This should happen in Load event of the host component (form or user control) by setting the HostControlLoaded property to true. This tells the PersistentSplitter control that all controls on the form was loaded, so it can set the size of left control from the cookie to restore its position (as below):
private void Form1_Load(object sender, EventArgs e)
{
persistentSplitter1.HostControlLoaded = true;
}
The code in SaveSplitterPosition is straightforward:
private void SaveSplitterPosition()
{
// if we have the cookie name set
if (m_cookieName != string.Empty)
// if this vertical splitter, save the width of docked control
if (this.Dock == DockStyle.Left || this.Dock == DockStyle.Right)
VWGHelper.SetCookiesParameter(m_cookieName,
m_dockedControl.Width.ToString());
else
// if this is horizontal splitter, save the height
if (this.Dock == DockStyle.Top || this.Dock == DockStyle.Bottom)
VWGHelper.SetCookiesParameter(m_cookieName,
m_dockedControl.Height.ToString());
else
// for safety
throw new Exception(
string.Format("{0}: Invalid Dock value", this.Name));
}
RestoreSplitterPosition works similarily. There is only one issue – since in this method we change the size of the docked control, this will fire Resize event, which will cause the event handler to call SaveSplitterPosition, which will attempt to save the cookie value again. To prevent this, we unbind from Resize event when we start the procedure, and bind again when finishing it. The code is shown below
private void RestoreSplitterPosition()
{
if (m_dockedControl != null && m_cookieName != string.Empty)
{
// we unbind from resize event of docked control,
// to avoid saving the position again in cookie
m_dockedControl.Resize -= new EventHandler(
m_dockedControl_Resize);
try
{
// read the last location from cookie
string offsetStr = VWGHelper.GetCookiesParameter(m_cookieName);
if (offsetStr != string.Empty)
{
int offsetInt = Int32.Parse(offsetStr);
bool dockValid = false;
// if vertical splitter
if (this.Dock == DockStyle.Left ||
this.Dock == DockStyle.Right)
{
m_dockedControl.Width = offsetInt;
dockValid = true;
}
else
// if vertical splitter
if (this.Dock == DockStyle.Top ||
this.Dock == DockStyle.Bottom)
{
m_dockedControl.Height = offsetInt;
dockValid = true;
}
if (!dockValid)
throw new Exception(
string.Format("{0}: Invalid Dock value", this.Name));
}
}
catch (Exception ex)
{
throw new Exception(
"Error in PersistentSplitter.RestoreSplitterPosition", ex) ;
}
finally
{
// we make sure we rebind to resize event,
// to save new splitter position if user change it
m_dockedControl.Resize = new EventHandler(
m_dockedControl_Resize);
}
}
}
You can view a sample page using the persistent splitter below. To try it, move the gray splitters around, the refresh or reload the page