ITaskbarList3::ThumbBarAddButtons 메서드(shobjidl_core.h)

작업 표시줄 단추 플라이아웃에서 창의 축소판 그림 이미지에 지정된 단추 집합이 있는 축소판 그림 도구 모음을 추가합니다.

Syntax

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

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

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

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

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

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

접근성

썸바 단추 이미지의 접근성에 대한 자세한 내용은 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

작업 표시줄 확장