Drop-Down Farbauswahl

Artikel
08/19/2023

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.

Introduction (Einführung)
Markup
Code
- Eigenschaften
- Befehlshandler
Zugehörige Themen

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.


`ThemeColors`Screenshot :[newline] [Zeilenumbruch]	`standardcolors`Screenshot :[newline] [Zeilenumbruch]	`highlightcolors`Screenshot:[newline]

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

Drop-Down Farbauswahl

Einführung

Markup

Code

Eigenschaften

Befehlshandler

Feedback

Feedback

Zusätzliche Ressourcen

Drop-Down Farbauswahl

Einführung

Markup

Code

Eigenschaften

Befehlshandler

Zugehörige Themen

Feedback

Feedback

Zusätzliche Ressourcen