CStatusBarCtrl 類別

發行項
08/04/2024

提供 Windows 通用狀態列控制項的功能。

語法

class CStatusBarCtrl : public CWnd

成員

公用建構函式

名稱	描述
CStatusBarCtrl：：CStatusBarCtrl	建構 `CStatusBarCtrl` 物件。

公用方法

名稱	描述
CStatusBarCtrl：：Create	建立狀態列控件，並將它附加至 `CStatusBarCtrl` 物件。
CStatusBarCtrl：：CreateEx	使用指定的 Windows 擴充樣式建立狀態列控件，並將它附加至 `CStatusBarCtrl` 物件。
CStatusBarCtrl：:D rawItem	當擁有者繪製狀態列控件的視覺層面變更時呼叫。
CStatusBarCtrl：：GetBorders	擷取狀態列控件的水準和垂直框線的目前寬度。
CStatusBarCtrl：：GetIcon	擷取目前狀態列控件中元件（也稱為窗格）的圖示。
CStatusBarCtrl：：GetParts	擷取狀態列控件中元件的計數。
CStatusBarCtrl：：GetRect	擷取狀態列控件中元件的周框。
CStatusBarCtrl：：GetText	從狀態列控件的指定部分擷取文字。
CStatusBarCtrl：：GetTextLength	從狀態欄控件的指定部分擷取文字的長度，以字元為單位。
CStatusBarCtrl：：GetTipText	擷取狀態列中窗格的工具提示文字。
CStatusBarCtrl：：IsSimple	檢查狀態視窗控制件，以判斷它是否處於簡單模式。
CStatusBarCtrl：：SetBkColor	設定狀態列中的背景色彩。
CStatusBarCtrl：：SetIcon	設定狀態列中窗格的圖示。
CStatusBarCtrl：：SetMinHeight	設定狀態列控件繪圖區域的最低高度。
CStatusBarCtrl：：SetParts	設定狀態列控制件中的元件數目，以及每個元件右邊緣的座標。
CStatusBarCtrl：：SetSimple	指定狀態列控制項是否顯示簡單文字，或顯示先前呼叫 `SetParts`所設定的所有控制元件。
CStatusBarCtrl：：SetText	在狀態列控制項的指定部分設定文字。
CStatusBarCtrl：：SetTipText	設定狀態列中窗格的工具提示文字。

備註

「狀態列控件」是水平視窗，通常顯示在父視窗底部，其中應用程式可以顯示各種狀態資訊。狀態欄控件可以分成多個部分，以顯示一種以上的信息類型。

此控件（因此類別 CStatusBarCtrl ）僅適用於在 Windows 95/98 和 Windows NT 3.51 版和更新版本下執行的程式。

如需使用 CStatusBarCtrl的詳細資訊，請參閱控件和使用 CStatusBarCtrl。

繼承階層架構

CObject

CCmdTarget

CWnd

CStatusBarCtrl

需求

標頭： afxcmn.h

CStatusBarCtrl：：Create

建立狀態列控件，並將它附加至 CStatusBarCtrl 物件。

virtual BOOL Create(
    DWORD dwStyle,
    const RECT& rect,
    CWnd* pParentWnd,
    UINT nID);

參數

dwStyle
指定狀態列控件的樣式。套用 Windows SDK 中通用控制樣式中列出的狀態列控件樣式的任何組合。此參數必須包含WS_CHILD樣式。它也應該包含WS_VISIBLE樣式。

rect
指定狀態列控制件的大小和位置。它可以是 CRect 物件或 RECT 結構。

pParentWnd
指定狀態列控制件的父視窗，通常是 CDialog。它不得為 NULL。

nID
指定狀態列控件的識別碼。

傳回值

如果成功則不為零，否則為 0。

備註

您會在兩個步驟中建構 CStatusBarCtrl 。首先，呼叫建構函式，然後呼叫 Create，這會建立狀態列控件並將它附加至 CStatusBarCtrl 物件。

