21.5 Using the Advanced Docking Windows Architecture

You can use the advanced docking windows architecture to provide any frame window (CFrameWnd, CMDIFrameWnd, CMDIChildWnd, SECFrameWnd, SECMDIFrameWnd, SECWorkbookWnd, and more) with docking support.

1. In your frame header, instantiate a docking feature (SECFrameDockingFeature) and a docking factory (SECLayoutDockFactory) object. The docking feature is the hook to enable the docking architecture for that window and the docking factory is a convenience object designed to simplify the process of creating dockable node participants. For example,

   protected: // AdvDocking Additions SECLayoutDockFactory m_LFactory; SECFrameDockingFeature m_dockFeat;

2. In your frame window's OnCreate() handler, call EnableDocking() on the docking feature. Note that this is a member of SECFrameDockingFeatureBase. Do not confuse it with MFC's CFrameWnd::EnableDocking() member. The prototype for SECFrameDockingFeatureBase::EnableDocking() is as follows:

   virtual BOOL EnableDocking(CWnd* pParent,DWORD dwDockStyle=SEC_DOCK_ANY, BOOL bCreateNewLocalDockMgr=FALSE, SECLNDockingMgr* pMgr=NULL);

   The first parameter is a pointer to the frame window to participate in the docking architecture.

   You can apply a combination of zero or more of the following flags to the second parameter:

   Table 52: DockStyle Flags

   Docking style	Behavior
   SEC_DOCK_LEFT	Allows docking to left border.
   SEC_DOCK_RIGHT	Allows docking to right border.
   SEC_DOCK_BOTTOM	Allows docking to bottom border.
   SEC_DOCK_TOP	Allows docking to top border.
   SEC_DOCK_ANY	Allows docking to any border.

   The third parameter specifies whether to create a local docking manager or not. If a local docking manager is created, then nodes docked to this docking feature will not be able to dock to any other docking features. This is typically used inside MDI children, to prevent docking with other frame windows.

   The fourth parameter is a pointer to the docking manager to associate with this feature. You can use the same manager for multiple dock features (1 feature per frame) to configure docking between specific windows. If this parameter is defined, bCreateNewLocalDockMgr is ignored.

   An example:

   int CMainFrame::OnCreate(LPCREATESTRUCT lpCreateStruct) { . . . m_dockFeat.EnableDocking(this); }

3. Using the dock factory, create a dockable node for each entity (CWnd or DC image) you want to incorporate into the docking framework. For example,

   // Get the CWnd you want to wrap in a dockable node CWnd* pMyWnd=GetMyWndFromSomewhere(); // Create the dockable node. The first parameter is the CWnd, // the second is the parent window, the third is the default // title string (displayed when floating) and the fourth // signals that we want this node to automatically scale when // sized. Note that the factory performs all memory // management, // do not deallocate directly. SECLayoutNode* pDockNode=m_LFactory.CreateDockableNodeWnd(pMyWnd, this,_T("Dockable Node 1"),TRUE); // Or, you could create a dockable node window from a // child control id: SECLayoutNode* pDockNode=m_LFactory.CreateDockableNodeWnd(IDC_CHILDID, this,_T("Dockable Node 2"));

   ---

   A similar procedure can be used for creating dockable Device Context Nodes. See Section 21.5.2, "To create dockable device context nodes."

   ---

4. Now, use DockNode() or FloatNode() or both members of SECFrameDockingFeature to place your dockable nodes created in the previous step initially. Several overloaded varieties of these functions are available for use so consult the online help for a thorough description of each parameter. For example:

   // Dock a node to the bottom, initially sized 100 pixels wide m_dockFeat.DockNode(pDockNode,SEC_DOCK_BOTTOM,100); // Dock a node to the bottom, using average row size m_dockFeat.DockNode(pDockNode2,SEC_DOCK_BOTTOM); // Dock a node to the right, creating a new column of width //of 50 pixels m_dockFeat.DockNode(pDockNode3,SEC_DOCK_RIGHT,50,TRUE); // Float a node at screen coordinates // left=100,top=150,right=300,bottom=400 m_dockFeat.FloatNode(pDockNode4,CRect(100,150,300,400));

