Metode ITaskbarList3::SetProgressValue (shobjidl_core.h)

Artikel
08/26/2023

Menampilkan atau memperbarui bilah kemajuan yang dihosting di tombol taskbar untuk memperlihatkan persentase tertentu yang selesai dari operasi penuh.

Sintaks

HRESULT SetProgressValue(
  [in] HWND      hwnd,
  [in] ULONGLONG ullCompleted,
  [in] ULONGLONG ullTotal
);

Parameter

[in] hwnd

Jenis: HWND

Handel jendela yang tombol taskbar terkaitnya sedang digunakan sebagai indikator kemajuan.

[in] ullCompleted

Jenis: ULONGLONG

Nilai yang ditentukan aplikasi yang menunjukkan proporsi operasi yang telah selesai pada saat metode dipanggil.

[in] ullTotal

Jenis: ULONGLONG

Nilai yang ditentukan aplikasi yang menentukan nilai ullCompleted akan memiliki ketika operasi selesai.

Nilai kembali

Jenis: HRESULT

Jika metode ini berhasil, metode akan mengembalikan S_OK. Jika tidak, kode kesalahan HRESULT akan dikembalikan.

Keterangan

Menentukan Siklus Hidup Bilah Kemajuan

Aplikasi pertama-tama memanggil SetProgressValue untuk memulai tampilan bilah kemajuan penentuan, lalu memanggilnya lagi sesuai kebutuhan untuk memperbarui bilah saat kemajuan berubah. Ketika kemajuan selesai, aplikasi harus memanggil SetProgressState dengan bendera TBPF_NOPROGRESS untuk menutup bilah kemajuan.

Bagaimana Tombol Bilah Tugas Memilih Indikator Kemajuan untuk Grup

Tombol taskbar dapat memperlihatkan indikator kemajuan hanya untuk satu jendela pada satu waktu. Ketika tombol taskbar mewakili grup dan lebih dari salah satu jendela dalam grup tersebut menyiarkan informasi kemajuan, tombol taskbar memilih tampilan kemajuannya berdasarkan prioritas status berikut.

Prioritas	Provinsi
1	TBPF_ERROR
2	TBPF_PAUSED
3	TBPF_NORMAL
4	TBPF_INDETERMINATE

Kecuali SetProgressState telah menetapkan status pemblokiran (TBPF_ERROR atau TBPF_PAUSED) untuk jendela, panggilan ke SetProgressValue mengasumsikan status TBPF_NORMAL meskipun tidak diatur secara eksplisit. Panggilan ke SetProgressValue mengambil alih dan menghapus status TBPF_INDETERMINATE.

Dalam kasus tabrakan prioritas di mana dua jendela menyiarkan kemajuan penentuan, jendela dengan kemajuan paling sedikit digunakan.

Berdasarkan prioritas tersebut, indikator kemajuan penentuan (persentase tertentu) ini dapat ditampilkan dalam kasus-kasus ini:

Tombol taskbar tidak mewakili grup dan satu jendela yang diwakilinya adalah menyiarkan menentukan informasi kemajuan melalui metode ini.
Tombol taskbar mewakili grup, hanya satu jendela dalam grup tersebut yang menyiarkan informasi kemajuan, dan jendela tersebut menyiarkan menentukan informasi kemajuan melalui metode ini.
Tombol taskbar mewakili grup, beberapa jendela dalam grup tersebut menyiarkan informasi kemajuan, setidaknya salah satu jendela tersebut menyiarkan informasi kemajuan melalui metode ini, dan tidak ada jendela yang mengatur status TBPF_ERROR atau TBPF_PAUSED .

Jika jendela dalam grup telah diatur TBPF_ERROR atau TBPF_PAUSED, status tersebut akan digunakan untuk tampilan tombol. Namun, Anda masih dapat melakukan panggilan ke SetProgressValue di jendela lain yang tidak diblokir dalam grup untuk memperbarui kemajuannya di latar belakang.

Contoh

Berikut adalah contoh bagaimana aplikasi dapat menggunakan ITaskbarList3 untuk menampilkan kemajuan saat melakukan operasi.

HRESULT CMyApp::ShowProgressInTaskbar(HWND hwnd, __in ITaskbarList3 *pTL)
{
    // Set the progress state of the button to indeterminate while you calculate
    // the number of operations to be performed.
    HRESULT hr = pTL->SetProgressState(hwnd, TBPF_INDETERMINATE);

    // Calculate the number of operations to perform.
    int cTotalOperations = _CalculateNumberOfOperationsToPerform();

    for (int i=0; i < cTotalOperations && SUCCEEDED(hr); i++)
    {
        // Update the progress. This call to SetProgressValue cancels the
        // indeterminate state and puts the button into normal progress mode.
        pTL->SetProgressValue(hwnd, i, cTotalOperations);
       
        // Do whatever operation your application needs to perform.
        hr = _PerformOperation(i);
    }

    // Tell the button that progress no longer needs to be displayed.
    pTL->SetProgressState(hwnd, TBPF_NOPROGRESS);
    
    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