CStatusBarCtrl (clase)

Artículo
06/16/2023

Proporciona la funcionalidad del control de barra de estado común de Windows.

Sintaxis

class CStatusBarCtrl : public CWnd

Miembros

Constructores públicos

Nombre	Descripción
CStatusBarCtrl::CStatusBarCtrl	Construye un objeto `CStatusBarCtrl`.

Métodos públicos

Nombre	Descripción
CStatusBarCtrl::Create	Crea un control de la barra de estado y lo adjunta a un objeto `CStatusBarCtrl`.
CStatusBarCtrl::CreateEx	Crea un control de la barra de estado con los estilos extendidos de Windows especificados y lo adjunta a un objeto `CStatusBarCtrl`.
CStatusBarCtrl::DrawItem	Se llama cuando cambia la apariencia de una barra de estado dibujada por el usuario.
CStatusBarCtrl::GetBorders	Recupera los anchos actuales de los bordes horizontales y verticales de un control de barra de estado.
CStatusBarCtrl::GetIcon	Recupera el icono de un elemento (también conocido como panel) en el control de la barra de estado actual.
CStatusBarCtrl::GetParts	Recupera un recuento de los elementos de un control de la barra de estado.
CStatusBarCtrl::GetRect	Recupera el rectángulo delimitador de un elemento en un control de barra de estado.
CStatusBarCtrl::GetText	Recupera el texto de un elemento determinado de un control de barra de estado.
CStatusBarCtrl::GetTextLength	Recupera la longitud, en caracteres, del texto de la parte especificada de un control de barra de estado.
CStatusBarCtrl::GetTipText	Recupera el texto de la información sobre herramientas de un panel en una barra de estado.
CStatusBarCtrl::IsSimple	Comprueba un control de ventana de estado para determinar si está en modo simple.
CStatusBarCtrl::SetBkColor	Establece el color de fondo en una barra de estado.
CStatusBarCtrl::SetIcon	Establece el icono de un panel en una barra de estado.
CStatusBarCtrl::SetMinHeight	Establece el alto mínimo del área de dibujo de un control de barra de estado.
CStatusBarCtrl::SetParts	Establece el número de partes de un control de barra de estado y la coordenada del borde derecho de cada parte.
CStatusBarCtrl::SetSimple	Especifica si un control de barra de estado muestra texto simple o muestra todos los elementos de control establecidos por una llamada anterior a `SetParts`.
CStatusBarCtrl::SetText	Establece el texto en un elemento determinado de un control de barra de estado.
CStatusBarCtrl::SetTipText	Establece el texto de la información sobre herramientas de un panel en una barra de estado.

Comentarios

Un «control de barra de estado» es una ventana horizontal, que habitualmente se muestra en la parte inferior de una ventana, en la que una aplicación puede mostrar información de estado de diferentes tipos. El control de barra de estado se puede dividir en partes para mostrar más de un tipo de información.

Este control (y, por tanto, la clase CStatusBarCtrl) solo está disponible para los programas que se ejecutan en Windows 95/98 y Windows NT 3.51 y posteriores.

Para más información sobre el uso de CStatusBarCtrl, consulte Controles y Uso de CStatusBarCtrl.

Jerarquía de herencia

CObject

CCmdTarget

CWnd

CStatusBarCtrl

Requisitos

Encabezado: afxcmn.h

CStatusBarCtrl::Create

Crea un control de la barra de estado y lo adjunta a un objeto CStatusBarCtrl.

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

Parámetros

dwStyle
Especifica el estilo del control de barra de estado. Aplique cualquier combinación de estilos de control de barra de estado enumerados en Estilos de control comunes en Windows SDK. Este parámetro debe incluir el estilo WS_CHILD. También debe incluir el estilo de WS_VISIBLE.

rect
Especifica el tamaño y la posición del control de barra de estado. Puede ser un objeto CRect o una estructura RECT.

