Метод ITaskbarList3::ThumbBarAddButtons (shobjidl_core.h)

Добавляет панель инструментов эскизов с указанным набором кнопок к эскизу окна во всплывающем элементе кнопки панели задач.

Синтаксис

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

Параметры

[in] hwnd

Тип: HWND

Дескриптор окна, представление эскиза которого получит панель инструментов. Этот дескриптор должен принадлежать вызывающей процедуре.

[in] cButtons

Тип: UINT

Число кнопок, определенных в массиве, на который указывает pButton. Максимально допустимое количество кнопок — 7.

[in] pButton

Тип: LPTHUMBBUTTON

Указатель на массив структур THUMBBUTTON . Каждая кнопка THUMBBUTTON определяет отдельную кнопку, добавляемую на панель инструментов. Кнопки нельзя добавить или удалить позже, поэтому это должен быть полный набор. Кнопки также не могут быть переупорядочены, поэтому их порядок в массиве, в котором они отображаются слева направо, будет их постоянным порядком.

Возвращаемое значение

Тип: HRESULT

Возвращает S_OK в случае успешного выполнения, или значение ошибки в противном случае, включая следующее:

Комментарии

Этот метод позволяет приложению определять кнопки для активного элемента управления панели инструментов, внедренного в предварительный просмотр эскизов панели задач окна. Это обеспечивает доступ к основным командам окна, не выполняя восстановление или активацию окна. Например, Медиаплеер Windows могут предлагать стандартные элементы управления транспортировкой мультимедиа, такие как воспроизведение, приостановка, отключение звука и остановка.

Панель инструментов, используемая в эскизе, по сути, является стандартным элементом управления панели инструментов . Он содержит не более семи кнопок и выравнивается по центру, прозрачн и отображается в области под эскизом, а не охватывает любую его часть. Идентификатор, изображение, подсказка и состояние каждой кнопки определяются в структуре THUMBBUTTON , которая затем передается на панель задач. Затем приложение может отображать, изменять или скрывать кнопки на панели инструментов эскизов в соответствии с требованиями текущего состояния путем вызова ITaskbarList3::ThumbBarUpdateButtons.

При нажатии кнопки на панели инструментов эскизов в окно, связанное с этим эскизом, отправляется WM_COMMAND сообщение с HIWORD для параметра wParam, для параметра wParam задано значение THBN_CLICKED , а в поле LOWORD — идентификатор кнопки.

После добавления панели инструментов в эскиз кнопки можно изменять только с помощью ITaskbarList3::ThumbBarUpdateButtons. Хотя отдельные кнопки нельзя добавлять или удалять, их можно отображать и скрывать с помощью ThumbBarUpdateButtons при необходимости. Саму панель инструментов нельзя удалить без повторного создания самого окна.

Поскольку существует ограниченное пространство для отображения эскизов, а также постоянно изменяющееся количество отображаемых эскизов, приложениям не гарантируется определенный размер панели инструментов. Если место на экране мало, при необходимости кнопки на панели инструментов усекаются справа налево. Таким образом, приложению следует приоритизировать команды, связанные с его кнопками, чтобы гарантировать, что команды с наивысшим приоритетом находятся слева и, следовательно, с меньшей вероятностью будут усечены.

Панели инструментов эскизов отображаются только при отображении эскизов. Например, если кнопка панели задач представляет группу с большим числом открытых окон, чем есть место для отображения эскизов, пользовательский интерфейс возвращается к меню прежних версий, а не эскизов.

Примеры

В следующем примере показано, как использовать ThumbBarAddButtons для добавления панели инструментов, содержащей две кнопки, к эскизу на расширенной панели задач.

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

Требования

См. также раздел

ITaskbarList

ITaskbarList2

ITaskbarList3

ITaskbarList3::ThumbBarSetImageList

ITaskbarList3::ThumbBarUpdateButtons

Расширения панели задач