CPane Class

 

For the latest documentation on Visual Studio 2017 RC, see Visual Studio 2017 RC Documentation.

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.

class CPane : public CBasePane  

Public Constructors

NameDescription
CPane::~CPaneDestructor.

Public Methods

NameDescription
CPane::AdjustSizeImmediateImmediately recalculates the layout of a pane.
CPane::AllocElementsAllocates storage for internal use.
CPane::AllowShowOnPaneMenuSpecifies whether the pane is listed in the runtime-generated list of panes for the application.
CPane::CalcAvailableSizeCalculates the difference in size between a specified rectangle and the current window rectangle.
CPane::CalcInsideRectCalculates the inside rectangle of a pane, taking into account the borders and grippers.
CPane::CalcRecentDockedRectCalculates the recently docked rectangle.
CPane::CalcSizeCalculates the size of the pane.
CPane::CanBeDockedDetermines whether the pane can be docked at the specified base pane.
CPane::CanBeTabbedDocumentDetermines whether the pane can be converted to a tabbed document.
CPane::ConvertToTabbedDocumentConverts a dockable pane to a tabbed document.
CPane::CopyStateCopies the state of a pane. (Overrides CBasePane::CopyState.)
CPane::CreateCreates a control bar and attaches it to the CPane object.
CPane::CreateDefaultMiniframeCreates a mini-frame window for a floating pane.
CPane::CreateExCreates a control bar and attaches it to the CPane object.
CPane::CreateObjectUsed by the framework to create a dynamic instance of this class type.
CPane::DockByMouseDocks a pane by using the mouse docking method.
CPane::DockPaneDocks the floating pane to a base pane.
CPane::DockPaneStandardDocks a pane by using outline (standard) docking.
CPane::DockToFrameWindowDocks a dockable pane to a frame. (Overrides CBasePane::DockToFrameWindow.)
CPane::DoesAllowSiblingBarsIndicates whether you can dock another pane at the same row where the current pane is docked.
CPane::FloatPaneFloats the pane.
CPane::GetAvailableExpandSizeReturns the amount, in pixels, that the pane can expand.
CPane::GetAvailableStretchSizeReturns the amount, in pixels, that the pane can shrink.
CPane::GetBordersReturns the width of the borders of the pane.
CPane::GetClientHotSpotReturns the hot spot for the pane.
CPane::GetDockSiteRowReturns the dock row in which the pane is docked.
CPane::GetExclusiveRowModeDetermines whether the pane is in exclusive row mode.
CPane::GetHotSpotReturns the hot spot that is stored in an underlying CMFCDragFrameImpl object.
CPane::GetMinSizeRetrieves the minimum allowed size for the pane.
CPane::GetPaneNameRetrieves the title for the pane.
CPane::GetResizeStepUsed internally.
CPane::GetThisClassUsed by the framework to obtain a pointer to the CRuntimeClass object that is associated with this class type.
CPane::GetVirtualRectRetrieves the virtual rectangle of the pane.
CPane::IsChangeStateAs 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::IsDragModeSpecifies whether the pane is being dragged.
CPane::IsInFloatingMultiPaneFrameWndSpecifies whether the pane is in a multi-pane frame window. (Overrides CBasePane::IsInFloatingMultiPaneFrameWnd.)
CPane::IsLeftOfDetermines whether the pane is left of (or above) the specified rectangle.
CPane::IsResizableDetermines whether the pane can be resized. (Overrides CBasePane::IsResizable.)
CPane::IsTabbedDetermines whether the pane has been inserted in the tab control of a tabbed window. (Overrides CBasePane::IsTabbed.)
CPane::LoadStateLoads the state of the pane from the registry. (Overrides CBasePane::LoadState.)
CPane::MoveByAlignmentMoves the pane and the virtual rectangle by the specified amount.
CPane::MovePaneMoves the pane to the specified rectangle.
CPane::OnAfterChangeParentCalled by the framework when the parent of a pane has changed.
CPane::OnBeforeChangeParentCalled by the framework when the parent of the pane is about to change.
CPane::OnPressCloseButtonCalled by the framework when the user chooses the Close button on the caption for the pane.
CPane::OnProcessDblClkUsed internally.
CPane::OnShowControlBarMenuCalled by the framework when a special pane menu is about to be displayed.
CPane::OnShowControlBarMenuCalled by the framework when a special pane menu is about to be displayed.
CPane::PrepareToDockUsed internally.
CPane::RecalcLayoutRecalculates layout information for the pane. (Overrides CBasePane::RecalcLayout.)
CPane::SaveStateSaves the state of the pane to the registry. (Overrides CBasePane::SaveState.)
CPane::SetActiveInGroupFlags a pane as active.
CPane::SetBordersSets the border values of the pane.
CPane::SetClientHotSpotSets the hot spot for the pane.
CPane::SetDockStateRestores docking state information for the pane.
CPane::SetExclusiveRowModeEnables or disables the exclusive row mode.
CPane::SetMiniFrameRTCSets the runtime class information for the default mini-frame window.
CPane::SetMinSizeSets the minimum allowed size for the pane.
CPane::SetVirtualRectSets the virtual rectangle of the pane.
CPane::StretchPaneDeferWndPosStretches the pane vertically or horizontally based on docking style.
CPane::ToggleAutoHideToggles auto-hide mode.
CPane::UndockPaneRemoves the pane from the dock site, default slider, or mini-frame window where it is currently docked. (Overrides CBasePane::UndockPane.)
CPane::UpdateVirtualRectUpdates the virtual rectangle.

