CPane Class

Article
08/03/2021

The CPane class is an enhancement of the CControlBar Class. If you are upgrading an existing MFC project, replace all occurrences of CControlBar with CPane.

Syntax

class CPane : public CBasePane

Members

Public Constructors

Name	Description
`CPane::~CPane`	Destructor.

Public Methods

Name	Description
CPane::AdjustSizeImmediate	Immediately recalculates the layout of a pane.
CPane::AllocElements	Allocates storage for internal use.
CPane::AllowShowOnPaneMenu	Specifies whether the pane is listed in the runtime-generated list of panes for the application.
CPane::CalcAvailableSize	Calculates the difference in size between a specified rectangle and the current window rectangle.
CPane::CalcInsideRect	Calculates the inside rectangle of a pane, taking into account the borders and grippers.
CPane::CalcRecentDockedRect	Calculates the recently docked rectangle.
CPane::CalcSize	Calculates the size of the pane.
CPane::CanBeDocked	Determines whether the pane can be docked at the specified base pane.
CPane::CanBeTabbedDocument	Determines whether the pane can be converted to a tabbed document.
CPane::ConvertToTabbedDocument	Converts a dockable pane to a tabbed document.
CPane::CopyState	Copies the state of a pane. (Overrides CBasePane::CopyState.)
CPane::Create	Creates a control bar and attaches it to the `CPane` object.
CPane::CreateDefaultMiniframe	Creates a mini-frame window for a floating pane.
CPane::CreateEx	Creates a control bar and attaches it to the `CPane` object.
`CPane::CreateObject`	Used by the framework to create a dynamic instance of this class type.
CPane::DockByMouse	Docks a pane by using the mouse docking method.
CPane::DockPane	Docks the floating pane to a base pane.
CPane::DockPaneStandard	Docks a pane by using outline (standard) docking.
CPane::DockToFrameWindow	Docks a dockable pane to a frame. (Overrides `CBasePane::DockToFrameWindow`.)
CPane::DoesAllowSiblingBars	Indicates whether you can dock another pane at the same row where the current pane is docked.
CPane::FloatPane	Floats the pane.
CPane::GetAvailableExpandSize	Returns the amount, in pixels, that the pane can expand.
CPane::GetAvailableStretchSize	Returns the amount, in pixels, that the pane can shrink.
CPane::GetBorders	Returns the width of the borders of the pane.
CPane::GetClientHotSpot	Returns the hot spot for the pane.
CPane::GetDockSiteRow	Returns the dock row in which the pane is docked.
CPane::GetExclusiveRowMode	Determines whether the pane is in exclusive row mode.
CPane::GetHotSpot	Returns the hot spot that is stored in an underlying `CMFCDragFrameImpl` object.
CPane::GetMinSize	Retrieves the minimum allowed size for the pane.
CPane::GetPaneName	Retrieves the title for the pane.
`CPane::GetResizeStep`	Used internally.
`CPane::GetThisClass`	Used by the framework to obtain a pointer to the CRuntimeClass object that is associated with this class type.
CPane::GetVirtualRect	Retrieves the virtual rectangle of the pane.
CPane::IsChangeState	As the pane is being moved, this method analyzes the position of the pane relative to other panes, dock rows, and mini-frame windows, and returns the appropriate AFX_CS_STATUS value.
CPane::IsDragMode	Specifies whether the pane is being dragged.
CPane::IsInFloatingMultiPaneFrameWnd	Specifies whether the pane is in a multi-pane frame window. (Overrides `CBasePane::IsInFloatingMultiPaneFrameWnd`.)
CPane::IsLeftOf	Determines whether the pane is left of (or above) the specified rectangle.
CPane::IsResizable	Determines whether the pane can be resized. (Overrides CBasePane::IsResizable.)
CPane::IsTabbed	Determines whether the pane has been inserted in the tab control of a tabbed window. (Overrides CBasePane::IsTabbed.)
CPane::LoadState	Loads the state of the pane from the registry. (Overrides CBasePane::LoadState.)
CPane::MoveByAlignment	Moves the pane and the virtual rectangle by the specified amount.
CPane::MovePane	Moves the pane to the specified rectangle.
CPane::OnAfterChangeParent	Called by the framework when the parent of a pane has changed.
CPane::OnBeforeChangeParent	Called by the framework when the parent of the pane is about to change.
CPane::OnPressCloseButton	Called by the framework when the user chooses the Close button on the caption for the pane.
`CPane::OnProcessDblClk`	Used internally.
CPane::OnShowControlBarMenu	Called by the framework when a special pane menu is about to be displayed.
CPane::OnShowControlBarMenu	Called by the framework when a special pane menu is about to be displayed.
`CPane::PrepareToDock`	Used internally.
CPane::RecalcLayout	Recalculates layout information for the pane. (Overrides CBasePane::RecalcLayout.)
CPane::SaveState	Saves the state of the pane to the registry. (Overrides CBasePane::SaveState.)
CPane::SetActiveInGroup	Flags a pane as active.
CPane::SetBorders	Sets the border values of the pane.
CPane::SetClientHotSpot	Sets the hot spot for the pane.
CPane::SetDockState	Restores docking state information for the pane.
CPane::SetExclusiveRowMode	Enables or disables the exclusive row mode.
CPane::SetMiniFrameRTC	Sets the runtime class information for the default mini-frame window.
CPane::SetMinSize	Sets the minimum allowed size for the pane.
CPane::SetVirtualRect	Sets the virtual rectangle of the pane.
CPane::StretchPaneDeferWndPos	Stretches the pane vertically or horizontally based on docking style.
CPane::ToggleAutoHide	Toggles auto-hide mode.
CPane::UndockPane	Removes the pane from the dock site, default slider, or mini-frame window where it is currently docked. (Overrides CBasePane::UndockPane.)
CPane::UpdateVirtualRect	Updates the virtual rectangle.

