Table of content

• Table of content
• Introduction
• ColorNamesDictionary and ColorHelper
  • Looking up a color name
  • Getting a color from a given name
    • Examples
  • How to provide custom color names
    • Example
  • Provide translations for a language of your choice
  • Use your own ColorHelper
• ColorCanvas
  • The user interface
  • Properties
  • Events
  • DynamicResources
  • Example
• ColorPalette
  • The user interface
  • Properties
  • DynamicResources
  • Example
  • Build in color palettes
• ColorEyeDropper
  • The user interface
  • Properties
  • Events
  • Example
• ColorPicker
  • The user interface
  • Properties
  • Events
  • DynamicResources
  • Example
    • Basic example
    • Using the SelectedColorChanged-Event
    • Customizing the content of the color picker

Introduction

The ColorPicker controls can be used to select any System.Windows.Media.Color (in this document simply called Color). There are four different controls available to select a Color.

ColorNamesDictionary and ColorHelper

Colors may have a name which is localize-able if you want to. The color names are stored in a Dictionary<Color?, string> which is used to get the name of the provided Color.

Looking up a color name

If you want to look up a name of a given Color in code behind use this line:

string nameOfTheColor = MahApps.Metro.Controls.ColorHelper.DefaultInstance.GetColorName(myColor, theDictionaryToUse);

Getting a color from a given name

You can also get back the color by looking up its name. The routine will first check the dictionary for the first occurrence of the given name and if it was not found it will try to use ColorConverter.ConvertFromString which also accepts the HTML-Notation of the Color. If the Color cannot be found it will return null.

Examples

Color? myColor = MahApps.Metro.Controls.ColorHelper.DefaultInstance.ColorFromString(myColorName, theDictionaryToUse);

// this will look up the German word "Blau" and returns blue color
Color? myColor = MahApps.Metro.Controls.ColorHelper.DefaultInstance.ColorFromString("Blau", null);

// this will look up the HTML-notation "#FF000000" and returns black color
Color? myColor = MahApps.Metro.Controls.ColorHelper.DefaultInstance.ColorFromString("#FF000000", null);

How to provide custom color names

You can change the build in dictionary via MahApps.Metro.Controls.ColorHelper.ColorNamesDictionary by adding, removing or changing any color name. You can also create your own Dictionary<Color?, string> anywhere in your Model or ViewModel to provide your own color names. That way you can use also different dictionaries for different ColorPicker.

Example

Dictionary<Color?, string> myColorNames = new Dictionary<Color?, string>()
{
    { Colors.Green, "every thing is fine" }, 
    { Colors.Yellow, "warning" },
    { Colors.Red, "error" }
};

public Dictionary<Color?, string> MyColorNames
{
    get { return myColorNames; }    
}

<!-- example usage -->
<!-- xmlns:mah="http://metro.mahapps.com/winfx/xaml/controls" -->
<mah:ColorPicker ColorNamesDictionary="{Binding MyColorNames}" />

Provide translations for a language of your choice

Currently implemented color languages are

• English
• German

You can help providing translations to the build in dictionary.

We recommend using the ResXManager.

Use your own ColorHelper

The ColorHelper can be derived from which lets you create your own logic for ColorFromString and GetColorName:

// Add this to your using-section
using MahApps.Metro.Controls;

namespace MyNamespace
{
    public class MyColorHelper : ColorHelper
    {
        public static new readonly MyColorHelper DefaultInstance = new();

        public override Color? ColorFromString(string? colorName, Dictionary<Color, string>? colorNamesDictionary)
        {
            // Your logic goes here
            return myFoundColor;
        }
    
        public override string? GetColorName(Color? color, Dictionary<Color, string>? colorNamesDictionary, bool useAlphaChannel)
        {
            // Your logic goes here
            return theNameOfMyColor;
        }
    }
}

You can then use this class like every other Property:

<!-- make sure to add the right namespace -->
<!-- xmlns:mah="http://metro.mahapps.com/winfx/xaml/controls" -->

<mah:ColorPicker ColorHelper="[[Bind here to your ColorHelper]]" />
<mah:ColorCanvas ColorHelper="[[Bind here to your ColorHelper]]" />
<mah:ColorPalette ColorHelper="[[Bind here to your ColorHelper]]" />

<!-- example usage -->
<!-- xmlns:my="clr-namespace:MyNamespace;assembly=YourAssembly" -->
<mah:ColorPicker ColorHelper="{Binding Source={x:Static my:MyColorHelper.DefaultInstance}}" />

ColorCanvas

The ColorCanvas control lets the user select a Color by the following options:

• Changing the ARGB-Values
• Changing the HSV-Values
• Entering the color name or HTML-notation
• Picking a color from anywhere of the screen

The user interface

Properties

Events

DynamicResources

You can override the following Resources to modify the appearance of the ColorCanvas further.

Example

<!-- make sure to add the right namespace -->
<!-- xmlns:mah="http://metro.mahapps.com/winfx/xaml/controls" -->

