Metode ITaskbarList3::SetProgressState (shobjidl_core.h)

Artikel
08/26/2023

Menyetel tipe dan status indikator kemajuan yang ditampilkan pada tombol bilah tugas.

Sintaks

HRESULT SetProgressState(
  [in] HWND    hwnd,
  [in] TBPFLAG tbpFlags
);

Parameter

[in] hwnd

Jenis: HWND

Handel jendela tempat kemajuan operasi sedang ditampilkan. Tombol bilah tugas terkait jendela ini akan menampilkan bilah kemajuan.

[in] tbpFlags

Jenis: TBPFLAG

Bendera yang mengontrol status tombol kemajuan saat ini. Tentukan hanya salah satu bendera berikut; semua negara bagian saling eksklusif dari yang lain.

TBPF_NOPROGRESS (0x00000000)

Berhenti menampilkan kemajuan dan mengembalikan tombol ke status normalnya. Panggil metode ini dengan bendera ini untuk menutup bilah kemajuan ketika operasi selesai atau dibatalkan.

TBPF_INDETERMINATE (0x00000001)

Indikator kemajuan tidak tumbuh dalam ukuran, tetapi siklus berulang kali sepanjang tombol taskbar. Ini menunjukkan aktivitas tanpa menentukan proporsi kemajuan apa yang selesai. Kemajuan sedang berlangsung, tetapi tidak ada prediksi berapa lama operasi akan berlangsung.

TBPF_NORMAL (0x00000002)

Indikator kemajuan tumbuh dalam ukuran dari kiri ke kanan sebanding dengan perkiraan jumlah operasi yang diselesaikan. Ini adalah indikator kemajuan yang menentukan; prediksi sedang dibuat selama durasi operasi.

TBPF_ERROR (0x00000004)

Indikator kemajuan berubah menjadi merah untuk menunjukkan bahwa kesalahan telah terjadi di salah satu jendela yang sedang menyiarkan kemajuan. Ini adalah negara yang menentukan. Jika indikator kemajuan dalam status tidak ditentukan, indikator tersebut beralih ke tampilan determinasi merah dari persentase generik yang tidak menunjukkan kemajuan aktual.

TBPF_PAUSED (0x00000008)

Indikator kemajuan berubah menjadi kuning untuk menunjukkan bahwa kemajuan saat ini dihentikan di salah satu jendela tetapi dapat dilanjutkan oleh pengguna. Tidak ada kondisi kesalahan dan tidak ada yang mencegah kemajuan berlanjut. Ini adalah negara yang menentukan. Jika indikator kemajuan dalam status tidak ditentukan, indikator akan beralih ke tampilan determinasi kuning dari persentase generik yang tidak menunjukkan kemajuan aktual.

Menampilkan nilai

Jenis: HRESULT

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

Keterangan

Informasi bilah kemajuan tidak ditampilkan dalam skema warna kontras tinggi untuk menjamin bahwa tidak ada kebutuhan aksesibilitas yang disusupi.

Pengembang yang terbiasa dengan kontrol bilah kemajuan yang ada harus menemukan indikator kemajuan tombol taskbar untuk menjadi pengalaman serupa baik dalam konsep maupun visual. Di sini, tombol taskbar itu sendiri menjadi bilah kemajuan. Indikator kemajuan tombol taskbar harus menjadi cerminan bilah kemajuan yang lebih rinci di jendela terkait. Ini memungkinkan pengguna untuk melihat secara spesifik, seperti jumlah persentase dan jumlah waktu yang tersisa, yang tidak dapat ditampilkan di tombol taskbar. Selain itu, karena tombol taskbar hanya dapat menunjukkan kemajuan satu jendela dalam grup, itu memungkinkan pengguna untuk memeriksa kemajuan jendela individual. Ini juga memberikan informasi kemajuan kepada pengguna ketika tombol taskbar tidak dapat, seperti dalam skema warna kontras tinggi.

Perhatikan bahwa bilah kemajuan tombol taskbar tidak dimaksudkan untuk digunakan dengan tindakan periferal biasanya seperti pemuatan halaman web atau pencetakan dokumen. Jenis kemajuan tersebut harus terus ditampilkan di bilah status jendela.

Indikator kemajuan ditampilkan antara ikon atau teks tombol taskbar dan latar belakang. Jika kemajuan ditampilkan untuk tombol taskbar aktif dan tombol tidak aktif, bayangan di bilah kemajuan masing-masing sedih sehingga tombol aktif masih jelas bagi pengguna. Selain itu, fungsionalitas tombol seperti tampilan gambar mini terus berfungsi secara normal ketika tombol digunakan untuk menampilkan kemajuan.

Saat keluar dari kesalahan atau status dijeda, panggil metode ini lagi dengan bendera TBPF_NORMAL atau TBPF_INDETERMINATE untuk melanjutkan dalam status asli atau TBPF_NOPROGRESS jika operasi dibatalkan.

Bagaimana Tombol Bilah Tugas Memilih Indikator Kemajuan untuk Grup

Tombol taskbar dapat memperlihatkan indikator kemajuan hanya untuk satu jendela pada satu waktu. Ini termasuk situasi di mana tombol taskbar mewakili grup dan lebih dari satu jendela dalam grup tersebut menyiarkan informasi kemajuan. Dalam hal ini, tombol taskbar memilih tampilan kemajuannya berdasarkan prioritas status. Prioritas status diperlihatkan dalam tabel berikut dengan prioritas 1 menjadi yang tertinggi.

Prioritas	Provinsi
1	TBPF_ERROR
2	TBPF_PAUSED
3	TBPF_NORMAL
4	TBPF_INDETERMINATE

Mengubah status jendela mengubah prioritasnya sehubungan dengan jendela lain dalam grup yang pada gilirannya dapat mengubah jendela mana dalam grup yang digunakan untuk indikator kemajuan di tombol taskbar.

Dalam kasus tabrakan prioritas antara dua jendela yang menyiarkan kemajuan penentuan, jendela dengan kemajuan paling sedikit digunakan.

Berdasarkan prioritas ini, indikator kemajuan yang tidak ditentukan dapat ditampilkan di tombol taskbar hanya dalam kasus ini:

Tombol taskbar tidak mewakili grup dan satu jendela yang diwakilinya telah diatur TBPF_INDETERMINATE.
Tombol taskbar mewakili grup, hanya satu jendela dalam grup tersebut yang menyiarkan informasi kemajuan, dan jendela tersebut telah mengatur TBPF_INDETERMINATE.
Tombol taskbar mewakili grup, beberapa jendela dalam grup tersebut menyiarkan informasi kemajuan, dan semua jendela tersebut telah diatur TBPF_INDETERMINATE.

Indikator kemajuan penentuan dapat ditampilkan dalam kasus ini:

Tombol taskbar tidak mewakili grup dan satu jendela yang diwakilinya menyiarkan informasi kemajuan penentuan.
Tombol taskbar mewakili grup, hanya satu jendela dalam grup tersebut yang menyiarkan informasi kemajuan, dan jendela tersebut menyiarkan informasi kemajuan penentuan.
Tombol taskbar mewakili grup, beberapa jendela dalam grup tersebut menyiarkan informasi kemajuan, setidaknya salah satu jendela tersebut menyiarkan informasi kemajuan yang ditentukan, dan tidak ada jendela yang diatur TBPF_ERROR atau TBPF_PAUSED.

Perhatikan bahwa panggilan ke SetProgressValue akan mengalihkan indikator kemajuan yang saat ini dalam mode yang tidak ditentukan (TBPF_INDETERMINATE) ke tampilan normal (menentukan) dan menghapus bendera TBPF_INDETERMINATE .

Persyaratan


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