Edit

Share via

CDockablePane Class

  • Article

Implements a pane that can either be docked in a dock site or included in a tabbed pane.

Syntax

class CDockablePane : public CPane

Members

Public Constructors

Name Description
CDockablePane::CDockablePane Constructs and initializes a CDockablePane object.

Public Methods

Name Description
CDockablePane::AttachToTabWnd Attaches a pane to another pane. This creates a tabbed pane.
CDockablePane::CalcFixedLayout Returns the size of the pane rectangle.
CDockablePane::CanAcceptMiniFrame Determines whether the specified mini frame can be docked to the pane.
CDockablePane::CanAcceptPane Determines whether another pane can be docked to the current pane.
CDockablePane::CanAutoHide Determines whether the pane supports auto-hide mode. (Overrides CBasePane::CanAutoHide.)
CDockablePane::CanBeAttached Determines whether the current pane can be docked to another pane.
CDockablePane::ConvertToTabbedDocument Converts one or more dockable panes to MDI tabbed documents.
CDockablePane::CopyState Copies the state of a dockable pane.
CDockablePane::Create Creates the Windows control and attaches it to the CDockablePane object.
CDockablePane::CreateDefaultPaneDivider Creates a default divider for the pane as it is being docked to a frame window.
CDockablePane::CreateEx Creates the Windows control and attaches it to the CDockablePane object.
CDockablePane::CreateTabbedPane Creates a tabbed pane from the current pane.
CDockablePane::DockPaneContainer Docks a container to the pane.
CDockablePane::DockPaneStandard Docks a pane by using outline (standard) docking.
CDockablePane::DockToFrameWindow Used internally. To dock a pane, use CPane::DockPane or CDockablePane::DockToWindow.
CDockablePane::DockToRecentPos Docks a pane to its stored recent docking position.
CDockablePane::DockToWindow Docks one docking pane to another docking pane.
CDockablePane::EnableAutohideAll Enables or disables auto-hide mode for this pane together with other panes in the container.
CDockablePane::EnableGripper Shows or hides the caption (gripper).
CDockablePane::GetAHRestoredRect Specifies the position of the pane when visible in auto-hide mode.
CDockablePane::GetAHSlideMode Retrieves the auto hide slide mode for the pane.
CDockablePane::GetAutoHideButton Used internally.
CDockablePane::GetAutoHideToolBar Used internally.
CDockablePane::GetCaptionHeight Returns the height of the current caption.
CDockablePane::GetDefaultPaneDivider Returns the default pane divider for the pane's container.
CDockablePane::GetDockingStatus Determines the ability of a pane to be docked based on the provided pointer location.
CDockablePane::GetDragSensitivity Returns the drag sensitivity of a docking pane.
CDockablePane::GetLastPercentInPaneContainer Retrieves the percentage of space that a pane occupies within its container.
CDockablePane::GetTabArea Retrieves the tab area for the pane.
CDockablePane::GetTabbedPaneRTC Returns the runtime class information about a tabbed window that is created when another pane docks to the current pane.
CDockablePane::HasAutoHideMode Specifies whether a docking pane can be switched to auto-hide mode.
CDockablePane::HitTest Specifies the specific location in a pane where the user clicks a mouse.
CDockablePane::IsAccessibilityCompatible Used internally.
CDockablePane::IsAutohideAllEnabled Indicates whether the docking pane and all other panes in the container can be placed in auto-hide mode.
CDockablePane::IsAutoHideMode Determines whether a pane is in auto-hide mode.
CDockablePane::IsChangeState Used internally.
CDockablePane::IsDocked Determines whether the current pane is docked.
CDockablePane::IsHideInAutoHideMode Determines the behavior of a pane that is in auto-hide mode if it's shown (or hidden) by calling ShowPane.
CDockablePane::IsInFloatingMultiPaneFrameWnd Specifies whether the pane is in a multi-pane frame window.
CDockablePane::IsResizable Specifies whether the pane is resizable.
CDockablePane::IsTabLocationBottom Specifies whether tabs are located at the top or bottom of the pane.
CDockablePane::IsTracked Specifies whether a pane is being dragged by the user.
CDockablePane::IsVisible Determines whether the current pane is visible.
CDockablePane::LoadState Used internally.
CDockablePane::OnAfterChangeParent Called by the framework when the parent of a pane has changed. (Overrides CPane::OnAfterChangeParent.)
CDockablePane::OnAfterDockFromMiniFrame Called by the framework when a floating docking bar docks at a frame window.
CDockablePane::OnBeforeChangeParent Called by the framework when the parent of the pane is about to change. (Overrides CPane::OnBeforeChangeParent.)
CDockablePane::OnBeforeFloat Called by the framework when a pane is about to float. (Overrides CPane::OnBeforeFloat.)
CDockablePane::RemoveFromDefaultPaneDividier The framework calls this method when a pane is being undocked.
CDockablePane::ReplacePane Replaces the pane with a specified pane.
CDockablePane::RestoreDefaultPaneDivider The framework calls this method as a pane is deserialized to restore the default pane divider.
CDockablePane::SaveState Used internally.
CDockablePane::Serialize Serializes the pane. (Overrides CBasePane::Serialize.)
CDockablePane::SetAutoHideMode Toggles the docking pane between visible and auto-hide mode.
CDockablePane::SetAutoHideParents Sets the auto-hide button and auto-hide toolbar for the pane.
CDockablePane::SetDefaultPaneDivider Used internally.
CDockablePane::SetLastPercentInPaneContainer Sets the percentage of space that a pane occupies within its container.
CDockablePane::SetResizeMode Used internally.
CDockablePane::SetRestoredDefaultPaneDivider Sets the restored default pane divider.
CDockablePane::SetTabbedPaneRTC Sets the runtime class information for a tabbed window that is created when two panes dock together.
CDockablePane::ShowPane Shows or hides a pane.
CDockablePane::Slide Shows or hides a pane with a sliding animation that displays only when the pane is in auto-hide mode.
CDockablePane::ToggleAutoHide Toggles auto-hide mode. (Overrides CPane::ToggleAutoHide .)
CDockablePane::UndockPane Undocks a pane from either the main frame window or a miniframe window container.
CDockablePane::UnSetAutoHideMode Used internally. To set the auto-hide mode, use CDockablePane::SetAutoHideMode