<mah:ColorCanvas x:Name="ColorCanvasExample"
                 SelectedColor="Blue"
                 DefaultColor="Transparent"
                 LabelAlphaChannel="Alpha"
                 LabelBlueChannel="Blue"
                 LabelGreenChannel="Green"
                 LabelRedChannel="Red" />

ColorPalette

The ColorPalette control can be used to present the user a swatch of predefined colors. As this control is derived from System.Windows.Controls.ListBox you can use all functionality know from the ListBox control.

The user interface

Properties

The available colors can be either added directly to the Items or by binding to the ItemsSource. The selection can be handled by binding to SelectedValue, SelectedItem or SelectedIndex.

In addition to this the ColorPalette provides the following properties.

DynamicResources

Example

The below example shows how to use the ColorPalette via setting the ItemsSource to a build in ColorPalette.

<!-- make sure to add the right namespace -->
<!-- xmlns:mah="http://metro.mahapps.com/winfx/xaml/controls" -->

<mah:ColorPalette Header="An Example Palette" 
                  ItemsSource="{x:Static mah:BuildInColorPalettes.WpfColorsPalette}" />

The second example shows how to add colors directly in XAML.

<!-- make sure to add the right namespace -->
<!-- xmlns:mah="http://metro.mahapps.com/winfx/xaml/controls" -->

<mah:ColorPalette Header="A second Example Palette" >
    <Color>Red</Color>
    <Color>Green</Color>
    <Color>Blue</Color>
</mah:ColorPalette>

Build in color palettes

MahApps provides the following build in ColorPalettes:

• WpfColorsPalette (all colors in Sytem.Windows.Media.Colors)
• StandardColorsPalette (the primary colors)
• RecentColors (used to store the recently selected colors)

All build in ColorPalettes are internally an ObservableCollection, so you can modify them to your needs.

ColorEyeDropper

The ColorEyeDropper control lets the user select a Color with the mouse directly from anywhere on the screen, even outside of your Application. As this control is derived from System.Windows.Controls.Button you can use all functionality know from the Button control.

The user interface

If the user presses the left mouse button on the ColorEyeDropper the cursor will change to an eye-dropper symbol and a preview popup will appear. Now the user needs to keep the mouse pressed while dragging the mouse to the desired pixel. A magnifier with a cross hair helps getting the exact pixel position. As soon as the user releases the left mouse button the SelectedColor will get updated.

Properties

Events

Example

<!-- make sure to add the right namespace -->
<!-- xmlns:mah="http://metro.mahapps.com/winfx/xaml/controls" -->

<mah:ColorEyeDropper Content="This is my EyeDropper"
                     SelectedColor="{Binding Path=MyColorToBind}" />

If you want to modify the preview template please take a look to the below example. It shows how to make a circular magnifier with the preview color shown in the outer circle.

<!-- make sure to add the right namespace -->
<!-- xmlns:mah="http://metro.mahapps.com/winfx/xaml/controls" -->
<!-- xmlns:po="http://schemas.microsoft.com/winfx/2006/xaml/presentation/options" -->

<mah:ColorEyeDropper Content="{iconPacks:Material Kind=Eyedropper}"
                     SelectedColor="{DynamicResource MahApps.Colors.AccentBase}">
    <mah:ColorEyeDropper.PreviewContentTemplate>
        <DataTemplate DataType="{x:Type mah:ColorEyePreviewData}">
            <Border Width="62"
                    Height="62"
                    Padding="0"
                    BorderBrush="{Binding PreviewBrush}"
                    BorderThickness="5"
                    CornerRadius="{Binding RelativeSource={RelativeSource Mode=Self}, Path=ActualHeight, Converter={mah:SizeToCornerRadiusConverter}}">
                <Grid HorizontalAlignment="Center" VerticalAlignment="Center">
                    <Grid.Clip>
                        <EllipseGeometry Center="25,25"
                                         RadiusX="25"
                                         RadiusY="25" />
                    </Grid.Clip>
                    <Image x:Name="PART_PreviewImage"
                           Width="50"
                           Height="50"
                           RenderOptions.BitmapScalingMode="NearestNeighbor"
                           Source="{Binding PreviewImage}" />
                    <Path Stroke="{Binding PreviewBrush, Converter={x:Static mah:BackgroundToForegroundConverter.Instance}}" StrokeThickness="1">
                        <Path.Data>
                            <PathGeometry po:Freeze="true" Figures=" m 0 25 20 0  m 5 5 0 20  m 5 -25 20 0  m -25 -25 0 20 m -5 0 H20 H30 V30 H20 z" />
                        </Path.Data>
                    </Path>
                </Grid>
            </Border>
        </DataTemplate>
    </mah:ColorEyeDropper.PreviewContentTemplate>
</mah:ColorEyeDropper>

ColorPicker

This control lets the user select a Color in a ComboBox-like control. The user can either select a Color from a predefined ColorPalette or select a custom one in a ColorCanvas.

The user interface

Properties

The ColorPicker can hold up to five different ColorPalettes which can be controlled by the following properties. As the properties repeat for all five ColorPalettes we use [###ColorPalette] as a placeholder. In your code please replace it with one of these names:

• StandardColorPalette
• AvailableColorPalette
• RecentColorPalette
• CustomColorPalette01
• CustomColorPalette02

The RecentColorPalette is a special ColorPalette which is used to store the recent selected colors. To control the behavior of this ColorPalette you can use these two properties.

Events

DynamicResources

Example

Basic example

<!-- make sure to add the right namespace -->
<!-- xmlns:mah="http://metro.mahapps.com/winfx/xaml/controls" -->

<mah:ColorPicker SelectedColor="{Binding myColor}" 
                 mah:TextBoxHelper.ClearTextButton="True"
                 mah:TextBoxHelper.UseFloatingWatermark="True"
                 mah:TextBoxHelper.Watermark="Select a color"
                 AddToRecentColorsTrigger="SelectedColorChanged" />

Using the SelectedColorChanged-Event

The following example shows how the SelectedColorChanged-Event can be used to create a custom theme.

<!-- make sure to add the right namespace -->
<!-- xmlns:mah="http://metro.mahapps.com/winfx/xaml/controls" -->

<mah:ColorPicker SelectedColorChanged="ColorPicker_SelectedColorChanged"
                 mah:TextBoxHelper.ClearTextButton="True"
                 mah:TextBoxHelper.UseFloatingWatermark="True"
                 mah:TextBoxHelper.Watermark="Select a color"
                 AddToRecentColorsTrigger="SelectedColorChanged" />

The event event is handled in the code behind section:

// Make sure you have addes these usings into your usings section
using ControlzEx.Theming;
using System.Windows;
using System.Windows.Media;

private void ColorPicker_SelectedColorChanged(object sender, RoutedPropertyChangedEventArgs<Color?> e)
{
    if (e.NewValue.HasValue)
    {
        Theme newTheme = new Theme(name: "CustomTheme",
                                   displayName: "CustomTheme",
                                   baseColorScheme: "Light",
                                   colorScheme: "CustomAccent",
                                   primaryAccentColor: e.NewValue.Value,
                                   showcaseBrush: new SolidColorBrush(e.NewValue.Value),
                                   isRuntimeGenerated: true,
                                   isHighContrast: false);

        ThemeManager.Current.ChangeTheme(Application.Current, newTheme);
    }
}

Customizing the content of the color picker

This section shows how the content (03 in the picture below) can be customized

There are also some build-in DataTemplates: MahApps.Metro Source ▶ Themes ▶ ColorPicker ▶ ColorPicker.xaml

ColorAndName (default)

<mah:ColorPicker Width="150"
                 SelectedColor="red"
                 SelectedColorTemplate="{DynamicResource MahApps.Templates.ColorPickerContent.ColorAndName}" />

ColorOnly

<mah:ColorPicker Width="150"
                 SelectedColor="red"
                 SelectedColorTemplate="{DynamicResource MahApps.Templates.ColorPickerContent.ColorOnly}" />

A custom DataTemplate could look like this:

<!-- make sure to add the right namespace -->
<!-- xmlns:mah="http://metro.mahapps.com/winfx/xaml/controls" -->

<!-- Add a DataTemplate in your Resources-Section. This can be in App.xaml, MainWindow.xaml or any other place. Here we define it inside a UserControl -->

<UserControl.Resources>
    <DataTemplate x:Key="My.Datatemplates.CustomColorPickerContent">
        <Grid x:Name="RootGrid">
            <Grid.ColumnDefinitions>
                <ColumnDefinition Width="Auto" />
                <ColumnDefinition Width="*" />
            </Grid.ColumnDefinitions>

            <mah:ClipBorder Grid.Column="0"
                            Width="80"
                            Height="80"
                            Background="{DynamicResource MahApps.Brushes.Tile.Small}"
                            BorderBrush="{DynamicResource MahApps.Brushes.Control.Border}"
                            BorderThickness="3"
                            CornerRadius="{Binding RelativeSource={RelativeSource Mode=Self}, Path=ActualHeight, Converter={mah:SizeToCornerRadiusConverter}}">
                <Grid Background="{Binding Converter={x:Static mah:ColorToSolidColorBrushConverter.DefaultInstance}}">
                    <TextBlock HorizontalAlignment="Center"
                               VerticalAlignment="Center"
                               Foreground="{Binding RelativeSource={RelativeSource Mode=FindAncestor, AncestorType=Grid}, Path=Background, Converter={x:Static mah:BackgroundToForegroundConverter.Instance}}"
                               Text="{Binding}" />
                </Grid>
            </mah:ClipBorder>
        </Grid>
        <DataTemplate.Triggers>
            <DataTrigger Binding="{Binding}" Value="{x:Null}">
                <Setter TargetName="RootGrid" Property="Visibility" Value="Collapsed" />
            </DataTrigger>
        </DataTemplate.Triggers>
    </DataTemplate>
</UserControl.Resources>

<!-- Now we need to reference our DataTemplate either as StaticResource or DynamicResource -->
<mah:ColorPicker Height="100"
                 HorizontalAlignment="Left"
                 SelectedColor="blue"
                 SelectedColorTemplate="{StaticResource My.Datatemplates.CustomColorPickerContent}" />

The final result will look like this: