Creating and Managing Container Controls at Runtime

• Aug 02, 2022
• 3 minutes to read

This topic provides examples of creating container controls, specifying their active child controls and moving child controls within the owning container.

You should use the following main methods and properties when managing container controls:

• A dock control’s DockTo method – can be used to create a container. Note: the docking target should be a dock panel or container. This method can also be used to undock a panel from a container, which may result in the container’s destruction. Finally, this method can be used to move a control within the owning container.

• A dock control’s MakeFloating method – can be used to undock a control from a container. Note: this may lead to container destruction.

• A container’s ActiveChildIndex property – used to specify the container’s active child. This is the active tab in tab containers and the expanded child in side containers.

• A dock control’s DockIndex property – determines the control’s index within the container. This property value can be assigned to the container’s ActiveChildIndex to activate the control within the container.

• A container’s Children, ChildCount, ValidChildren and ValidChildCount properties – can be used to access a container control’s children.

• A dock control’s ParentDockControl, TabContainer, SideContainer properties – allow access to the parent dock control.

The sample code below assumes that there are five dock panels in the application. The code creates a tab container that includes three panels and a vertical side container containing the other two panels.

var
  ATabContainer: TdxTabContainerDockSite;
  ASideContainer: TdxSideContainerDockSite;
begin
  // create a side container by docking the second panel
  // to the center of the first one
  dxDockPanel2.DockTo(dxDockPanel1, dtClient, 1);
  // obtaining the tab container created
  ATabContainer := dxDockPanel1.TabContainer;
  if ATabContainer = nil then Exit;
  // adding the third panel to the tab container
  dxDockPanel3.DockTo(ATabContainer, dtClient, 2);
  // switching to the first panel (tab)
  ATabContainer.ActiveChildIndex := dxDockPanel1.DockIndex;
  // create a vertical side container
  dxDockPanel4.DockTo(dxDockPanel5, dtTop, 0);
  // obtain the side container created
  ASideContainer := dxDockPanel4.SideContainer;
  if ASideContainer = nil then Exit;
  // expand the top panel within the side container
  ASideContainer.ActiveChildIndex := dxDockPanel4.DockIndex;
  // dock the side container to a site's right edge
  ASideContainer.DockTo(dxDockSite1, dtRight, 0);
  // dock the tab container to a site's bottom edge
  ATabContainer.DockTo(dxDockSite1, dtBottom, 0);
end;

The image below shows the sample code execution’s result.

The following code customizes the layout created.

var
  ATabContainer: TdxTabContainerDockSite;
  ASideContainer: TdxSideContainerDockSite;
begin
  // obtain the tab container
  ATabContainer := dxDockPanel1.TabContainer;
  if ATabContainer = nil then Exit;
  // create a horizontal side container comprised of the
  // tab container and the third panel
  dxDockPanel3.DockTo(ATabContainer, dtRight, 1);
  // change the first panel's position within the tab container
  dxDockPanel1.DockTo(ATabContainer, dtClient, 1);
  // obtain the side container
  ASideContainer := dxDockPanel4.SideContainer;
  if ASideContainer = nil then Exit;
  // cancel the top panel's expansion
  ASideContainer.ActiveChildIndex := -1;
end;

The image below shows the result.