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 미디어 플레이어 재생, 일시 중지, 음소거 및 중지와 같은 표준 미디어 전송 컨트롤을 제공할 수 있습니다.

썸네일에서 사용되는 도구 모음은 기본적으로 표준 도구 모음 컨트롤입니다. 최대 7개의 단추가 있으며, 중앙에 정렬되고 투명하며 썸네일 아래의 영역에 표시되어 있습니다. 각 단추의 ID, 이미지, 도구 설명 및 상태는 THUMBBUTTON 구조에 정의되어 작업 표시줄에 전달됩니다. 그런 다음, 애플리케이션은 ITaskbarList3::ThumbBarUpdateButtons를 호출하여 현재 상태에서 필요에 따라 썸네일 도구 모음에서 단추를 표시, 변경 또는 숨길 수 있습니다.

축소판 그림 도구 모음의 단추를 클릭하면 해당 썸네일과 연결된 창에 wParam 매개 변수의 HIWORD가 THBN_CLICKED 로 설정된 WM_COMMAND 메시지가 전송되고 LOWORD가 단추 ID로 전송됩니다.

도구 모음을 축소판 그림에 추가한 후에는 ITaskbarList3::ThumbBarUpdateButtons를 통해서만 단추를 변경할 수 있습니다. 개별 단추를 추가하거나 제거할 수는 없지만 필요에 따라 ThumbBarUpdateButtons 를 통해 표시 및 숨길 수 있습니다. 창 자체를 다시 만들지 않으면 도구 모음 자체를 제거할 수 없습니다.

썸네일을 표시할 공간이 제한되어 있을 뿐만 아니라 표시할 축소판 그림의 수가 지속적으로 변경되기 때문에 애플리케이션은 특정 도구 모음 크기를 보장하지 않습니다. 표시 공간이 부족하면 필요에 따라 도구 모음의 단추가 오른쪽에서 왼쪽으로 잘립니다. 따라서 애플리케이션은 단추와 연결된 명령의 우선 순위를 지정하여 우선 순위가 가장 높은 명령이 왼쪽에 있으므로 잘릴 가능성이 가장 큽니다.

축소판 그림 도구 모음은 축소판 그림이 표시될 때만 표시됩니다. instance 경우 작업 표시줄 단추가 축소판 그림을 표시할 공간이 있는 것보다 열린 창이 더 많은 그룹을 나타내는 경우 UI는 축소판 그림이 아닌 레거시 메뉴로 되돌아갑니다.

예제

다음 예제에서는 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

작업 표시줄 확장