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

Artigo
03/02/2024

Mostra, habilita, desabilita ou oculta botões em uma barra de ferramentas de miniatura, conforme exigido pelo estado atual da janela. Uma barra de ferramentas em miniatura é uma barra de ferramentas inserida em uma imagem em miniatura de uma janela em um submenu de botão da barra de tarefas.

Sintaxe

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

Parâmetros

[in] hwnd

Digite: HWND

O identificador da janela cuja representação em miniatura contém a barra de ferramentas.

[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. Essa matriz contém apenas estruturas que representam botões existentes que estão sendo atualizados.

[in] pButton

Tipo: LPTHUMBBUTTON

Um ponteiro para uma matriz de estruturas THUMBBUTTON . Cada THUMBBUTTON define um botão individual. Se o botão já existir (o valor iId já está definido), esse botão existente será atualizado com as informações fornecidas na estrutura.

Retornar valor

Tipo: HRESULT

Se o método for bem-sucedido, ele retornará S_OK. Caso contrário, ele retornará um código de erro HRESULT.

Comentários

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 fiquem à esquerda e, portanto, sejam menos propensos a serem truncados.

As barras de ferramentas de miniatura são exibidas somente quando miniaturas estão sendo exibidas na barra de tarefas. Por exemplo, se um botão da 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 ThumbBarUpdateButtons para alterar o texto e a imagem em um botão existente em uma barra de ferramentas em miniatura na barra de tarefas estendida.

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