TablePanel Class

A panel with a table layout, where each cell can host a control.

Namespace: DevExpress.Utils.Layout

Assembly: DevExpress.Utils.v20.1.dll

Declaration

public class TablePanel :
    XtraLayoutPanelBase,
    ITablePanel,
    IXtraLayoutPanel
Public Class TablePanel
    Inherits XtraLayoutPanelBase
    Implements ITablePanel,
               IXtraLayoutPanel

Remarks

The figure below illustrates the table layout of a sample TablePanel, and the same panel populated with controls.

sample

Columns and Rows

The fastest way to add columns and rows to a Table Panel is to click related buttons at design time.

sample

You can also use the panel's smart tag menu. Two "Edit..." links open the Collection Editor that allows you to customize rows and columns as you add them.

sample

Each row and column provides the Style property, which specifies size mode and size unit types.

  • Absolute - Width and Height properties specify the absolute row/column size, in pixels.
  • Relative - Width and Height properties store relative values. For example, three columns with relative widths of 1, 1 and 2 split the panel in four equal parts; first two columns have equal widths, and the last column is twice as wide.
  • AutoSize - Rows and columns resize automatically depending on their content. The Width and Height settings are ignored

The sample below illustrates how to add columns and rows in code.

tablePanel2.Columns.AddRange(new DevExpress.Utils.Layout.TablePanelColumn[] {
    new DevExpress.Utils.Layout.TablePanelColumn(DevExpress.Utils.Layout.TablePanelEntityStyle.Relative, 2F),
    new DevExpress.Utils.Layout.TablePanelColumn(DevExpress.Utils.Layout.TablePanelEntityStyle.Relative, 2F),
    new DevExpress.Utils.Layout.TablePanelColumn(DevExpress.Utils.Layout.TablePanelEntityStyle.Relative, 2F),
    new DevExpress.Utils.Layout.TablePanelColumn(DevExpress.Utils.Layout.TablePanelEntityStyle.Relative, 3F)
});

tablePanel2.Rows.AddRange(new DevExpress.Utils.Layout.TablePanelRow[] {
    new DevExpress.Utils.Layout.TablePanelRow(DevExpress.Utils.Layout.TablePanelEntityStyle.AutoSize, 1F),
    new DevExpress.Utils.Layout.TablePanelRow(DevExpress.Utils.Layout.TablePanelEntityStyle.AutoSize, 1F),
    new DevExpress.Utils.Layout.TablePanelRow(DevExpress.Utils.Layout.TablePanelEntityStyle.AutoSize, 1F),
    new DevExpress.Utils.Layout.TablePanelRow(DevExpress.Utils.Layout.TablePanelEntityStyle.AutoSize, 1F),
    new DevExpress.Utils.Layout.TablePanelRow(DevExpress.Utils.Layout.TablePanelEntityStyle.AutoSize, 1F),
    new DevExpress.Utils.Layout.TablePanelRow(DevExpress.Utils.Layout.TablePanelEntityStyle.AutoSize, 1F)
});

To select a column or row at design time, hover a mouse pointer over it in close proximity to a border. Once a column or row is highlighted, you can drag it to a new position, and right-click it to change the Style.

tablelayoutdrag

Add and Arrange Controls

To add a control to a Table Panel, drag it into a table cell. You can drag controls from one cell to another to re-arrange them. Note that you can create a StackPanel, fill it with items, and drag this entire panel into a Table Panel cell.

When a control is added to a panel's Controls collection, it dispays four extender properties in the Visual Studio Property Grid. These properties specify the cell where the control locates, and the number of rows/columns this column stretches across.

  • Row
  • Column
  • RowSpan
  • ColumnSpan

Since the control itself does not have these settings, use related panel methods if you need to arrange controls in code.

The following sample illustrates how to fill the table created in the previous section with buttons.

sample

tablePanel2.Controls.AddRange(new Control[] {
    button1, button3, button4, button5, button6,
    button7, button8, button9, button10, button11,
    button12, button13, button14});

tablePanel2.SetCell(button1, 0, 0);
tablePanel2.SetColumnSpan(button1, 2);
tablePanel2.SetRowSpan(button1, 4);
button1.Dock = DockStyle.Fill;

tablePanel2.SetCell(button3, 0, 2);

tablePanel2.SetCell(button4, 0, 3);

tablePanel2.SetCell(button5, 1, 2);

tablePanel2.SetCell(button6, 1, 3);

tablePanel2.SetCell(button7, 2, 2);

tablePanel2.SetCell(button8, 2, 3);

tablePanel2.SetCell(button9, 3, 2);

tablePanel2.SetCell(button10, 3, 3);

tablePanel2.SetCell(button11, 4, 0);

tablePanel2.SetCell(button12, 4, 1);
tablePanel2.SetColumnSpan(button12, 3);

tablePanel2.SetCell(button13, 5, 0);

tablePanel2.SetCell(button14, 5, 1);
tablePanel2.SetColumnSpan(button14, 3);

Overlap Multiple Cells

In Absolute and Relative row/column size mode, the Table Panel resizes controls placed inside the panel so they fit the bounds of cells.

However, a control within a Table Panel may impose size restrictions or calculate size itself. For instance, LabelControl sets its default size according to its content. Any control can limit its size with the MinimumSize property. In these cases, the control can overlap adjacent cells within the Table Panel.

To allow a control to occupy only one cell, consider the following solutions.

  • Resize the Table Panel's rows and columns, so that each control only resides within its cell.
  • Enable AutoSize mode for rows/columns, as shown above.

  • Disable auto-size mode for controls within cells. For LabelControl, use the LabelControl.AutoSizeMode property.
  • Set the MinimumSize property for a control within a cell to a smaller value.
  • If controls overlap adjacent cells when a user resizes the Table Panel (or the parent form), you can prevent the Table Panel/form from being resized (use their MinimumSize properties).

Auto-Size Mode

The TablePanel can automatically adjust its size to fit its contents. Use the following two properties to enable the panel's auto-size mode:

  • AutoSize - Set this option to true to enable the auto-size functionality.
  • AutoSizeMode - Use this property to choose the auto-size behavior - GrowOnly or GrowAndShrink. See the AutoSizeMode topic in MSDN to learn more.
TIP

You can additionally enable the auto-size functionality for controls within the TablePanel, and for containers (e.g., a form) where the TablePanel resides.

The resize behavior of individual rows and columns in the TablePanel is specified by their Style settings. This property is interpreted as follows when you enable auto-size mode for the panel:

  • Set the Style property for the row/column to Absolute to fix the row's/column's length.
  • Set the Style property to AutoSize to make the row/column resize itself according to the row's/column's contents.
  • The Relative option assigned to the Style property is interpreted as the AutoSize option.

Other Settings

  • AutoScroll - Gets or sets whether the panel enables scrollbars that allow you to scroll to any controls placed outside the panel's visible boundaries.
  • AutoTabOrder - Gets or sets whether the panel maintains an automatic tab order of its child controls.
  • LabelVertAlignment - Gets or sets how LabelControls are vertically aligned in relation to the text editors displayed to the label's right (to the label's left in right-to-left locales).
See Also