狀態窗口的預設位置是沿著父視窗底部，但您可以指定CCS_TOP樣式，讓它出現在父視窗工作區的頂端。您可以指定SBARS_SIZEGRIP樣式，以在狀態視窗的右端包含重設大小夾。不建議合併CCS_TOP和SBARS_SIZEGRIP樣式，因為即使系統將它繪製在狀態視窗中，產生的重設大小夾仍無法運作。

若要建立具有擴充視窗樣式的狀態列，請呼叫 CStatusBarCtrl：：CreateEx ，而不是 Create。

範例

VERIFY(m_wndSBC.Create(WS_CHILD | WS_VISIBLE | CCS_BOTTOM | SBARS_SIZEGRIP,
                       CRect(0, 0, 0, 0), this, IDC_STATUSBARCTRL));

CStatusBarCtrl：：CreateEx

建立控件（子視窗），並將它與 CStatusBarCtrl 對象產生關聯。

virtual BOOL CreateEx(
    DWORD dwExStyle,
    DWORD dwStyle,
    const RECT& rect,
    CWnd* pParentWnd,
    UINT nID);

參數

dwExStyle
指定要建立之控件的擴充樣式。如需擴充 Windows 樣式的清單，請參閱 Windows SDK 中 CreateWindowEx 的 dwExStyle 參數。

rect
RECT 結構的參考，描述要建立之視窗的大小和位置，在 pParentWnd 的用戶端座標中。

pParentWnd
控件父系之視窗的指標。

nID
控制件的子視窗識別碼。

傳回值

如果成功則為非零；否則為 0。

備註

使用 CreateEx 而不是 Create 來套用延伸的 Windows 樣式，由 Windows 擴充樣式前文WS_EX_所指定。

CStatusBarCtrl：：CStatusBarCtrl

建構 CStatusBarCtrl 物件。

CStatusBarCtrl();

CStatusBarCtrl：:D rawItem

當擁有者繪製狀態列控件的視覺層面變更時，由架構呼叫。

virtual void DrawItem(LPDRAWITEMSTRUCT lpDrawItemStruct);

參數

lpDrawItemStruct
DRAWITEMSTRUCT 結構的長指標，其中包含所需繪圖類型的相關信息。

備註

結構 itemAction 的成員 DRAWITEMSTRUCT 會定義要執行的繪圖動作。

根據預設，此成員函式不會執行任何動作。覆寫這個成員函式，以實作擁有者繪製對象的繪圖 CStatusBarCtrl 。

應用程式應該還原針對 lpDrawItemStruct 中提供的顯示內容選取的所有圖形裝置介面（GDI）物件，然後這個成員函式終止。

CStatusBarCtrl：：GetBorders

擷取狀態列控件的水準和垂直框線的目前寬度，以及矩形之間的間距。

BOOL GetBorders(int* pBorders) const;

BOOL GetBorders(
    int& nHorz,
    int& nVert,
    int& nSpacing) const;

參數

pBorders
具有三個元素的整數陣列位址。第一個專案會接收水準框線的寬度，第二個元素會接收垂直框線的寬度，而第三個元素會接收矩形之間的框線寬度。

nHorz
接收水平框線寬度的整數參考。

nVert
接收垂直框線寬度的整數參考。

nSpacing
整數的參考，這個整數會接收矩形之間的框線寬度。

傳回值

如果成功則不為零，否則為 0。

備註

這些框線會決定控件外邊緣與控件內包含文字之矩形之間的間距。

範例

RECT rectPane1;
VERIFY(m_wndSBC.GetRect(1, &rectPane1));

int borderArray[3];
VERIFY(m_wndSBC.GetBorders(borderArray));

int nHorz, nVert, nSpacing;
VERIFY(m_wndSBC.GetBorders(nHorz, nVert, nSpacing));

CStatusBarCtrl：：GetIcon

擷取目前狀態列控件中元件（也稱為窗格）的圖示。

HICON GetIcon(int iPart) const;

參數

iPart
[in]元件之以零起始的索引，其中包含要擷取的圖示。如果此參數是 -1，則狀態列會假設為簡單模式狀態列。

