CStatusBarCtrl, classe

Article
10/12/2023

Fournit les fonctionnalités du contrôle commun de barre d'état Windows.

Syntaxe

class CStatusBarCtrl : public CWnd

Membres

Constructeurs publics

Nom	Description
CStatusBarCtrl ::CStatusBarCtrl	Construit un objet `CStatusBarCtrl`.

Méthodes publiques

Nom	Description
CStatusBarCtrl ::Create	Crée un contrôle de barre d’état et l’attache à un `CStatusBarCtrl` objet.
CStatusBarCtrl ::CreateEx	Crée un contrôle de barre d’état avec les styles étendus Windows spécifiés et l’attache à un `CStatusBarCtrl` objet.
CStatusBarCtrl ::D rawItem	Appelé lorsqu’un aspect visuel d’un contrôle de barre d’état de dessin propriétaire change.
CStatusBarCtrl ::GetBorders	Récupère les largeurs actuelles des bordures horizontales et verticales d’un contrôle de barre d’état.
CStatusBarCtrl ::GetIcon	Récupère l’icône d’une partie (également appelée volet) dans le contrôle de barre d’état actuel.
CStatusBarCtrl ::GetParts	Récupère un nombre de parties dans un contrôle de barre d’état.
CStatusBarCtrl ::GetRect	Récupère le rectangle englobant d’une partie dans un contrôle de barre d’état.
CStatusBarCtrl ::GetText	Récupère le texte de la partie donnée d’un contrôle de barre d’état.
CStatusBarCtrl ::GetTextLength	Récupérez la longueur, en caractères, du texte de la partie donnée d’un contrôle de barre d’état.
CStatusBarCtrl ::GetTipText	Récupère le texte d’info-bulle d’un volet dans une barre d’état.
CStatusBarCtrl ::IsSimple	Vérifie un contrôle de fenêtre d’état pour déterminer s’il est en mode simple.
CStatusBarCtrl ::SetBkColor	Définit la couleur d’arrière-plan dans une barre d’état.
CStatusBarCtrl ::SetIcon	Définit l’icône d’un volet dans une barre d’état.
CStatusBarCtrl ::SetMinHeight	Définit la hauteur minimale de la zone de dessin d’un contrôle de barre d’état.
CStatusBarCtrl ::SetParts	Définit le nombre de parties dans un contrôle de barre d’état et la coordonnée du bord droit de chaque partie.
CStatusBarCtrl ::SetSimple	Spécifie si un contrôle de barre d’état affiche du texte simple ou affiche toutes les parties de contrôle définies par un appel précédent à `SetParts`.
CStatusBarCtrl ::SetText	Définit le texte dans la partie spécifiée d'un contrôle de barre d'état.
CStatusBarCtrl ::SetTipText	Définit le texte d’info-bulle d’un volet dans une barre d’état.

Notes

Un « contrôle de barre d’état » est une fenêtre horizontale, généralement affichée en bas d’une fenêtre parente, dans laquelle une application peut afficher différents types d’informations d’état. Le contrôle de barre d’état peut être divisé en parties pour afficher plusieurs types d’informations.

Ce contrôle (et par conséquent la CStatusBarCtrl classe) est disponible uniquement pour les programmes exécutés sous Windows 95/98 et Windows NT version 3.51 et ultérieure.

Pour plus d’informations sur l’utilisation CStatusBarCtrl, consultez Contrôles et utilisation de CStatusBarCtrl.

Hiérarchie d'héritage

CObject

CCmdTarget

CWnd

CStatusBarCtrl

Spécifications

En-tête : afxcmn.h

CStatusBarCtrl ::Create

Crée un contrôle de barre d’état et l’attache à un CStatusBarCtrl objet.

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

Paramètres

dwStyle
Spécifie le style du contrôle de barre d’état. Appliquez n’importe quelle combinaison de styles de contrôle de barre d’état répertoriés dans Les styles de contrôle communs dans le Kit de développement logiciel (SDK) Windows. Ce paramètre doit inclure le style WS_CHILD. Il doit également inclure le style WS_VISIBLE.

rect
Spécifie la taille et la position du contrôle de barre d’état. Il peut s’agir d’un objet CRect ou d’une structure RECT .

pParentWnd
Spécifie la fenêtre parente du contrôle de barre d’état, généralement un CDialog. Elle ne doit pas être NULL.

nID
Spécifie l’ID du contrôle de barre d’état.

Valeur de retour

Valeur différente de zéro en cas de réussite ; sinon, zéro.

Notes

Vous construisez une CStatusBarCtrl étape en deux étapes. Tout d’abord, appelez le constructeur, puis appelez Create, qui crée le contrôle de barre d’état et l’attache à l’objet CStatusBarCtrl .

La position par défaut d’une fenêtre d’état est le long du bas de la fenêtre parente, mais vous pouvez spécifier le style CCS_TOP pour qu’il apparaisse en haut de la zone cliente de la fenêtre parente. Vous pouvez spécifier le style SBARS_SIZEGRIP pour inclure une poignée de dimensionnement à l’extrémité droite de la fenêtre d’état. La combinaison des styles CCS_TOP et SBARS_SIZEGRIP n’est pas recommandée, car la poignée de dimensionnement résultante n’est pas fonctionnelle même si le système le dessine dans la fenêtre d’état.

Pour créer une barre d’état avec des styles de fenêtre étendus, appelez CStatusBarCtrl ::CreateEx au lieu de Create.

Exemple

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

CStatusBarCtrl ::CreateEx

Crée un contrôle (fenêtre enfant) et l’associe à l’objet CStatusBarCtrl .

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

Paramètres

dwExStyle
Spécifie le style étendu du contrôle en cours de création. Pour obtenir la liste des styles Windows étendus, consultez le paramètre dwExStyle pour CreateWindowEx dans le Kit de développement logiciel (SDK) Windows.

rect
Référence à une structure RECT décrivant la taille et la position de la fenêtre à créer, dans les coordonnées clientes de pParentWnd.

pParentWnd
Pointeur vers la fenêtre qui est le parent du contrôle.

nID
ID de la fenêtre enfant du contrôle.

Valeur de retour

Valeur différente de zéro cas de réussite ; sinon, 0.

Notes

Utilisez CreateEx plutôt que Créer pour appliquer des styles Windows étendus, spécifiés par le préface de style étendu Windows WS_EX_.

CStatusBarCtrl ::CStatusBarCtrl

Construit un objet CStatusBarCtrl.

CStatusBarCtrl();

CStatusBarCtrl ::D rawItem

Appelé par l’infrastructure lorsqu’un aspect visuel d’un contrôle de barre d’état de dessin propriétaire change.

virtual void DrawItem(LPDRAWITEMSTRUCT lpDrawItemStruct);

Paramètres

lpDrawItemStruct
Pointeur long vers une structure DRAWITEMSTRUCT qui contient des informations sur le type de dessin requis.

Notes

Le itemAction membre de la DRAWITEMSTRUCT structure définit l’action de dessin à effectuer.

Par défaut, cette fonction membre ne fait rien. Remplacez cette fonction membre pour implémenter le dessin pour un objet de dessin CStatusBarCtrl propriétaire.

L’application doit restaurer tous les objets GDI (Graphics Device Interface) sélectionnés pour le contexte d’affichage fourni dans lpDrawItemStruct avant que cette fonction membre ne se termine.

CStatusBarCtrl ::GetBorders

Récupère les largeurs actuelles du contrôle de barre d’état des bordures horizontales et verticales et de l’espace entre les rectangles.

BOOL GetBorders(int* pBorders) const;

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

Paramètres

pBorders
Adresse d’un tableau entier ayant trois éléments. Le premier élément reçoit la largeur de la bordure horizontale, le second reçoit la largeur de la bordure verticale, et le troisième reçoit la largeur de la bordure entre les rectangles.

nHorz
Référence à un entier qui reçoit la largeur de la bordure horizontale.

nVert
Référence à un entier qui reçoit la largeur de la bordure verticale.

nSpacing
Référence à un entier qui reçoit la largeur de la bordure entre les rectangles.

Valeur de retour

