Drop-Down颜色选取器

Windows功能区框架提供了专门的Drop-Down颜色选取器控件,该控件通过拆分按钮和可自定义的下拉颜色选择器公开各种颜色设置。

简介

通过模拟Microsoft Office颜色选取器的外观和功能,功能区框架既能受益于各种应用程序,又有助于实现一致性和熟悉性。

标记

与所有功能区控件一样,Drop-Down颜色选取器可通过标记轻松实现和自定义。 框架为Drop-Down颜色选取器提供了许多元素属性来公开各种级别的功能。 下表列出了Drop-Down颜色选取器属性。

Attribute 说明
ColorTemplate 指定Drop-Down颜色选取器类型的布局模板。
有三个模板,每个模板指定关联的属性和属性键的控件布局和默认值。
  • ThemeColors
  • StandardColors
  • HighlightColors
ChipSize 每个颜色芯片的大小 (或手表) 。
  • Small
  • Medium
  • Large
颜色芯片的数量 (或) 列。
CommandName 关联的命令声明的名称。
IsAutomaticColorButtonVisible “自动 ”按钮) 显示 (或隐藏。
仅当 ColorTemplate 的值为 ThemeColorsStandardColors.
IsNoColorButtonVisible 显示 (或隐藏) “无颜色 ”按钮。
适用于所有 ColorTemplate 值。
RecentColorGridRows 最近 颜色 区域中 (或监视) 行的颜色芯片数。
仅当 ColorTemplate 的值为 ThemeColors.
StandardColorGridRows 标准 颜色 区域中 (或监视) 行的颜色芯片数。
ThemeColorGridRows 主题 颜色 区域中 (或监视) 行的颜色芯片数。
仅当 ColorTemplate 的值为 ThemeColors.

以下屏幕截图演示三种颜色模板的默认Drop-Down颜色选取器布局。

     
ThemeColors:[newline] screen shot of the dropdowncolorpicker element with the colortemplate attribute set to 'themecolors'.[newline] standardcolors:[newline] screen shot of the dropdowncolorpicker element with the colortemplate attribute set to 'standardcolors'.[newline] highlightcolors:[newline] screen shot of the dropdowncolorpicker element with the colortemplate attribute set to 'highlightcolors'.

以下示例演示了每个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颜色选取器控件 的属性键 集合。

通常,通过调用 IUIFramework::InvalidateUICommand 方法使与控件关联的命令失效,Drop-Down颜色选取器属性在功能区 UI 中更新。 处理无效事件,并使用 IUICommandHandler::UpdateProperty 回调方法定义的属性更新。

不会执行 IUICommandHandler::UpdateProperty 回调方法,并且应用程序会查询更新的属性值,直到框架需要该属性。 例如,当选项卡被激活且在功能区 UI 中显示控件或显示工具提示时。

注意

在某些情况下,可以通过 IUIFramework::GetUICommandProperty 方法检索属性,并使用 IUIFramework::SetUICommandProperty 方法进行设置。

下表列出了与Drop-Down颜色选取器控件关联的属性键。

属性键 说明 说明
UI_PKEY_AutomaticColorLabel 定义 “自动 颜色”按钮的标签。
仅当 ColorTemplate 的值为 ThemeColorsStandardColors.
支持 IUIFramework::GetUICommandPropertyIUIFramework::SetUICommandProperty
UI_PKEY_Color 将所选颜色值定义为 COLORREF
当UI_PKEY_ColorType 具有值 UI_SWATCHCOLORTYPE_RGB时有效。
支持 IUIFramework::GetUICommandPropertyIUIFramework::SetUICommandProperty
UI_PKEY_ColorType 定义所选颜色类型。
支持 IUIFramework::GetUICommandPropertyIUIFramework::SetUICommandProperty
UI_PKEY_Enabled 定义控件响应用户交互的能力。
支持 IUIFramework::GetUICommandPropertyIUIFramework::SetUICommandProperty
UI_PKEY_Keytip 只能通过无效更新。
UI_PKEY_Label 定义控件标签的字符串。
只能通过无效更新。
UI_PKEY_LargeHighContrastImage 定义要为控件显示的大型高对比度图像。
只能通过无效更新。
有关图像格式的详细信息,请参阅 “指定功能区图像资源”。
UI_PKEY_LargeImage 定义要为控件显示的大型图像。
只能通过无效更新。
有关图像格式的详细信息,请参阅 “指定功能区图像资源”。
UI_PKEY_MoreColorsLabel 定义 “更多颜色...” 按钮的标签。
仅当 ColorTemplate 的值为 ThemeColorsStandardColors.
支持 IUIFramework::GetUICommandPropertyIUIFramework::SetUICommandProperty
UI_PKEY_NoColorLabel 定义 “无颜色 ”按钮的标签。
适用于所有 ColorTemplate 值。
支持 IUIFramework::GetUICommandPropertyIUIFramework::SetUICommandProperty
UI_PKEY_RecentColorsCategoryLabel 定义 最近颜色 类别的标签。
仅当 ColorTemplate 的值为 ThemeColors. 这是唯一包含已标记类别的模板。
支持 IUIFramework::GetUICommandPropertyIUIFramework::SetUICommandProperty
UI_PKEY_SmallHighContrastImage 定义要为控件显示的小型高对比度图像。
只能通过无效更新。
有关图像格式的详细信息,请参阅 指定功能区图像资源
UI_PKEY_SmallImage 定义要为控件显示的小型图像。
只能通过无效更新。
有关图像格式的详细信息,请参阅 指定功能区图像资源
UI_PKEY_StandardColors 为Drop-Down颜色选取器的色板定义 COLORREF 值的数组。
每个Drop-Down颜色选取器 ColorTemplate 都包含一个 StandardColors 网格。
[!注意]
将显示数组的初始 StandardColorGridRows x 中的 COLORREF 值。 如果数组定义的颜色少于标记中声明的 StandardColors 色板数,则为缺失的芯片显示空白空间。

支持 IUIFramework::GetUICommandPropertyIUIFramework::SetUICommandProperty
UI_PKEY_StandardColorsCategoryLabel 定义 标准颜色 类别的标签。
仅当 ColorTemplate 具有值 ThemeColors时有效。 这是唯一包含已标记类别的模板。
支持 IUIFramework::GetUICommandPropertyIUIFramework::SetUICommandProperty
UI_PKEY_StandardColorsTooltips 定义网格的颜色监视工具提示的 StandardColors 字符串数组。
每个Drop-Down颜色选取器 ColorTemplate 都包含一个 StandardColors 网格。
[!注意]
仅使用这些工具提示来标记网格中显示的 StandardColors 颜色色板。 如果提供的标签数少于网格中的 StandardColors 样本数,则为保留的表提供默认值。

支持 IUIFramework::GetUICommandPropertyIUIFramework::SetUICommandProperty
UI_PKEY_ThemeColors 为Drop-Down颜色选取器的色板定义 COLORREF 值的数组。
仅当 ColorTemplate 具有值 ThemeColors时有效。
[!注意]
将显示数组的初始 ThemeColorGridRows x 中的 COLORREF 值。 如果数组定义的颜色少于标记中声明的 ThemeColors 色板数,则为缺失的芯片显示空白空间。

支持 IUIFramework::GetUICommandPropertyIUIFramework::SetUICommandProperty
UI_PKEY_ThemeColorsTooltips 定义网格的颜色监视工具提示的 ThemeColors 字符串数组。
仅当 ColorTemplate 具有值 ThemeColors时有效。
[!注意]
仅使用这些工具提示来标记网格中显示的 ThemeColors 颜色色板。 如果提供的标签数少于网格中的 ThemeColors 样本数,则为保留的表提供默认值。

支持 IUIFramework::GetUICommandPropertyIUIFramework::SetUICommandProperty
UI_PKEY_ThemeColorsCategoryLabel 定义 主题颜色 类别的标签。
仅当 ColorTemplate 具有值 ThemeColors时有效。 这是唯一包含已标记类别的模板。
支持 IUIFramework::GetUICommandPropertyIUIFramework::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 示例