Export (0) Print
Expand All
6 out of 11 rated this helpful - Rate this topic

TableLayoutPanel Class

Updated: July 2008

Represents a panel that dynamically lays out its contents in a grid composed of rows and columns.

Namespace:  System.Windows.Forms
Assembly:  System.Windows.Forms (in System.Windows.Forms.dll)
[DockingAttribute(DockingBehavior.Never)]
[ComVisibleAttribute(true)]
[ClassInterfaceAttribute(ClassInterfaceType.AutoDispatch)]
public class TableLayoutPanel : Panel, 
	IExtenderProvider

The TableLayoutPanel control arranges its contents in a grid. Because the layout is performed both at design time and run time, it can change dynamically as the application environment changes. This gives the controls in the panel the ability to proportionally resize, so it can respond to changes such as the parent control resizing or text length changing due to localization.

Any Windows Forms control can be a child of the TableLayoutPanel control, including other instances of TableLayoutPanel. This allows you to construct sophisticated layouts that adapt to changes at runtime.

The TableLayoutPanel control can expand to accommodate new controls when they are added, depending on the value of the RowCount, ColumnCount, and GrowStyle properties. Setting either the RowCount or ColumnCount property to a value of 0 specifies that the TableLayoutPanel will be unbound in the corresponding direction.

You can also control the direction of expansion (horizontal or vertical) after the TableLayoutPanel control is full of child controls. By default, the TableLayoutPanel control expands downward by adding rows.

If you want rows and columns that behave differently from the default behavior, you can control the properties of rows and columns by using the RowStyles and ColumnStyles properties. You can set the properties of rows or columns individually.

The TableLayoutPanel control adds the following properties to its child controls: Cell, Column, Row, ColumnSpan, and RowSpan.

You can merge cells in the TableLayoutPanel control by setting the ColumnSpan or RowSpan properties on a child control.

NoteNote:

To set the Cell, Column, Row, ColumnSpan, and RowSpan properties at run time, use the SetCellPosition, SetColumn, SetRow, SetColumnSpan, and SetRowSpan methods.

To read the Cell, Column, Row, ColumnSpan, and RowSpan properties at run time, use the GetCellPosition, GetColumn, GetRow, GetColumnSpan, and GetRowSpan methods.

The docking behavior of child controls is the same as other container controls.

The anchoring behavior of child controls in a TableLayoutPanel differs from the behavior in other container controls. If the value of the child control's Anchor property is set to Left or Right, the control will be placed against the left or right border of the cell, at a distance that is the sum of the control's Margin property and the panel's Padding property. If both the Left and Right values are set, the control will be sized to the width of the cell, with the Margin and Padding values taken into account. The behavior for Top and Bottom anchoring is analogous. For more information, see How to: Anchor and Dock Child Controls in a TableLayoutPanel Control.

If you need a child control to mimic the default anchoring behavior in other container controls, you can adjust the Margin and Padding properties to maintain a constant distance between the control's border and the cell's border.

Setting the values of both the Column and Row properties of a child control to -1 will cause the control to be moved to the first empty cell in the TableLayoutPanel control. The empty cell will be chosen in a search that proceeds from left to right and from top to bottom. This order is dependent on the culture, so it will behave correctly in right-to-left (RTL) layouts.

NoteNote:

Only controls that have the Visible property set to true participate in the TableLayoutPanel control's layout computations.

TopicLocation
How to: Align and Stretch a Control in a TableLayoutPanel ControlWindows Forms Controls
How to: Span Rows and Columns in a TableLayoutPanel ControlWindows Forms Controls
How to: Edit Columns and Rows in a TableLayoutPanel ControlWindows Forms Controls
Walkthrough: Arranging Controls on Windows Forms Using a TableLayoutPanelWindows Forms Controls
How to: Align and Stretch a Control in a TableLayoutPanel ControlWindows Forms Controls
How to: Span Rows and Columns in a TableLayoutPanel ControlWindows Forms Controls
How to: Edit Columns and Rows in a TableLayoutPanel ControlWindows Forms Controls
Walkthrough: Arranging Controls on Windows Forms Using a TableLayoutPanelWindows Forms Controls
How to: Align and Stretch a Control in a TableLayoutPanel Control
How to: Span Rows and Columns in a TableLayoutPanel Control
How to: Edit Columns and Rows in a TableLayoutPanel Control
Walkthrough: Arranging Controls on Windows Forms Using a TableLayoutPanel
How to: Align and Stretch a Control in a TableLayoutPanel ControlWindows Forms Controls
How to: Span Rows and Columns in a TableLayoutPanel ControlWindows Forms Controls
How to: Edit Columns and Rows in a TableLayoutPanel ControlWindows Forms Controls
Walkthrough: Arranging Controls on Windows Forms Using a TableLayoutPanelWindows Forms Controls
How to: Align and Stretch a Control in a TableLayoutPanel Control
How to: Span Rows and Columns in a TableLayoutPanel Control
How to: Edit Columns and Rows in a TableLayoutPanel Control
Walkthrough: Arranging Controls on Windows Forms Using a TableLayoutPanel

The following code example demonstrates how to override the OnCellPaint method to create a custom appearance for a cell. For an example that uses the TableLayoutPanel control to create layouts that respond well to resizing, see TableLayoutPanel Control Sample.

public class DemoTableLayoutPanel : TableLayoutPanel
{
	protected override void OnCellPaint(TableLayoutCellPaintEventArgs e)
	{
		base.OnCellPaint(e);

        Control c = this.GetControlFromPosition(e.Column, e.Row);

        if ( c != null )
        {
            Graphics g = e.Graphics;

            g.DrawRectangle(
				Pens.Red, 
				e.CellBounds.Location.X+1,
				e.CellBounds.Location.Y + 1,
				e.CellBounds.Width - 2, e.CellBounds.Height - 2);

			g.FillRectangle(
				Brushes.Blue, 
				e.CellBounds.Location.X + 1, 
				e.CellBounds.Location.Y + 1, 
				e.CellBounds.Width - 2, 
				e.CellBounds.Height - 2);
        };
	}

}
System.Object
  System.MarshalByRefObject
    System.ComponentModel.Component
      System.Windows.Forms.Control
        System.Windows.Forms.ScrollableControl
          System.Windows.Forms.Panel
            System.Windows.Forms.TableLayoutPanel
              System.ComponentModel.Design.ByteViewer
Any public static (Shared in Visual Basic) members of this type are thread safe. Any instance members are not guaranteed to be thread safe.

Windows 7, Windows Vista, Windows XP SP2, Windows XP Media Center Edition, Windows XP Professional x64 Edition, Windows XP Starter Edition, Windows Server 2008 R2, Windows Server 2008, Windows Server 2003, Windows Server 2000 SP4, Windows Millennium Edition, Windows 98

The .NET Framework and .NET Compact Framework do not support all versions of every platform. For a list of the supported versions, see .NET Framework System Requirements.

.NET Framework

Supported in: 3.5, 3.0, 2.0

Date

History

Reason

July 2008

Added note to the Remarks section to clarify getting and setting properties added to a child control. Corrected remark about setting Column and Row properties to -1.

Customer feedback.

Did you find this helpful?
(1500 characters remaining)
Thank you for your feedback

Community Additions

ADD
Show:
© 2014 Microsoft. All rights reserved.