CMFCCaptionBar 類別

CMFCCaptionBar對像是可顯示三個元素的控制列：按鈕、文字標籤和點陣圖。 它一次只能每個類型各顯示一個項目。 您可以將每個項目對齊控制項的左緣或右緣，或對齊中央。 您也可以將平面或 3D 樣式套用至標題列的上框線和下框線。

語法

class CMFCCaptionBar : public CPane

成員

公用方法

名稱	描述
CMFCCaptionBar：：Create	建立標題欄控件，並將它附加至 CMFCCaptionBar 物件。
CMFCCaptionBar：:D oesAllowDynInsertBefore	指出是否可以動態插入標題列與其父框架之間的另一個窗格。 （覆寫 CBasePane：:D oesAllowDynInsertBefore.）
CMFCCaptionBar：：EnableButton	啟用或停用標題列上的按鈕。
CMFCCaptionBar：：GetAlignment	傳回指定專案的對齊方式。
CMFCCaptionBar：：GetBorderSize	傳回標題列的框線大小。
CMFCCaptionBar：：GetButtonRect	擷取標題列上按鈕的周框。
CMFCCaptionBar：：GetMargin	傳回標題列專案邊緣與標題欄控件邊緣之間的距離。
CMFCCaptionBar：：IsMessageBarMode	指定標題列是否處於消息列模式。
CMFCCaptionBar：：RemoveBitmap	從標題列移除位圖影像。
CMFCCaptionBar：：RemoveButton	從標題列移除按鈕。
CMFCCaptionBar：：RemoveIcon	從標題列移除圖示。
CMFCCaptionBar：：RemoveText	從標題列移除文字標籤。
CMFCCaptionBar：：SetBitmap	設定標題列的點陣圖影像。
CMFCCaptionBar：：SetBorderSize	設定標題列的框線大小。
CMFCCaptionBar：：SetButton	設定標題列的按鈕。
CMFCCaptionBar：：SetButtonPressed	指定按鈕是否保持按下狀態。
CMFCCaptionBar：：SetButtonToolTip	設定按鈕的工具提示。
CMFCCaptionBar：：SetFlatBorder	設定標題列的框線樣式。
CMFCCaptionBar：：SetIcon	設定標題列的圖示。
CMFCCaptionBar：：SetImageToolTip	設定標題列影像的工具提示。
CMFCCaptionBar：：SetMargin	設定標題列元素邊緣與標題欄控件邊緣之間的距離。
CMFCCaptionBar：：SetText	設定標題列的文字標籤。

受保護的方法

名稱	描述
CMFCCaptionBar：：OnDrawBackground	由架構呼叫以填滿標題列的背景。
CMFCCaptionBar：：OnDrawBorder	由架構呼叫以繪製標題列的框線。
CMFCCaptionBar：：OnDrawButton	由架構呼叫以繪製標題列按鈕。
CMFCCaptionBar：：OnDrawImage	由架構呼叫以繪製標題欄影像。
CMFCCaptionBar：：OnDrawText	由架構呼叫以繪製標題列文字。

資料成員

名稱	描述
CMFCCaptionBar：：m_clrBarBackground	標題列的背景色彩。
CMFCCaptionBar：：m_clrBarBorder	標題列框線的色彩。
CMFCCaptionBar：：m_clrBarText	標題列文字的色彩。

備註

若要建立標題欄，請遵循下列步驟：

1. 建構 CMFCCaptionBar 物件。 一般而言，您會將標題列新增至框架窗口類別。

2. 呼叫 CMFCCaptionBar：：Create 方法來建立標題欄控件，並將它附加至 CMFCCaptionBar 物件。

3. 呼叫 CMFCCaptionBar：：SetButton、 CMFCCaptionBar：：SetText、 CMFCCaptionBar：：SetIcon 和 CMFCCaptionBar：：SetBitmap 來設定標題欄元素。

當您設定 button 元素時，必須將命令標識碼指派給按鈕。 當使用者按鍵時，標題列會將具有此標識碼的WM_COMMAND訊息路由傳送至父框架視窗。

標題列也可以在消息列模式中運作，以模擬出現在 Office 2007 應用程式中Microsoft訊息列。 在消息列模式中，標題欄會顯示點陣圖、訊息和按鈕（通常會開啟對話框）。您可以將工具提示指派給點陣圖。

