Drop-Down 色彩選擇器

發行項
08/19/2023

Windows 功能區架構提供特殊的 Drop-Down 色彩選擇器控制項，可透過分割按鈕和可自訂的下拉式色彩選取器來公開各種色彩設定。

簡介
加成
程式碼
- 屬性
- 命令處理常式
相關主題

簡介

藉由模擬 Microsoft Office 色彩選擇器的外觀和功能，功能區架構能夠受益于各種應用程式的一致性和熟悉度，

加成

如同所有功能區控制項，Drop-Down 色彩選擇器可以輕鬆地透過標記實作和自訂。架構提供一些元素屬性，供 Drop-Down 色彩選擇器公開各種功能層級。下表列出 Drop-Down 色彩選擇器屬性。

屬性	描述
ColorTemplate	指定色彩選擇器類型的版面配置範本 Drop-Down。有三個範本，分別指定相關聯屬性和屬性索引鍵的控制項配置和預設值。 `ThemeColors` `StandardColors` `HighlightColors`
ChipSize	每個色彩晶片的大小 (或色板) 。 `Small` `Medium` `Large`
資料行	色晶片 (或) 資料行的色板數目。
CommandName	相關聯 Command 宣告的名稱。
IsAutomaticColorButtonVisible	顯示 (或隱藏) [ 自動] 按鈕。只有在 ColorTemplate 的值為 `ThemeColors` 或 `StandardColors` 時才有效。
IsNoColorButtonVisible	顯示 (或隱藏) [ 無色彩 ] 按鈕。適用于所有 ColorTemplate 值。
RecentColorGridRows	[最近色彩] 區域中 (或) 列的色彩晶片數目。只有在 ColorTemplate 的值為 `ThemeColors` 時才有效。
StandardColorGridRows	標準色彩區域中 (或色板) 列的色彩晶片數目。
ThemeColorGridRows	主題色彩區域中 (或色板) 列的色彩晶片數目。只有在 ColorTemplate 的值為 `ThemeColors` 時才有效。

下列螢幕擷取畫面說明三種色彩範本的預設 Drop-Down 色彩選擇器版面配置。


`ThemeColors`：[newline] [分行符號]	`standardcolors`：[newline] [分行符號]	`highlightcolors`：[newline]

下列範例示範每個 Drop-Down 色彩選擇器類型所需的基本標記：

注意

Drop-Down 色彩選擇器是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>

程式碼

作為支援自訂的特殊控制項，任何利用這些功能的 Drop-Down 色彩選擇器實作，都需要特殊化應用程式程式碼來管理屬性，並處理控制項發出的任何命令。

屬性

功能區架構會定義 Drop-Down 色彩選擇器控制項的屬性索引鍵集合。

一般而言，Drop-Down 色彩選擇器屬性會在功能區 UI 中更新，方法是透過 呼叫 IUIFramework：：InvalidateUICommand 方法，使與控制項相關聯的 Command 失效。會處理無效事件，以及 IUICommandHandler：：UpdateProperty 回呼方法所定義的屬性更新。

不會執行 IUICommandHandler：：UpdateProperty回呼方法，而且應用程式會查詢更新的屬性值，直到架構需要屬性為止。例如，當索引標籤啟動時，以及功能區 UI 中顯示的控制項，或顯示工具提示時。

注意

在某些情況下，可以透過 IUIFramework：：GetUICommandProperty 方法擷取屬性，並使用 IUIFramework：：SetUICommandProperty 方法進行設定。

下表列出與 Drop-Down 色彩選擇器控制項相關聯的屬性索引鍵。

