Freigeben über


Drop-Down Farbauswahl

Das Windows-Menübandframework bietet ein spezielles Drop-Down-Steuerelement für die Farbauswahl, das eine Vielzahl von Farbeinstellungen über eine geteilte Schaltfläche und eine anpassbare Dropdown-Farbauswahl verfügbar macht.

Einführung

Durch die Emulierung des Aussehens und der Funktionalität der Microsoft Office-Farbauswahl kann das Menübandframework sowohl von Konsistenz und Vertrautheit in einer vielzahl von Anwendungen profitieren als auch dazu beitragen.

Markup

Wie alle Menübandsteuerelemente kann die Drop-Down Farbauswahl einfach implementiert und über Markup angepasst werden. Das Framework stellt eine Reihe von Elementattributen für die Drop-Down Farbauswahl bereit, um verschiedene Funktionalitätsebenen verfügbar zu machen. In der folgenden Tabelle sind die Attribute der Drop-Down Farbauswahl aufgeführt.

attribute BESCHREIBUNG
ColorTemplate Layoutvorlagen, die den Typ der Drop-Down Farbauswahl angeben.
Es gibt drei Vorlagen, von denen jede ein Steuerelementlayout und Standardwerte für zugeordnete Attribute und Eigenschaftenschlüssel angibt.
  • ThemeColors
  • StandardColors
  • HighlightColors
ChipSize Die Größe jedes Farbchips (oder Farbfelds).
  • Small
  • Medium
  • Large
Spalten Die Anzahl der Farbchipspalten (oder Farbfeldspalten).
CommandName Der Name der zugeordneten Command-Deklaration.
IsAutomaticColorButtonVisible Zeigt die Schaltfläche Automatisch an (oder blendet sie aus).
Nur gültig, wenn ColorTemplate über den Wert oder ThemeColors verfügt StandardColors.
IsNoColorButtonVisible Zeigt die Schaltfläche Keine Farbe an (oder blendet sie aus).
Gültig für alle ColorTemplate-Werte .
RecentColorGridRows Die Anzahl der Zeilen des Farbchips (oder des Farbfelds) im Bereich Zuletzt verwendete Farben .
Nur gültig, wenn ColorTemplate über den Wert verfügt ThemeColors.
StandardColorGridRows Die Anzahl von Farbchipzeilen (oder Farbfeldzeilen) im Bereich Standardfarben .
ThemeColorGridRows Die Anzahl von Farbchipzeilen (oder Farbfeldzeilen) im Bereich Designfarben .
Nur gültig, wenn ColorTemplate über den Wert verfügt ThemeColors.

Die folgenden Screenshots veranschaulichen die Standardlayouts Drop-Down Farbauswahl für die drei Farbvorlagen.

     
ThemeColorsScreenshot :[newline] des dropdowncolorpicker-Elements mit dem colortemplate-Attribut, das auf [Zeilenumbruch] standardcolorsScreenshot :[newline] des dropdowncolorpicker-Elements mit dem colortemplate-Attribut, das auf [Zeilenumbruch] highlightcolorsScreenshot:[newline] des dropdowncolorpicker-Elements mit dem colortemplate-Attribut, das auf

Das grundlegende Markup, das für jeden Drop-Down Farbauswahltyp erforderlich ist, wird in den folgenden Beispielen veranschaulicht:

Hinweis

Die Drop-Down Farbauswahl ist ein gültiges Button-Steuerelement in einer SizeDefinition-Vorlage .

<!-- 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>

Code

Als spezielles Steuerelement, das anpassungsfähig ist, erfordert jede Implementierung der Drop-Down Farbauswahl, die diese Funktionen nutzt, speziellen Anwendungscode, um Eigenschaften zu verwalten und alle vom Steuerelement ausgegebenen Befehle zu verarbeiten.

Eigenschaften

Das Menübandframework definiert eine Auflistung von Eigenschaftenschlüsseln für das Drop-Down Farbauswahl-Steuerelement.

In der Regel wird eine Drop-Down Farbauswahleigenschaft auf der Menübandbenutzeroberfläche aktualisiert, indem der dem Steuerelement zugeordnete Befehl durch einen Aufruf der IUIFramework::InvalidateUICommand-Methode ungültig wird. Das Invalidation-Ereignis wird von der IUICommandHandler::UpdateProperty-Rückrufmethode behandelt und die Eigenschaft aktualisiert.