若要啟用消息列模式，請呼叫 CMFCCaptionBar：：Create 並將第四個參數 （bIsMessageBarMode） 設定為 TRUE。

範例

下例示範如何在 CMFCCaptionBar 類別中使用各種方法。 這個範例示範如何建立標題列控件、設定標題列的 3D 框線、設定標題列元素邊緣與標題列控件邊緣之間的距離、設定標題欄控件的按鈕、設定按鈕的工具提示、設定標題欄的文字卷標、 設定標題列的點陣圖影像，並在標題欄中設定影像的工具提示。 此代碼段是 MS Office 2007 示範範例的一部分。

CMFCCaptionBar m_wndMessageBar;

BOOL CMainFrame::CreateMessageBar()
{
   // The this pointer points to a CMainFrame class which extends the CFrameWndEx class.
   if (!m_wndMessageBar.Create(WS_CHILD | WS_VISIBLE | WS_CLIPSIBLINGS, this, ID_VIEW_MESSAGEBAR, -1, TRUE))
   {
      TRACE0("Failed to create caption bar\n");
      return FALSE;
   }

   m_wndMessageBar.SetFlatBorder(FALSE);
   m_wndMessageBar.SetMargin(10);
   m_wndMessageBar.SetButton(_T("Options..."), ID_TOOLS_OPTIONS, CMFCCaptionBar::ALIGN_LEFT, FALSE);
   m_wndMessageBar.SetButtonToolTip(_T("Click here to see more options"));

   m_wndMessageBar.SetText(_T("Welcome to the MFC MSOffice2007 demonstration!"), CMFCCaptionBar::ALIGN_LEFT);

   m_wndMessageBar.SetBitmap(IDB_INFO, RGB(255, 255, 255), FALSE, CMFCCaptionBar::ALIGN_LEFT);
   m_wndMessageBar.SetImageToolTip(_T("Important"), _T("Please take a look at MSOffice2007Demo source code to learn how to create advanced user interface in minutes."));

   return TRUE;
}

繼承階層架構

CObject

CCmdTarget

CWnd

CBasePane

CPane

CMFCCaptionBar

需求

標頭： afxcaptionbar.h

CMFCCaptionBar：：Create

建立標題欄控件，並將它附加至 CMFCCaptionBar 物件。

BOOL Create(
    DWORD dwStyle,
    CWnd* pParentWnd,
    UINT uID,
    int nHeight=-1,
    BOOL bIsMessageBarMode=FALSE);

參數

dwStyle
標題欄樣式的邏輯 OR 組合。

pParentWnd
標題欄控件的父視窗。

uID
標題欄控件的標識碼。

nHeight
標題欄控件的高度，以像素為單位。 如果是 -1，則會根據圖示的高度、標題欄控件顯示的文字和按鈕來計算高度。

bIsMessageBarMode
如果標題列處於消息列模式，則為TRUE;否則為 FALSE。

傳回值

如果成功建立標題欄控件，則為TRUE;否則為 FALSE。

備註

您會在兩個步驟中建構 CMFCCaptionBar 物件。 首先，您會呼叫 建構函式，然後呼叫 Create 方法，該方法會建立 Windows 控件並將它附加至 CMFCCaptionBar 物件。

CMFCCaptionBar：:D oesAllowDynInsertBefore

指出是否可以動態插入標題列與其父框架之間的另一個窗格。

virtual BOOL DoesAllowDynInsertBefore() const;

傳回值

除非覆寫，否則會傳回 FALSE。

備註

CMFCCaptionBar：：EnableButton

啟用或停用標題列上的按鈕。

void EnableButton(BOOL bEnable=TRUE);

參數

bEnable
[in]TRUE 表示啟用按鈕，FALSE 表示停用按鈕。

CMFCCaptionBar：：GetAlignment

傳回指定專案的對齊方式。

BarElementAlignment GetAlignment(BarElement elem);

參數

elem
[in]要為其擷取對齊的標題列專案。

傳回值

專案的對齊方式，例如按鈕、位圖、文字或圖示。

備註

專案的對齊方式可以是下列其中一個值：

• ALIGN_INVALID

• ALIGN_LEFT

• ALIGN_RIGHT

• ALIGN_CENTER

CMFCCaptionBar：：GetBorderSize

傳回標題列的框線大小。

int GetBorderSize() const;

傳回值

框線的大小，以像素為單位。

