CMFCCaptionButton Class

 

The new home for Visual Studio documentation is Visual Studio 2017 Documentation on docs.microsoft.com.

The latest version of this topic can be found at CMFCCaptionButton Class.

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

[in] nHit
The command associated with the button.

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

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

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

[in] ptTo
The new location.

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

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

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

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

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

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

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

See Also

Hierarchy Chart
Classes
CPaneFrameWnd Class
CDockablePane Class