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

Artículo
03/02/2024

Agrega una barra de herramientas en miniatura con un conjunto especificado de botones a la imagen en miniatura de una ventana en un control flotante del botón de la barra de tareas.

Sintaxis

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

Parámetros

[in] hwnd

Tipo: HWND

Identificador de la ventana cuya representación en miniatura recibirá la barra de herramientas. Este identificador debe pertenecer al proceso de llamada.

[in] cButtons

Tipo: UINT

Número de botones definidos en la matriz a la que apunta pButton. El número máximo de botones permitido es 7.

[in] pButton

Tipo: LPTHUMBBUTTON

Puntero a una matriz de estructuras THUMBBUTTON . Cada THUMBBUTTON define un botón individual que se agregará a la barra de herramientas. Los botones no se pueden agregar ni eliminar más adelante, por lo que debe ser el conjunto completo definido. Los botones tampoco se pueden reordenar, por lo que su orden en la matriz, que es el orden en que se muestran de izquierda a derecha, será su orden permanente.

Valor devuelto

Tipo: HRESULT

Devuelve S_OK si se ejecuta correctamente o un valor de error de lo contrario, incluido lo siguiente:

Código devuelto	Descripción
E_INVALIDARG	El parámetro hwnd no especifica un identificador que pertenece al proceso o no especifica una ventana asociada a un botón de barra de tareas. Este valor también se devuelve si pButton es menor que 1 o mayor que 7.

Comentarios

Este método permite a una aplicación definir botones para un control de barra de herramientas activo incrustado en la vista previa de miniaturas de la barra de tareas de una ventana. Esto proporciona acceso a los comandos esenciales de la ventana sin hacer que el usuario restaure o active la ventana. Por ejemplo, Reproductor multimedia de Windows puede ofrecer controles de transporte multimedia estándar, como reproducir, pausar, silenciar y detener.

La barra de herramientas usada en la miniatura es básicamente un control de barra de herramientas estándar. Tiene un máximo de siete botones, y está alineado en el centro, transparente y se muestra en un área debajo de la miniatura en lugar de cubrir cualquier parte de él. El identificador, la imagen, la información sobre herramientas y el estado de cada botón se definen en una estructura THUMBBUTTON , que luego se pasa a la barra de tareas. A continuación, la aplicación puede mostrar, modificar u ocultar botones de la barra de herramientas en miniatura según sea necesario en su estado actual llamando a ITaskbarList3::ThumbBarUpdateButtons.

Cuando se hace clic en un botón de una barra de herramientas en miniatura, la ventana asociada a esa miniatura se envía un mensaje de WM_COMMAND con el HIWORD de su parámetro wParam establecido en THBN_CLICKED y loWORD al identificador del botón.

Una vez agregada una barra de herramientas a una miniatura, los botones solo se pueden modificar a través de ITaskbarList3::ThumbBarUpdateButtons. Aunque no se pueden agregar o quitar botones individuales, se pueden mostrar y ocultar a través de ThumbBarUpdateButtons según sea necesario. La propia barra de herramientas no se puede quitar sin volver a crear la ventana.

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 de visualización 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. Por ejemplo, si un botón de barra de tareas representa un grupo con más ventanas abiertas de las que hay espacio para mostrar miniaturas, la interfaz de usuario se revierte a un menú heredado en lugar de miniaturas.

Ejemplos

En el ejemplo siguiente se muestra cómo usar ThumbBarAddButtons para agregar una barra de herramientas que contiene dos botones a una miniatura en la barra de tareas extendida.

HRESULT AddThumbarButtons(HWND hwnd, HIMAGELIST himl, HIMAGELIST himlHot)
{
    // Define an array of two buttons. These buttons provide images through an 
    // image list and also provide tooltips.
    DWORD dwMask = THB_BITMAP | THB_TOOLTIP | THB_FLAGS;
    
    THUMBBUTTON thbButtons[2];
    thbButtons[0].dwMask = dwMask;
    thbButtons[0].iId = 0;
    thbButtons[0].iBitmap = 0;
    thbButtons[0].pszTip = TEXT("Button 1");
    thbButtons[0].dwFlags = THBF_DISMISSONCLICK;

    dwMask = THB_BITMAP | THB_TOOLTIP;
    thbButtons[1].dwMask = dwMask;
    thbButtons[1].iId = 1;
    thbButtons[1].iBitmap = 1;
    thbButtons[1].pszTip = TEXT("Button 2");
    
    // Create an instance of ITaskbarList3
    ITaskBarList3 *ptbl;
    HRESULT hr = CoCreateInstance(CLSID_TaskbarList, 
                                  NULL, 
                                  CLSCTX_INPROC_SERVER, 
                                  IID_PPV_ARGS(&ptbl);

    if (SUCCEEDED(hr))
    {
        // Declare the image list that contains the button images.
        hr = ptbl->ThumbBarSetImageList(hwnd, himl);

        if (SUCCEEDED(hr))
        {
            // Attach the toolbar to the thumbnail.
            hr = ptbl->ThumbBarAddButtons(hwnd, ARRAYSIZE(thbButtons), &thbButtons);
        }
        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 (include Shobjidl.h)
Library	Explorerframe.lib
Archivo DLL	Explorerframe.dll