Pemilih Warna Drop-Down

Artikel
06/13/2023

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.

Pendahuluan
Markup
Kode
- Properti
- Penangan perintah
Topik terkait

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. `ThemeColors` `StandardColors` `HighlightColors`
ChipSize	Ukuran setiap chip warna (atau swatch). `Small` `Medium` `Large`
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] [baris baru]	`standardcolors`:[newline] [baris baru]	`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=&quot;cmdDropDownColorPickerGroup&quot;
       SizeDefinition=&quot;ThreeButtons&quot;>
  <DropDownColorPicker
    CommandName=&quot;cmdDropDownColorPickerThemeColors&quot;
    ColorTemplate=&quot;ThemeColors&quot;/>
  <DropDownColorPicker
    CommandName=&quot;cmdDropDownColorPickerStandardColors&quot;
    ColorTemplate=&quot;StandardColors&quot;/>
  <DropDownColorPicker
    CommandName=&quot;cmdDropDownColorPickerHighlightColors&quot;
    ColorTemplate=&quot;HighlightColors&quot;
    StandardColorGridRows=&quot;1&quot;/>
</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;
}

Pustaka Kontrol Windows Ribbon Framework
Elemen markup DropDownColorPicker
Properti Pemilih Warna
Mengkustomisasi Pita Melalui Definisi Ukuran dan Kebijakan Penskalaan
Sampel DropDownColorPicker

Bagikan melalui

Pemilih Warna Drop-Down

Pengantar

Markup

Kode

Properti

Penangan perintah

Saran dan Komentar

Saran dan Komentar

Sumber Daya Tambahan:

Bagikan melalui

Pemilih Warna Drop-Down

Pengantar

Markup

Kode

Properti

Penangan perintah

Topik terkait

Saran dan Komentar

Saran dan Komentar

Sumber Daya Tambahan: