Creating, Destroying, Showing and Hiding Dock Controls

• Dec 28, 2020
• 5 minutes to read

This topic provides simple examples of creating, destroying dock controls and changes to their visibility. Note: manual creation and destruction of dock controls is generally needed for dock panels representing documents. Dock panels representing tool windows are likely to be created at design-time and not destroyed during the application’s execution. For tool windows, you will generally change the visible state.

Summary

---

A dock control’s visibility is specified by its Visible property. Set the property to False to hide the control. Note: a control can also be hidden by calling its Close method. Bear in mind though, that this method only hides the control if the docking manager’s doFreeOnClose option is disabled. Otherwise, the Close method destroys the control. Another way to hide a control is to undock it using the UnDock method. In this case, the control has no parent, and thus the control is not displayed. Finally, you can destroy a dock control directly by calling its Free method.

Note

you will not have to create and destroy container controls. They are created and destroyed automatically as the result of docking operations.

Note

if a control is hidden, it still takes part in layout customization since its parent dock control is preserved. For instance, if a control located within a tab container is hidden and then displayed again, it will appear in the same tab container as before.

Note

if the auto hide feature is enabled for a control and the control is not visible on the screen, setting the control’s Visible property to False does nothing. You have two alternative ways of hiding a dock control in this case. First, you can make the control visible on the screen and then set the control’s Visible property to False. Another method is to disable the auto hide feature for the control before attempting to hide it.

You can respond to changes to a dock control’s visibility by handling the VisibleChanged and VisibleChanging events. You can also respond to closing a control by using the OnClose event. Finally, you can restrict end-users from closing a dock control by handling the OnCloseQuery event.

Showing and Hiding Dock Controls

---

This section provides a simple code sample showing how to show and hide dock controls. The code below represents a button’s OnClick event handler. The code toggles a dock panel’s visible state. Note: it even handles the case when the panel’s auto hide feature is enabled and the panel’s client area is not currently visible.

procedure TForm1. Button1Click(Sender: TObject);
begin
  if dxDockPanel1.AutoHide and not dxDockPanel1.Visible then
  begin
    dxDockingController.BeginUpdate;
    try
      // make the panel's client area visible on screen
      dxDockPanel1.Visible := True;
      // hide the panel
      dxDockPanel1.Visible := False;
    finally
      dxDockingController.EndUpdate;
    end;
  end
  else
    dxDockPanel1.Visible := not dxDockPanel1.Visible;
end;

Creating and Destroying Dock Controls

---

This section shows how to create an application that enables you to display images on separate dock panels. An image can be loaded by pressing the INSERT key. Once an image has been loaded, it is placed on a dynamically created dock panel docked to the site. Pressing the DELETE key destroys all panels.

To create the sample application, follow the steps below:

• Create a new application.

• Place a TdxDockingManager component on the form.

• Place a TOpenDialog component on the form.

• Place a TdxDockSite control on the form and set its Align property to alClient.

• Write the following handler for the form’s OnCreate event.

procedure TForm1.FormCreate(Sender: TObject);
begin
  // specify the open dialog's filter
  OpenDialog1.Filter := '*.bmp|*.bmp';
  with dxDockingManager1 do
  begin
    // force dock controls to be destroyed when closed
    Options := dxDockingManager1.Options + [doFreeOnClose];
    // specify the default tabs position and
    // the dock controls paint style
    DefaultTabContainerSiteProperties.TabsPosition := tctpTop;
    ViewStyle := vsNET;
  end;
end;

Write the following handler for the form’s OnKeyDown event.

procedure TForm1.FormKeyDown(Sender: TObject; var Key: Word;
  Shift: TShiftState);
var
  APicture: TPicture;
  APanel: TdxDockPanel;
  AImage: TImage;
  ALastIndex, I: Integer;
begin
  if Key = VK_INSERT then
  begin
    // open the file and create the corresponding image object
    if not OpenDialog1.Execute() then Exit;
    APicture := TPicture.Create();
    APicture.LoadFromFile(OpenDialog1.FileName);
    // create a new panel that will hold the image
    APanel := TdxDockPanel.Create(Self);
    APanel.Caption := ExtractFileName(OpenDialog1.FileName);
    // check whether the dock site already has docked controls
    if dxDockSite1.ChildCount > 0 then
    begin
      // add the panel to the tab container
      ALastIndex := dxDockSite1.Children[1].ChildCount;
      APanel.DockTo(dxDockSite1.Children[1], dtClient, ALastIndex + 1);
    end
    else
      // dock the panel to the dock site
      APanel.DockTo(dxDockSite1, dtClient, 0);
    // create an image control and place it on the panel
    AImage := TImage.Create(Self);
    AImage.Parent := APanel;
    AImage.Align := alClient;
    AImage.Center := True;
    AImage.Picture := APicture;
  end;
  // delete all panels if the DELETE key has been pressed
  if Key = VK_DELETE then
  begin
    for I := 0 to dxDockingController.DockControlCount - 1 do
    begin
      if dxDockingController.DockControls[I] is TdxDockPanel then
        dxDockingController.DockControls[I].Close;
    end;
  end;
end;

The image below shows the appearance of this sample application.