pParentWnd
El valor de este parámetro se usa para especificar la ventana primaria del control de información sobre la barra de estado, que suele ser un elemento CDialog. No debe ser NULL.

Nid
Especifica el id. del control de barra de estado.

Valor devuelto

Es distinto de cero si es correcto. En caso contrario, es cero.

Comentarios

El proceso de construcción de un elemento CStatusBarCtrl se divide en dos pasos. En primer lugar, llame al constructor y, luego, a Create, lo que crea el control de barra de estado y lo asocia al objeto CStatusBarCtrl.

La posición predeterminada de una ventana de estado se encuentra en la parte inferior de la ventana primaria, pero puede especificar el estilo de CCS_TOP para que aparezca en la parte superior del área cliente de la ventana primaria. Puede especificar el estilo de SBARS_SIZEGRIP para incluir un control de tamaño en el extremo derecho de la ventana de estado. No se recomienda combinar los estilos CCS_TOP y SBARS_SIZEGRIP, ya que el agarre de tamaño resultante no es funcional aunque el sistema lo dibuja en la ventana de estado.

Para crear una barra de estado con estilos de ventana extendidos, llame a CStatusBarCtrl::CreateEx en lugar de Create.

Ejemplo

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

CStatusBarCtrl::CreateEx

Esta función puede usarse para crear un control (una ventana secundaria) y asociarlo con el objeto CStatusBarCtrl.

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

Parámetros

dwExStyle
El valor de este parámetro se usa para especificar el estilo extendido del control que se va a crear. Para ver una lista de estilos extendidos de Windows, consulte el parámetro dwExStyle para CreateWindowEx en Windows SDK.

rect
Referencia a una estructura RECT que describe el tamaño y la posición de la ventana que se va a crear, en coordenadas de cliente de pParentWnd.

pParentWnd
Un puntero a la ventana que constituye el elemento primario del control.

Nid
El identificador de ventana secundaria del control.

Valor devuelto

Si es correcta, su valor es distinto de cero. En caso contrario, es cero.

Comentarios

Use CreateEx en lugar de Create para aplicar estilos extendidos de Windows, especificados por el prefacio de estilo extendido de Windows WS_EX_.

CStatusBarCtrl::CStatusBarCtrl

Construye un objeto CStatusBarCtrl.

CStatusBarCtrl();

CStatusBarCtrl::DrawItem

Se llama al marco cuando cambia la apariencia de una barra de estado dibujada por el usuario.

virtual void DrawItem(LPDRAWITEMSTRUCT lpDrawItemStruct);

Parámetros

lpDrawItemStruct
Puntero largo a una estructura DRAWITEMSTRUCT que contiene información sobre el tipo de dibujo necesario.

Comentarios

El miembro itemAction de la estructura DRAWITEMSTRUCT define la acción de dibujo que se realizará.

De manera predeterminada, esta función miembro no hace nada. Invalida esta función miembro para implementar el dibujo de un objeto CStatusBarCtrl dibujado por el propietario.

La aplicación debe restaurar todos los objetos de Interfaz de dispositivo gráfico (GDI) seleccionados para el contexto de presentación proporcionado en lpDrawItemStruct antes de que finalice esta función miembro.

CStatusBarCtrl::GetBorders

Recupera los anchos actuales del control de barra de estado de los bordes horizontales y verticales y del espacio entre rectángulos.

BOOL GetBorders(int* pBorders) const;

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

Parámetros

pBorders
Dirección de una matriz de enteros que tiene tres elementos. El primer elemento recibe el ancho del borde horizontal, el segundo recibe el ancho del borde vertical y el tercero recibe el ancho del borde entre rectángulos.

nHorz
Referencia a un entero que recibe el ancho del borde horizontal.

nVert
Referencia a un entero que recibe el ancho del borde vertical.

nSpacing
Referencia a un entero que recibe el ancho del borde entre rectángulos.

Valor devuelto

Es distinto de cero si es correcto. En caso contrario, es cero.

Comentarios

