CStatusBarCtrl (clase)
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
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.
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
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"));
Consulte también
Comentarios
Próximamente: A lo largo de 2024 iremos eliminando gradualmente GitHub Issues como mecanismo de comentarios sobre el contenido y lo sustituiremos por un nuevo sistema de comentarios. Para más información, vea: https://aka.ms/ContentUserFeedback.
Enviar y ver comentarios de