Protected Methods

Name	Description
CPane::OnAfterDock	Called by the framework when a pane has been docked.
CPane::OnAfterFloat	Called by the framework when a pane has been floated.
CPane::OnBeforeDock	Called by the framework when the pane is about to be docked.
CPane::OnBeforeFloat	Called by the framework when a pane is about to be floated.

Data Members

Name	Description
CPane::m_bHandleMinSize	Enables consistent handling of the minimal size for panes.
CPane::m_recentDockInfo	Contains recent docking information.

Remarks

Typically, CPane objects are not instantiated directly. If you require a pane that has docking functionality, derive your object from CDockablePane. If you require toolbar functionality, derive your object from CMFCToolBar.

When you derive a class from CPane, it can be docked in a CDockSite and it can be floated in a CPaneFrameWnd.

Inheritance Hierarchy

Requirements

Header: afxPane.h

CPane::AdjustSizeImmediate

Immediately recalculates the layout of a pane.

virtual void AdjustSizeImmediate(BOOL bRecalcLayout = TRUE);

Parameters

bRecalcLayout
[in] TRUE to automatically recalculate the layout of the pane; otherwise, FALSE.

Remarks

Call this method when you dynamically change the layout of a pane. For example, you may want to call this method when you hide or show toolbar buttons.

CPane::AllocElements

Allocates storage for internal use.

BOOL AllocElements(
    int nElements,
    int cbElement);

Parameters

nElements
[in] The number of elements for which to allocate storage.

cbElement
[in] The size, in bytes, of an element.

Return Value

FALSE if memory allocation fails; otherwise, TRUE.

CPane::AllowShowOnPaneMenu

Specifies whether the pane is listed in the runtime-generated list of panes for the application.

virtual BOOL AllowShowOnPaneMenu() const;

Return Value

TRUE if the pane is displayed in the list; otherwise, FALSE. The base implementation always returns TRUE.

Remarks

The AppWizard-generated application contains a menu option that lists panes that it contains. This method determines whether the pane is displayed in the list.

CPane::CalcAvailableSize

Calculates the difference in size between a specified rectangle and the current window rectangle.

virtual CSize CalcAvailableSize(CRect rectRequired);

Parameters

rectRequired
[in] The required rectangle.

Return Value

The difference in width and height between rectRequired and the current window rectangle.

CPane::CalcInsideRect

Calculates the inside rectangle of a pane, including the borders and grippers.

void CalcInsideRect(
    CRect& rect,
    BOOL bHorz) const;

Parameters

rect
[out] Contains the size and offset of the client area of the pane.

bHorz
[in] TRUE if the pane is oriented horizontally; otherwise, FALSE.

Remarks

This method is called by the framework when it has to recalculate the layout for a pane. The rect parameter is filled with the size and offset of the client area of the pane. This includes its borders and grippers.

CPane::CalcRecentDockedRect

Calculates the recently docked rectangle.

void CalcRecentDockedRect();

Remarks

This method updates CPane::m_recentDockInfo.

CPane::CalcSize

Calculates the size of the pane.

virtual CSize CalcSize(BOOL bVertDock);

Parameters

bVertDock
[in] TRUE if the pane is being docked vertically, FALSE otherwise.

Return Value

The default implementation of this method returns a size of (0, 0).

Remarks

Derived classes should override this method.

CPane::CanBeDocked

Determines if the pane can be docked at the specified base pane.

virtual BOOL CanBeDocked(CBasePane* pDockBar) const;

Parameters

pDockBar
[in] Specifies the pane where this pane is to be docked.

Return Value

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

Remarks