Estos bordes determinan el espaciado entre el borde exterior del control y los rectángulos dentro del control que contienen texto.

Ejemplo

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

Recupera el icono de un elemento (también conocido como panel) en el control de la barra de estado actual.

HICON GetIcon(int iPart) const;

Parámetros

iPart
[in] Índice de base cero del elemento que contiene el icono que se va a recuperar. Si este parámetro es -1, se supone que la barra de estado es una barra de estado de modo simple.

Valor devuelto

Identificador del icono si el método se ejecuta correctamente; de lo contrario, NULL.

Comentarios

Al usar este método, se envía el mensaje SB_GETICON, que se describe en Windows SDK.

Un control de barra de estado consta de una fila de paneles de salida de texto, que también se conocen como partes. Para obtener más información sobre la barra de estado, vea Implementación de la barra de estado en MFC y Establecer el modo de un objeto CStatusBarCtrl.

Ejemplo

En el primer ejemplo de código se define una variable, m_statusBar, que se usa para acceder al control de barra de estado actual. Esta variable se utiliza en el siguiente ejemplo.

public:
CStatusBarCtrl m_statusBar;

En el ejemplo de código siguiente se copia un icono en dos paneles del control de barra de estado actual. En una sección anterior del ejemplo de código hemos creado un control de barra de estado con tres paneles y, a continuación, hemos agregado un icono al primer panel. En este ejemplo se recupera el icono del primer panel y, a continuación, se agrega al segundo y tercer panel.

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

Recupera un recuento de los elementos de un control de la barra de estado.

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

Parámetros

nParts
Número de partes para las que se van a recuperar las coordenadas. Si este parámetro es mayor que el número de partes del control, el mensaje recupera solo las coordenadas de las partes existentes.

pParts
Dirección de una matriz de enteros que tiene el mismo número de elementos que el número de partes especificadas por nParts. Cada elemento de la matriz recibe la coordenada del cliente del borde derecho de la parte correspondiente. Si un elemento se establece en - 1, la posición del borde derecho de esa parte se extiende al borde derecho de la barra de estado.

Valor devuelto

Número de partes del control si se ejecuta correctamente o cero de lo contrario.

Comentarios

Esta función miembro también recupera la coordenada del borde derecho del número determinado de partes.

Ejemplo

int pParts[2];

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

CStatusBarCtrl::GetRect

Recupera el rectángulo delimitador de un elemento en un control de barra de estado.

BOOL GetRect(
    int nPane,
    LPRECT lpRect) const;

Parámetros

nPane
Índice de base cero de la parte cuyo rectángulo delimitador se va a recuperar.

lpRect
Dirección de una estructura RECT que recibe el rectángulo delimitador.

Valor devuelto

Es distinto de cero si es correcto. En caso contrario, es cero.

Ejemplo

CRect rectPane1;

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

CStatusBarCtrl::GetText

Recupera el texto de un elemento determinado de un control de barra de estado.

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

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

Parámetros

lpszText
Dirección del búfer que recibe el texto. Este parámetro es una cadena terminada en null.

nPane
Índice de base cero del elemento desde el que se va a recuperar texto.

pType
Puntero a un entero que recibe la información de tipo. El tipo puede ser uno de estos valores:

0 El texto se dibuja con un borde que aparece inferior al plano de la barra de estado.
SBT_NOBORDERS El texto se dibuja sin bordes.
SBT_POPOUT El texto se dibuja con un borde para que aparezca más alto que el plano de la barra de estado.
SBT_OWNERDRAW Si el texto tiene el tipo de dibujo SBT_OWNERDRAW, pType recibe este mensaje y devuelve el valor de 32 bits asociado al texto en lugar del tipo de operación y longitud.

Valor devuelto

Longitud, en caracteres, del texto o de un CString que contiene el texto actual.

Ejemplo

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

Recupera la longitud, en caracteres, del texto de la parte especificada de un control de barra de estado.

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

Parámetros