屬性索引鍵	描述	注意
UI_PKEY_AutomaticColorLabel	定義 [自動色彩] 按鈕的標籤。只有在 ColorTemplate 的值為 `ThemeColors` 或 `StandardColors` 時才有效。	支援 IUIFramework：：GetUICommandProperty 和 IUIFramework：：SetUICommandProperty。
UI_PKEY_Color	將選取的色彩值定義為 COLORREF。只有在 UI_PKEY_ColorType 值為 `UI_SWATCHCOLORTYPE_RGB` 時才有效。	支援 IUIFramework：：GetUICommandProperty 和 IUIFramework：：SetUICommandProperty。
UI_PKEY_ColorType	定義選取的色彩類型。	支援 IUIFramework：：GetUICommandProperty 和 IUIFramework：：SetUICommandProperty。
UI_PKEY_Enabled	定義控制項回應使用者互動的能力。	支援 IUIFramework：：GetUICommandProperty 和 IUIFramework：：SetUICommandProperty。
UI_PKEY_Keytip	只能透過失效來更新。
UI_PKEY_Label	定義控制項標籤的字元字串。	只能透過失效來更新。
UI_PKEY_LargeHighContrastImage	定義控制項要顯示的大型高對比影像。	只能透過失效來更新。如需影像格式的詳細資訊，請參閱指定功能區映射資源。
UI_PKEY_LargeImage	定義控制項要顯示的大型影像。	只能透過失效來更新。如需影像格式的詳細資訊，請參閱指定功能區映射資源。
UI_PKEY_MoreColorsLabel	定義 [更多色彩...] 按鈕的標籤。只有在 ColorTemplate 的值為 `ThemeColors` 或 `StandardColors` 時才有效。	支援 IUIFramework：：GetUICommandProperty 和 IUIFramework：：SetUICommandProperty。
UI_PKEY_NoColorLabel	定義 [ 無色彩 ] 按鈕的標籤。適用于所有 ColorTemplate 值。	支援 IUIFramework：：GetUICommandProperty 和 IUIFramework：：SetUICommandProperty。
UI_PKEY_RecentColorsCategoryLabel	定義 [最近色彩 ] 類別的標籤。只有在 ColorTemplate 的值為 `ThemeColors` 時才有效。這是唯一包含已標記類別的範本。	支援 IUIFramework：：GetUICommandProperty 和 IUIFramework：：SetUICommandProperty。
UI_PKEY_SmallHighContrastImage	定義控制項要顯示的小型高對比影像。	只能透過失效來更新。如需影像格式的詳細資訊，請參閱指定功能區映射資源。
UI_PKEY_SmallImage	定義控制項要顯示的小型影像。	只能透過失效來更新。如需影像格式的詳細資訊，請參閱指定功能區映射資源。
UI_PKEY_StandardColors	定義 Drop-Down 色彩選擇器之色板的 COLORREF 值陣列。每個 Drop-Down 色彩選擇器 ColorTemplate 都包含網格 `StandardColors` 線。注意：會顯示陣列初始StandardColorGridRowsx Columns中的COLORREF值。如果陣列定義的色彩少於標記中所宣告的色板數目 `StandardColors` ，則會針對遺漏的晶片顯示空白。	支援 IUIFramework：：GetUICommandProperty 和 IUIFramework：：SetUICommandProperty。
UI_PKEY_StandardColorsCategoryLabel	定義標準色彩類別的標籤。只有在 ColorTemplate 的值為 `ThemeColors` 時才有效。這是唯一包含已標記類別的範本。	支援 IUIFramework：：GetUICommandProperty 和 IUIFramework：：SetUICommandProperty。
UI_PKEY_StandardColorsTooltips	定義格線色彩色板工具提示的 `StandardColors` 字串陣列。每個 Drop-Down 色彩選擇器 ColorTemplate 都包含網格 `StandardColors` 線。注意：只會使用標記格線中顯示的 `StandardColors` 色彩樣板所需的工具提示。如果提供的標籤比方格中的 `StandardColors` 色板數目少，則會為保留的監看式提供預設值。	支援 IUIFramework：：GetUICommandProperty 和 IUIFramework：：SetUICommandProperty。
UI_PKEY_ThemeColors	定義 Drop-Down 色彩選擇器之色板的 COLORREF 值陣列。只有在 ColorTemplate 的值為 `ThemeColors` 時才有效。注意：會顯示陣列初始ThemeColorGridRowsx Columns中的COLORREF值。如果陣列定義的色彩少於標記中所宣告的色板數目 `ThemeColors` ，則會針對遺漏的晶片顯示空白。	支援 IUIFramework：：GetUICommandProperty 和 IUIFramework：：SetUICommandProperty。
UI_PKEY_ThemeColorsTooltips	定義格線色彩色板工具提示的 `ThemeColors` 字串陣列。只有在 ColorTemplate 的值為 `ThemeColors` 時才有效。注意：只會使用標記格線中顯示的 `ThemeColors` 色彩樣板所需的工具提示。如果提供的標籤比方格中的 `ThemeColors` 色板數目少，則會為保留的監看式提供預設值。	支援 IUIFramework：：GetUICommandProperty 和 IUIFramework：：SetUICommandProperty。
UI_PKEY_ThemeColorsCategoryLabel	定義主題色彩類別的標籤。只有在 ColorTemplate 的值為 `ThemeColors` 時才有效。這是唯一包含已標記類別的範本。	支援 IUIFramework：：GetUICommandProperty 和 IUIFramework：：SetUICommandProperty。
UI_PKEY_TooltipDescription	定義與 UI_PKEY_TooltipTitle相關聯之工具提示描述的字元字串。	只能透過失效來更新。
UI_PKEY_TooltipTitle	定義命令工具提示的字元字串。	只能透過失效來更新。

命令處理常式

IUICommandHandler：：UpdateProperty方法可用來透過上面所列的屬性索引鍵自訂 Drop-Down 色彩選擇器。下列範例示範如何根據自訂樣式喜好設定或標記中宣告的自訂樣板格線，設定 Drop-Down 色彩選擇器的色彩樣板。

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

下列範例示範 IUICommandHandler：：Execute 方法的實作，這個方法會將 Drop-Down 色彩選擇器色樣公開至功能區應用程式。

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

Windows 功能區架構控制項程式庫
DropDownColorPicker 標記專案
色彩選擇器屬性
透過大小定義和調整原則自訂功能區
DropDownColorPicker 範例

共用方式為

Drop-Down 色彩選擇器

簡介

加成

程式碼

屬性

命令處理常式

意見反應

其他資源

共用方式為

Drop-Down 色彩選擇器

簡介

加成

程式碼

屬性

命令處理常式

相關主題

意見反應

其他資源