description | title | ms.date | f1_keywords | helpviewer_keywords | ms.assetid | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Learn more about: CMFCCaptionBar Class |
CMFCCaptionBar Class |
11/04/2016 |
|
|
acb54d5f-14ff-4c96-aeb3-7717cf566d9a |
A CMFCCaptionBar
object is a control bar that can display three elements: a button, a text label, and a bitmap. It can only display one element of each type at a time. You can align each element to the left or right edges of the control or to the center. You can also apply a flat or 3D style to the top and bottom borders of the caption bar.
class CMFCCaptionBar : public CPane
Name | Description |
---|---|
CMFCCaptionBar::Create | Creates the caption bar control and attaches it to the CMFCCaptionBar object. |
CMFCCaptionBar::DoesAllowDynInsertBefore | Indicates whether another pane can be dynamically inserted between the caption bar and its parent frame. (Overrides CBasePane::DoesAllowDynInsertBefore.) |
CMFCCaptionBar::EnableButton | Enables or disables the button on the caption bar. |
CMFCCaptionBar::GetAlignment | Returns the alignment of the specified element. |
CMFCCaptionBar::GetBorderSize | Returns the border size of the caption bar. |
CMFCCaptionBar::GetButtonRect | Retrieves the bounding rectangle of the button on the caption bar. |
CMFCCaptionBar::GetMargin | Returns the distance between the edge of the caption bar elements and the edge of the caption bar control. |
CMFCCaptionBar::IsMessageBarMode | Specifies whether the caption bar is in the message bar mode. |
CMFCCaptionBar::RemoveBitmap | Removes the bitmap image from the caption bar. |
CMFCCaptionBar::RemoveButton | Removes the button from the caption bar. |
CMFCCaptionBar::RemoveIcon | Removes the icon from the caption bar. |
CMFCCaptionBar::RemoveText | Removes the text label from the caption bar. |
CMFCCaptionBar::SetBitmap | Sets the bitmap image for the caption bar. |
CMFCCaptionBar::SetBorderSize | Sets the border size of the caption bar. |
CMFCCaptionBar::SetButton | Sets the button for the caption bar. |
CMFCCaptionBar::SetButtonPressed | Specifies whether the button stays pressed. |
CMFCCaptionBar::SetButtonToolTip | Sets the tooltip for the button. |
CMFCCaptionBar::SetFlatBorder | Sets the border style of the caption bar. |
CMFCCaptionBar::SetIcon | Sets the icon for a caption bar. |
CMFCCaptionBar::SetImageToolTip | Sets the tooltip for the image for the caption bar. |
CMFCCaptionBar::SetMargin | Sets the distance between the edge of the caption bar element and the edge of the caption bar control. |
CMFCCaptionBar::SetText | Sets the text label for the caption bar. |
Name | Description |
---|---|
CMFCCaptionBar::OnDrawBackground | Called by the framework to fill the background of the caption bar. |
CMFCCaptionBar::OnDrawBorder | Called by the framework to draw the border of the caption bar. |
CMFCCaptionBar::OnDrawButton | Called by the framework to draw the caption bar button. |
CMFCCaptionBar::OnDrawImage | Called by the framework to draw the caption bar image. |
CMFCCaptionBar::OnDrawText | Called by the framework to draw the caption bar text. |
Name | Description |
---|---|
CMFCCaptionBar::m_clrBarBackground | The background color of the caption bar. |
CMFCCaptionBar::m_clrBarBorder | The color of the border of the caption bar. |
CMFCCaptionBar::m_clrBarText | The color of the caption bar text. |
To create a caption bar, follow these steps:
-
Construct the
CMFCCaptionBar
object. Typically, you would add the caption bar to a frame window class. -
Call the CMFCCaptionBar::Create method to create the caption bar control and attach it to the
CMFCCaptionBar
object. -
Call CMFCCaptionBar::SetButton, CMFCCaptionBar::SetText, CMFCCaptionBar::SetIcon, and CMFCCaptionBar::SetBitmap to set the caption bar elements.
When you set the button element, you must assign a command ID to the button. When the user clicks the button, the caption bar routes the WM_COMMAND messages that have this ID to the parent frame window.
The caption bar can also work in message bar mode, which emulates the message bar that appears in Microsoft Office 2007 applications. In message bar mode, the caption bar displays a bitmap, a message, and a button (which typically opens a dialog box.) You can assign a tooltip to the bitmap.
To enable message bar mode, call CMFCCaptionBar::Create and set the fourth parameter (bIsMessageBarMode) to TRUE.
The following example demonstrates how to use various methods in the CMFCCaptionBar
class. The example shows how to create the caption bar control, set a 3D border of the caption bar, set the distance, in pixels, between the edge of the caption bar elements and the edge of the caption bar control, set the button for the caption bar, set the tooltip for the button, set the text label for the caption bar, set the bitmap image for the caption bar, and set the tooltip for the image in the caption bar. This code snippet is part of the MS Office 2007 Demo sample.
[!code-cppNVC_MFC_MSOffice2007Demo#1] [!code-cppNVC_MFC_MSOffice2007Demo#2]
Header: afxcaptionbar.h
Creates the caption bar control and attaches it to the CMFCCaptionBar
object.
BOOL Create(
DWORD dwStyle,
CWnd* pParentWnd,
UINT uID,
int nHeight=-1,
BOOL bIsMessageBarMode=FALSE);
dwStyle
The logical OR combination of the caption bar styles.
pParentWnd
The parent window of the caption bar control.
uID
The ID of caption bar control.
nHeight
The height, in pixels, of the caption bar control. If it is -1, the height is calculated according to the height of the icon, the text and the button that the caption bar control displays.
bIsMessageBarMode
TRUE if the caption bar is in the message bar mode; FALSE otherwise.
TRUE if the caption bar control is created successfully; FALSE otherwise.
You construct a CMFCCaptionBar
object in two steps. First you call the constructor, and then you call the Create
method, which creates the Windows control and attaches it to the CMFCCaptionBar
object.
Indicates whether another pane can be dynamically inserted between the caption bar and its parent frame.
virtual BOOL DoesAllowDynInsertBefore() const;
Returns FALSE unless overridden.
Enables or disables the button on the caption bar.
void EnableButton(BOOL bEnable=TRUE);
bEnable
[in] TRUE to enable the button, FALSE to disable the button.
Returns the alignment of the specified element.
BarElementAlignment GetAlignment(BarElement elem);
elem
[in] A caption bar element for which to retrieve alignment.
The alignment of an element, such as a button, a bitmap, text, or an icon.
The alignment of the element can be one of the following values:
-
ALIGN_INVALID
-
ALIGN_LEFT
-
ALIGN_RIGHT
-
ALIGN_CENTER
Returns the border size of the caption bar.
int GetBorderSize() const;
The size, in pixels, of the border.
Retrieves the bounding rectangle of the button on the caption bar.
CRect GetButtonRect() const;
A CRect
object that contains the coordinates of the bounding rectangle of the button on the caption bar.
Returns the distance between the edge of the caption bar elements and the edge of the caption bar control.
int GetMargin() const;
The distance, in pixels, between the edge of the caption bar elements and the edge of the caption bar control.
Specifies whether the caption bar is in the message bar mode.
BOOL IsMessageBarMode() const;
TRUE if the caption bar is in the message bar mode; FALSE otherwise.
In the message bar mode, the caption bar displays an image with a tooltip, a message text, and a button.
The background color of the caption bar.
COLORREF m_clrBarBackground
The color of the border of the caption bar.
COLORREF m_clrBarBorder
The color of the caption bar text.
COLORREF m_clrBarText
Called by the framework to fill the background of the caption bar.
virtual void OnDrawBackground(
CDC* pDC,
CRect rect);
pDC
[in] A pointer to the device context of the caption bar.
rect
[in] The bounding rectangle to fill.
The OnDrawBackground
method is called when the background of the caption bar is about to be filled. The default implementation fills the background by using the CMFCCaptionBar::m_clrBarBackground color.
Override this method in a CMFCCaptionBar
derived class to customize the appearance of the caption bar.
Called by the framework to draw the border of the caption bar.
virtual void OnDrawBorder(
CDC* pDC,
CRect rect);
pDC
[in] A device context that is used to display the borders.
rect
[in] The bounding rectangle.
By default, the borders have the flat style.
Override this method in a CMFCCaptionBar
derived class to customize the appearance of the caption bar's borders.
Called by the framework to draw the caption bar button.
virtual void OnDrawButton(
CDC* pDC,
CRect rect,
const CString& strButton,
BOOL bEnabled);
pDC
[in] A pointer to a device context that is used to display the button.
rect
[in] The bounding rectangle of the button.
strButton
[in] The button's text label.
bEnabled
[in] TRUE if the button is enabled; FALSE otherwise.
Override this method in a CMFCCaptionBar
derived class to customize the appearance of the caption bar's button.
Called by the framework to draw the caption bar image.
virtual void OnDrawImage(
CDC* pDC,
CRect rect);
pDC
[in] A pointer to a device context that is used to display the image.
rect
[in] Specifies the bounding rectangle of the image.
Override this method in a CMFCCaptionBar
derived class to customize the image appearance.
Called by the framework to draw the caption bar text.
virtual void OnDrawText(
CDC* pDC,
CRect rect,
const CString& strText);
pDC
[in] A pointer to a device context that is used to display the button.
rect
[in] The bounding rectangle of the text.
strText
[in] The text string to display.
The default implementation displays the text by using CDC::DrawText
and CMFCCaptionBar::m_clrBarText color.
Override this method in a CMFCCaptionBar
derived class to customize the appearance of the caption bar's text.
Removes the bitmap image from the caption bar.
void RemoveBitmap();
Removes the button from the caption bar.
void RemoveButton();
The layout of caption bar elements are adjusted automatically.
Removes the icon from the caption bar.
void RemoveIcon();
Removes the text label from the caption bar.
void RemoveText();
Sets the bitmap image for the caption bar.
void SetBitmap(
HBITMAP hBitmap,
COLORREF clrTransparent,
BOOL bStretch=FALSE,
BarElementAlignment bmpAlignment=ALIGN_RIGHT);
void SetBitmap(
UINT uiBmpResID,
COLORREF clrTransparent,
BOOL bStretch=FALSE,
BarElementAlignment bmpAlignment=ALIGN_RIGHT);
hBitmap
[in] The handle to the bitmap to set.
clrTransparent
[in] An RGB value that specifies the transparent color of the bitmap.
bStretch
[in] If TRUE, the bitmap is stretched if it does not fit to the image bounding rectangle. Otherwise the bitmap is not stretched.
bmpAlignment
[in] The alignment of the bitmap.
Use this method to set a bitmap on a caption bar.
The previous bitmap is destroyed automatically. If the caption bar displays an icon because you called the CMFCCaptionBar::SetIcon method, the bitmap will not be displayed unless you remove the icon by calling CMFCCaptionBar::RemoveIcon.
The bitmap is aligned as specified by the bmpAlignment parameter. This parameter can be one of the following BarElementAlignment
values:
-
ALIGN_INVALID
-
ALIGN_LEFT
-
ALIGN_RIGHT
-
ALIGN_CENTER
Sets the border size of the caption bar.
void SetBorderSize(int nSize);
nSize
[in] The new size, in pixels, of the caption bar border.
Sets the button for the caption bar.
void SetButton(
LPCTSTR lpszLabel,
UINT uiCmdUI,
BarElementAlignment btnAlignmnet=ALIGN_LEFT,
BOOL bHasDropDownArrow=TRUE);
lpszLabel
The button's command label.
uiCmdUI
The button's command ID.
btnAlignmnet
The button's alignment.
bHasDropDownArrow
TRUE if the button displays a drop down arrow, FALSE otherwise.
Specifies whether the button stays pressed.
void SetButtonPressed(BOOL bPresed=TRUE);
bPresed
TRUE if the button keeps its pressed state, FALSE otherwise.
Sets the tooltip for the button.
void SetButtonToolTip(
LPCTSTR lpszToolTip,
LPCTSTR lpszDescription=NULL);
lpszToolTip
[in] The tooltip caption.
lpszDescription
[in] The tooltip description.
Sets the border style of the caption bar.
void SetFlatBorder(BOOL bFlat=TRUE);
bFlat
[in] TRUE if the border of a caption bar is flat. FALSE if the border is 3D.
Sets the icon for a caption bar.
void SetIcon(
HICON hIcon,
BarElementAlignment iconAlignment=ALIGN_RIGHT);
hIcon
[in] The handle to the icon to set.
iconAlignment
[in] The alignment of the icon.
Caption bars can display either icons or bitmaps. See CMFCCaptionBar::SetBitmap to find out how to display a bitmap. If you set both an icon and a bitmap, the icon is always displayed. Call CMFCCaptionBar::RemoveIcon to remove an icon from the caption bar.
The icon is aligned according to the iconAlignment parameter. It can be one of the following BarElementAlignment
values:
-
ALIGN_INVALID
-
ALIGN_LEFT
-
ALIGN_RIGHT
-
ALIGN_CENTER
Sets the tooltip for the image in the caption bar.
void SetImageToolTip(
LPCTSTR lpszToolTip,
LPCTSTR lpszDescription=NULL);
lpszToolTip
[in] The text of the tooltip.
lpszDescription
[in] The tooltip description.
Sets the distance between the edge of the caption bar element and the edge of the caption bar control.
void SetMargin(int nMargin);
nMargin
[in] The distance, in pixels, between the edge of the caption bar elements and the edge of the caption bar control.
Sets the text label for the caption bar.
void SetText(
const CString& strText,
BarElementAlignment textAlignment=ALIGN_RIGHT);
strText
[in] The text string to set.
textAlignment
[in] The text alignment.
The text label is aligned as specified by the textAlignment parameter. It can be one of the following BarElementAlignment
values:
-
ALIGN_INVALID
-
ALIGN_LEFT
-
ALIGN_RIGHT
-
ALIGN_CENTER