Controlling Docking Operations

You can manage docking operations relative to a specific pane with the IlvDockable class. Each docking pane has an instance of the IlvDockable class connected to it. This instance can be automatically created when adding the pane using the member function addDockingPane, or can be specified by the user.

This section covers the following topic:

Connecting an Instance of the IlvDockable Class to a Pane

To connect an instance of the IlvDockable class to a pane, you first have to create an instance of the IlvDockable class or of a subclass like this:

IlvDockable* dockable = new IlvDockable();

Then you can set it to your pane using the static member function SetDockable.

To retrieve the IlvDockable instance connected to a pane, call:

IlvDockable* dockable = IlvDockable::GetDockable(pane);

This member function returns 0 if pane is not a docking pane.

To retrieve the pane connected to an IlvDockable instance, call:

IlvPane* pane = dockable->getPane();

Docking and Undocking a Pane

When a pane is docked, you can undock it using the member function unDock.

When a pane is undocked, you can dock it using the member function dock. This member function calls addDockingPane to dock the pane.

To know whether a pane is docked, use the isDocked member function.

Controlling User Interactions

You can dock or undock a docking pane by double-clicking its handle.

To prevent a pane from being docked, you can press the Ctrl key while dragging it onto a dockable container.

To cancel a docking operation, press the Escape key.

Filtering Docking Operations

Potentially, a docking pane can be attached to any dockable container in your application. You can, however, control docking operations and prevent docking panes from being attached to a given container.

When you drag a pane onto a dockable container, the virtual member function acceptDocking is called. If it returns true, the pane can be docked; otherwise, the operation is not allowed.

Here is a brief description of what acceptDocking checks:

  • If the target container is the same as the current paned container, acceptDocking returns IlTrue.

  • The target container is asked whether docking is allowed for the pane with the member function acceptDocking. If the dockable container returns IlFalse, docking is not allowed and acceptDocking returns IlFalse. By default, the member function acceptDocking returns the dockable state of the container. You can change this state with the member function setDockable.

  • The docking direction set is compared with the direction of the target container. If both directions do not match, docking is not carried out and acceptDocking returns IlFalse. You can set the docking direction using the member function setDockingDirection. This function is useful if you want to force a pane to always dock horizontally for example. By default, a pane can be docked both to a vertical and a horizontal container.