nPane
Índice de base cero del elemento desde el que se va a recuperar texto.

pType
Puntero a un entero que recibe la información de tipo. El tipo puede ser uno de estos valores:

0 El texto se dibuja con un borde que aparece inferior al plano de la barra de estado.
SBT_NOBORDERS El texto se dibuja sin bordes.
SBT_OWNERDRAW La ventana primaria dibuja el texto.
SBT_POPOUT El texto se dibuja con un borde para que aparezca más alto que el plano de la barra de estado.

Valor devuelto

Longitud del texto en caracteres.

Ejemplo

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

Recupera el texto de la información sobre herramientas de un panel en una barra de estado.

CString GetTipText(int nPane) const;

Parámetros

nPane
Índice de base cero del panel de la barra de estado para recibir el texto de la información sobre herramientas.

Valor devuelto

Objeto CString que contiene el texto que se va a usar en la información sobre herramientas.

Comentarios

En esta función miembro, se implementa el comportamiento del mensaje SB_GETTIPTEXT de Win32, tal y como se describe en Windows SDK.

Ejemplo

CString csPane0TipText = m_wndSBC.GetTipText(0);

CStatusBarCtrl::IsSimple

Comprueba un control de ventana de estado para determinar si está en modo simple.

BOOL IsSimple() const;

Valor devuelto

Distinto de cero si el control de ventana de estado está en modo simple; de lo contrario, cero.

Comentarios

En esta función miembro, se implementa el comportamiento del mensaje SB_ISSIMPLE de Win32, tal y como se describe en Windows SDK.

CStatusBarCtrl::SetBkColor

Establece el color de fondo en una barra de estado.

COLORREF SetBkColor(COLORREF cr);

Parámetros

cr
Un valor COLORREF que especifica el nuevo color de fondo. Especifique el valor de CLR_DEFAULT para que la barra de estado use su color de fondo predeterminado.

Valor devuelto

Valor COLORREF que representa el color de fondo predeterminado anterior.

Comentarios

Esta función miembro implementa el comportamiento del mensaje SB_SETBKCOLOR de Win32, tal y como se describe en Windows SDK.

Ejemplo

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

Establece el icono de un panel en una barra de estado.

BOOL SetIcon(
    int nPane,
    HICON hIcon);

Parámetros

nPane
Índice de base cero del panel que recibirá el icono. Si este parámetro es -1, se supone que la barra de estado es una barra de estado simple.

hIcon
Identificador del icono que se vaya a establecer. Si este valor es NULL, el icono se quita de la parte.

Valor devuelto

Es distinto de cero si es correcto. En caso contrario, es cero.

Comentarios

Esta función miembro implementa el comportamiento del mensaje SB_SETICON de Win32, tal y como se describe en Windows SDK.

Ejemplo

Vea el ejemplo de CStatusBarCtrl::SetBkColor.

CStatusBarCtrl::SetMinHeight

Establece el alto mínimo del área de dibujo de un control de barra de estado.

void SetMinHeight(int nMin);

Parámetros

nMin
Altura mínima, en píxeles, del control.

Comentarios

El alto mínimo es la suma de nMin y dos veces el ancho, en píxeles, del borde vertical del control de barra de estado.

Ejemplo

m_wndSBC.SetMinHeight(40);

CStatusBarCtrl::SetParts

Establece el número de partes de un control de barra de estado y la coordenada del borde derecho de cada parte.

BOOL SetParts(
    int nParts,
    int* pWidths);

Parámetros

nParts
Número de partes que se van a establecer. El número de partes no puede ser mayor que 255.

pWidths
Dirección de una matriz de enteros que tiene el mismo número de elementos que las partes especificadas por nParts. Cada elemento de la matriz especifica la posición, en coordenadas de cliente, del borde derecho de la parte correspondiente. Si un elemento es - 1, la posición del borde derecho de esa parte se extiende al borde derecho del control.

Valor devuelto

Es distinto de cero si es correcto. En caso contrario, es cero.