傳回值

如果方法成功，則為圖示的句柄;否則為 NULL。

備註

這個方法會傳送 windows SDK 中所述的 SB_GETICON訊息。

狀態列控件是由一列文字輸出窗格所組成，也稱為元件。如需狀態列的詳細資訊，請參閱 MFC 中的狀態列實作和設定 CStatusBarCtrl 物件的模式。

範例

第一個程式代碼範例會定義用來存取目前狀態列控制件的變數 m_statusBar。下一個範例中會使用此變數。

public:
CStatusBarCtrl m_statusBar;

下一個程式代碼範例會將圖示複製到目前狀態列控件的兩個窗格。在程式代碼範例的先前區段中，我們建立了具有三個窗格的狀態欄控件，然後將圖示新增至第一個窗格。本範例會從第一個窗格擷取圖示，然後將它新增至第二和第三個窗格。

// Get the icon from pane 1 and set it in panes 2 and 3.
HICON hIcon = m_statusBar.GetIcon(0);
m_statusBar.SetIcon(1, hIcon);
m_statusBar.SetIcon(2, hIcon);

CStatusBarCtrl：：GetParts

擷取狀態列控件中元件的計數。

int GetParts(
    int nParts,
    int* pParts) const;

參數

nParts
要擷取座標的元件數目。如果此參數大於控件中的元件數目，訊息只會擷取現有元件的座標。

pParts
整數數位的位址，其元素數目與 nParts 所指定的元件數目相同。數位列中的每個項目都會接收對應元件右邊緣的用戶端座標。如果元素設定為 - 1，該部分的右邊緣位置會延伸到狀態列的右邊緣。

傳回值

如果成功，則為控件中的元件數目，否則為零。

備註

這個成員函式也會擷取指定部分數目右邊緣的座標。

範例

int pParts[2];

int nParts = m_wndSBC.GetParts(2, pParts);

CStatusBarCtrl：：GetRect

擷取狀態列控件中元件的周框。

BOOL GetRect(
    int nPane,
    LPRECT lpRect) const;

參數

nPane
要擷取周框之元件之以零起始的索引。

lpRect
接收周框之 RECT 結構的位址。

傳回值

如果成功則不為零，否則為 0。

範例

CRect rectPane1;

VERIFY(m_wndSBC.GetRect(1, &rectPane1));

CStatusBarCtrl：：GetText

從狀態列控件的指定部分擷取文字。

CString GetText(
    int nPane,
    int* pType = NULL) const;

int GetText(
    LPCTSTR lpszText,
    int nPane,
    int* pType = NULL) const;

參數

lpszText
接收文字之緩衝區的位址。此參數是 Null 終止的字串。

nPane
要從中擷取文字之元件的以零起始的索引。

pType
接收類型資訊的整數指標。此類型可以是下列其中一個值：

0 文字會以框線繪製，以低於狀態列平面。
SBT_NOBORDERS沒有框線繪製文字。
SBT_POPOUT 文字會以框線繪製，以顯示高於狀態列平面。
SBT_OWNERDRAW如果文字具有SBT_OWNERDRAW繪圖類型， pType 會收到此訊息，並傳回與文字相關聯的 32 位值，而不是長度和作業類型。

傳回值

包含目前文字的文字或 CString 的長度，以字元為單位。

範例

int nType;
TCHAR *pszPaneOneText;

pszPaneOneText = new TCHAR[m_wndSBC.GetTextLength(1, &nType) + 1];
int nTextLength = m_wndSBC.GetText(pszPaneOneText, 1, &nType);

switch (nType)
{
case 0:
   // Text is drawn with a border to appear lower than the
   // plane of the status bar
   break;
case SBT_NOBORDERS:
   // text is drawn without borders
   break;
case SBT_OWNERDRAW:
   // Text is drawn by the parent window
   break;
case SBT_POPOUT:
   // Text is drawn with a border to appear higher than the
   // plane of the status bar
   break;
}

delete pszPaneOneText;

CStatusBarCtrl：：GetTextLength

從狀態欄控件的指定部分擷取文字的長度，以字元為單位。

int GetTextLength(
    int nPane,
    int* pType = NULL) const;

參數

nPane
要從中擷取文字之元件的以零起始的索引。

pType
接收類型資訊的整數指標。此類型可以是下列其中一個值：

0 文字會以框線繪製，以低於狀態列平面。
SBT_NOBORDERS沒有框線繪製文字。
SBT_OWNERDRAW父視窗繪製文字。
SBT_POPOUT 文字會以框線繪製，以顯示高於狀態列平面。

傳回值

文字的長度，以字元為單位。

範例

int nType;
int nLength = m_wndSBC.GetTextLength(0, &nType);

switch (nType)
{
case 0:
   // Text is drawn with a border to appear lower than the
   // plane of the status bar
   break;
case SBT_NOBORDERS:
   // text is drawn without borders
   break;
case SBT_OWNERDRAW:
   // Text is drawn by the parent window
   break;
case SBT_POPOUT:
   // Text is drawn with a border to appear higher than the
   // plane of the status bar
   break;
}

CStatusBarCtrl：：GetTipText

擷取狀態列中窗格的工具提示文字。

CString GetTipText(int nPane) const;

參數

nPane
要接收工具提示文字的狀態列窗格以零起始的索引。

傳回值

CString 物件，其中包含工具提示中使用的文字。

備註

此成員函式會實作 Win32 訊息 SB_GETTIPTEXT的行為，如 Windows SDK 中所述。

範例

CString csPane0TipText = m_wndSBC.GetTipText(0);

CStatusBarCtrl：：IsSimple

檢查狀態視窗控制件，以判斷它是否處於簡單模式。

BOOL IsSimple() const;

傳回值

如果狀態視窗控制件處於簡單模式，則為非零;否則為零。

備註

此成員函式會實作 Win32 訊息 SB_ISSIMPLE的行為，如 Windows SDK 中所述。

CStatusBarCtrl：：SetBkColor

設定狀態列中的背景色彩。

COLORREF SetBkColor(COLORREF cr);

參數

鉻
指定新背景色彩的 COLORREF 值。指定CLR_DEFAULT值，讓狀態列使用其預設背景色彩。

傳回值

代表先前預設背景色彩的 COLORREF 值。

備註

此成員函式會實作 Win32 訊息 SB_SETBKCOLOR的行為，如 Windows SDK 中所述。

範例

m_wndSBC.SetBkColor(RGB(0, 0, 250));

HICON hIcon = AfxGetApp()->LoadIcon(IDI_PANE_0_ICON);
VERIFY(hIcon);
VERIFY(m_wndSBC.SetIcon(0, hIcon));

CStatusBarCtrl：：SetIcon

設定狀態列中窗格的圖示。

BOOL SetIcon(
    int nPane,
    HICON hIcon);

參數

nPane
將接收圖示之窗格之以零起始的索引。如果此參數是 -1，則狀態列會假設為簡單的狀態列。

hIcon
要設定之圖示的句柄。如果此值為 NULL，則會從元件中移除圖示。

傳回值

如果成功則不為零，否則為 0。

備註

此成員函式會實作 Win32 訊息 SB_SETICON的行為，如 Windows SDK 中所述。

範例

請參閱 CStatusBarCtrl：：SetBkColor 的範例。

CStatusBarCtrl：：SetMinHeight

設定狀態列控件繪圖區域的最低高度。

void SetMinHeight(int nMin);

參數

nMin
控件的最小高度，以像素為單位。

備註

最小高度是 nMin 的總和，而寬度是狀態列控件垂直框線的圖元兩倍。

範例

m_wndSBC.SetMinHeight(40);

CStatusBarCtrl：：SetParts

設定狀態列控制件中的元件數目，以及每個元件右邊緣的座標。

BOOL SetParts(
    int nParts,
    int* pWidths);

參數

nParts
要設定的元件數目。元件數目不能大於 255。