Protected Methods

Name Description
CDockablePane::CheckAutoHideCondition Determines whether the docking pane is hidden (in auto-hide mode).
CDockablePane::CheckStopSlideCondition Determines when an auto-hide docking pane should stop sliding.
CDockablePane::DrawCaption Draws the docking pane caption (gripper).
CDockablePane::OnPressButtons Called when the user presses a caption button other than the AFX_HTCLOSE and AFX_HTMAXBUTTON buttons.
CDockablePane::OnSlide Called by the framework to render the auto-hide slide effect when the pane is either shown or hidden.

Data Members

Name Description
CDockablePane::m_bDisableAnimation Specifies whether auto-hide animation of the dockable pane is disabled.
CDockablePane::m_bHideInAutoHideMode Determines the behavior of the pane when the pane is in auto-hide mode.
CDockablePane::m_nSlideSteps Specifies the animation speed of the pane when it's being shown or hidden when in auto-hide mode.

Remarks

CDockablePane implements the following functionality:

  • Docking a pane to a main frame window.

  • Switching a pane to auto-hide mode.

  • Attaching a pane to a tabbed window.

  • Floating a pane in a miniframe window.

  • Docking a pane to another pane that is floating in a miniframe window.

  • Resizing a pane.

  • Loading and saving state for a docking pane.

    Note

    State information is saved to the Windows registry.

  • Creating a pane with or without a caption. The caption can have a text label and it can be filled with a gradient color.

  • Dragging a pane while displaying the contents of the pane

  • Dragging a pane while displaying a drag rectangle.

To use a docking pane in your application, derive your pane class from the CDockablePane class. Either embed the derived object into the main frame window object or into a window object that controls the instance of your pane. Then call the CDockablePane::Create method or the CDockablePane::CreateEx method when you process the WM_CREATE message in the main frame window. Finally, set up the pane object by calling CBasePane::EnableDocking, CBasePane::DockPane, or CDockablePane::AttachToTabWnd.

Customization Tips

The following tips apply to CDockablePane objects:

  • If you call CDockablePane::AttachToTabWnd for two non-tabbed, dockable panes, a pointer to a tabbed window will be returned in the ppTabbedControlBar parameter. You can continue to add tabs to the tabbed window by using this parameter.

  • The kind of tabbed pane that is created by CDockablePane::AttachToTabWnd is determined by the CDockablePane object in the pTabControlBarAttachTo parameter. You can call CDockablePane::SetTabbedPaneRTC to set the kind of tabbed pane that the CDockablePane will create. The default type is determined by the dwTabbedStyle of CDockablePane::Create when you first create the CDockablePane. If dwTabbedStyle is AFX_CBRS_OUTLOOK_TABS the default type is CMFCOutlookBar Class; if dwTabbedStyle is AFX_CBRS_REGULAR_TABS the default type is CTabbedPane Class.

  • If you want to dock one dockable pane to another, call the CDockablePane::DockToWindow method. The original pane must be docked somewhere before you call this method.

  • The member variable CDockablePane::m_bHideInAutoHideMode controls how dockable panes behave in auto hide mode when you call CDockablePane::ShowPane. If this member variable is set to TRUE, dockable panes and their auto hide buttons will be hidden. Otherwise, they'll slide in and out.

  • You can disable auto-hide animation by setting the CDockablePane::m_bDisableAnimation member variable to TRUE.

Example

The following example demonstrates how to configure a CDockablePane object by using various methods in the CDockablePane class. The example illustrates how to enable the auto-hide all feature for the dockable pane, enable the caption or the gripper, enable the auto-hide mode, show the pane, and animate a pane that is in auto-hide mode. This code snippet is part of the Visual Studio Demo sample.

// GetOwner is an inherited method.
CDockablePane *pParentBar = DYNAMIC_DOWNCAST(CDockablePane, GetOwner());

pParentBar->EnableAutohideAll();
pParentBar->EnableGripper(true);
pParentBar->SetAutoHideMode(true, CBRS_ALIGN_LEFT);
pParentBar->ShowPane(true, false, true);
pParentBar->Slide(true);

Inheritance Hierarchy

CObject

CCmdTarget

CWnd

CBasePane

CPane

CDockablePane

Requirements

Header: afxDockablePane.h

CDockablePane::AttachToTabWnd

Attaches the current pane to a target pane, creating a tabbed pane.

virtual CDockablePane* AttachToTabWnd(
    CDockablePane* pTabControlBarAttachTo,
    AFX_DOCK_METHOD dockMethod,
    BOOL bSetActive= TRUE,
    CDockablePane** ppTabbedControlBar = NULL);

Parameters

pTabControlBarAttachTo
[in, out] Specifies the target pane that the current pane attaches to. The target pane must be a dockable pane.

dockMethod
[in] Specifies the docking method.

bSetActive
[in] TRUE to activate the tabbed pane after the attach operation; otherwise, FALSE.

ppTabbedControlBar
[out] Contains the tabbed pane that results from the attach operation.

Return Value

A pointer to the current pane, if it isn't a tabbed pane; otherwise a pointer to the tabbed pane that results from the attach operation. The return value is NULL if the current pane can't be attached, or if an error occurs.

Remarks

