Método ITaskbarList3::ThumbBarUpdateButtons (shobjidl_core.h)

Artículo
03/02/2024

Muestra, habilita, deshabilita u oculta botones en una barra de herramientas en miniatura según lo requiera el estado actual de la ventana. Una barra de herramientas en miniatura es una barra de herramientas incrustada en una imagen en miniatura de una ventana en un control flotante de botón de barra de tareas.

Sintaxis

HRESULT ThumbBarUpdateButtons(
  [in] HWND          hwnd,
  [in] UINT          cButtons,
  [in] LPTHUMBBUTTON pButton
);

Parámetros

[in] hwnd

Tipo: HWND

Identificador de la ventana cuya representación en miniatura contiene la barra de herramientas.

[in] cButtons

Tipo: UINT

Número de botones definidos en la matriz a la que apunta pButton. El número máximo de botones permitidos es 7. Esta matriz contiene solo estructuras que representan los botones existentes que se están actualizando.

[in] pButton

Tipo: LPTHUMBBUTTON

Puntero a una matriz de estructuras THUMBBUTTON . Cada THUMBBUTTON define un botón individual. Si el botón ya existe (el valor de iId ya está definido), ese botón existente se actualiza con la información proporcionada en la estructura.

Valor devuelto

Tipo: HRESULT

Si este método se realiza correctamente, devuelve S_OK. De lo contrario, devuelve un código de error de HRESULT.

Comentarios

Dado que hay una cantidad limitada de espacio en el que mostrar miniaturas, así como un número constantemente cambiante de miniaturas para mostrar, las aplicaciones no garantizan un tamaño de barra de herramientas específico. Si el espacio para mostrar es bajo, los botones de la barra de herramientas se truncan de derecha a izquierda según sea necesario. Por lo tanto, una aplicación debe priorizar los comandos asociados a sus botones para asegurarse de que las de mayor prioridad están a la izquierda y, por lo tanto, es menos probable que se trunquen.

Las barras de herramientas en miniatura solo se muestran cuando se muestran miniaturas en la barra de tareas. Por ejemplo, si un botón de la barra de tareas representa un grupo con más ventanas abiertas de las que hay espacio para mostrar miniaturas, la interfaz de usuario vuelve a un menú heredado en lugar de miniaturas.

Ejemplos

En el ejemplo siguiente se muestra cómo usar ThumbBarUpdateButtons para cambiar el texto y la imagen en un botón existente en una barra de herramientas en miniatura de la barra de tareas extendida.

HRESULT UpdateThumbarButton(HWND hwnd)
{
    // Define a single structure for the button to update. The ID is that
    // of an existing button, so the other information (bitmap index and 
    // tooltip) overwrites the existing values, updating the button.
    THUMBBUTON thbButton;
    thbButton.dwMask = THB_BITMAP | THB_TOOLTIP;
    thbButtons[0].iId = 1;
    thbButton.iBitmap = 3;
    thbButton.pszTip = TEXT("Different Text");
    
    // Create an instance of ITaskbarList3
    ITaskBarList3 *ptbl;
    HRESULT hr = CoCreateInstance(CLSID_TaskbarList, 
                                  NULL, 
                                  CLSCTX_INPROC_SERVER, 
                                  IID_PPV_ARGS(&ptbl);

    if (SUCCEEDED(hr))
    {
        // Update the toolbar. In this case, only the single button is updated.
        hr = ptbl->ThumbBarUpdateButtons(hwnd, 1, &thbButton);
        ptbl->Release();
    }
    return hr;
}

Requisitos

Requisito	Value
Cliente mínimo compatible	Windows 7 [solo aplicaciones de escritorio]
Servidor mínimo compatible	Windows Server 2008 R2 [solo aplicaciones de escritorio]
Plataforma de destino	Windows
Encabezado	shobjidl_core.h (incluya Shobjidl.h)
Library	Explorerframe.lib
Archivo DLL	Explorerframe.dll