pWidths
整數數位的位址，其項目數目與 nParts 所指定的元件相同。數位列中的每個元素都會指定對應元件右邊緣的位置，以用戶端座標為單位。如果元素是 - 1，該部分的右邊緣位置會延伸至控件的右邊緣。

傳回值

如果成功則不為零，否則為 0。

範例

const int c_nParts = 4;
CRect rect;

m_wndSBC.GetClientRect(&rect);
int aWidths[c_nParts] = {rect.right - 300, rect.right - 200, rect.right - 100,
                         -1};

VERIFY(m_wndSBC.SetParts(c_nParts, aWidths));

CStatusBarCtrl：：SetSimple

指定狀態列控制項是否顯示簡單文字，或顯示先前呼叫 SetParts 所設定的所有控制元件。

BOOL SetSimple(BOOL bSimple = TRUE);

參數

bSimple
[in]顯示類型旗標。如果此參數為TRUE，控件會顯示簡單的文字;如果為 FALSE，則會顯示多個元件。

傳回值

永遠傳回 0。

備註

如果您的應用程式將狀態列控件從非簡單變更為簡單，反之亦然，系統會立即重新繪製控件。

CStatusBarCtrl：：SetText

在狀態列控制項的指定部分設定文字。

BOOL SetText(
    LPCTSTR lpszText,
    int nPane,
    int nType);

參數

lpszText
以 Null 結束的字串位址，其指定要設定的文字。如果 nType 是SBT_OWNERDRAW，lpszText 代表 32 位的數據。

nPane
要設定之部分的以零為起始的索引。如果此值為 255，則假設狀態列控制項是只有一個部分的簡單控制項。

nType
繪圖作業的類型。如需可能值的清單，請參閱 SB_SETTEXT訊息。

傳回值

如果成功則不為零，否則為 0。

備註

當控件下次收到WM_PAINT訊息時，訊息會使控件的部分變更失效，導致它顯示新的文字。

範例

VERIFY(m_wndSBC.SetText(_T("Text For Pane 1"), 1, 0));

CStatusBarCtrl：：SetTipText

設定狀態列中窗格的工具提示文字。

void SetTipText(
    int nPane,
    LPCTSTR pszTipText);

參數

nPane
要接收工具提示文字的狀態列窗格以零起始的索引。

pszTipText
包含工具提示文字之字串的指標。

備註

此成員函式會實作 Win32 訊息 SB_SETTIPTEXT的行為，如 Windows SDK 中所述。

範例

m_wndSBC.SetTipText(0, _T("This is Pane 0"));

另請參閱

CWnd 類別
 階層架構圖表
 CToolBarCtrl 類別

共用方式為

CStatusBarCtrl 類別

語法

成員

公用建構函式

公用方法

備註

繼承階層架構

需求

CStatusBarCtrl：：Create

參數

傳回值

備註

範例

CStatusBarCtrl：：CreateEx

參數

傳回值

備註

CStatusBarCtrl：：CStatusBarCtrl

CStatusBarCtrl：:D rawItem

參數

備註

CStatusBarCtrl：：GetBorders

參數

傳回值

備註

範例

CStatusBarCtrl：：GetIcon

參數

傳回值

備註

範例

CStatusBarCtrl：：GetParts

參數

傳回值

備註

範例

CStatusBarCtrl：：GetRect

參數

傳回值

範例

CStatusBarCtrl：：GetText

參數

傳回值

範例

CStatusBarCtrl：：GetTextLength

參數

傳回值

範例

CStatusBarCtrl：：GetTipText

參數

傳回值

備註

範例

CStatusBarCtrl：：IsSimple

傳回值

備註

CStatusBarCtrl：：SetBkColor

參數

傳回值

備註

範例

CStatusBarCtrl：：SetIcon

參數

傳回值

備註

範例

CStatusBarCtrl：：SetMinHeight

參數

備註

範例

CStatusBarCtrl：：SetParts

參數

傳回值

範例

CStatusBarCtrl：：SetSimple

參數

傳回值

備註

CStatusBarCtrl：：SetText