When one dockable pane attaches to another pane using this method, the following occurs:

  1. The framework checks whether the target pane pTabControlBarAttachTo is a regular docking pane or if it's derived from CBaseTabbedPane.

  2. If the target pane is a tabbed pane, the framework adds the current pane to it as a tab.

  3. If the target pane is a regular docking pane, the framework creates a tabbed pane.

    • The framework calls pTabControlBarAttachTo->CreateTabbedPane. The style of the new tabbed pane depends on the m_pTabbedControlBarRTC member. By default, this member is set to the runtime class of CTabbedPane. If you pass the AFX_CBRS_OUTLOOK_TABS style as the dwTabbedStyle parameter to the CDockablePane::Create method, the runtime class object is set to the runtime class of CMFCOutlookBar. You can change this member at any time to change the style of the new pane.

    • When this method creates a tabbed pane, the framework replaces the pointer to pTabControlBarAttachTo (if the pane is docked or floating in a multi-miniframe window) with a pointer to the new tabbed pane.

    • The framework adds the pTabControlBarAttachTo pane to the tabbed pane as the first tab. The framework then adds the current pane as a second tab.

  4. If the current pane is derived from CBaseTabbedPane, all of its tabs are moved to pTabControlBarAttachTo and the current pane is destroyed. Therefore, be careful when you call this method, because a pointer to the current pane may be invalid when the method returns.

If you attach one pane to another when building a docking layout, set dockMethod to DM_SHOW.

You should dock the first pane before you attach another pane to it.

CDockablePane::CalcFixedLayout

Returns the size of the pane rectangle.

virtual CSize CalcFixedLayout(
    BOOL bStretch,
    BOOL bHorz);

Parameters

bStretch
[in] Not used.

bHorz
[in] Not used.

Return Value

A CSize object that contains the size of the pane rectangle.

CDockablePane::CanAcceptMiniFrame

Determines whether the specified mini-frame can be docked to the pane.

virtual BOOL CanAcceptMiniFrame(CPaneFrameWnd* pMiniFrame) const;

Parameters

pMiniFrame
[in] Pointer to a CPaneFrameWnd object.

Return Value

TRUE if pMiniFrame can be docked to the pane; otherwise, FALSE.

CDockablePane::CanAcceptPane

Determines whether another pane can be docked to the current pane.

virtual BOOL CanAcceptPane(const CBasePane* pBar) const;

Parameters

pBar
[in] Specifies the pane to dock to the current pane.

Return Value

TRUE if the specified pane can be docked to this pane; otherwise, FALSE.

Remarks

The framework calls this method before a pane is docked to the current pane.

Override this function in a derived class to enable or disable docking to a specific pane.

By default, this method returns TRUE if either pBar or its parent is of type CDockablePane.

CDockablePane::CanAutoHide

Determines whether the pane can auto-hide.

virtual BOOL CanAutoHide() const;

Return Value

TRUE if the pane can auto-hide; otherwise, FALSE.

Remarks

CDockablePane::CanAutoHide returns FALSE in any of the following situations:

  • The pane has no parent.

  • The docking manager doesn't allow panes to auto-hide.

  • The pane isn't docked.

CDockablePane::CanBeAttached

Determines whether the current pane can be docked to another pane.

virtual BOOL CanBeAttached() const;

Return Value

TRUE if the dockable pane can be docked to another pane or to the main frame window; otherwise, FALSE.

Remarks

By default, this method always returns TRUE. Override this method in a derived class to enable or disable docking without calling CBasePane::EnableDocking.

CDockablePane::CDockablePane

Constructs and initializes a CDockablePane object.

CDockablePane();

Remarks

After you construct a dockable pane object, call CDockablePane::Create or CDockablePane::CreateEx to create it.

CDockablePane::ConvertToTabbedDocument

Converts one or more dockable panes to MDI tabbed documents.

virtual void ConvertToTabbedDocument(BOOL bActiveTabOnly = TRUE);

Parameters

bActiveTabOnly
[in] When you convert a CTabbedPane, specify TRUE to convert only the active tab. Specify FALSE to convert all tabs in the pane.

CDockablePane::CheckAutoHideCondition

Determines whether the docking pane is hidden (also known as autohide mode).

virtual BOOL CheckAutoHideCondition();

Return Value

TRUE if the hide condition is met; otherwise, FALSE.

Remarks

The framework uses a timer to periodically check whether to hide an autohide dockable pane. The method returns TRUE when the pane isn't active, the pane isn't being resized, and the mouse pointer isn't over the pane.

If all the previous conditions are met, the framework calls CDockablePane::Slide to hide the pane.

CDockablePane::CheckStopSlideCondition

Determines when an autohide docking pane should stop sliding.

virtual BOOL CheckStopSlideCondition(BOOL bDirection);

Parameters

bDirection
[in] TRUE if the pane is visible; FALSE if the pane is hidden.

Return Value

TRUE if the stop condition is met; otherwise, FALSE.

Remarks

When a dockable pane is set to autohide mode, the framework uses sliding effects to show or hide the pane. The framework calls this function when the pane is sliding. CheckStopSlideCondition returns TRUE when the pane is fully visible or when it's fully hidden.

Override this method in a derived class to implement custom autohide effects.

CDockablePane::CopyState

Copies the state of a dockable pane.

virtual void CopyState(CDockablePane* pOrgBar);

Parameters

pOrgBar
[in] A pointer to a dockable pane.

Remarks

CDockablePane::CopyState copies the state of pOrgBar to the current pane by calling the following methods:

CDockablePane::Create

Creates the Windows control and attaches it to the CDockablePane object.

virtual BOOL Create(
    LPCTSTR lpszCaption,
    CWnd* pParentWnd,
    const RECT& rect,
    BOOL bHasGripper,
    UINT nID,
    DWORD dwStyle,
    DWORD dwTabbedStyle = AFX_CBRS_REGULAR_TABS,
    DWORD dwControlBarStyle = AFX_DEFAULT_DOCKING_PANE_STYLE,
    CCreateContext* pContext = NULL);

virtual BOOL Create(
    LPCTSTR lpszWindowName,
    CWnd* pParentWnd,
    CSize sizeDefault,
    BOOL bHasGripper,
    UINT nID,
    DWORD dwStyle = WS_CHILD|WS_VISIBLE|CBRS_TOP|CBRS_HIDE_INPLACE,
    DWORD dwTabbedStyle = AFX_CBRS_REGULAR_TABS,
    DWORD dwControlBarStyle = AFX_DEFAULT_DOCKING_PANE_STYLE);

Parameters

lpszCaption
[in] Specifies the window name.

pParentWnd
[in, out] Specifies the parent window.

rect
[in] Specifies the size and position of the window, in client coordinates of pParentWnd.

bHasGripper
[in] TRUE to create the pane with a caption; otherwise, FALSE.

nID
[in] Specifies the ID of the child window. This value must be unique if you want to save docking state for this docking pane.

dwStyle
[in] Specifies the window style attributes.

dwTabbedStyle
[in] Specifies the tabbed style of a tabbed window that is created when the user drags a pane on the caption of this pane.

dwControlBarStyle
[in] Specifies additional style attributes.

pContext
[in, out] Specifies the create context of the window.

lpszWindowName
[in] Specifies the window name.

sizeDefault
[in] Specifies the size of the window.

Return Value

TRUE if the dockable pane is successfully created; otherwise, FALSE.

Remarks

Creates a Windows pane and attaches it to the CDockablePane object.

If the dwStyle window style has the CBRS_FLOAT_MULTI flag, the miniframe window can float with other panes in the miniframe window. By default, docking panes can only float individually.

If the dwTabbedStyle parameter has the AFX_CBRS_OUTLOOK_TABS flag specified, the pane creates Outlook-style tabbed panes when another pane is attached to this pane using the CDockablePane::AttachToTabWnd method. By default, dockable panes create regular tabbed panes of type CTabbedPane.

CDockablePane::CreateDefaultPaneDivider

Creates a default divider for the pane as it is being docked to a frame window.

static CPaneDivider* __stdcall CreateDefaultPaneDivider(
    DWORD dwAlignment,
    CWnd* pParent,
    CRuntimeClass* pSliderRTC = NULL);

Parameters

dwAlignment
[in] Specifies the side of the main frame to which the pane is being docked. If dwAlignment contains the CBRS_ALIGN_LEFT or CBRS_ALIGN_RIGHT flag, this method creates a vertical (CPaneDivider::SS_VERT) divider; otherwise, this method creates a horizontal (CPaneDivider::SS_HORZ) divider.

pParent
[in] Pointer to the parent frame.

pSliderRTC
[in] Not used.

Return Value

This method returns a pointer to the newly-created divider, or NULL if divider creation fails.

Remarks

dwAlignment can be any of the following values:

Value Description
CBRS_ALIGN_TOP The pane is being docked to the top of the client area of a frame window.
CBRS_ALIGN_BOTTOM The pane is being docked to the bottom of the client area of a frame window.
CBRS_ALIGN_LEFT The pane is being docked to the left side of the client area of a frame window.
CBRS_ALIGN_RIGHT The pane is being docked to the right side of the client area of a frame window.

CDockablePane::CreateEx

Creates the Windows control and attaches it to the CDockablePane object.

virtual BOOL CreateEx(
    DWORD dwStyleEx,
    LPCTSTR lpszCaption,
    CWnd* pParentWnd,
    const RECT& rect,
    BOOL bHasGripper,
    UINT nID,
    DWORD dwStyle,
    DWORD dwTabbedStyle = AFX_CBRS_REGULAR_TABS,
    DWORD dwControlBarStyle = AFX_DEFAULT_DOCKING_PANE_STYLE,
    CCreateContext* pContext = NULL);

Parameters

dwStyleEx
[in] Specifies the extended style attributes for the new window.

lpszCaption
[in] Specifies the window name.

pParentWnd
[in, out] Specifies the parent window.

rect
[in] Specifies the size and position of the window, in client coordinates of pParentWnd.

bHasGripper
[in] TRUE to create the pane with a caption; otherwise, FALSE.

nID
[in] Specifies the ID of the child window. This value must be unique if you want to save the docking state for this docking pane.

dwStyle
[in] Specifies the window style attributes.

dwTabbedStyle
[in] Specifies the tabbed style of a tabbed window that is created when the user drags a pane on the caption of this pane.

dwControlBarStyle
[in] Specifies the additional style attributes.

pContext
[in, out] Specifies the create context of the window.

Return Value

TRUE if the dockable pane is successfully created; otherwise, FALSE.

Remarks

Creates a Windows pane and attaches it to the CDockablePane object.

If the dwStyle window style has the CBRS_FLOAT_MULTI flag, the miniframe window can float with other panes in the miniframe window. By default, docking panes can only float individually.

If the dwTabbedStyle parameter has the AFX_CBRS_OUTLOOK_TABS flag specified, the pane creates Outlook-style tabbed panes when another pane is attached to this pane using the CDockablePane::AttachToTabWnd method. By default, dockable panes create regular tabbed panes of type CTabbedPane.

CDockablePane::CreateTabbedPane

Creates a tabbed pane from the current pane.

virtual CTabbedPane* CreateTabbedPane();

Return Value

The new tabbed pane, or NULL if the create operation failed.

Remarks

The framework calls this method when it creates a tabbed pane to replace this pane. For more information, see CDockablePane::AttachToTabWnd.

Override this method in a derived class to customize how tabbed panes are created and initialized.

The tabbed pane is created according to the runtime class information stored in the m_pTabbedControlBarRTC member, which is initialized by the CDockablePane::CreateEx method.

CDockablePane::DockPaneContainer

Docks a container to the pane.

virtual BOOL DockPaneContainer(
    CPaneContainerManager& barContainerManager,
    DWORD dwAlignment,
    AFX_DOCK_METHOD dockMethod);

Parameters

barContainerManager
[in] A reference to the container manager of the container that is being docked.

dwAlignment
[in] DWORD that specifies the side of the pane to which the container is being docked.

dockMethod
[in] Not used.

Return Value

TRUE if the container was successfully docked to the pane; otherwise, FALSE.

Remarks

dwAlignment can be any of the following values:

Value Description
CBRS_ALIGN_TOP The container is being docked to the top of the pane.
CBRS_ALIGN_BOTTOM The container is being docked to the bottom of the pane.
CBRS_ALIGN_LEFT The container is being docked to the left of the pane.
CBRS_ALIGN_RIGHT The container is being docked to the right of the pane.

CDockablePane::DockPaneStandard

Docks a pane by using outline (standard) docking.

virtual CPane* DockPaneStandard(BOOL& bWasDocked);

Parameters

bWasDocked
[in] When the method returns, this value contains TRUE if the pane was successfully docked; otherwise, it contains FALSE.

Return Value

If the pane was docked to a tabbed window, or if a tabbed window was created as a result of docking, this method returns a pointer to the tabbed window. If the pane was otherwise successfully docked, this method returns the this pointer. If docking failed, this method returns NULL.

CDockablePane::DockToRecentPos

Docks a pane to its stored docking position.

BOOL CDockablePane::DockToRecentPos();

Return Value

TRUE if the pane is successfully docked; otherwise, FALSE.

Remarks

Dockable panes store recent docking information in a CRecentDockSiteInfo object.

CDockablePane::DockToWindow

Docks one docking pane to another docking pane.

virtual BOOL DockToWindow(
    CDockablePane* pTargetWindow,
    DWORD dwAlignment,
    LPCRECT lpRect = NULL);

Parameters

pTargetWindow
[in, out] Specifies the dockable pane to dock this pane to.

dwAlignment
[in] Specifies the docking alignment for the pane. May be one of CBRS_ALIGN_LEFT, CBRS_ALIGN_TOP, CBRS_ALIGN_RIGHT, CBRS_ALIGN_BOTTOM or CBRS_ALIGN_ANY. (Defined in afxres.h.)

lpRect
[in] Specifies the docking rectangle for the pane.

Return Value

TRUE if the pane was docked successfully; otherwise, FALSE.

Remarks

Call this method to dock one pane to another pane with the alignment specified by dwAlignment.

CDockablePane::DrawCaption

Draws the caption (also called the gripper) of a docking pane.

virtual void DrawCaption(
    CDC* pDC,
    CRect rectCaption);

Parameters

pDC
[in] Represents the device context used for drawing.

rectCaption
[in] Specifies the bounding rectangle of the pane's caption.

Remarks

The framework calls this method to draw the caption of a dockable pane.

Override this method in a derived class to customize the appearance of the caption.

CDockablePane::EnableAutohideAll

Enables or disables autohide mode for this pane and for other panes in the container.

void EnableAutohideAll(BOOL bEnable = TRUE);

Parameters

bEnable
[in] TRUE to enable the autohide all feature for the dockable pane; otherwise, FALSE.

Remarks

When a user holds the Ctrl key and clicks the pin button to switch a pane to autohide mode, all other panes in the same container are also switched to autohide mode.

Call this method with bEnable set to FALSE to disable this feature for a particular pane.

CDockablePane::EnableGripper

Shows or hides the caption (also called the gripper).

virtual void EnableGripper(BOOL bEnable);

Parameters

bEnable
[in] TRUE to enable the caption; otherwise, FALSE.

Remarks

When the framework creates dockable panes, they don't have the WS_STYLE window style, even if specified. This means that the pane's caption is a non-client area that is controlled by the framework, but this area differs from the standard window caption.

You can show or hide the caption at any time. The framework hides the caption when a pane is added as a tab to a tabbed window or when a pane is floated in a miniframe window.

CDockablePane::GetAHRestoredRect

Specifies the position of the pane when in auto-hide mode.

CRect GetAHRestoredRect() const;

Return Value

A CRect object that contains the position of the pane when it is in auto-hide mode.

Remarks

CDockablePane::GetAHSlideMode

Retrieves the auto-hide slide mode for the pane.

virtual UINT GetAHSlideMode() const;

Return Value

A UINT that specifies the auto-hide slide mode for the pane. The return value can be either AFX_AHSM_MOVE or AFX_AHSM_STRETCH, but the implementation only uses AFX_AHSM_MOVE.

Remarks

CDockablePane::GetCaptionHeight

Returns the height, in pixels, of the current caption.

virtual int GetCaptionHeight() const;

Return Value

The height of the caption, in pixels.

Remarks

The caption height is 0 if the caption was hidden by the CDockablePane::EnableGripper method, or if the pane doesn't have a caption.

CDockablePane::GetDefaultPaneDivider

Returns the default pane divider for the pane's container.

CPaneDivider* GetDefaultPaneDivider() const;

Return Value

A valid CPaneDivider object if the dockable pane is docked to the main frame window, or NULL if the dockable pane isn't docked or if it's floating.

Remarks

For more information about pane dividers, see CPaneDivider Class.

CDockablePane::GetDockingStatus

Determines the ability of a pane to be docked based on the provided pointer location.

virtual AFX_CS_STATUS GetDockingStatus(
    CPoint pt,
    int nSensitivity);

Parameters

pt
[in] The location of the pointer in screen coordinates.

nSensitivity
[in] The distance, in pixels, away from the edge of a rectangle the pointer must be to enable docking.

Return Value

One of the following status values:

AFX_CS_STATUS value Meaning
CS_NOTHING The pointer isn't over a dock site. The framework doesn't dock the pane.
CS_DOCK_IMMEDIATELY The pointer is located over the dock site in immediate mode (the pane uses the DT_IMMEDIATE docking mode). The framework docks the pane immediately.
CS_DELAY_DOCK The pointer is over a dock site that is another docking pane or is an edge of the main frame. The framework docks the pane after a delay. See the Remarks section for more information about this delay.
CS_DELAY_DOCK_TO_TAB The pointer is located over a dock site that causes the pane to be docked in a tabbed window. This occurs when the pointer is located over the caption of another docking pane or over the tab area of a tabbed pane.

Remarks

The framework calls this method to handle docking of a floating pane.

For floating toolbars or docking panes that use the DT_IMMEDIATE docking mode, the framework delays the dock command to enable the user to move the window out of the client area of the parent frame before docking occurs. The length of the delay is measured in milliseconds and is controlled by the CDockingManager::m_nTimeOutBeforeToolBarDock data member.. The default value of CDockingManager::m_nTimeOutBeforeToolBarDock is 200. This behavior emulates the docking behavior of Microsoft Word 2007.

For delayed docking states (CS_DELAY_DOCK and CS_DELAY_DOCK_TO_TAB), the framework doesn't perform docking until the user releases the mouse button. If a pane uses the DT_STANDARD docking mode, the framework displays a rectangle at the projected docking location. If a pane uses the DT_SMART docking mode, the framework displays smart docking markers and semi-transparent rectangles at the projected docking location. To specify the docking mode for your pane, call the CBasePane::SetDockingMode method. For more information about smart docking, see CDockingManager::GetSmartDockingParams.

CDockablePane::GetDragSensitivity

Returns the drag sensitivity of a docking pane.

static const CSize& GetDragSensitivity();

Return Value

A CSize object that contains the width and height, in pixels, of a rectangle centered on a drag point. The drag operation doesn't begin until the mouse pointer moves outside this rectangle.

CDockablePane::GetLastPercentInPaneContainer

Retrieves the percentage of space that a pane occupies in its container ( CPaneContainer Class).

int GetLastPercentInPaneContainer() const;

Return Value

An int that specifies the percentage of space that the pane occupies in its container.

Remarks

This method is used when the container adjusts its layout.

CDockablePane::GetTabArea

Retrieves the tab area for the pane.

virtual void GetTabArea(
    CRect& rectTabAreaTop,
    CRect& rectTabAreaBottom) const;

Parameters

rectTabAreaTop
[in] GetTabArea fills this variable with the tab area if tabs are located at the top of the pane. If tabs are located at the bottom of the pane, this variable is filled with an empty rectangle.

rectTabAreaBottom
[in] GetTabArea fills this variable with the tab area if tabs are located at the bottom of the pane. If tabs are located at the top of the pane, this variable is filled with an empty rectangle.

Remarks

This method is used only in classes that are derived from CDockablePane and have tabs. For more information, see CTabbedPane::GetTabArea and CMFCOutlookBar::GetTabArea.

CDockablePane::GetTabbedPaneRTC

Returns the runtime class information about a tabbed window that is created when another pane docks to the current pane.

CRuntimeClass* GetTabbedPaneRTC() const;

Return Value

The runtime class information for the dockable pane.

Remarks

Call this method to retrieve the runtime class information for tabbed panes that are created dynamically. This can occur when a user drags one pane to the caption of another pane, or if you call the CDockablePane::AttachToTabWnd method to programmatically create a tabbed pane from two dockable panes.

You can set the runtime class information by calling the CDockablePane::SetTabbedPaneRTC method.

CDockablePane::HasAutoHideMode

Specifies whether a docking pane can be switched to autohide mode.

virtual BOOL HasAutoHideMode() const;

Return Value

TRUE if the dockable pane can be switched to autohide mode; otherwise, FALSE.

Remarks

Override this method in a derived class to disable autohide mode for a specific dockable pane.

CDockablePane::HitTest

Specifies the location in a pane where the user clicks a mouse.

virtual int HitTest(
    CPoint point,
    BOOL bDetectCaption = FALSE);

Parameters

point
[in] Specifies the point to test.

bDetectCaption
[in] TRUE if HTCAPTION should be returned if the point is on the pane's caption; otherwise, FALSE.

Return Value

One of the following values:

  • HTNOWHERE if point isn't in the dockable pane.

  • HTCLIENT if point is in the client area of the dockable pane.

  • HTCAPTION if point is in the caption area of the dockable pane.

  • AFX_HTCLOSE if point is on the close button.

  • HTMAXBUTTON if point is on the pin button.

CDockablePane::IsAutohideAllEnabled

Indicates whether the docking pane and all other panes in the container can be switched to autohide mode.

virtual BOOL IsAutohideAllEnabled() const;

Return Value

TRUE if the dockable pane, and all other panes in the container, can be switched to autohide mode; otherwise, FALSE.

Remarks

A user enables autohide mode by clicking the docking pin button while holding the Ctrl key

To enable or disable this behavior, call the CDockablePane::EnableAutohideAll method.

CDockablePane::IsAutoHideMode

Determines whether a pane is in autohide mode.

virtual BOOL IsAutoHideMode() const;

Return Value

TRUE if the dockable pane is in autohide mode; otherwise, FALSE.

CDockablePane::IsDocked

Determines whether the current pane is docked.

virtual BOOL IsDocked() const;

Return Value

TRUE if the dockable pane doesn't belong to a miniframe window or if it's floating in a miniframe window with another pane. FALSE if the pane is a child of a miniframe window and there are no other panes that belong to the miniframe window.

Remarks

To determine whether the pane is docked to the main frame window, call CDockablePane::GetDefaultPaneDivider. If the method returns a non-NULL pointer, the pane is docked at the main frame window.

CDockablePane::IsHideInAutoHideMode

Determines the behavior of a pane that is in autohide mode if it's shown (or hidden) by calling CDockablePane::ShowPane.

virtual BOOL IsHideInAutoHideMode() const;

Return Value

TRUE if the dockable pane should be hidden when in autohide mode; otherwise, FALSE.

Remarks

When a dockable pane is in autohide mode, it behaves differently when you call ShowPane to hide or show the pane. This behavior is controlled by the static member CDockablePane::m_bHideInAutoHideMode. If this member is TRUE, the dockable pane and its related autohide toolbar or autohide button is hidden or shown when you call ShowPane. Otherwise, the dockable pane is activated or deactivated, and its related autohide toolbar or autohide button is always visible.

Override this method in a derived class to change the default behavior for individual panes.

The default value for m_bHideInAutoHideMode is FALSE.

CDockablePane::IsInFloatingMultiPaneFrameWnd

Specifies whether the pane is in a multi-pane frame window ( CMultiPaneFrameWnd Class).

virtual BOOL IsInFloatingMultiPaneFrameWnd() const;

Return Value

TRUE if the pane is in a multi-pane frame window; otherwise, FALSE.

Remarks

CDockablePane::IsResizable

Specifies whether the pane is resizable.

virtual BOOL IsResizable() const;

Return Value

TRUE if the pane is resizable; otherwise, FALSE.

Remarks

By default, dockable panes are resizable. To prevent resizing, override this method in a derived class and return FALSE. Note that a FALSE value leads to a failed ASSERT in CPane::DockPane. Use CDockingManager::AddPane instead to dock a pane within a parent frame.

Panes that can't be resized can neither float nor enter auto-hide mode and are always located at the outer edge of the parent frame.

CDockablePane::IsTabLocationBottom

Specifies whether tabs are located at the top or bottom of the pane.

virtual BOOL IsTabLocationBottom() const;

Return Value

TRUE if tabs are located at the bottom of the pane; FALSE if tabs are located at the top of the pane.

Remarks

For more information, see CTabbedPane::IsTabLocationBottom.

CDockablePane::IsTracked

Specifies whether a pane is being moved by the user.

BOOL IsTracked() const;

Return Value

TRUE if the pane is being moved; otherwise, FALSE.

CDockablePane::IsVisible

Determines whether the current pane is visible.

virtual BOOL IsVisible() const;

Return Value

TRUE if the dockable pane is visible; otherwise, FALSE.

Remarks

Call this method to determine whether a dockable pane is visible. You can use this method instead of calling CWnd::IsWindowVisible or testing for the WS_VISIBLE style. The returned visibility state depends on whether autohide mode is enabled or disabled and on the value of the CDockablePane::IsHideInAutoHideMode property.

If the dockable pane is in autohide mode and IsHideInAutoHideMode returns FALSE the visibility state is always FALSE.

If the dockable pane is in autohide mode and IsHideInAutoHideMode returns TRUE the visibility state depends on the visibility state of the related autohide toolbar.

If the dockable pane isn't in autohide mode, the visibility state is determined by the CBasePane::IsVisible method.

## CDockablePane::LoadState

For internal use only. For more detail, see the source code located in the mfc folder of your Visual Studio installation. For example, %ProgramFiles(x86)%\Microsoft Visual Studio\2019\Enterprise\VC\Tools\MSVC\14.29.30133\atlmfc\src\mfc.

virtual BOOL LoadState(
   LPCTSTR lpszProfileName = NULL,
   int nIndex = -1,
   UINT uiID = (UINT) -1
);

CDockablePane::m_bDisableAnimation

Specifies whether autohide animation of the dockable pane is disabled.

AFX_IMPORT_DATA static BOOL m_bDisableAnimation;

CDockablePane::m_bHideInAutoHideMode

Determines the behavior of the pane when the pane is in autohide mode.

AFX_IMPORT_DATA static BOOL m_bHideInAutoHideMode;

Remarks

This value affects all docking panes in the application.

If you set this member to TRUE, dockable panes are hidden or shown with their related autohide toolbars and buttons when you call CDockablePane::ShowPane.

If you set this member to FALSE, dockable panes are activated or deactivated when you call CDockablePane::ShowPane.

CDockablePane::m_nSlideSteps

Specifies the animation speed of the pane when it is in autohide mode.

AFX_IMPORT_DATA static int m_nSlideSteps;

Remarks

For a faster animation effect, decrease this value. For a slower animation effect, increase this value.

CDockablePane::OnAfterChangeParent

For more detail, see the source code located in the mfc folder of your Visual Studio installation. For example, %ProgramFiles(x86)%\Microsoft Visual Studio\2019\Enterprise\VC\Tools\MSVC\14.29.30133\atlmfc\src\mfc.

virtual void OnAfterChangeParent(CWnd* pWndOldParent);

Parameters

[in] pWndOldParent\

Remarks

CDockablePane::OnAfterDockFromMiniFrame

Called by the framework when a floating docking bar docks at a frame window.

virtual void OnAfterDockFromMiniFrame();

Remarks

By default, this method does nothing.

CDockablePane::OnBeforeChangeParent

The framework calls this method before it changes the parent of the pane.

virtual void OnBeforeChangeParent(
    CWnd* pWndNewParent,
    BOOL bDelay = FALSE);

Parameters

pWndNewParent
[in] A pointer to the new parent window.

bDelay
[in] BOOL that specifies whether to delay recalculation of the docking layout if the pane is undocked. For more information, see CDockablePane::UndockPane.

Remarks

If the pane is docked and the new parent doesn't allow docking, this method undocks the pane.

If the pane is being converted to a tabbed document, this method stores its recent docking position. The framework uses the recent docking position to restore the position of the pane when it's converted back to a docked state.

CDockablePane::OnBeforeFloat

The framework calls this method before a pane transitions to a floating state.

virtual BOOL OnBeforeFloat(
    CRect& rectFloat,
    AFX_DOCK_METHOD dockMethod);

Parameters

rectFloat
[in] Specifies the position and size of the pane when it is in a floating state.

dockMethod
[in] Specifies the docking method. See CPane::DockPane for a list of possible values.

Return Value

TRUE if the pane can be floated; otherwise, FALSE.

Remarks

This method is called by the framework when a pane is about to float. You can override this method in a derived class if you want to perform any processing before the pane floats.

CDockablePane::OnPressButtons

Called when the user presses a caption button other than the AFX_HTCLOSE and AFX_HTMAXBUTTON buttons.

virtual void OnPressButtons(UINT nHit);

Parameters

nHit
[in] This parameter isn't used.

Remarks

If you add a custom button to the caption of a dockable pane, override this method to receive notifications when a user presses the button.

CDockablePane::OnSlide

Called by the framework to animate the pane when it is in autohide mode.

virtual void OnSlide(BOOL bSlideOut);

Parameters

bSlideOut
[in] TRUE to show the pane; FALSE to hide the pane.

Remarks

Override this method in a derived class to implement custom autohide effects.

CDockablePane::RemoveFromDefaultPaneDividier

The framework calls this method when a pane is being undocked.

void RemoveFromDefaultPaneDividier();

Remarks

This method sets the default pane divider to NULL and removes the pane from its container.

CDockablePane::ReplacePane

Replaces the pane with a specified pane.

BOOL ReplacePane(
    CDockablePane* pBarToReplaceWith,
    AFX_DOCK_METHOD dockMethod,
    BOOL bRegisterWithFrame = FALSE);

Parameters

pBarToReplaceWith
[in] A pointer to a dockable pane.

dockMethod
[in] Not used.

bRegisterWithFrame
[in] If TRUE, the new pane is registered with the docking manager of the parent of the old pane. The new pane is inserted at the index of the old pane in the list of panes that is maintained by the docking manager.

Return Value

TRUE if the replacement is successful; otherwise, FALSE.

CDockablePane::RestoreDefaultPaneDivider

When a pane is deserialized, the framework calls this method to restore the default pane divider.

void RestoreDefaultPaneDivider();

Remarks

The restored default pane divider replaces the current default pane divider, if it exists.

CDockablePane::SetAutoHideMode

Toggles the docking pane between visible and autohide mode.

virtual CMFCAutoHideBar* SetAutoHideMode(
    BOOL bMode,
    DWORD dwAlignment,
    CMFCAutoHideBar* pCurrAutoHideBar = NULL,
    BOOL bUseTimer = TRUE);

Parameters

bMode
[in] TRUE to enable autohide mode; FALSE to enable regular docking mode.

dwAlignment
[in] Specifies the alignment of the autohide pane to create.

pCurrAutoHideBar
[in, out] A pointer to the current autohide toolbar. Can be NULL.

bUseTimer
[in] Specifies whether to use the autohide effect when the user switches the pane to autohide mode or to hide the pane immediately.

Return Value

The autohide toolbar that was created as a result of switching to autohide mode, or NULL.

Remarks

The framework calls this method when a user clicks the pin button to switch the dockable pane to autohide mode or to regular docking mode.

Call this method to switch a dockable pane to autohide mode programmatically. The pane must be docked to the main frame window ( CDockablePane::GetDefaultPaneDivider must return a valid pointer to the CPaneDivider).

CDockablePane::SetAutoHideParents

Sets the auto-hide button and auto-hide toolbar for the pane.

void SetAutoHideParents(
    CMFCAutoHideBar* pToolBar,
    CMFCAutoHideButton* pBtn);

Parameters

pToolBar
[in] Pointer to an auto-hide toolbar.

pBtn
[in] Pointer to an auto-hide button.

CDockablePane::SetLastPercentInPaneContainer

Sets the percentage of space that a pane occupies in its container.

void SetLastPercentInPaneContainer(int n);

Parameters

n
[in] An int that specifies the percentage of space that the pane occupies in its container.

Remarks

The framework adjusts the pane to use the new value when the layout is recalculated.

CDockablePane::SetRestoredDefaultPaneDivider

Sets the restored default pane divider.

void SetRestoredDefaultPaneDivider(HWND hRestoredSlider);

Parameters

hRestoredSlider
[in] A handle to a pane divider (slider).

Remarks

A restored default pane divider is obtained when a pane is deserialized. For more information, see CDockablePane::RestoreDefaultPaneDivider.

CDockablePane::SetTabbedPaneRTC

Sets the runtime class information for a tabbed window that is created when two panes dock together.

void SetTabbedPaneRTC(CRuntimeClass* pRTC);

Parameters

pRTC
[in] The runtime class information for the tabbed pane.

Remarks

Call this method to set the runtime class information for tabbed panes that are created dynamically. This can occur when a user drags one pane to the caption of another pane, or if you call the CDockablePane::AttachToTabWnd method to programmatically create a tabbed pane from two dockable panes.

The default runtime class is set according to the dwTabbedStyle parameter of CDockablePane::Create and CDockablePane::CreateEx. To customize the new tabbed panes, derive your class from one of the following classes:

Then, call this method with the pointer to its runtime class information.

CDockablePane::ShowPane

Shows or hides a pane.

virtual void ShowPane(
    BOOL bShow,
    BOOL bDelay,
    BOOL bActivate);

Parameters

bShow
[in] TRUE to show the pane; FALSE to hide the pane.

bDelay
[in] TRUE to delay adjusting the docking layout; FALSE to adjust the docking layout immediately.

bActivate
[in] TRUE to activate the pane when shown; otherwise, FALSE.

Remarks

Call this method instead of the CWnd::ShowWindow when showing or hiding dockable panes.

CDockablePane::Slide

Animates a pane that is in autohide mode.

virtual void Slide(
    BOOL bSlideOut,
    BOOL bUseTimer = TRUE);

Parameters

bSlideOut
[in] TRUE to show the pane; FALSE to hide the pane.

bUseTimer
[in] TRUE to show or hide the pane with the autohide effect; FALSE to show or hide the pane immediately.

Remarks

The framework calls this method to animate a pane that is in autohide mode.

This method uses the CDockablePane::m_nSlideDefaultTimeOut value to determine the time out for the slide effect. The default value for the time out is 1. If you customize the autohide algorithm, modify this member to change the time out.

CDockablePane::ToggleAutoHide

Toggles the pane between always visible and auto-hide mode.

virtual void ToggleAutoHide();

Remarks

This method toggles auto-hide mode for the pane by calling CDockablePane::SetAutoHideMode.

CDockablePane::UndockPane

Undocks a pane from either the main frame window or a miniframe window container.

virtual void UndockPane(BOOL bDelay = FALSE);

Parameters

bDelay
[in] TRUE to delay calculating the docking layout; FALSE to recalculate the docking layout immediately.

Remarks

Call this method to undock a pane from the main frame window or from a multi-miniframe window container (a pane that is floating in a single miniframe window with other panes).

You must undock a pane before you perform any external operation that isn't performed by the CDockingManager. For example, you must undock a pane to move it programmatically from one location to another.

The framework automatically undocks panes before they're destroyed.

See also

Hierarchy Chart
Classes
CPane Class