Метод 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 Media может предлагать стандартные элементы управления транспортировкой мультимедиа, такие как воспроизведение, приостановка, отключение и остановка.

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

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

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

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

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

Доступность

Сведения о специальных возможностях в изображениях кнопок на панели пальца см. в разделе "Примечания" в ThumbBarSetImageList.

Примеры

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

HRESULT AddThumbBarButtons(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

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