This method is usually called by the framework to determine whether a pane can be docked at the specified docking pane. To determine whether the pane can be docked, the method evaluates the pane's currently enabled docking alignment.

You enable docking to the various sides of the frame window by calling CBasePane::EnableDocking.

CPane::CanBeTabbedDocument

Determines if the pane can be converted to a tabbed document.

virtual BOOL CanBeTabbedDocument() const;

Return Value

TRUE if the pane can be converted to a tabbed document; otherwise, FALSE.

Remarks

Override this method in a derived class and return FALSE if you want to prevent a pane from being converted to a tabbed document. A tabbed document will not be listed in the Window Position menu.

CPane::ConvertToTabbedDocument

Converts a dockable pane to a tabbed document.

virtual void ConvertToTabbedDocument(BOOL bActiveTabOnly = TRUE);

Parameters

bActiveTabOnly
[in] Not used in CPane::ConvertToTabbedDocument.

Remarks

Only dockable panes can be converted to tabbed documents. For information, see CDockablePane::ConvertToTabbedDocument.

CPane::CopyState

Copies the state of a pane.

virtual void CopyState(CPane* pOrgBar);

Parameters

pOrgBar
[in] A pointer to a pane.

Remarks

This method copies the state of pOrgBar to the current pane.

CPane::Create

Creates a control bar and attaches it to the CPane object.

virtual BOOL Create(
    LPCTSTR lpszClassName,
    DWORD dwStyle,
    const RECT& rect,
    CWnd* pParentWnd,
    UINT nID,
    DWORD dwControlBarStyle = AFX_DEFAULT_PANE_STYLE,
    CCreateContext* pContext = NULL);

Parameters

lpszClassName
[in] Specifies the name of the Windows class.

dwStyle
[in] Specifies the window style attributes. For more information, see Window Styles.

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

pParentWnd
[in, out] Specifies the parent window of this pane.

nID
[in] Specifies the ID of the pane.

dwControlBarStyle
[in] Specifies the style for the pane. For more information, see CBasePane::CreateEx.

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

Return Value

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

Remarks

This method creates a Windows pane and attaches it to the CPane object.

If you have not explicitly initialized CPane::m_recentDockInfo before you call Create, the parameter rect will be used as the rectangle when floating or docking the pane.

CPane::CreateDefaultMiniframe

Creates a mini-frame window for a floating pane.

virtual CPaneFrameWnd* CreateDefaultMiniframe(CRect rectInitial);

Parameters

rectInitial
[in] Specifies the initial size and position, in screen coordinates, of the mini-frame window to create.

Return Value

The newly created mini-frame window.

Remarks

This method is called by the framework to create a mini-frame window when a pane is floated. The mini-frame window can be of type CPaneFrameWnd or of type CMultiPaneFrameWnd. A multi mini-frame window is created if the pane has the AFX_CBRS_FLOAT_MULTI style.

The runtime class information for the mini-frame window is stored in the CPane::m_pMiniFrameRTC member. You can use a derived class to set this member if you decide to create customized mini-frame windows.

CPane::CreateEx

Creates a control bar and attaches it to the CPane object.

virtual BOOL CreateEx(
    DWORD dwStyleEx,
    LPCTSTR lpszClassName,
    DWORD dwStyle,
    const RECT& rect,
    CWnd* pParentWnd,
    UINT nID,
    DWORD dwControlBarStyle = AFX_DEFAULT_PANE_STYLE,
    CCreateContext* pContext = NULL);

Parameters

dwStyleEx
[in] Specifies extended window style attributes. For more information, see Extended Window Styles.

lpszClassName
[in] Specifies the name of the Windows class.

dwStyle
[in] Specifies window style attributes. For more information, see Window Styles.

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

pParentWnd
[in, out] Specifies the parent window of this pane.

nID
[in] Specifies the ID of the pane.

dwControlBarStyle
[in] Specifies the style for the pane. For more information, see CBasePane::CreateEx.

pContext
[in, out] Specifies the create context for the pane.

Return Value

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

Remarks

This method creates a Windows pane and attaches it to the CPane object.

If you have not explicitly initialized CPane::m_recentDockInfo before you call CreateEx, the parameter rect will be used as the rectangle when floating or docking the pane.

CPane::DockByMouse

Docks a pane by using the mouse.

virtual BOOL DockByMouse(CBasePane* pDockBar);

Parameters

pDockBar
[in] Specifies the base pane to which to dock this pane.

Return Value

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

CPane::DockPane

Docks the floating pane to a base pane.

virtual BOOL DockPane(
    CBasePane* pDockBar,
    LPCRECT lpRect,
    AFX_DOCK_METHOD dockMethod);

Parameters

pDockBar
[in, out] Specifies the base pane to dock this pane to.

lpRect
[in] Specifies the rectangle on the base pane where this pane is to be docked.