CMFCCaptionBar：：GetButtonRect

擷取標題列上按鈕的周框。

CRect GetButtonRect() const;

傳回值

CRect物件，其中包含標題欄上按鈕周框的座標。

CMFCCaptionBar：：GetMargin

傳回標題列專案邊緣與標題欄控件邊緣之間的距離。

int GetMargin() const;

傳回值

標題欄元素邊緣與標題欄控件邊緣之間的距離，以像素為單位。

CMFCCaptionBar：：IsMessageBarMode

指定標題列是否處於消息列模式。

BOOL IsMessageBarMode() const;

傳回值

如果標題列處於消息列模式，則為TRUE;否則為 FALSE。

備註

在消息列模式中，標題列會顯示具有工具提示、消息正文和按鈕的影像。

CMFCCaptionBar：：m_clrBarBackground

標題列的背景色彩。

COLORREF m_clrBarBackground

CMFCCaptionBar：：m_clrBarBorder

標題列框線的色彩。

COLORREF m_clrBarBorder

CMFCCaptionBar：：m_clrBarText

標題列文字的色彩。

COLORREF m_clrBarText

CMFCCaptionBar：：OnDrawBackground

由架構呼叫以填滿標題列的背景。

virtual void OnDrawBackground(
    CDC* pDC,
    CRect rect);

參數

pDC
[in]標題列之裝置內容的指標。

rect
[in]要填滿的周框。

備註

當 OnDrawBackground 標題列的背景即將填滿時，會呼叫 方法。 默認實作會使用 CMFCCaptionBar：：m_clrBarBackground 色彩填滿背景。

覆寫衍生類別中的 CMFCCaptionBar 這個方法，以自定義標題列的外觀。

CMFCCaptionBar：：OnDrawBorder

由架構呼叫以繪製標題列的框線。

virtual void OnDrawBorder(
    CDC* pDC,
    CRect rect);

參數

pDC
[in]用來顯示框線的裝置內容。

rect
[in]周框。

備註

根據預設，框線具有平面樣式。

覆寫衍生類別中的 CMFCCaptionBar 這個方法，以自定義標題欄框線的外觀。

CMFCCaptionBar：：OnDrawButton

由架構呼叫以繪製標題列按鈕。

virtual void OnDrawButton(
    CDC* pDC,
    CRect rect,
    const CString& strButton,
    BOOL bEnabled);

參數

pDC
[in]用來顯示按鈕之裝置內容的指標。

rect
[in]按鈕的周框。

strButton
[in]按鈕的文字標籤。

bEnabled
[in]如果啟用按鈕，則為TRUE;否則為 FALSE。

備註

覆寫衍生類別中的 CMFCCaptionBar 這個方法，以自定義標題欄按鈕的外觀。

CMFCCaptionBar：：OnDrawImage

由架構呼叫以繪製標題欄影像。

virtual void OnDrawImage(
    CDC* pDC,
    CRect rect);

參數

pDC
[in]用來顯示影像之裝置內容的指標。

rect
[in]指定影像的周框。

備註

覆寫衍生類別中的 CMFCCaptionBar 這個方法，以自定義影像外觀。

CMFCCaptionBar：：OnDrawText

由架構呼叫以繪製標題列文字。

virtual void OnDrawText(
    CDC* pDC,
    CRect rect,
    const CString& strText);

參數

pDC
[in]用來顯示按鈕之裝置內容的指標。

rect
[in]文字的周框。

strText
[in]要顯示的文字字串。

備註

默認實作會使用 CDC::DrawText 和 CMFCCaptionBar：：m_clrBarText 色彩來顯示文字。

覆寫衍生類別中的 CMFCCaptionBar 這個方法，以自定義標題欄文字的外觀。

CMFCCaptionBar：：RemoveBitmap

從標題列移除位圖影像。

void RemoveBitmap();

CMFCCaptionBar：：RemoveButton

從標題列移除按鈕。

void RemoveButton();

備註

標題欄專案的版面配置會自動調整。

CMFCCaptionBar：：RemoveIcon

從標題列移除圖示。

void RemoveIcon();

CMFCCaptionBar：：RemoveText

從標題列移除文字標籤。

void RemoveText();

CMFCCaptionBar：：SetBitmap

設定標題列的點陣圖影像。

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]要設定之點陣圖的句柄。

clrTransparent
[in]指定點圖透明色彩的 RGB 值。

