CMFCCaptionButton Class

Note

The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation.

The CMFCCaptionButton class implements a button that is displayed on the caption bar for a docking pane or a mini-frame window. Typically, the framework creates caption buttons automatically.

Syntax

class CMFCCaptionButton : public CObject

Members

Constructors

Name	Description
CMFCCaptionButton::CMFCCaptionButton	Constructs a CMFCCaptionButton object.

Public Methods

Name	Description
CMFCCaptionButton::GetHit	Returns the command represented by the button.
CMFCCaptionButton::GetIconID	Returns the image ID associated with the button.
CMFCCaptionButton::GetRect	Returns the rectangle occupied by the button.
CMFCCaptionButton::GetSize	Returns the width and height of the button.
CMFCCaptionButton::IsMiniFrameButton	Indicates whether the title bar height is set to mini size.
CMFCCaptionButton::Move	Sets the button draw location and window show state.
CMFCCaptionButton::OnDraw	Draws the caption button.
CMFCCaptionButton::SetMiniFrameButton	Sets the mini size of the title bar.

Remarks

You can derive a class from CPaneFrameWnd Class and use the protected method, AddButton, to add caption buttons to a mini frame window.

CPaneFrameWnd.h defines command IDs for two types of caption buttons:

• AFX_CAPTION_BTN_PIN, which displays a pin button when the docking pane supports auto-hide mode.

• AFX_CAPTION_BTN_CLOSE, which displays a Close button when the pane can be closed or hidden.

Example

The following example demonstrates how to construct a CMFCCaptionButton object and set the mini size of the title bar.

CMFCCaptionButton *captionButton = new CMFCCaptionButton(AFX_HTCLOSE);
captionButton->SetMiniFrameButton(true);

Inheritance Hierarchy

CObject

CMFCCaptionButton

Requirements

Header: afxcaptionbutton.h

CMFCCaptionButton::CMFCCaptionButton

Constructs a CMFCCaptionButton object.

CMFCCaptionButton();

CMFCCaptionButton(
    UINT nHit,
    BOOL bLeftAlign = FALSE);

Parameters

nHit
[in] The command associated with the button.

bLeftAlign
[in] Specifies whether the button is aligned to the left.

The following table lists possible values for the nHit parameter.

Value	Command
AFX_HTCLOSE	Close button.
HTMINBUTTON	Minimize button.
HTMAXBUTTON	Maximize button.
AFX_HTLEFTBUTTON	Left arrow button.
AFX_HTRIGHTBUTTON	Right arrow button.
AFX_HTMENU	Down arrow menu button.
HTNOWHERE	The default value; represents no command.

Remarks

By default, caption buttons are not associated with a command.

Caption buttons are aligned either on the right or left.

CMFCCaptionButton::GetHit

Returns the command represented by the button.

UINT GetHit() const;

Return Value

The command represented by the button.

The following table lists possible return values.

Value	Command
AFX_HTCLOSE	Close button.
HTMINBUTTON	Minimize button.
HTMAXBUTTON	Maximize button.
AFX_HTLEFTBUTTON	Left arrow button.
AFX_HTRIGHTBUTTON	Right arrow button.
AFX_HTMENU	Down arrow menu button.
HTNOWHERE	The default value; represents no command.

CMFCCaptionButton::GetIconID

Returns the image ID associated with the button.

virtual CMenuImages::IMAGES_IDS GetIconID(
    BOOL bHorz,
    BOOL bMaximized = FALSE) const;

Parameters

bHorz
[in] TRUE for left or right arrow image IDs; FALSE for up or down arrow image IDs.

bMaximized
[in] TRUE for a maximize image ID; FALSE for a minimize image ID.

Return Value

The image ID.

Remarks

The parameters specify image IDs for minimize or maximize caption buttons.

CMFCCaptionButton::GetRect

Returns the rectangle occupied by the button.

virtual CRect GetRect() const;

Return Value

The rectangle that represents the location of the button.

Remarks

If you cannot see the button, the size returned is 0.

CMFCCaptionButton::GetSize

Returns the width and height of the button.

static CSize GetSize();

Return Value

The outer dimensions of the button.

Remarks

The size returned includes button margin and border.

CMFCCaptionButton::IsMiniFrameButton

Indicates whether the title bar height is set to mini size.

BOOL IsMiniFrameButton() const;

Return Value

TRUE if the caption is set to mini size; otherwise FALSE.

Remarks

CMFCCaptionButton::Move

Sets the button draw location and window show state.

void Move(
    const CPoint& ptTo,
    BOOL bHide = FALSE);

Parameters

ptTo
[in] The new location.

bHide
[in] Whether to show the button.

CMFCCaptionButton::OnDraw

Draws the caption button.

virtual void OnDraw(
    CDC* pDC,
    BOOL bActive,
    BOOL bHorz = TRUE,
    BOOL bMaximized = TRUE,
    BOOL bDisabled = FALSE);

Parameters

pDC
[in] Pointer to a device context for the button.

bActive
[in] Whether to draw an active button image.

bHorz
[in] Reserved for use in a derived class.

bMaximized
[in] Whether to draw a maximized button image.

bDisabled
[in] Whether to draw an enabled button image.

Remarks

The bMaximized parameter is used when the button is a maximize or minimize button.

CMFCCaptionButton::SetMiniFrameButton

Sets the mini size of the title bar.

void SetMiniFramebutton(BOOL bSet = TRUE);

Parameters

bSet
[in] TRUE for mini title bar height; FALSE for default title bar height.

See also

Hierarchy Chart
Classes
CPaneFrameWnd Class
CDockablePane Class