dockMethod
[in] Specifies the docking method to use. Available options are as follows:

Option	Description
DM_UNKNOWN	The framework uses this option when the docking method is unknown. The pane does not store its most recent floating position. You can also use this option to programmatically dock a pane when you do not have to store the recent floating position.
DM_MOUSE	Used internally.
DM_DBL_CLICK	This option is used when the gripper is double-clicked. The pane is repositioned at its most recent docking position. If the pane is undocked by double-clicking, the pane is repositioned at its most recent floating position.
DM_SHOW	This option can be used to programmatically dock the pane. The pane stores its most recent floating position.
DM_RECT	The pane is docked in the region that is specified by lpRect.
DM_STANDARD	When you use this option, the framework draws the pane as an outline frame while it is being moved.

Return Value

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

Remarks

This method docks the pane to the base pane that is specified by the pDockBar parameter. You must first enable docking by calling CBasePane::EnableDocking.

CPane::DockPaneStandard

Docks a pane by using outline (standard) docking.

virtual CPane* DockPaneStandard(BOOL& bWasDocked);

Parameters

bWasDocked
[in] TRUE if the pane was successfully docked; otherwise, FALSE.

Return Value

This method always returns the this pointer.

Remarks

This method is used only for panes that are derived from the CDockablePane Class. For more information, see CDockablePane::DockPaneStandard.

CPane::DockToFrameWindow

Docks a dockable pane to a frame.

virtual BOOL DockToFrameWindow(
    DWORD dwAlignment,
    LPCRECT lpRect = NULL,
    DWORD dwDockFlags = DT_DOCK_LAST,
    CBasePane* pRelativeBar = NULL,
    int nRelativeIndex = -1,
    BOOL bOuterEdge = FALSE);

Parameters

dwAlignment
[in] The side of the parent frame that you want to dock the pane to.

lpRect
[in] The specified size.

dwDockFlags
[in] Ignored.

pRelativeBar
[in] Ignored.

nRelativeIndex
[in] Ignored.

bOuterEdge
[in] If TRUE and there are other dockable panes at the side that are specified by dwAlignment, the pane is docked outside the other panes, closer to the edge of the parent frame. If FALSE, the pane is docked closer to the center of the client area.

Return Value

FALSE if a pane divider ( CPaneDivider Class) cannot be created; otherwise, TRUE.

Remarks

CPane::DoesAllowSiblingBars

Indicates whether you can dock another pane at the same row where the current pane is docked.

virtual BOOL DoesAllowSiblingBars() const;

Return Value

TRUE if this pane can dock to another pane on the same row as itself; otherwise, FALSE.

Remarks

You can enable or disable this behavior by calling CPane::SetExclusiveRowMode.

By default, toolbars have exclusive row mode disabled and the menu bar has exclusive row mode enabled.

CPane::FloatPane

Floats the pane.

virtual BOOL FloatPane(
    CRect rectFloat,
    AFX_DOCK_METHOD dockMethod = DM_UNKNOWN,
    bool bShow = true);

Parameters

rectFloat
[in] Specifies the location, in screen coordinates, to position the pane when it is floated.

dockMethod
[in] Specifies the docking method to use when the pane is floated. For a list of possible values, see CPane::DockPane.

bShow
[in] TRUE to show the pane when floated; otherwise, FALSE.

Return Value

TRUE if the pane was floated successfully or if the pane cannot be floated because CBasePane::CanFloat returns FALSE; otherwise, FALSE.

Remarks

Call this method to float the pane at the position that is specified by the rectFloat parameter. This method automatically creates a parent mini-frame window for the pane.

CPane::GetAvailableExpandSize

Returns the amount, in pixels, that the pane can expand.

virtual int GetAvailableExpandSize() const;

Return Value

If the pane is docked horizontally, the return value is the available width; otherwise, the return value is the available height.

Remarks

CPane::GetAvailableStretchSize

Returns the amount, in pixels, that the pane can shrink.

virtual int GetAvailableStretchSize() const;

Return Value

The amount, in pixels, that the pane can shrink. If the pane is docked horizontally, this amount is the available width; otherwise, it is the available height.

Remarks

The available stretch size is calculated by subtracting the minimum allowed size for the pane ( CPane::GetMinSize) from the current size ( CWnd::GetWindowRect).

CPane::GetBorders

Returns the width of the borders of the pane.

CRect GetBorders() const;

Return Value

A CRect object that contains the current width, in pixels, of each side of the pane. For example, the value of the left member of the CRect object is the width of the left border.

Remarks

To set the size of the borders, call CPane::SetBorders.

CPane::GetClientHotSpot

Returns the hot spot for the pane.

CPoint GetClientHotSpot() const;

Return Value

Remarks