bStretch
[in]如果為 TRUE，則如果點圖不符合影像周框的矩形，則會延展。 否則不會延展位圖。

bmpAlignment
[in]位圖的對齊方式。

備註

使用此方法在標題列上設定位圖。

先前的點陣圖會自動終結。 如果標題列顯示圖示，因為您呼叫 CMFCCaptionBar：：SetIcon 方法，除非您呼叫 CMFCCaptionBar：：RemoveIcon 移除圖示，否則不會顯示位圖。

位圖會對齊 bmpAlignment 參數所指定。 這個參數可以是下列其中一個 BarElementAlignment 值：

• ALIGN_INVALID

• ALIGN_LEFT

• ALIGN_RIGHT

• ALIGN_CENTER

CMFCCaptionBar：：SetBorderSize

設定標題列的框線大小。

void SetBorderSize(int nSize);

參數

nSize
[in]標題欄框線框線的新大小，以像素為單位。

CMFCCaptionBar：：SetButton

設定標題列的按鈕。

void SetButton(
    LPCTSTR lpszLabel,
    UINT uiCmdUI,
    BarElementAlignment btnAlignmnet=ALIGN_LEFT,
    BOOL bHasDropDownArrow=TRUE);

參數

lpszLabel
按鈕的命令標籤。

uiCmdUI
按鈕的命令標識碼。

btnAlignmnet
按鈕的對齊方式。

bHasDropDownArrow
如果按鈕顯示下拉箭號，則為TRUE，否則為 FALSE。

CMFCCaptionBar：：SetButtonPressed

指定按鈕是否保持按下狀態。

void SetButtonPressed(BOOL bPresed=TRUE);

參數

bPresed
如果按鈕保持按下狀態，則為TRUE，否則為 FALSE。

CMFCCaptionBar：：SetButtonToolTip

設定按鈕的工具提示。

void SetButtonToolTip(
    LPCTSTR lpszToolTip,
    LPCTSTR lpszDescription=NULL);

參數

lpszToolTip
[in]工具提示標題。

lpszDescription
[in]工具提示描述。

CMFCCaptionBar：：SetFlatBorder

設定標題列的框線樣式。

void SetFlatBorder(BOOL bFlat=TRUE);

參數

bFlat
[in]如果標題列的框線是平面的，則為TRUE。 如果框線為 3D，則為 FALSE。

CMFCCaptionBar：：SetIcon

設定標題列的圖示。

void SetIcon(
    HICON hIcon,
    BarElementAlignment iconAlignment=ALIGN_RIGHT);

參數

hIcon
[in]要設定之圖示的句柄。

iconAlignment
[in]圖示的對齊方式。

備註

標題列可以顯示圖示或點陣圖。 請參閱 CMFCCaptionBar：：SetBitmap 以瞭解如何顯示位圖。 如果您同時設定圖示和點陣圖，則一律會顯示圖示。 呼叫 CMFCCaptionBar：：RemoveIcon ，從標題列移除圖示。

圖示會根據 iconAlignment 參數對齊。 它可以是下列 BarElementAlignment 其中一個值：

• ALIGN_INVALID

• ALIGN_LEFT

• ALIGN_RIGHT

• ALIGN_CENTER

CMFCCaptionBar：：SetImageToolTip

設定標題列中影像的工具提示。

void SetImageToolTip(
    LPCTSTR lpszToolTip,
    LPCTSTR lpszDescription=NULL);

參數

lpszToolTip
[in]工具提示的文字。

lpszDescription
[in]工具提示描述。

CMFCCaptionBar：：SetMargin

設定標題列元素邊緣與標題欄控件邊緣之間的距離。

void SetMargin(int nMargin);

參數

nMargin
[in]標題欄元素邊緣與標題欄控件邊緣之間的距離，以像素為單位。

CMFCCaptionBar：：SetText

設定標題列的文字標籤。

void SetText(
    const CString& strText,
    BarElementAlignment textAlignment=ALIGN_RIGHT);

參數

strText
[in]要設定的文字字串。

textAlignment
[in]文字對齊方式。

備註

文字標籤會對齊 textAlignment 參數所指定。 它可以是下列 BarElementAlignment 其中一個值：

• ALIGN_INVALID

• ALIGN_LEFT

• ALIGN_RIGHT

• ALIGN_CENTER

另請參閱

階層架構圖表
類別