Ejemplo

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

Especifica si un control de barra de estado muestra texto simple o muestra todos los elementos de control establecidos por una llamada anterior a SetParts.

BOOL SetSimple(BOOL bSimple = TRUE);

Parámetros

bSimple
[in] Marca de tipo de presentación. Si este parámetro es TRUE, el control muestra texto simple; si es FALSE, muestra varias partes.

Valor devuelto

Siempre devuelve 0.

Comentarios

Si la aplicación cambia el control de barra de estado de no simple a simple, o viceversa, el sistema vuelve a dibujar inmediatamente el control.

CStatusBarCtrl::SetText

Establece el texto en un elemento determinado de un control de barra de estado.

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

Parámetros

lpszText
Dirección de una cadena terminada en null que especifica el texto que se debe establecer. Si nType es SBT_OWNERDRAW, lpszText representa 32 bits de datos.

nPane
El índice de base cero del elemento que se debe establecer. Si este valor es 255, se asume que el control de barra de estado es un control simple que solo contiene un elemento.

nType
Tipo de operación de dibujo. Consulte el mensaje SB_SETTEXT para obtener una lista de valores posibles.

Valor devuelto

Es distinto de cero si es correcto. En caso contrario, es cero.

Comentarios

El mensaje invalida la parte del control que ha cambiado y se muestra el texto nuevo cuando el control siguiente recibe el mensaje VM_PAINT.

Ejemplo

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

CStatusBarCtrl::SetTipText

Establece el texto de la información sobre herramientas de un panel en una barra de estado.

void SetTipText(
    int nPane,
    LPCTSTR pszTipText);

Parámetros

nPane
Índice de base cero del panel de la barra de estado para recibir el texto de la información sobre herramientas.

pszTipText
Puntero a una cadena que contiene el texto de información sobre herramientas.

Comentarios

En esta función miembro, se implementa el comportamiento del mensaje SB_SETTIPTEXT de Win32, tal y como se describe en Windows SDK.

Ejemplo

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

Vea también

CWnd (clase)
Gráfico de jerarquías
CToolBarCtrl (clase)

Compartir vía

CStatusBarCtrl (clase)

Sintaxis

Miembros

Constructores públicos

Métodos públicos

Comentarios

Jerarquía de herencia

Requisitos

CStatusBarCtrl::Create

Parámetros

Valor devuelto

Comentarios

Ejemplo

CStatusBarCtrl::CreateEx

Parámetros

Valor devuelto

Comentarios

CStatusBarCtrl::CStatusBarCtrl

CStatusBarCtrl::DrawItem

Parámetros

Comentarios

CStatusBarCtrl::GetBorders

Parámetros

Valor devuelto

Comentarios

Ejemplo

CStatusBarCtrl::GetIcon

Parámetros

Valor devuelto

Comentarios

Ejemplo

CStatusBarCtrl::GetParts

Parámetros

Valor devuelto

Comentarios

Ejemplo

CStatusBarCtrl::GetRect

Parámetros

Valor devuelto

Ejemplo

CStatusBarCtrl::GetText

Parámetros

Valor devuelto

Ejemplo

CStatusBarCtrl::GetTextLength

Parámetros

Valor devuelto

Ejemplo

CStatusBarCtrl::GetTipText

Parámetros

Valor devuelto

Comentarios

Ejemplo

CStatusBarCtrl::IsSimple

Valor devuelto

Comentarios

CStatusBarCtrl::SetBkColor

Parámetros

Valor devuelto

Comentarios

Ejemplo

CStatusBarCtrl::SetIcon

Parámetros

Valor devuelto

Comentarios

Ejemplo

CStatusBarCtrl::SetMinHeight

Parámetros

Comentarios

Ejemplo

CStatusBarCtrl::SetParts

Parámetros

Valor devuelto

Ejemplo

CStatusBarCtrl::SetSimple

Parámetros

Valor devuelto

Comentarios

CStatusBarCtrl::SetText