The hot spot is the point on the pane that the user selects and holds to move the pane. A hot spot is used for smooth animation when the pane is moved from a docked position.

CPane::GetDockSiteRow

Returns the dock row ( CDockingPanesRow Class) in which the pane is docked.

CDockingPanesRow* GetDockSiteRow() const;

Return Value

A CDockingPanesRow* that points to the dock row in which the pane is docked, or NULL if the pane is not docked.

CPane::GetExclusiveRowMode

Determines if the pane is in exclusive row mode.

virtual BOOL GetExclusiveRowMode() const;

Return Value

TRUE if the pane is in exclusive row mode; otherwise, FALSE.

Remarks

For more information about exclusive row mode, see CPane::SetExclusiveRowMode.

CPane::GetHotSpot

Returns the hot spot that is stored in an underlying CMFCDragFrameImpl object.

CPoint GetHotSpot() const;

Return Value

Remarks

The CPane class contains a CMFCDragFrameImpl object, m_dragFrameImpl, that is responsible for drawing the rectangle that appears when the user moves a pane in the standard docking mode. The hot spot is used to draw the rectangle relative to the current mouse position as the user moves the pane.

CPane::GetMinSize

Retrieves the minimum allowed size for the pane.

virtual void GetMinSize(CSize& size) const;

Parameters

size
[out] A CSize object that is filled with the minimum allowed size.

Remarks

CPane::GetPaneName

Retrieves the title for the pane.

virtual void GetPaneName(CString& strName) const;

Parameters

strName
[out] A CString object that is filled with the caption name.

Remarks

The pane title is displayed in the caption area when the pane is docked or floating. If the pane is part of a tabbed group, the title is displayed in the tab area. If the pane is in auto-hide mode, the title is displayed on a CMFCAutoHideButton.

CPane::GetVirtualRect

Retrieves the virtual rectangle of the pane.

void GetVirtualRect(CRect& rectVirtual) const;

Parameters

rectVirtual
[out] A CRect object that is filled with the virtual rectangle.

Remarks

When a pane is moved, the framework stores the original position of the pane in a virtual rectangle. The framework can use the virtual rectangle to restore the original position of the pane.

Do not call methods that are related to virtual rectangles unless you are moving panes programmatically.

CPane::IsChangeState

As the pane is being moved, this method analyzes its position relative to other panes, dock rows, and mini-frame windows, and returns the appropriate AFX_CS_STATUS value.

virtual AFX_CS_STATUS IsChangeState(
    int nOffset,
    CBasePane** ppTargetBar) const;

Parameters

nOffset
[in] Specifies docking sensitivity. For example, a pane that is moved within nOffset pixels from a dock row will be docked.

ppTargetBar
[in] When the method returns, ppTargetBar contains either a pointer to the object to which the current pane should be docked, or NULL if no docking should occur.

Return Value

One of the following AFX_CS_STATUS values:

Value	Description
CS_NOTHING	The pane is not near a dock site. The framework does not dock the pane.
CS_DOCK_IMMEDIATELY	The pane is over a dock site, and the DT_IMMEDIATE style is enabled. The framework docks the pane immediately.
CS_DELAY_DOCK	The pane is over a dock site that is either another docking pane or an edge of the main frame. The framework docks the pane when the user releases the move.
CS_DELAY_DOCK_TO_TAB	The pane is over a dock site that causes the pane to be docked in a tabbed window. This occurs when the pane is either over the caption of another docking pane or over the tab area of a tabbed pane. The framework docks the pane when the user releases the move.

CPane::IsDragMode

Specifies whether the pane is being moved.

virtual BOOL IsDragMode() const;

Return Value

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

Remarks

CPane::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

Only dockable panes can float in a multi-pane frame window. Therefore, CPane::IsInFloatingMultiPaneFrameWnd always returns FALSE.

CPane::IsLeftOf

Determines whether the pane is left of (or above) the specified rectangle.

bool IsLeftOf(
    CRect rect,
    bool bWindowRect = true) const;

Parameters

rect
[in] A CRect object that is used for comparison.

bWindowRect
[in] If TRUE, rect is assumed to contain screen coordinates; if FALSE, rect is assumed to contain client coordinates.

Return Value

Remarks

If the pane is docked horizontally, this method checks whether its location is left of rect. Otherwise, this method checks whether the location is above rect.

CPane::IsResizable

Specifies whether the pane is resizable.

virtual BOOL IsResizable() const;

Return Value

TRUE if the pane is resizable; otherwise, FALSE.

Remarks

Base CPane objects are not resizable.

The docking manager uses the resizable flag to determine pane layout. Non-resizable panes are always located at the outer edges of the parent frame.

Non-resizable panes cannot reside in docking containers.

CPane::IsTabbed

