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

Artigo
08/26/2023

Adiciona uma barra de ferramentas em miniatura com um conjunto especificado de botões à imagem em miniatura de uma janela em um submenu de botão da barra de tarefas.

Sintaxe

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

Parâmetros

[in] hwnd

Digite: HWND

O identificador da janela cuja representação em miniatura receberá a barra de ferramentas. Esse identificador deve pertencer ao processo de chamada.

[in] cButtons

Tipo: UINT

O número de botões definidos na matriz apontada por pButton. O número máximo de botões permitidos é 7.

[in] pButton

Tipo: LPTHUMBBUTTON

Um ponteiro para uma matriz de estruturas THUMBBUTTON . Cada THUMBBUTTON define um botão individual a ser adicionado à barra de ferramentas. Os botões não podem ser adicionados ou excluídos posteriormente, portanto, esse deve ser o conjunto completo definido. Os botões também não podem ser reordenados, portanto, sua ordem na matriz, que é a ordem na qual eles são exibidos da esquerda para a direita, será sua ordem permanente.

Retornar valor

Tipo: HRESULT

Retorna S_OK se tiver êxito ou um valor de erro, incluindo o seguinte:

Código de retorno	Descrição
E_INVALIDARG	O parâmetro hwnd não especifica um identificador que pertence ao processo ou não especifica uma janela associada a um botão de barra de tarefas. Esse valor também será retornado se pButton for menor que 1 ou maior que 7.

Comentários

Esse método permite que um aplicativo defina botões para um controle de barra de ferramentas ativo inserido na visualização da miniatura da barra de tarefas de uma janela. Isso fornece acesso aos comandos essenciais da janela sem fazer o usuário restaurar ou ativar a janela. Por exemplo, Reprodutor Multimídia do Windows pode oferecer controles de transporte de mídia padrão, como reproduzir, pausar, ativar mudo e parar.

A barra de ferramentas usada na miniatura é essencialmente um controle de barra de ferramentas padrão. Ele tem no máximo sete botões e é centralizado, transparente e exibido em uma área abaixo da miniatura, em vez de cobrir qualquer parte dele. A ID, a imagem, a dica de ferramenta e o estado de cada botão são definidos em uma estrutura THUMBBUTTON , que é então passada para a barra de tarefas. Em seguida, o aplicativo pode mostrar, alterar ou ocultar botões da barra de ferramentas de miniatura, conforme exigido pelo estado atual, chamando ITaskbarList3::ThumbBarUpdateButtons.

Quando um botão em uma barra de ferramentas em miniatura é clicado, a janela associada a essa miniatura é enviada uma mensagem WM_COMMAND com o HIWORD de seu parâmetro wParam definido como THBN_CLICKED e LOWORD para a ID do botão.

Depois que uma barra de ferramentas tiver sido adicionada a uma miniatura, os botões só poderão ser alterados por meio de ITaskbarList3::ThumbBarUpdateButtons. Embora os botões individuais não possam ser adicionados ou removidos, eles podem ser mostrados e ocultos por meio de ThumbBarUpdateButtons , conforme necessário. A própria barra de ferramentas não pode ser removida sem recriar a própria janela.

Como há uma quantidade limitada de espaço para exibir miniaturas, bem como um número constante de miniaturas a serem exibidas, os aplicativos não têm garantia de um tamanho específico da barra de ferramentas. Se o espaço de exibição for baixo, os botões na barra de ferramentas serão truncados da direita para a esquerda, conforme necessário. Portanto, um aplicativo deve priorizar os comandos associados aos botões para garantir que aqueles de prioridade mais alta sejam à esquerda e, portanto, tenham menos probabilidade de serem truncados.

As barras de ferramentas de miniatura são exibidas somente quando miniaturas estão sendo exibidas. Por exemplo, se um botão de barra de tarefas representar um grupo com janelas mais abertas do que há espaço para exibir miniaturas, a interface do usuário será revertida para um menu herdado em vez de miniaturas.

Exemplos

O exemplo a seguir mostra como usar ThumbBarAddButtons para adicionar uma barra de ferramentas que contém dois botões a uma miniatura na barra de tarefas estendida.

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	Valor
Cliente mínimo com suporte	Windows 7 [somente aplicativos da área de trabalho]
Servidor mínimo com suporte	Windows Server 2008 R2 [somente aplicativos da área de trabalho]
Plataforma de Destino	Windows
Cabeçalho	shobjidl_core.h (inclua Shobjidl.h)
Biblioteca	Explorerframe.lib
DLL	Explorerframe.dll