Protected Methods

NameDescription
CPane::OnAfterDockCalled by the framework when a pane has been docked.
CPane::OnAfterFloatCalled by the framework when a pane has been floated.
CPane::OnBeforeDockCalled by the framework when the pane is about to be docked.
CPane::OnBeforeFloatCalled by the framework when a pane is about to be floated.

Data Members

NameDescription
CPane::m_bHandleMinSizeEnables consistent handling of the minimal size for panes.
CPane::m_recentDockInfoContains recent docking information.

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.

CObject

CCmdTarget

CWnd

CBasePane

CPane

Header: afxPane.h

Immediately recalculates the layout of a pane.

virtual void AdjustSizeImmediate(BOOL bRecalcLayout = TRUE);

Parameters

[in] bRecalcLayout
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.

Allocates storage for internal use.

BOOL AllocElements(
    int nElements,  
    int cbElement);

Parameters

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

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

Return Value

FALSE if memory allocation fails; otherwise, TRUE.

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.

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

virtual CSize CalcAvailableSize(CRect rectRequired);

Parameters

[in] rectRequired
The required rectangle.

Return Value

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

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

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

Parameters

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

[in] bHorz
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.

Calculates the recently docked rectangle.

void CalcRecentDockedRect();

Remarks

This method updates CPane::m_recentDockInfo.

Calculates the size of the pane.

virtual CSize CalcSize(BOOL bVertDock);

Parameters

[in] bVertDock
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.

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

virtual BOOL CanBeDocked(CBasePane* pDockBar) const;  

Parameters

[in] pDockBar
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.

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.

Converts a dockable pane to a tabbed document.

virtual void ConvertToTabbedDocument(BOOL bActiveTabOnly = TRUE);

Parameters

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

Remarks

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

Copies the state of a pane.

virtual void CopyState(CPane* pOrgBar);

Parameters

[in] pOrgBar
A pointer to a pane.

Remarks

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

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

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

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

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

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

[in] nID
Specifies the ID of the pane.

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

[in] [out] pContext
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.

Creates a mini-frame window for a floating pane.

virtual CPaneFrameWnd* CreateDefaultMiniframe(CRect rectInitial);

Parameters

[in] rectInitial
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.

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

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

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

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

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

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

[in] nID
Specifies the ID of the pane.

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

[in] [out] pContext
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.

Docks a pane by using the mouse.

virtual BOOL DockByMouse(CBasePane* pDockBar);

Parameters

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

Return Value

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

Docks the floating pane to a base pane.

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

Parameters

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

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

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

OptionDescription
DM_UNKNOWNThe 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_MOUSEUsed internally.
DM_DBL_CLICKThis 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_SHOWThis option can be used to programmatically dock the pane. The pane stores its most recent floating position.
DM_RECTThe pane is docked in the region that is specified by lpRect.
DM_STANDARDWhen 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.

Docks a pane by using outline (standard) docking.

virtual CPane* DockPaneStandard(BOOL& bWasDocked);

Parameters

[in] bWasDocked
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.

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

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

[in] lpRect
The specified size.

[in] dwDockFlags
Ignored.

[in] pRelativeBar
Ignored.