Determines whether the pane has been inserted into the tab control of a tabbed window.

virtual BOOL IsTabbed() const;

Return Value

TRUE if the pane is tabbed; otherwise, FALSE.

Remarks

The tabbed state is treated separately from the floating, docked, and auto-hide states.

CPane::LoadState

Loads the state of the pane from the registry.

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

Parameters

lpszProfileName
[in] Profile name.

nIndex
[in] Profile index.

uiID
[in] Pane ID.

Return Value

TRUE if the pane state was loaded successfully; otherwise, FALSE.

Remarks

The framework calls this method to load the pane state from the registry. Override it in a derived class to load additional information that is saved by CPane::SaveState.

When you override this method, also call the base method, and return FALSE if the base method returns FALSE.

CPane::m_bHandleMinSize

Enables consistent handling of minimum pane sizes.

AFX_IMPORT_DATA static BOOL m_bHandleMinSize;

Remarks

If one or more docking panes in your application override GetMinSize, or if your application calls SetMinSize, you may want to set this static member to TRUE in order to enable the framework to consistently handle how panes are sized.

If this value is set to TRUE, all panes whose size should be reduced below their minimum size are clipped, not stretched. Because the framework uses window regions for pane sizing purposes, do not change the size of the window region for docking panes if this value is set to TRUE.

CPane::m_recentDockInfo

Contains recent docking information.

CRecentDockSiteInfo m_recentDockInfo;

Remarks

The framework stores the latest docking state information for the pane in this member.

CPane::MoveByAlignment

Moves the pane and the virtual rectangle by the specified amount.

BOOL MoveByAlignment(
    DWORD dwAlignment,
    int nOffset);

Parameters

dwAlignment
[in] Specifies pane alignment.

nOffset
[in] The amount, in pixels, by which to move the pane and the virtual rectangle.

Return Value

Remarks

dwAlignment can be any of the following values:

Value	Description
CBRS_ALIGN_TOP	Enables the pane to be docked to the top of the client area of a frame window.
CBRS_ALIGN_BOTTOM	Enables the pane to be docked to the bottom of the client area of a frame window.
CBRS_ALIGN_LEFT	Enables the pane to be docked to the left side of the client area of a frame window.
CBRS_ALIGN_RIGHT	Enables the pane to be docked to the right side of the client area of a frame window.
CBRS_ALIGN_ANY	Enables the pane to be docked to any side of the client area of a frame window.

If dwAlignment contains the CBRS_ALIGN_LEFT or CBRS_ALIGN_RIGHT flag, the pane and virtual rectangle are moved horizontally; otherwise, if dwAlignment contains the CBRS_ALIGN_TOP or CBRS_ALIGN_BOTTOM flag, the pane and virtual rectangle are moved vertically.

CPane::MovePane

Moves the pane to the specified rectangle.

virtual CSize MovePane(
    CRect rectNew,
    BOOL bForceMove,
    HDWP& hdwp);

Parameters

rectNew
[in] Specifies the new rectangle for the pane.

bForceMove
[in] If TRUE, this method ignores the minimum allowed pane size ( CPane::GetMinSize); otherwise, the pane is adjusted, if necessary, to ensure that it is at least the minimum allowed size.

hdwp
[in] Not used.

Return Value

A CSize object that contains the differences in width and height between the new and old rectangles (old rectangle - rectNew).

Remarks

This method is used only for dockable panes.

CPane::OnAfterChangeParent

Called by the framework when the parent of a pane has changed.

virtual void OnAfterChangeParent(CWnd* pWndOldParent);

Parameters

pWndOldParent
[in, out] The pane's previous parent window.

Remarks

This method is called by the framework when the parent of a pane has changed because of a docking or floating operation.

CPane::OnAfterDock

Called by the framework when a pane has been docked.

virtual void OnAfterDock(
    CBasePane* pBar,
    LPCRECT lpRect,
    AFX_DOCK_METHOD dockMethod);

Parameters

pBar
[in] This parameter is not used.

lpRect
[in] This parameter is not used.

dockMethod
[in] This parameter is not used.

CPane::OnAfterFloat

Called by the framework after a pane floats.

virtual void OnAfterFloat();

Remarks

You can override this method in a derived class if you want to perform any processing after a pane floats.

CPane::OnBeforeChangeParent

Called by the framework when the parent of the pane is about to change.

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

Parameters

pWndNewParent
[in, out] Specifies the new parent window.

bDelay
[in] TRUE to delay the global docking layout adjustment; otherwise, FALSE.

Remarks

This method is called by the framework when the parent of the pane is about to change because the pane is being docked or floated.

By default, the pane is unregistered with the docking pane by calling CDockSite::RemovePane.

CPane::OnBeforeDock

Called by the framework when the pane is about to dock.

virtual BOOL OnBeforeDock(
    CBasePane** ppDockBar,
    LPCRECT lpRect,
    AFX_DOCK_METHOD dockMethod);

Parameters

ppDockBar
[in, out] Specifies the pane that this pane is docking to.

lpRect
[in] Specifies the docking rectangle.

dockMethod
[in] Specifies the docking method.

Return Value

TRUE if the pane can be docked. If the function returns FALSE, the docking operation will be aborted.

Remarks

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

CPane::OnBeforeFloat

Called by the framework when a pane is about to float.

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 of the pane.

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 finally floats.

CPane::OnPressCloseButton

Called by the framework when the user presses the close button on the caption for the pane.

virtual void OnPressCloseButton();

Remarks

This method is called by the framework when a user presses the Close button on the pane's caption. To receive notifications about the Close event, you can override this method in a derived class.

CPane::OnShowControlBarMenu

Called by the framework when a special pane menu is about to be displayed.

virtual BOOL OnShowControlBarMenu(CPoint point);

Parameters

point
[in] Specifies the menu location.

Return Value

TRUE if the menu can be displayed; otherwise, FALSE.

Remarks

The menu contains several items that enable you to specify the pane's behavior, namely: Floating, Docking, AutoHide, and Hide. You can enable this menu for all panes by calling CDockingManager::EnableDockSiteMenu.

CPane::RecalcLayout

Recalculates layout information for the pane.

virtual void RecalcLayout();

Remarks

If the pane is docked, this method updates the virtual rectangle for the pane by setting its size to the current size of the pane.

If the pane is floating, this method notifies the parent mini-frame to adjust the size of the pane to the size of the mini-frame. The framework ensures that the mini-frame is at least the minimum allowed size for the pane ( CPane::GetMinSize) and resizes the mini-frame if necessary.

CPane::SaveState

Saves the state of the pane to the registry.

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

Parameters

lpszProfileName
[in] Profile name.

nIndex
[in] Profile index.

uiID
[in] Pane ID.

Return Value

TRUE if the state was saved successfully; otherwise, FALSE.

Remarks

The framework calls this method when it saves the state of the pane to the registry. Override SaveState in a derived class to store additional information.

When you override this method, also call the base method, and return FALSE if the base method returns FALSE.

CPane::SetActiveInGroup

Flags a pane as active.

virtual void SetActiveInGroup(BOOL bActive);

Parameters

bActive
[in] A BOOL that specifies whether the pane is flagged as active.

Remarks

When a dockable pane is shown or an auto-hide button is chosen, the corresponding auto-hide pane is marked as active.

The appearance of an auto-hide button that is associated with the pane is based on two factors. If the pane is active, and the static BOOL CMFCAutoHideButton::m_bOverlappingTabs is TRUE, the framework displays the auto-hide button as an icon and a label. For an inactive pane, the framework displays only the auto-hide icon.

If CMFCAutoHideButton::m_bOverlappingTabs is FALSE, or if the pane is not located in a group, the framework displays the associated auto-hide button as an icon and a label.

CPane::SetBorders

Sets the border values of the pane.

void SetBorders(
    int cxLeft = 0,
    int cyTop = 0,
    int cxRight = 0,
    int cyBottom = 0);

void SetBorders(LPCRECT lpRect);

Parameters

cxLeft
[in] Specifies the width, in pixels, of the left border of the pane.

cyTop
[in] Specifies the width, in pixels, of the top border of the pane.

cxRight
[in] Specifies the width, in pixels, of the right border of the pane.

cyBottom
[in] Specifies the width, in pixels, of the bottom border of the pane.

lpRect
[in] A CRect object that contains the width, in pixels, of each border of the pane.

Remarks

Call this function to set the sizes of the pane's borders.

CPane::SetClientHotSpot

Sets the hot spot for the pane.

void SetClientHotSpot(const CPoint& ptNew);

Parameters

ptNew
[in] A CPoint object that specifies the new hot spot.

Remarks

The hot spot is the point on the pane that the user selects and holds to move the pane. A hot spot is used for smooth animation when the pane is dragged from a docked position.

CPane::SetDockState

Restores docking state information for the pane.

virtual void SetDockState(CDockingManager* pDockManager);

Parameters

pDockManager
[in] Pointer to the docking manager for the main frame window.

Remarks

This method is called by the framework to restore recent docking state information for the pane. A pane stores recent docking state information in CPane::m_recentDockInfo. For more information, see the CRecentDockSiteInfo Class.

You can also call this method to set the docking state when you load pane information from an external source.

CPane::SetExclusiveRowMode

Enables or disables the exclusive row mode.

virtual void SetExclusiveRowMode(BOOL bExclusive = TRUE);

Parameters

bExclusive
[in] TRUE to enable exclusive row mode; otherwise, FALSE.

Remarks

Call this method to enable or disable exclusive row mode. When a pane is in exclusive row mode, it cannot share the same row with any other toolbars.

By default, all toolbars have exclusive row mode disabled and the menu bar has exclusive row mode enabled.

CPane::SetMinSize

Sets the minimum allowed size for the pane.

void SetMinSize(const CSize& size);

Parameters

size
[in] A CSize object that contains the minimum allowed size for the pane.

Remarks

CPane::SetVirtualRect

Sets the virtual rectangle of the pane.

void SetVirtualRect(
    const CRect& rect,
    BOOL bMapToParent = TRUE);

Parameters

rect
[in] A CRect object that specifies the virtual rectangle to be set.

bMapToParent
[in] Specify TRUE if rect contains points relative to the parent window.

Remarks

A virtual rectangle stores the original position of a pane when it is moved. The framework can use the virtual rectangle to restore the original position.

Do not call methods that are related to virtual rectangles unless you are moving panes programmatically.

CPane::SetMiniFrameRTC

Sets the runtime class information for the default mini-frame window.

void SetMiniFrameRTC(CRuntimeClass* pClass);

Parameters

pClass
[in, out] Specifies the runtime class information for the mini-frame window.

Remarks

When a pane is floated, it is put on a CPaneFrameWnd (mini-frame) window. You can provide a custom CPaneFrameWnd-derived class that will be used when CPane::CreateDefaultMiniframe is called.

CPane::StretchPaneDeferWndPos

Stretches the pane vertically or horizontally based on docking style.

virtual int StretchPaneDeferWndPos(
    int nStretchSize,
    HDWP& hdwp);

Parameters

nStretchSize
[in] The amount, in pixels, to stretch the pane. Use a negative value to shrink the pane.

hdwp
[in] Not used.

Return Value

The actual amount, in pixels, that the pane was stretched.

Remarks

If necessary, this method modifies nStretchSize to ensure that the pane does not exceed size limits. These limits are obtained by calling CPane::GetAvailableStretchSize and CPane::GetAvailableExpandSize.

CPane::ToggleAutoHide

Toggles auto-hide mode.

virtual void ToggleAutoHide();

Remarks

Call this method to toggle auto-hide mode. A pane must be docked to a main frame window in order to be switch to auto-hide mode.

CPane::UndockPane

Removes the pane from the dock site, default slider, or mini-frame window where it is currently docked.

virtual void UndockPane(BOOL bDelay = FALSE);

Parameters

bDelay
[in] If FALSE, the framework calls CBasePane::AdjustDockingLayout to adjust the docking layout.

Remarks

Use this method to programmatically undock a pane.

CPane::UpdateVirtualRect

Updates the virtual rectangle.

void UpdateVirtualRect();
void UpdateVirtualRect(CPoint ptOffset);
void UpdateVirtualRect(CSize sizeNew);

Parameters

ptOffset
[in] A CPoint object that specifies an offset by which to shift the pane.

sizeNew
[in] A CSize object that specifies a new size for the pane.

Remarks

The first overload sets the virtual rectangle by using the current position and size of the pane.

The second overload shifts the virtual rectangle by the amount that is specified by ptOffset.

The third overload sets the virtual rectangle by using the current position of the pane and the size that is specified by sizeNew.

Share via

CPane Class

Syntax

Members

Public Constructors

Public Methods

Protected Methods

Data Members

Remarks

Inheritance Hierarchy

Requirements

CPane::AdjustSizeImmediate

Parameters

Remarks

CPane::AllocElements

Parameters

Return Value

CPane::AllowShowOnPaneMenu

Return Value

Remarks

CPane::CalcAvailableSize

Parameters

Return Value

CPane::CalcInsideRect

Parameters

Remarks

CPane::CalcRecentDockedRect

Remarks

CPane::CalcSize

Parameters

Return Value

Remarks

CPane::CanBeDocked

Parameters

Return Value

Remarks

CPane::CanBeTabbedDocument

Return Value

Remarks

CPane::ConvertToTabbedDocument

Parameters

Remarks

CPane::CopyState

Parameters

Remarks

CPane::Create

Parameters

Return Value

Remarks

CPane::CreateDefaultMiniframe

Parameters

Return Value

Remarks

CPane::CreateEx

Parameters

Return Value

Remarks

CPane::DockByMouse

Parameters

Return Value

CPane::DockPane

Parameters

Return Value

Remarks

CPane::DockPaneStandard

Parameters

Return Value

Remarks

CPane::DockToFrameWindow

Parameters

Return Value

Remarks

CPane::DoesAllowSiblingBars

Return Value

Remarks

CPane::FloatPane

Parameters

Return Value

Remarks

CPane::GetAvailableExpandSize