How to use the AutomatedDocking Library

One of the benefits of the modern user interface is its flexibility. Users want to be able to adjust the UI every which way. Besides menu and toolbar customization, a flexible user interface should provide users with the ability to customize their desktop to fit their needs. Docking is one of the most elegant solutions for this.

The AutomatedDocking Library is an advanced product that was specially engineered to add docking facilities to your VCL and CLX applications. The basic concept of docking is very intuitive: You drag the windows of your application and dock them to docking sites or to each other; similar to how you dock windows in Delphi and Visual Studio .NET.

This topic will explain how you can use the AutomatedDocking Library components and to illustrate what you can expect from the product, so you can decide for yourself if you want take advantage of everything it has to offer you.

How It Works

Above, we said that the docking concept is intuitive: You simply drag a window to the desired location which can be a docking site or another window and drop it there. While dragging, a gray rectangle shows the location that the window will have when released. Note that pressing Ctrl while dragging will prevent the window from docking when released (the shortcut that prevents docking can be changed via the AutoDragKey property of the TaqDockingManager component).

You can dock a window to any side of another window – top, bottom, left or right. If you dock two windows to the same spot, they will appear as tabbed pages:

When a window is floating, it looks like an ordinary application window:

A docked window has a few extra buttons in the top-right corner:

They are called caption buttons. They let you undock or hide the window, maximize it within the docking site, call the on-line help, etc. For more information on caption buttons read the Creating Panels and Changing the Look-and-Feel Properties sections of this topic.

A right-click on the caption of a docked window displays the following context menu:

Items of this menu are similar to the caption buttons. There are two items that are only on the context menu, they are Rename and Align. Rename opens an edit dialog where you can change the window’s caption. Align opens a sub menu, which lets you align the window within the docking site.

A right-click on a tabbed page displays another context menu:

The Tabs item opens a sub menu which allows you to bring up the desired tabbed page. This may be useful when the docking site is not wide enough to display the captions of all of the tabbed pages. Top and Bottom specify the location of the tabbed page captions. Help calls the help topic for the currently selected window.

One way to get a good feel for the ease and simplicity of docking is to run the demo application that is included with the AutomatedDocking Library.

Terms

The AutomatedDocking Library includes three components:

The docking controls are special objects that can be docked or remain floating. There are two types of docking controls: Panels and Containers.

Placing Controls on a Form

The first step in using the AutomatedDocking Library is to place the TaqDockingManager and TaqDockingSite components on a form in your application. By default, these components are installed on the AutomatedQA page of the Component Palette:

1. Select the TaqDockingManager component in the AutomatedQA page of the Component Palette and then click somewhere on the form to place this component on it.
2. Select the TaqDockingSite component in the Component Palette and then click somewhere on the form to place this component on it.
3. (Optional step) After the component has been placed on the form, switch to the Object Inspector and select alClient in the Align property. Now, the docking site will occupy the entire form. Another way to enlarge area of the docking site is to drag the bound markers.
4. Select the docking site component on the form and switch to the Object Inspector. Now specify aqDockingManager1 in the DockingManager property of the docking site component.

We have associated the docking site with the docking manager. Now the docking controls that are created by the manager are able to dock to the docking site.

Creating Panels

Once you have placed the docking manager on the form, you can create docking controls:

1. Select the TaqDockingManager component on your form, then either switch to the Object Inspector and press the ellipsis button of the Items property, or right-click on the docking manager and select Setup from the context menu. The Docking Setup dialog will appear:

   

2. Press New. This will create a new docking control (panel) and display its name in the Panels list.
3. Select the new panel in the Panels list and switch to the Object Inspector. Here we can modify the panel’s properties. For instance, we can change the default panel name, aqDockingControl1, to DCEditor and specify Editor as the panel caption.
4. Let’s create one more panel. It will have the name DCImage and the caption Image:

   

5. At design-time, all existing panels are displayed as tabbed pages in the docking site. This is done to make the development of the panels easier.

   

6. Now we can place components on our panels. Let’s put a TMemo onto DCEditor and a TImage onto DCImage.
   To place a TMemo:
   Click on the DCEditor tabbed page to bring it up.
   Click TMemo in the Component Palette and then click somewhere on the DCEditor panel to place TMemo onto it.
   Select the TMemo component, then switch to the Object Inspector and specify alClient in the Align property.

   

   Using the same steps add the TImage component to the DCImage panel.

7. By default, all of the panels that you have created are visible at run time. To make the panel hidden once the application starts, set the Visible property of this panel to False. To make this panel visible at run time either change the panel’s Visible property or call the ForceVisible method:
   
   aqDockingControl1.ForceVisible;
     or
   aqDockingControl1.Visible := True;

8. One more feature that we need to pay attention to is the ShowContainerCaption property of the docking manager. It specifies if the container captions are visible. This may be important for docking containers in CLX applications: To dock or undock a docking control (panel or container) in a CLX application, you have to drag the control’s caption, not the forms caption. By default, the captions of inside and horizontal containers are not visible, so you are unable to dock and undock these containers. The ShowContainerCaption property helps you avoid this problem: Just set the following values in the Object Inspector.

Note that the containers of the inside type are divided into inside containers with tab page captions at the top of the container (cnInsideTop) and inside containers with tab page captions at the bottom of the container (cnInsideBottom). This makes it possible to control the appearance of docking contorls in a more flexible manner.

Now you can run the application and try docking the panels.

You may note that by default floating forms remain on top when they lose focus. If you want to change the default behavior, use the FloatFormsOnTop property. When set to False, the floating windows will go to the back when you bring up another application window.

Note that the captions of the docked panels hold several buttons. They are (from the left to the right): Help, Custom, Maximize or Restore, Undock and Hide. These buttons are called caption buttons. By default, all of the buttons are visible except for Custom one (This button allows you to create user-defined actions for the panels. For more information on using it, see the on-line help). The docking manager’s CaptionButtons property lets you specify which of these buttons are visible and which are not. Use this property to hide or display the caption buttons.

One more property that has effect on the caption buttons is ShowDisabledButtons (in ver. 1.2 and earlier this property was called AutoHideButtons). Under certain conditions, some of caption buttons can be disabled. This typically occurs with the Maximize/Restore button when the panel is the only docking control within the docking site. If ShowDisabledButtons is set to True then the disabled buttons are hidden. The following figures illustrate this –

ShowDisabledButtons = False	ShowDisabledButtons = True

Making Forms Dockable

The docking manager object handles the docking and undocking operations. Docking controls can be docked to the docking site or to the panels that are registered in the same docking manager. Panels and containers are created via the docking manager; therefore, they belong to the form that holds the docking manager. You might have noticed this when you performed the operations that were described in the previous step. All of the panels and all of the controls on these panels belong to the form that holds the docking manager, that is, they belong to one form:

TMainForm = class(TForm)
    MainMenu1: TMainMenu;

 
    aqDockingSite1: TaqDockingSite;

    aqDockingManager1: TaqDockingManager;

    DCEditor: TaqDockingControl;

    DCImage: TaqDockingControl;

    Memo1: TMemo;    // <-- This component
    was placed on the Editor

    panel Image1: TImage; // <-- This component
        was placed on the Image

        panel

        . . .
 private
 { Private declarations } public
 { Public declarations } end;

Concentration of the entire UI on one form is uncommon. Normally, applications include multiple forms. In this step we’ll describe one of the ways to make the forms in your application “dockable”. This is easy. All you need to do is create a docking control and make it the parent control of your form. You can do this by modifying the form’s properties and adding a few lines of code. The detailed explanation is below. Although it is for Delphi, you can perform the steps in Kylix and end up with the same result.

In our example, we will call the form that holds the docking manager MainForm, and the form that will be “dockable” Form2:

1. Open MainForm in Delphi’s designer and create a new docking control. It will be the parent control for Form2.

   

2. Open Form2 in Delphi’s designer.

3. Specify the following code within the OnCreate event handler of Form2:

   procedure TForm2.FormCreate(Sender: TObject);
    
   begin
     . . .
   
    { This line is required. It specifies
       that the docking control
   
       will be the parent of Form2. aqDockingControl3 is the docking control that was created
   
       in the first step. } Parent := MainForm.aqDockingControl3;
    
    { The following lines modify the properties
           of the docking
   
           control so that they correspond to the Form2 properties.} 
   
           MainForm.aqDockingControl3.Caption:= Caption;
   
           MainForm.aqDockingControl3.PreferredWidth := Width;
   
           MainForm.aqDockingControl3.PreferredHeight := Height;
   
           . . .
    end;

   The code above makes the panel the parent control of Form2. Now, if the panel is hidden, Form2 is also hidden regardless of the state of its Visible property. To make the form visible, you should make the panel visible. To do this you can use the following code —

   aqDockingControl3.Visible := True;

   instead of calling the Form2.Show method.

4. To ensure that the form is displayed properly within the panel, we should modify some of the form’s properties:

   Assign bsNone to the BorderStyle property. This will hide the form’s caption. We recommend that you set this value, because normally there is no need to display the form’s caption within a panel.
   Set the Align property to alClient. This is necessary to ensure that the child controls of the form display properly within the panel. If you do not set this property, the child controls can end up being displayed out of the panel’s client area when the panel is docked. This occurs because Delphi does not send certain notifications to unaligned controls, so the controls’ coordinates cannot be adjusted to fit the panel’s client area.
   Set the form’s Visible property to True. This will make the form visible within the panel. If Visible is set to False, the form will remain hidden even when the panel is visible.
5. Perform the steps 1-4 for each form that you want to behave like a docking panel.

Selecting the Docking Style

The AutomatedDocking Library lets you select the docking style that your application will use: Native, VS2005 or VSWhidbey. (The docking styles are supported in vertsion 1.2 and later).

If you select the Native docking style, then when you are dragging a panel caption in order to dock it to another desired panel or docking site, a gray rectangle will show you where the panel will be positioned after docking.

If you select the VS2005 or VSWhidbey docking style, then the docking will look very much like docking in Visual Studio 2005. When you are dragging an undocked panel over another panel, the docking zone selector appears. It lets you specify where the panel will be docking if you released it:

To dock a panel to the top, left, bottom or right edge of the lower panel, move the mouse cursor to the appropriate icon within the selector and then release the mouse button.

The difference between the VS2005 and VSWhidbey styles is images used for docking zone selectors. The VS2005 style uses images similar to those used in Visual Studio 2005, whereas VSWhidbey uses images that were used by beta versions of Visual Studio 2005 (codenamed Whidbey).

To specify the desired docking style, open the Object Inspector and then select the desired docking style using the DockingStyle property:

You can also change the docking style programmatically. For more information on this, see the Working With Styles topic in on-line help.

Auto-Hiding Support

Panels that are docked to a docking site or that belong to a container docked to a docking site can be auto-hidden. Auto-hiding means a panel can be minimized along one of the sides of the docking site, so only the panel’s caption remains visible:

To enable the auto-hide mode, simply assign True to the AutoHideEnabled property of the docking manager.

When the auto-hide mode is active, the panel captions hold the button, a click on which hides the panel.

To view an auto-hidden panel, move the mouse cursor to the panel caption or click the caption - the panel will pop up (see the image above).

To show a hidden panel, simply click the button on the panel caption (see the image above).

Changing Look-and-Feel Properties

So far we have described how to create docking controls. Now it’s time to specify how they look. Of course, each panel has a number of properties that let you specify the panel’s background color, icon, etc. However, many more “look-and-feel” properties are provided by styles. Styles define the colors, fonts, drawing style (gradient or not), caption button size, etc. for the docking controls. The third component included in the AutomatedDocking Library, TaqStyleManager, is used to create and edit styles. Currently, the AutomatedDocking Library includes three types of styles: Ordinary, themed and Qt-based. If you use an ordinary style, you have to manually specify all of its properties. For instance, you can select the gradient fill for the panel captions and select the colors for it. Themed styles use the color settings of the currently selected Windows XP Visual Style. They also let you select images for the buttons than are displayed in the docking control captions. If you don’t use Windows XP, then the settings are ignored. Qt-based styles draw docking controls using the current Qt settings (Qt is a library used by the open source community for building graphic user interfaces). You can use Qt-based styles in CLX applications only. Themed styles can be used in VCL applications only and ordinary styles can be used in both application types. Qt styles are supported only by AutomatedDocking Library ver. 1.2 and earler.

To create a new style, follow these steps:

1. First, you place the TaqStyleManager component onto the form that holds the docking manager: Select TaqStyleManager on the AutomatedQA page of the Component Palette and then click somewhere on your form to place the style manager on it.

2. Associate the style manager with the docking manager. To do this, select the TaqStyleManager component on the form and switch to the Object Inspector. Then, specify aqStyleManager1 in the StyleManager property.

   

3. Styles are created in the Edit Style dialog. To call this dialog right-click on the TaqStyleManager component on the form and select Edit Styles from the context menu.

   

4. This dialog allows you to create your own styles based on one of two pre-defined styles. In VCL applications, the basic styles are Default and Themed (AutomatedDocking Library v.1.2 adds three more basic styles - Standard, Flat and Enhanced; version 1.5 adds the OfficeXP style and version 1.9 adds the VS2005 style). In CLX applications the basic styles are Default and Qt-based. Let’s create a new ordinary (Default) style. To do this —
   Click the down arrow button displayed next to the icon and select Default from the dropdown list.
   A new style - Default1 - will appear in the style list. To rename the style, click and specify MyNewStyle as the new style name.

   

5. Select the new style in the style list and switch to the Object Inspector. Here you can modify the style properties. For instance, you modify the fill type setting in the ActiveCaptionColor or TabColor properties (ActiveCaptionColor and TabColor specifies the color and fill settings for the panel captions).

   

6. To apply a style to the docking controls, click on the docking manager on the form, switch to the Object Inspector and select the style name (in our example, it is MyNewStyle) in the Style property.

   

The style will be applied to the docking controls. Now you can launch the application and see the results.

By using different fill style and color settings you can achieve different visualization effects. For instance,

Besides color settings, styles let you specify which font you wish to use for captions, custom images for caption buttons, splitter width, etc. Styles have a great set of “custom draw” event handlers. They let you customize any aspect of the controls visualization. Just have a look at the Events page of the Object Inspector for a style:

We will not explain what code you should use for these event handlers at this point. For more information about them, see the on-line help system.

Conclusion

This topic is only an introduction to the AutomatedDocking Library. It describes the following main points:

We hope that this information will at least help you get started using the product. Of course, some features, such as using actions and using the custom caption button, were left out. If you would like more detailed information about them, please review the on-line help. In the on-line help you will also find lots of useful samples and the How to… topic that will provide solutions for a number of frequently performed tasks. If you come across a problem using the product or have a suggestion for it, do not hesitate to write to our support team. We will be glad to help you.