CStatusBarCtrl 類別
提供 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 。
繼承階層架構
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樣式。
矩形
指定狀態列控制項的大小和位置。 它可以是 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 參數 。
dwStyle
指定狀態列控制項的樣式。 套用 Windows SDK 中通用控制項樣式 中列出的 狀態列控制項樣式的任何組合。 此參數必須包含WS_CHILD樣式。 它也應該包含WS_VISIBLE樣式。
矩形
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);
參數
鉻
指定新背景色彩的 COLORRE光圈值。 指定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"));
另請參閱
意見反應
即將登場：在 2024 年，我們將逐步淘汰 GitHub 問題作為內容的意見反應機制，並將它取代為新的意見反應系統。 如需詳細資訊，請參閱：https://aka.ms/ContentUserFeedback。
提交並檢視相關的意見反應