Die IUICommandHandler::UpdateProperty-Rückrufmethode wird nicht ausgeführt, und die Anwendung wird nach einem aktualisierten Eigenschaftswert abgefragt, bis die Eigenschaft vom Framework erforderlich ist. Beispielsweise, wenn eine Registerkarte aktiviert ist und ein Steuerelement auf der Menüband-Benutzeroberfläche angezeigt wird, oder wenn eine QuickInfo angezeigt wird.

Hinweis

In einigen Fällen kann eine Eigenschaft über die IUIFramework::GetUICommandProperty-Methode abgerufen und mit der IUIFramework::SetUICommandProperty-Methode festgelegt werden.

In der folgenden Tabelle sind die Eigenschaftenschlüssel aufgeführt, die dem steuerelement Drop-Down Farbauswahl zugeordnet sind.

Eigenschaftenschlüssel BESCHREIBUNG Hinweise
UI_PKEY_AutomaticColorLabel Definiert die Bezeichnung für die Schaltfläche "Automatische Farbe".
Nur gültig, wenn ColorTemplate über den Wert oder ThemeColors verfügt StandardColors.
Unterstützt IUIFramework::GetUICommandProperty und IUIFramework::SetUICommandProperty.
UI_PKEY_Color Definiert den ausgewählten Farbwert als COLORREF.
Nur gültig, wenn UI_PKEY_ColorType den Wert hat UI_SWATCHCOLORTYPE_RGB.
Unterstützt IUIFramework::GetUICommandProperty und IUIFramework::SetUICommandProperty.
UI_PKEY_ColorType Definiert den ausgewählten Farbtyp.
Unterstützt IUIFramework::GetUICommandProperty und IUIFramework::SetUICommandProperty.
UI_PKEY_Enabled Definiert die Fähigkeit eines Steuerelements, auf Benutzerinteraktionen zu reagieren.
Unterstützt IUIFramework::GetUICommandProperty und IUIFramework::SetUICommandProperty.
UI_PKEY_Keytip Kann nur durch Ungültige aktualisiert werden.
UI_PKEY_Label Definiert die Zeichenfolge für eine Steuerelementbezeichnung.
Kann nur durch Ungültige aktualisiert werden.
UI_PKEY_LargeHighContrastImage Definiert das große Bild mit hohem Kontrast, das für ein Steuerelement angezeigt werden soll.
Kann nur durch Ungültige aktualisiert werden.
Weitere Informationen zu Bildformaten finden Sie unter Angeben von Menübandbildressourcen.
UI_PKEY_LargeImage Definiert das große Bild, das für ein Steuerelement angezeigt werden soll.
Kann nur durch Ungültige aktualisiert werden.
Weitere Informationen zu Bildformaten finden Sie unter Angeben von Menübandbildressourcen.
UI_PKEY_MoreColorsLabel Definiert die Bezeichnung für die Schaltfläche Weitere Farben...
Nur gültig, wenn ColorTemplate über den Wert oder ThemeColors verfügt StandardColors.
Unterstützt IUIFramework::GetUICommandProperty und IUIFramework::SetUICommandProperty.
UI_PKEY_NoColorLabel Definiert die Bezeichnung für die Schaltfläche Keine Farbe .
Gültig für alle ColorTemplate-Werte .
Unterstützt IUIFramework::GetUICommandProperty und IUIFramework::SetUICommandProperty.
UI_PKEY_RecentColorsCategoryLabel Definiert die Bezeichnung für die Kategorie Zuletzt verwendete Farben .
Nur gültig, wenn ColorTemplate den Wert hat ThemeColors. Dies ist die einzige Vorlage, die beschriftete Kategorien enthält.
Unterstützt IUIFramework::GetUICommandProperty und IUIFramework::SetUICommandProperty.
UI_PKEY_SmallHighContrastImage Definiert das kleine Bild mit hohem Kontrast, das für ein Steuerelement angezeigt werden soll.
Kann nur durch ungültige Aktualisierung aktualisiert werden.
Weitere Informationen zu Bildformaten finden Sie unter Angeben von Menübandbildressourcen.
UI_PKEY_SmallImage Definiert das kleine Bild, das für ein Steuerelement angezeigt werden soll.
Kann nur durch ungültige Aktualisierung aktualisiert werden.
Weitere Informationen zu Bildformaten finden Sie unter Angeben von Menübandbildressourcen.
UI_PKEY_StandardColors Definiert ein Array von COLORREF-Werten für die Farbfelder einer Drop-Down Farbauswahl.
Jede Drop-Down Color Picker ColorTemplate enthält ein StandardColors Raster.
Hinweis: Die COLORREF-Werte aus den anfänglichen StandardColorGridRows x Spalten des Arrays werden angezeigt. Wenn das Array weniger Farben definiert als die Anzahl der StandardColors im Markup deklarierten Farbfelder, werden leere Leerzeichen für die fehlenden Chips angezeigt.
Unterstützt IUIFramework::GetUICommandProperty und IUIFramework::SetUICommandProperty.
UI_PKEY_StandardColorsCategoryLabel Definiert die Bezeichnung für die Kategorie Standardfarben .
Nur gültig, wenn ColorTemplate den Wert hat ThemeColors. Dies ist die einzige Vorlage, die beschriftete Kategorien enthält.
Unterstützt IUIFramework::GetUICommandProperty und IUIFramework::SetUICommandProperty.
UI_PKEY_StandardColorsTooltips Definiert ein Zeichenfolgenarray von Farbfeld-QuickInfos für das StandardColors Raster.
Jede Drop-Down Color Picker ColorTemplate enthält ein StandardColors Raster.
Hinweis: Es werden nur die Tooltipps verwendet, die zum Beschriften der im StandardColors Raster angezeigten Farbfelder erforderlich sind. Wenn weniger Bezeichnungen als die Anzahl der Farbfelder im StandardColors Raster angegeben werden, wird eine Standardeinstellung für die verbleibenden Farbfelder bereitgestellt.
Unterstützt IUIFramework::GetUICommandProperty und IUIFramework::SetUICommandProperty.
UI_PKEY_ThemeColors Definiert ein Array von COLORREF-Werten für die Farbfelder einer Drop-Down Farbauswahl.
Nur gültig, wenn ColorTemplate den Wert hat ThemeColors.
Hinweis: Die COLORREF-Werte aus den anfänglichen ThemeColorGridRows x Spalten des Arrays werden angezeigt. Wenn das Array weniger Farben definiert als die Anzahl der ThemeColors im Markup deklarierten Farbfelder, werden leere Leerzeichen für die fehlenden Chips angezeigt.
Unterstützt IUIFramework::GetUICommandProperty und IUIFramework::SetUICommandProperty.
UI_PKEY_ThemeColorsTooltips Definiert das Zeichenfolgenarray von Farbfeld-QuickInfos für das ThemeColors Raster.
Nur gültig, wenn ColorTemplate den Wert hat ThemeColors.
Hinweis: Es werden nur die Tooltipps verwendet, die zum Beschriften der im ThemeColors Raster angezeigten Farbfelder erforderlich sind. Wenn weniger Bezeichnungen als die Anzahl der Farbfelder im ThemeColors Raster angegeben werden, wird eine Standardeinstellung für die verbleibenden Farbfelder bereitgestellt.
Unterstützt IUIFramework::GetUICommandProperty und IUIFramework::SetUICommandProperty.
UI_PKEY_ThemeColorsCategoryLabel Definiert die Bezeichnung für die Kategorie Designfarben .
Nur gültig, wenn ColorTemplate den Wert hat ThemeColors. Dies ist die einzige Vorlage, die beschriftete Kategorien enthält.
Unterstützt IUIFramework::GetUICommandProperty und IUIFramework::SetUICommandProperty.
UI_PKEY_TooltipDescription Definiert die Zeichenfolge für eine QuickInfo-Beschreibung, die einem UI_PKEY_TooltipTitle zugeordnet ist.
Kann nur durch ungültige Aktualisierung aktualisiert werden.
UI_PKEY_TooltipTitle Definiert die Zeichenfolge für eine Befehls-QuickInfo.
Kann nur durch ungültige Aktualisierung aktualisiert werden.

Befehlshandler

Die IUICommandHandler::UpdateProperty-Methode wird verwendet, um eine Drop-Down Farbauswahl über die oben aufgeführten Eigenschaftenschlüssel anzupassen. Im folgenden Beispiel wird veranschaulicht, wie die Farbfelder einer Drop-Down Farbauswahl basierend auf einer benutzerdefinierten Formateinstellung oder einem benutzerdefinierten Farbfeldraster festgelegt werden, das im Markup deklariert ist.

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

Das folgende Beispiel veranschaulicht eine Implementierung der IUICommandHandler::Execute-Methode , die die Drop-Down Farbfeldfarben für die Menübandanwendung verfügbar macht.

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 Ribbon Framework-Steuerelementbibliothek

DropDownColorPicker-Markupelement

Eigenschaften der Farbauswahl

Anpassen eines Menübands durch Größendefinitionen und Skalierungsrichtlinien

DropDownColorPicker-Beispiel