5. The result of the preceding code would be a layout similar to the following figure:

   Figure 145: Sample Advanced Docking Windows application

   

Note you can apply the DockNode() and FloatNode() methods iteratively to reset the position of a particular dockable node throughout the lifetime of that particular node. In addition, you can use SECFrameDockingFeatureBase::ShowNode() to show or hide a docked node. For examples of configurations, Section 21.3.5, "Advanced Docking Configurations."

The Advanced Docking architecture enables you to create lightweight, windowless (no HWND) dockable nodes based on Device Context drawing. This node type is ideal for rendered images, pictures, and MVC ViewPorts. To create a dockable DC node, do the following:

1. Derive a class from SECReparentableNodeDC and then override the following protected virtual method:

   class CMyDCNode : public SECReparentableNodeDC { protected: virtual void OnDrawNode(HDC hDC,const CRect& rectDraw); };

2. In your override, render your image to the DC passed in, given the bounding rect passed in. For example:

   void CMyDCNode::OnDrawNode(HDC hDC,const CRect& rectDraw) { CDC* pDC=CDC::FromHandle(hDC); ASSERT_VALID(pDC); pDC->FillSolidRect(rectDraw,m_clr); CRect rc=rectDraw; pDC->SetTextColor(COLORREF(RGB(0,255,0))); pDC->DrawText(m_strDraw,rc,DT_SINGLELINE|DT_CENTER|DT_VCENTER); }

3. Follow the procedure described in Section 21.5.1, with one exception. Instead of creating a dockable node, use the CreateDockableNodeDC() method of SECLayoutDockFactory. For example:

   // The DC node will be wrapped in a dockable node wrapper. // If we need to manipulate the DC node, it can be done // through a back pointer returned via the NODEBP macro // below. CMyDCNode* pDCNode; SECLayoutNode* pDockNode; // Create the dockable DC node, and its docking wrapper // (pDockNode). // The docking wrapper should be used for the DockNode // operation, not the pDCNode back pointer. The NODEDC_CLASS // macro is used to provide the run-time class name for // factory allocation. // Note that the factory performs all memory management, // do not deallocate directly. pDockNode = m_LFactory.CreateDockableNodeDC(this, NODEDC_CLASS(CMyDCNode), _T("Node 1"), NODEBP(pDockNode)); ASSERT(pDockNode && pDCNode); // pDockNode back-pointer provided for object manipulation, // if needed. If not needed, you could have called // CreateDockableNodeDC like this: pDockNode = m_LFactory.CreateDockableNodeDC(this, NODEDC_CLASS(CMyDCNode)); // Call a CMyDCNode function (i.e. App-Specific) pDockNode ->SetDrawColors(COLORREF(RGB(0,0,255))); m_dockFeat.DockNode(pDockNode); // no second parm, use // defaults

The following code demonstrates one way you can use the SECDockInsertionConstraints object to create an advanced docking configuration.

CMainFrame::OnCreate(…) { // (EnableDocking call, then node creation) // Create our reusable insertion constraint object SECDockInsertionConstraints cnstr; // Dock the first node to the bottom dock site, using default // sizing cnstr.SetDockSite(SEC_DOCK_BOTTOM); m_dockFeat.DockNode(pDockNode,cnstr); // Dock a second node immediately after pDockNode (to the right, // since the bottom is horizontal), but set the second // node to occupy exactly 100 pixels in width. pDockNode will // subsequently be adjusted to fit the remaining width cnstr.m_nForcedSize=100; m_dockFeat.DockNode(pDockNode2,cnstr); // Dock a third node immediately below nodes 1 and 2, occupying a // new line with a height of 75 pixels cnstr.m_bCreateNewLine=TRUE; cnstr.m_nForcedNewLineSize=75; m_dockFeat.DockNode(pDockNode3,cnstr); // Now dock a node to the top border instead cnstr.Reset(); // reset constraints set above back to defaults cnstr.SetDockSite(SEC_DOCK_TOP); m_dockFeat.DockNode(pDockNode4,cnstr); // Let's set node 5 to not be dynamic, i.e. not provide a sizing // splitter to change its width within the top docksite. // Dock next to node 4 (to the right) cnstr.m_bDynamicNode=FALSE; m_dockFeat.DockNode(pDockNode5,cnstr); // Dock node 6 to the left (before) node 4, i.e. the head of the // row. Node 6 is a dynamic node, so reset constraint from the last // step cnstr.Reset(); cnstr.m_pNodeRelative=pDockNode4; cnstr.m_bInsertAfter=FALSE; m_dockFeat.DockNode(pDockNode6,cnstr); ...

The preceding constraints would create a layout similar to the following figure:

Figure 146: Objective Toolkit Advanced Docking Windows Sample

Use the SECFrameDockingFeature::SetBorderSizing() method to control sizing properties specific to each border docksite (top, bottom, left, and right) individually or as a group. This method provides the following support:

Figure 147: Objective Toolkit Advanced Docking Windows Sample with no sizing splitter

You can use this feature to enable or disable. Use the following static function:

static SECDragDropDockingFeature::SetRealtimeDrag(BOOL bEnable);

By default, this support is enabled, you can disable via the following static function:

static SECFloatDynGridLineTarget::EnableMultiDock(BOOL bEnable);

By default, the frame docking feature is configured so that the top and bottom borders receives precedence over the left and right borders, (for example, the top/bottom always occupies the entire available client width and the left/right borders shrink to accommodate the height between the top/bottom borders). This mode is configurable so that the left/right borders can receive priority over the top/bottom.

The following function is provided to modify the border layout logic:

SECFrameDockingFeatureBase::SetBorderLayout( SECLNBorderClient::BorderAlgorithm BorderAlg, BOOL bRecalc=TRUE);

By default, the top and bottom dock sites receive precedence over the left and right dock sites. This behavior is the same as MFC's CDockbar layout algorithm's behavior. The following figure illustrates this layout:

Figure 148: Sample demonstrating top/bottom precedence

The following code can be used to toggle the border mode so that left/right receives priority over top/bottom.

m_dockFeat.SetBorderLayout(SEC_DOCKBORDERS_LRTB);

This appears as follows. Notice how the left/right borders now occupy the entire height, whereas the bottom is shrunk to fit between. Note also the dockable toolbar and menubar are participants in MFC's controlbar architecture so they are not subject to this layout manipulation.

Figure 149: Sample Demonstrating Left/Right Precedence

1. Follow the steps as described in Section 21.5.1, "To incorporate advanced docking windows into your application." However, allocate and initialize inside your CChildFrame class instead of CMainFrame.

   ---

   The lifetime of dockable nodes associated with a MDI child frame can be shorter than that of your mainframe. By default, enabling a MDI childframe for docking using the procedure outlined above allows any dockable node on the mainframe to be docked to that MDI child, and vice versa. In addition, the MDI child nodes can be docked to other MDI child nodes. As a result, when the MDI child is closed, all contained nodes, regardless of their original parent, are destroyed as well. Avoid accessing node pointers that were destroyed with the destruction of a MDI childframe.

   ---

2. If you want to limit the docking of a MDI child exclusively to that child, you must call EnableDocking() with the third parameter set to TRUE. For example:

   m_dockFeat.EnableDocking(this,SEC_DOCK_ANY,TRUE);

The third parameter signals to the docking feature that all nodes initialized for that frame can only dock to that frame and no other. In addition, dockable nodes created for other frames do not participate with that MDI child in the docking operation (for example, you cannot dock a node from the mainframe to that child frame, or vice versa). This is similar to how MFC's controlbar architecture works.

For more information on defining a docking participant subset, please refer to Objective Toolkit Class Reference for SECFrameDockingFeature::EnableDocking().

The following figure illustrates an MDI childframe with docking windows. The same core docking logic is leveraged in both the mainframe and childframe.

Figure 150: Sample demonstrating an MDI childframe with docking windows

Copyright © Rogue Wave Software, Inc. All Rights Reserved.

The Rogue Wave name and logo, and Stingray, are registered trademarks of Rogue Wave Software. All other trademarks are the property of their respective owners.
Provide feedback to Rogue Wave about its documentation.