Valeur différente de zéro en cas de réussite ; sinon, zéro.

Notes

Ces bordures déterminent l’espacement entre le bord extérieur du contrôle et les rectangles du contrôle qui contiennent du texte.

Exemple

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

Récupère l’icône d’une partie (également appelée volet) dans le contrôle de barre d’état actuel.

HICON GetIcon(int iPart) const;

Paramètres

iPart
[in] Index de base zéro du composant qui contient l’icône à récupérer. Si ce paramètre est -1, la barre d’état est supposée être une barre d’état en mode simple.

Valeur de retour

Handle sur l’icône si la méthode réussit ; sinon, NULL.

Notes

Cette méthode envoie le message SB_GETICON , qui est décrit dans le Kit de développement logiciel (SDK) Windows.

Un contrôle de barre d’état se compose d’une ligne de volets de sortie de texte, également appelés parties. Pour plus d’informations sur la barre d’état, consultez Implémentation de barre d’état dans MFC et définition du mode d’un objet CStatusBarCtrl.

Exemple

Le premier exemple de code définit une variable, m_statusBarutilisée pour accéder au contrôle de barre d’état actuel. Cette variable est utilisée dans l'exemple suivant.

public:
CStatusBarCtrl m_statusBar;

L’exemple de code suivant copie une icône dans deux volets du contrôle de barre d’état actuel. Dans une section précédente de l’exemple de code, nous avons créé un contrôle de barre d’état avec trois volets, puis ajouté une icône au premier volet. Cet exemple récupère l’icône du premier volet, puis l’ajoute au deuxième et au troisième volet.

// 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

Récupère un nombre de parties dans un contrôle de barre d’état.

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

Paramètres

nParts
Nombre de parties pour lesquelles récupérer des coordonnées. Si ce paramètre est supérieur au nombre de parties dans le contrôle, le message récupère les coordonnées des parties existantes uniquement.

pParts
Adresse d’un tableau entier ayant le même nombre d’éléments que le nombre de parties spécifiées par nParts. Chaque élément du tableau reçoit la coordonnée cliente du bord droit de la partie correspondante. Si un élément est défini sur - 1, la position du bord droit de cette partie s’étend au bord droit de la barre d’état.

Valeur de retour

Nombre de parties dans le contrôle en cas de réussite ou zéro dans le cas contraire.

Notes

Cette fonction membre récupère également la coordonnée du bord droit du nombre donné de parties.

Exemple

int pParts[2];

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

CStatusBarCtrl ::GetRect

Récupère le rectangle englobant d’une partie dans un contrôle de barre d’état.

BOOL GetRect(
    int nPane,
    LPRECT lpRect) const;

Paramètres

nPane
Index de base zéro de la partie dont le rectangle englobant doit être récupéré.

lpRect
Adresse d’une structure RECT qui reçoit le rectangle englobant.

Valeur de retour

Valeur différente de zéro en cas de réussite ; sinon, zéro.

Exemple

CRect rectPane1;

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

CStatusBarCtrl ::GetText

Récupère le texte de la partie donnée d’un contrôle de barre d’état.

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

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

Paramètres

lpszText
Adresse de la mémoire tampon qui reçoit le texte. Ce paramètre est une chaîne terminée par null.

nPane
Index de base zéro de la partie à partir duquel récupérer du texte.

pType
Pointeur vers un entier qui reçoit les informations de type. Le type peut être l’une des valeurs suivantes :

0 Le texte est dessiné avec une bordure à afficher inférieure au plan de la barre d’état.
SBT_NOBORDERS Le texte est dessiné sans bordures.
SBT_POPOUT Le texte est dessiné avec une bordure pour apparaître plus haut que le plan de la barre d’état.
SBT_OWNERDRAW Si le texte a le type de dessin SBT_OWNERDRAW, pType reçoit ce message et retourne la valeur 32 bits associée au texte au lieu de la longueur et du type d’opération.

Valeur de retour

Longueur, en caractères, du texte ou d’une CString contenant le texte actif.

Exemple

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

Récupère la longueur, en caractères, du texte de la partie donnée d’un contrôle de barre d’état.

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

Paramètres

nPane
Index de base zéro de la partie à partir duquel récupérer du texte.

pType
Pointeur vers un entier qui reçoit les informations de type. Le type peut être l’une des valeurs suivantes :

0 Le texte est dessiné avec une bordure à afficher inférieure au plan de la barre d’état.
SBT_NOBORDERS Le texte est dessiné sans bordures.
SBT_OWNERDRAW Le texte est dessiné par la fenêtre parente.
SBT_POPOUT Le texte est dessiné avec une bordure pour apparaître plus haut que le plan de la barre d’état.

Valeur de retour

Longueur, en caractères, du texte.

Exemple

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

Récupère le texte d’info-bulle d’un volet dans une barre d’état.

CString GetTipText(int nPane) const;

Paramètres

nPane
Index de base zéro du volet de barre d’état pour recevoir le texte de l’info-bulle.

Valeur de retour

Objet CString contenant le texte à utiliser dans l’info-bulle.

Notes

Cette fonction membre implémente le comportement du message Win32 SB_GETTIPTEXT, comme décrit dans le Kit de développement logiciel (SDK) Windows.

Exemple

CString csPane0TipText = m_wndSBC.GetTipText(0);

CStatusBarCtrl ::IsSimple

Vérifie un contrôle de fenêtre d’état pour déterminer s’il est en mode simple.

BOOL IsSimple() const;

Valeur de retour

Différent de zéro si le contrôle de fenêtre d’état est en mode simple ; sinon zéro.

Notes

Cette fonction membre implémente le comportement du message Win32 SB_ISSIMPLE, comme décrit dans le Kit de développement logiciel (SDK) Windows.

CStatusBarCtrl ::SetBkColor

Définit la couleur d’arrière-plan dans une barre d’état.

COLORREF SetBkColor(COLORREF cr);

Paramètres

cr
Valeur COLORREF qui spécifie la nouvelle couleur d’arrière-plan. Spécifiez la valeur CLR_DEFAULT pour que la barre d’état utilise sa couleur d’arrière-plan par défaut.

Valeur de retour

Valeur COLORREF qui représente la couleur d’arrière-plan par défaut précédente.

Notes

Cette fonction membre implémente le comportement du message Win32 SB_SETBKCOLOR, comme décrit dans le Kit de développement logiciel (SDK) Windows.

Exemple

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

Définit l’icône d’un volet dans une barre d’état.

BOOL SetIcon(
    int nPane,
    HICON hIcon);

Paramètres

nPane
Index de base zéro du volet qui recevra l’icône. Si ce paramètre est -1, la barre d’état est supposée être une barre d’état simple.

hIcon
Gérez l’icône à définir. Si cette valeur est NULL, l’icône est supprimée de la partie.

Valeur de retour

Valeur différente de zéro en cas de réussite ; sinon, zéro.

Notes

Cette fonction membre implémente le comportement du message Win32 SB_SETICON, comme décrit dans le Kit de développement logiciel (SDK) Windows.

Exemple

Consultez l’exemple de CStatusBarCtrl ::SetBkColor.

CStatusBarCtrl ::SetMinHeight

Définit la hauteur minimale de la zone de dessin d’un contrôle de barre d’état.

void SetMinHeight(int nMin);

Paramètres

nMin
Hauteur minimale, en pixels, du contrôle.

Notes

La hauteur minimale est la somme de nMin et deux fois la largeur, en pixels, de la bordure verticale du contrôle de barre d’état.

Exemple

m_wndSBC.SetMinHeight(40);

CStatusBarCtrl ::SetParts

Définit le nombre de parties dans un contrôle de barre d’état et la coordonnée du bord droit de chaque partie.

BOOL SetParts(
    int nParts,
    int* pWidths);

Paramètres

nParts
Nombre de parties à définir. Le nombre de parties ne peut pas être supérieur à 255.

pWidths
Adresse d’un tableau entier ayant le même nombre d’éléments que les parties spécifiées par nParts. Chaque élément du tableau spécifie la position, dans les coordonnées du client, du bord droit de la partie correspondante. Si un élément est - 1, la position du bord droit de cette partie s’étend au bord droit du contrôle.

Valeur de retour

Valeur différente de zéro en cas de réussite ; sinon, zéro.

Exemple

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

Spécifie si un contrôle de barre d’état affiche du texte simple ou affiche tous les composants de contrôle définis par un appel précédent à SetParts.

BOOL SetSimple(BOOL bSimple = TRUE);

Paramètres

bSimple
[in] Indicateur de type d’affichage. Si ce paramètre a la valeur TRUE, le contrôle affiche du texte simple ; s’il s’agit de FALSE, il affiche plusieurs parties.

Valeur de retour

Retourne toujours 0.

Notes

Si votre application modifie le contrôle de barre d’état d’un contrôle non simple à simple ou inversement, le système redessine immédiatement le contrôle.

CStatusBarCtrl ::SetText

Définit le texte dans la partie spécifiée d'un contrôle de barre d'état.

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

Paramètres

lpszText
Adresse d'une chaîne se terminant par null spécifiant le texte à définir. Si nType est SBT_OWNERDRAW, lpszText représente 32 bits de données.

nPane
Index de base zéro de la partie à définir. Si cette valeur est égale à 255, le contrôle de barre d'état est considéré comme un simple contrôle constitué d'une seule partie.

nType
Type d'opération de dessin. Consultez SB_SETTEXT message pour obtenir la liste des valeurs possibles.

Valeur de retour

Valeur différente de zéro en cas de réussite ; sinon, zéro.

Notes

Le message invalide la partie du contrôle qui a changé, ce qui lui permet d’afficher le nouveau texte lorsque le contrôle reçoit ensuite le message WM_PAINT.

Exemple

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

CStatusBarCtrl ::SetTipText

Définit le texte d’info-bulle d’un volet dans une barre d’état.

void SetTipText(
    int nPane,
    LPCTSTR pszTipText);

Paramètres

nPane
Index de base zéro du volet de barre d’état pour recevoir le texte de l’info-bulle.

pszTipText
Pointeur vers une chaîne contenant le texte de l’info-bulle.

Notes

Cette fonction membre implémente le comportement du message Win32 SB_SETTIPTEXT, comme décrit dans le Kit de développement logiciel (SDK) Windows.

Exemple

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

Voir aussi

CWnd, classe
Graphique hiérarchique
CToolBarCtrl, classe

Partager via

CStatusBarCtrl, classe

Syntaxe

Membres

Constructeurs publics

Méthodes publiques

Notes

Hiérarchie d'héritage

Spécifications

CStatusBarCtrl ::Create

Paramètres

Valeur de retour

Notes

Exemple

CStatusBarCtrl ::CreateEx

Paramètres

Valeur de retour

Notes

CStatusBarCtrl ::CStatusBarCtrl

CStatusBarCtrl ::D rawItem

Paramètres

Notes

CStatusBarCtrl ::GetBorders

Paramètres

Valeur de retour

Notes

Exemple

CStatusBarCtrl ::GetIcon

Paramètres

Valeur de retour

Notes

Exemple

CStatusBarCtrl ::GetParts

Paramètres

Valeur de retour

Notes

Exemple

CStatusBarCtrl ::GetRect

Paramètres

Valeur de retour

Exemple

CStatusBarCtrl ::GetText

Paramètres

Valeur de retour

Exemple

CStatusBarCtrl ::GetTextLength

Paramètres

Valeur de retour

Exemple

CStatusBarCtrl ::GetTipText

Paramètres

Valeur de retour

Notes

Exemple

CStatusBarCtrl ::IsSimple

Valeur de retour

Notes

CStatusBarCtrl ::SetBkColor

Paramètres

Valeur de retour

Notes

Exemple

CStatusBarCtrl ::SetIcon

Paramètres

Valeur de retour

Notes

Exemple

CStatusBarCtrl ::SetMinHeight

Paramètres

Notes

Exemple

CStatusBarCtrl ::SetParts

Paramètres

Valeur de retour

Exemple

CStatusBarCtrl ::SetSimple

Paramètres

Valeur de retour

Notes

CStatusBarCtrl ::SetText