Pemilih Warna Drop-Down
Kerangka kerja Pita Windows menyediakan kontrol pemilih warna Drop-Down khusus yang mengekspos berbagai pengaturan warna melalui tombol terpisah dan pemilih warna drop-down yang dapat disesuaikan.
Pengantar
Dengan meniru tampilan dan fungsionalitas pemilih warna Microsoft Office, kerangka kerja Pita dapat memanfaatkan, dan berkontribusi pada, konsistensi, dan keakraban di berbagai aplikasi.
Markup
Seperti semua kontrol Pita, pemilih warna Drop-Down mudah diimplementasikan dan dikustomisasi melalui markup. Kerangka kerja ini menyediakan sejumlah atribut elemen untuk pemilih warna Drop-Down untuk mengekspos berbagai tingkat fungsionalitas. Tabel berikut mencantumkan atribut pemilih warna Drop-Down.
Atribut | Deskripsi |
---|---|
ColorTemplate | Templat tata letak yang menentukan jenis pemilih warna Drop-Down. Ada tiga templat, yang masing-masing menentukan tata letak kontrol dan nilai default untuk atribut dan kunci properti terkait.
|
ChipSize | Ukuran setiap chip warna (atau swatch).
|
Kolom | Jumlah kolom chip warna (atau swatch). |
CommandName | Nama deklarasi Perintah terkait. |
IsAutomaticColorButtonVisible | Menampilkan (atau menyembunyikan) tombol Otomatis . Hanya valid ketika ColorTemplate memiliki nilai ThemeColors atau StandardColors . |
IsNoColorButtonVisible | Menampilkan (atau menyembunyikan) tombol Tanpa warna . Berlaku untuk semua nilai ColorTemplate . |
RecentColorGridRows | Jumlah baris chip warna (atau swatch) di area Warna terbaru . Hanya valid ketika ColorTemplate memiliki nilai ThemeColors . |
StandardColorGridRows | Jumlah baris chip warna (atau swatch) di area Warna standar . |
ThemeColorGridRows | Jumlah baris chip warna (atau swatch) di area Warna tema . Hanya valid ketika ColorTemplate memiliki nilai ThemeColors . |
Cuplikan layar berikut mengilustrasikan tata letak pemilih warna Drop-Down default untuk tiga templat warna.
ThemeColors :[newline] ![]() |
standardcolors :[newline] ![]() |
highlightcolors :[newline] ![]() |
Markup dasar yang diperlukan untuk setiap jenis Pemilih Warna Drop-Down ditunjukkan dalam contoh berikut:
Catatan
Pemilih Warna Drop-Down adalah kontrol Tombol yang valid dalam templat SizeDefinition .
<!-- DropDownColorPickers -->
<Command Name="cmdDropDownColorPickerGroup"
Symbol="cmdDropDownColorPickerGroup"
Comment="DropDownColorPicker Group"
Id="55000"/>
<Command Name="cmdDropDownColorPickerThemeColors"
Symbol="cmdDropDownColorPickerThemeColors"
Comment="DropDownColorPicker ThemeColors"
Id="55010"
LabelTitle="ThemeColors"
LabelDescription="ThemeColors\ndescription."/>
<Command Name="cmdDropDownColorPickerStandardColors"
Symbol="cmdDropDownColorPickerStandardColors"
Comment="DropDownColorPicker StandardColors"
Id="55011"
LabelTitle="StandardColors"/>
<Command Name="cmdDropDownColorPickerHighlightColors"
Symbol="cmdDropDownColorPickerHighlightColors"
Comment="DropDownColorPicker HighlightColors"
Id="55012"
LabelTitle="HighlightColors"/>
<Group CommandName="cmdDropDownColorPickerGroup"
SizeDefinition="ThreeButtons">
<DropDownColorPicker
CommandName="cmdDropDownColorPickerThemeColors"
ColorTemplate="ThemeColors"/>
<DropDownColorPicker
CommandName="cmdDropDownColorPickerStandardColors"
ColorTemplate="StandardColors"/>
<DropDownColorPicker
CommandName="cmdDropDownColorPickerHighlightColors"
ColorTemplate="HighlightColors"
StandardColorGridRows="1"/>
</Group>
Kode
Sebagai kontrol khusus yang mendukung penyesuaian, penerapan apa pun dari pemilih warna Drop-Down yang memanfaatkan kemampuan ini memerlukan kode aplikasi khusus untuk mengelola properti dan menangani Perintah apa pun yang dikeluarkan oleh kontrol.
Properti
Kerangka kerja Pita menentukan kumpulan kunci properti untuk kontrol pemilih warna Drop-Down.
Biasanya, properti pemilih warna Drop-Down diperbarui di UI pita dengan membatalkan Perintah yang terkait dengan kontrol melalui panggilan ke metode IUIFramework::InvalidateUICommand . Peristiwa pembatalan ditangani, dan pembaruan properti ditentukan, oleh metode panggilan balik IUICommandHandler::UpdateProperty .
Metode panggilan balik IUICommandHandler::UpdateProperty tidak dijalankan, dan aplikasi dikueri untuk nilai properti yang diperbarui, hingga properti diperlukan oleh kerangka kerja. Misalnya, saat tab diaktifkan dan kontrol terungkap di UI pita, atau saat tipsalat ditampilkan.
Catatan
Dalam beberapa kasus, properti dapat diambil melalui metode IUIFramework::GetUICommandProperty dan diatur dengan metode IUIFramework::SetUICommandProperty .
Tabel berikut mencantumkan kunci properti yang terkait dengan kontrol pemilih warna Drop-Down.
Kunci Properti | Deskripsi | Catatan |
---|---|---|
UI_PKEY_AutomaticColorLabel | Menentukan label untuk tombol Warna otomatis . Hanya valid ketika ColorTemplate memiliki nilai ThemeColors atau StandardColors . |
Mendukung IUIFramework::GetUICommandProperty dan IUIFramework::SetUICommandProperty. |
UI_PKEY_Color | Menentukan nilai warna yang dipilih sebagai COLORREF. Hanya valid ketika UI_PKEY_ColorType memiliki nilai UI_SWATCHCOLORTYPE_RGB . |
Mendukung IUIFramework::GetUICommandProperty dan IUIFramework::SetUICommandProperty. |
UI_PKEY_ColorType | Menentukan tipe warna terpilih. |
Mendukung IUIFramework::GetUICommandProperty dan IUIFramework::SetUICommandProperty. |
UI_PKEY_Enabled | Menentukan kemampuan kontrol untuk merespons interaksi pengguna. |
Mendukung IUIFramework::GetUICommandProperty dan IUIFramework::SetUICommandProperty. |
UI_PKEY_Keytip | Hanya dapat diperbarui melalui pembatalan. | |
UI_PKEY_Label | Menentukan string karakter untuk label kontrol. |
Hanya dapat diperbarui melalui pembatalan. |
UI_PKEY_LargeHighContrastImage | Menentukan gambar kontras tinggi besar untuk ditampilkan untuk kontrol. |
Hanya dapat diperbarui melalui pembatalan. Untuk informasi selengkapnya tentang format gambar, lihat Menentukan Sumber Daya Gambar Pita. |
UI_PKEY_LargeImage | Menentukan gambar besar yang akan ditampilkan untuk kontrol. |
Hanya dapat diperbarui melalui pembatalan. Untuk informasi selengkapnya tentang format gambar, lihat Menentukan Sumber Daya Gambar Pita. |
UI_PKEY_MoreColorsLabel | Mendefinisikan label untuk tombol Warna lainnya... . Hanya valid ketika ColorTemplate memiliki nilai ThemeColors atau StandardColors . |
Mendukung IUIFramework::GetUICommandProperty dan IUIFramework::SetUICommandProperty. |
UI_PKEY_NoColorLabel | Menentukan label untuk tombol Tanpa warna . Berlaku untuk semua nilai ColorTemplate . |
Mendukung IUIFramework::GetUICommandProperty dan IUIFramework::SetUICommandProperty. |
UI_PKEY_RecentColorsCategoryLabel | Menentukan label untuk kategori Warna terbaru . Hanya valid ketika ColorTemplate memiliki nilai ThemeColors . Ini adalah satu-satunya templat yang berisi kategori berlabel. |
Mendukung IUIFramework::GetUICommandProperty dan IUIFramework::SetUICommandProperty. |
UI_PKEY_SmallHighContrastImage | Menentukan gambar kontras tinggi kecil untuk ditampilkan untuk kontrol. |
Hanya dapat diperbarui melalui pembatalan. Untuk informasi selengkapnya tentang format gambar, lihat Menentukan Sumber Daya Gambar Pita. |
UI_PKEY_SmallImage | Menentukan gambar kecil yang akan ditampilkan untuk kontrol. |
Hanya dapat diperbarui melalui pembatalan. Untuk informasi selengkapnya tentang format gambar, lihat Menentukan Sumber Daya Gambar Pita. |
UI_PKEY_StandardColors | Menentukan array nilai COLORREF untuk swatch pemilih warna Drop-Down. Setiap Pemilih Warna Drop-Down ColorTemplate berisi StandardColors kisi. Catatan: Nilai COLORREF dari Kolom StandardColorGridRows x awal array ditampilkan. Jika array mendefinisikan lebih sedikit warna daripada jumlah StandardColors swatch yang dideklarasikan dalam markup, spasi kosong ditampilkan untuk chip yang hilang. |
Mendukung IUIFramework::GetUICommandProperty dan IUIFramework::SetUICommandProperty. |
UI_PKEY_StandardColorsCategoryLabel | Menentukan label untuk kategori Warna standar . Hanya valid ketika ColorTemplate memiliki nilai ThemeColors . Ini adalah satu-satunya templat yang berisi kategori berlabel. |
Mendukung IUIFramework::GetUICommandProperty dan IUIFramework::SetUICommandProperty. |
UI_PKEY_StandardColorsTooltips | Menentukan array string tipsalat swatch warna untuk StandardColors kisi.Setiap Pemilih Warna Drop-Down ColorTemplate berisi StandardColors kisi. Catatan: Hanya tips alat yang diperlukan untuk melabeli swatch warna yang ditampilkan di StandardColors kisi yang digunakan. Jika lebih sedikit label yang disediakan daripada jumlah swatch dalam StandardColors kisi, default disediakan untuk swatch yang tersisa. |
Mendukung IUIFramework::GetUICommandProperty dan IUIFramework::SetUICommandProperty. |
UI_PKEY_ThemeColors | Menentukan array nilai COLORREF untuk swatch pemilih warna Drop-Down. Hanya valid ketika ColorTemplate memiliki nilai ThemeColors . Catatan: Nilai COLORREF dari Kolom x ThemeColorGridRows awal dari array ditampilkan. Jika array mendefinisikan lebih sedikit warna daripada jumlah ThemeColors swatch yang dideklarasikan dalam markup, spasi kosong ditampilkan untuk chip yang hilang. |
Mendukung IUIFramework::GetUICommandProperty dan IUIFramework::SetUICommandProperty. |
UI_PKEY_ThemeColorsTooltips | Menentukan array string tipsalat swatch warna untuk ThemeColors kisi.Hanya valid ketika ColorTemplate memiliki nilai ThemeColors . Catatan: Hanya tips alat yang diperlukan untuk melabeli swatch warna yang ditampilkan di ThemeColors kisi yang digunakan. Jika lebih sedikit label yang disediakan daripada jumlah swatch dalam ThemeColors kisi, default disediakan untuk swatch yang tersisa. |
Mendukung IUIFramework::GetUICommandProperty dan IUIFramework::SetUICommandProperty. |
UI_PKEY_ThemeColorsCategoryLabel | Menentukan label untuk kategori warna Tema . Hanya valid ketika ColorTemplate memiliki nilai ThemeColors . Ini adalah satu-satunya templat yang berisi kategori berlabel. |
Mendukung IUIFramework::GetUICommandProperty dan IUIFramework::SetUICommandProperty. |
UI_PKEY_TooltipDescription | Menentukan string karakter untuk deskripsi tipsalat yang terkait dengan UI_PKEY_TooltipTitle. |
Hanya dapat diperbarui melalui pembatalan. |
UI_PKEY_TooltipTitle | Menentukan string karakter untuk tipsalat Perintah. |
Hanya dapat diperbarui melalui pembatalan. |
Penangan perintah
Metode IUICommandHandler::UpdateProperty digunakan untuk menyesuaikan pemilih warna Drop-Down melalui kunci properti yang tercantum di atas. Contoh berikut menunjukkan cara mengatur swatch warna pemilih warna Drop-Down, berdasarkan preferensi gaya kustom atau kisi swatch kustom yang dideklarasikan dalam markup.
STDMETHODIMP DropDownColorPickerHandler::UpdateProperty(
UINT nCmdID,
__in REFPROPERTYKEY key,
__in_opt const PROPVARIANT* ppropvarCurrentValue,
__out PROPVARIANT* ppropvarNewValue)
{
HRESULT hr = E_NOTIMPL;
if (key == UI_PKEY_ThemeColors)
{
COLORREF rThemeColors[TOT_THEME_COLORS];
for (LONG i = 0; i < ARRAYSIZE(rThemeColors); i++)
{
// any COLORREF
rThemeColors[i] = RGB(0, 255, 0);
}
hr = InitPropVariantFromUInt32Vector(
&rThemeColors, ARRAYSIZE(rThemeColors), ppropvarNewValue);
}
else if (key == UI_PKEY_StandardColors)
{
ULONG rStandardColors[TOT_STANDARD_COLORS];
for (LONG i = 0; i < ARRAYSIZE(rStandardColors); i++)
{
// any COLORREF
rStandardColors[i] = RGB(255, 0, 0);
}
hr = InitPropVariantFromUInt32Vector(
&rStandardColors, ARRAYSIZE(rStandardColors),ppropvarNewValue);
}
else if (key == UI_PKEY_ThemeColorsTooltips)
{
BSTR rThemeTooltips[TOT_THEME_COLORS];
for (LONG i = 0; i < ARRAYSIZE(rThemeTooltips); i++)
{
// any constant character string
rThemeTooltips[i] = L"Green";
}
hr = InitPropVariantFromStringVector((PCWSTR *)&rThemeTooltips, 50, ppropvarNewValue);
}
else if (key == UI_PKEY_StandardColorsTooltips)
{
static BSTR rStandardTooltips[TOT_STANDARD_COLORS];
for (LONG i = 0; i < ARRAYSize(rStandardTooltips); i++)
{
// any constant character string
rStandardTooltips[i] = L"Red";
}
hr = InitPropVariantFromStringVector(
(PCWSTR *)&rStandardTooltips, 20, ppropvarNewValue);
}
return hr;
}
Contoh berikut menunjukkan implementasi metode IUICommandHandler::Execute yang mengekspos warna swatch Pemilih Warna Drop-Down ke aplikasi Pita.
STDMETHODIMP DropDownColorPickerHandler::Execute(
UINT nCmdID,
UI_EXECUTIONVERB verb,
__in_opt const PROPERTYKEY* key,
__in_opt const PROPVARIANT* ppropvarValue,
__in_opt IUISimplePropertySet* pCommandExecutionProperties)
{
HRESULT hr = E_NOTIMPL;
if (*key == UI_PKEY_ColorType)
{
UI_SWATCHCOLORTYPE uType =
(UI_SWATCHCOLORTYPE)PropVariantToUInt32WithDefault(
*ppropvarValue,
UI_SWATCHCOLORTYPE_NOCOLOR);
COLORREF color;
switch(uType)
{
case UI_SWATCHCOLORTYPE_RGB:
PROPVARIANT var;
pCommandExecutionProperties->GetValue(UI_PKEY_Color, &var);
color = PropVariantToUInt32WithDefault(var, 0);
break;
case UI_SWATCHCOLORTYPE_AUTOMATIC:
color = COLOR_WINDOWTEXT;
break;
case UI_SWATCHCOLORTYPE_NOCOLOR:
color = MSONoFill;
break;
}
// do with your color what you will...
gInternalColor = color;
hr = S_OK;
}
return hr;
}
Topik terkait
Saran dan Komentar
https://aka.ms/ContentUserFeedback.
Segera hadir: Sepanjang tahun 2024 kami akan menghentikan penggunaan GitHub Issues sebagai mekanisme umpan balik untuk konten dan menggantinya dengan sistem umpan balik baru. Untuk mengetahui informasi selengkapnya, lihat:Kirim dan lihat umpan balik untuk