[in] nRelativeIndex
Ignored.

[in] bOuterEdge
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

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.

Floats the pane.

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

Parameters

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

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

[in] bShow
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.

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

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).

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.

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.

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.

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.

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.

Retrieves the minimum allowed size for the pane.

virtual void GetMinSize(CSize& size) const;  

Parameters

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

Remarks

Retrieves the title for the pane.

virtual void GetPaneName(CString& strName) const;  

Parameters

[out] strName
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.

Retrieves the virtual rectangle of the pane.

void GetVirtualRect(CRect& rectVirtual) const;  

Parameters

[out] rectVirtual
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.

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

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

[in] ppTargetBar
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:

ValueDescription
CS_NOTHINGThe pane is not near a dock site. The framework does not dock the pane.
CS_DOCK_IMMEDIATELYThe pane is over a dock site, and the DT_IMMEDIATE style is enabled. The framework docks the pane immediately.
CS_DELAY_DOCKThe 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_TABThe 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.

Specifies whether the pane is being moved.

virtual BOOL IsDragMode() const;  

Return Value

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

Remarks

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.

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

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

Parameters

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

[in] bWindowRect
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.

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.

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.

Loads the state of the pane from the registry.

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

Parameters

[in] lpszProfileName
Profile name.

[in] nIndex
Profile index.

[in] uiID
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.

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.

Contains recent docking information.

CRecentDockSiteInfo m_recentDockInfo;  

Remarks

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

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

BOOL MoveByAlignment(
    DWORD dwAlignment,  
    int nOffset);

Parameters

[in] dwAlignment
Specifies pane alignment.

[in] nOffset
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:

ValueDescription
CBRS_ALIGN_TOPEnables the pane to be docked to the top of the client area of a frame window.
CBRS_ALIGN_BOTTOMEnables the pane to be docked to the bottom of the client area of a frame window.
CBRS_ALIGN_LEFTEnables the pane to be docked to the left side of the client area of a frame window.
CBRS_ALIGN_RIGHTEnables the pane to be docked to the right side of the client area of a frame window.
CBRS_ALIGN_ANYEnables 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.

Moves the pane to the specified rectangle.

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

Parameters

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

[in] bForceMove
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.

[in] hdwp
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.

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

virtual void OnAfterChangeParent(CWnd* pWndOldParent);

Parameters

[in] [out] pWndOldParent
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.

Called by the framework when a pane has been docked.

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

Parameters

[in] pBar
This parameter is not used.

[in] lpRect
This parameter is not used.

[in] dockMethod
This parameter is not used.

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.

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

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

Parameters

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

[in] bDelay
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.

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

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

Parameters

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

[in] lpRect
Specifies the docking rectangle.

[in] dockMethod
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.

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

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

Parameters

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

[in] dockMethod
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.

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.

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

virtual BOOL OnShowControlBarMenu(CPoint point);

Parameters

[in] point
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.

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.

Saves the state of the pane to the registry.

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

Parameters

[in] lpszProfileName
Profile name.

[in] nIndex
Profile index.

[in] uiID
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.

Flags a pane as active.

virtual void SetActiveInGroup(BOOL bActive);  

Parameters

[in] bActive
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.

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

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

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

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

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

[in] lpRect
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.

Sets the hot spot for the pane.

void SetClientHotSpot(const CPoint& ptNew);

Parameters

[in] ptNew
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.

Restores docking state information for the pane.

virtual void SetDockState(CDockingManager* pDockManager);

Parameters

[in] pDockManager
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.

Enables or disables the exclusive row mode.

virtual void SetExclusiveRowMode(BOOL bExclusive = TRUE);

Parameters

[in] bExclusive
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.

Sets the minimum allowed size for the pane.

void SetMinSize(const CSize& size);

Parameters

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

Remarks

Sets the virtual rectangle of the pane.

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

Parameters

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

[in] bMapToParent
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.

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

void SetMiniFrameRTC(CRuntimeClass* pClass);

Parameters

[in] [out] pClass
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.

Stretches the pane vertically or horizontally based on docking style.

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

Parameters

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

[in] hdwp
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.

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.

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

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

Remarks

Use this method to programmatically undock a pane.

Updates the virtual rectangle.

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

Parameters

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

[in] sizeNew
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.

Hierarchy Chart
Classes
CBasePane Class

Show: