Metode ITaskbarList3::ThumbBarAddButtons (shobjidl_core.h)

Artikel
08/26/2023

Menambahkan toolbar gambar mini dengan sekumpulan tombol tertentu ke gambar mini jendela di flyout tombol taskbar.

Sintaks

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

Parameter

[in] hwnd

Jenis: HWND

Handel jendela yang representasi gambar mininya akan menerima toolbar. Handel ini harus termasuk dalam proses panggilan.

[in] cButtons

Jenis: UINT

Jumlah tombol yang ditentukan dalam array yang ditunjukkan oleh pButton. Jumlah maksimum tombol yang diizinkan adalah 7.

[in] pButton

Jenis: LPTHUMBBUTTON

Penunjuk ke array struktur THUMBBUTTON . Setiap THUMBBUTTON mendefinisikan tombol individual untuk ditambahkan ke toolbar. Tombol tidak dapat ditambahkan atau dihapus nanti, jadi ini harus menjadi set lengkap yang ditentukan. Tombol juga tidak dapat diurutkan ulang, sehingga urutannya dalam array, yang merupakan urutan di mana tombol ditampilkan dari kiri ke kanan, akan menjadi urutan permanennya.

Nilai kembali

Jenis: HRESULT

Mengembalikan S_OK jika berhasil, atau nilai kesalahan sebaliknya, termasuk yang berikut ini:

Menampilkan kode	Deskripsi
E_INVALIDARG	Parameter hwnd tidak menentukan handel yang termasuk dalam proses atau tidak menentukan jendela yang terkait dengan tombol taskbar. Nilai ini juga dikembalikan jika pButton kurang dari 1 atau lebih besar dari 7.

Keterangan

Metode ini memungkinkan aplikasi untuk menentukan tombol untuk kontrol toolbar aktif yang disematkan dalam pratinjau gambar mini taskbar jendela. Ini menyediakan akses ke perintah penting jendela tanpa membuat pemulihan pengguna atau mengaktifkan jendela. Misalnya, Pemutar Media Windows mungkin menawarkan kontrol transportasi media standar seperti putar, jeda, matikan suara, dan berhenti.

Toolbar yang digunakan dalam gambar mini pada dasarnya adalah kontrol toolbar standar. Ini memiliki maksimal tujuh tombol, dan sejajar tengah, transparan, dan ditampilkan di area di bawah gambar mini daripada menutupi bagian mana pun. ID, gambar, tipsalat, dan status setiap tombol didefinisikan dalam struktur THUMBBUTTON , yang kemudian diteruskan ke taskbar. Aplikasi kemudian dapat menampilkan, mengubah, atau menyembunyikan tombol dari toolbar gambar mini sebagaimana diperlukan oleh statusnya saat ini dengan memanggil ITaskbarList3::ThumbBarUpdateButtons.

Saat tombol di toolbar gambar mini diklik, jendela yang terkait dengan gambar mini tersebut dikirimi pesan WM_COMMAND dengan HIWORD parameter wParam-nya diatur ke THBN_CLICKED dan LOWORD ke ID tombol.

Setelah toolbar ditambahkan ke gambar mini, tombol hanya dapat diubah melalui ITaskbarList3::ThumbBarUpdateButtons. Meskipun tombol individual tidak dapat ditambahkan atau dihapus, tombol dapat ditampilkan dan disembunyikan melalui ThumbBarUpdateButtons sesuai kebutuhan. Bilah alat itu sendiri tidak dapat dihapus tanpa membuat ulang jendela itu sendiri.

Karena ada sejumlah ruang terbatas untuk menampilkan gambar mini, serta jumlah gambar mini yang terus berubah untuk ditampilkan, aplikasi tidak dijamin ukuran toolbar tertentu. Jika ruang tampilan rendah, tombol di toolbar dipotok dari kanan ke kiri sesuai kebutuhan. Oleh karena itu, aplikasi harus memprioritaskan perintah yang terkait dengan tombolnya untuk memastikan bahwa yang memiliki prioritas tertinggi ada di sebelah kiri dan karenanya paling tidak mungkin dipotok.

Bilah alat gambar mini hanya ditampilkan saat gambar mini ditampilkan. Misalnya, jika tombol taskbar mewakili grup dengan jendela yang lebih terbuka daripada ruang untuk menampilkan gambar mini, UI kembali ke menu warisan daripada gambar mini.

Contoh

Contoh berikut menunjukkan cara menggunakan ThumbBarAddButtons untuk menambahkan toolbar yang berisi dua tombol ke gambar mini pada taskbar yang diperluas.

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

Persyaratan

Persyaratan	Nilai
Klien minimum yang didukung	Windows 7 [hanya aplikasi desktop]
Server minimum yang didukung	Windows Server 2008 R2 [hanya aplikasi desktop]
Target Platform	Windows
Header	shobjidl_core.h (termasuk Shobjidl.h)
Pustaka	Explorerframe.lib
DLL	Explorerframe.dll