WinForms › Office2007 Color Picker › BinaryOfficeColorPickerComboBox

BinaryOfficeColorPickerComboBox

class.NET 6 / 8 / 10.NET Framework 4.8Binarymission.WinForms.Controls.ColorPickers

A combo box for choosing a colour from an Office-style palette: it shows the chosen colour as a swatch with its RGB values or name, and drops down a BinaryOfficeColorPicker with theme colours, standard colours, "More colors..." and optional alpha blending.

public partial class BinaryOfficeColorPickerComboBox : System.Windows.Forms.ComboBox

Inherits from / implements: System.Windows.Forms.ComboBox

Remarks

What it is for

Use it wherever users pick a colour and expect the Office look – text and fill colours in an editor, a category colour in a planner, a series colour in a report designer.

How it works

A click on the control opens the palette just below it; a second click on the control closes it.
A single click on a swatch updates SelectedColor straight away and raises SelectedColorChanged, leaving the palette open so the user can try colours. A double-click on a swatch, or a click on the preview swatch, commits the choice and closes the palette.
With EnableSettingAlphaValue, the palette also offers an alpha slider and a blend colour; the colour reported is the chosen colour mixed with BlendTargetColor.

The palette's appearance is set through this control – HeadingBackColor, HeadingForeColor, BorderColor, CustomColorForRectangleBorder, ShowToolTip. The closed control is drawn flat, its border in CustomControlBorderColor while it has the focus or the pointer. Right-to-left layout is not supported.

Note

After the palette is closed by a click elsewhere, the next click on the control does not open it; the click after that does.

Examples

using System;
using System.Drawing;
using System.Windows.Forms;
using Binarymission.WinForms.Controls.ColorPickers;

public class CategoryForm : Form
{
    private readonly BinaryOfficeColorPickerComboBox categoryColour;
    private readonly Label preview;

    public CategoryForm()
    {
        Text = "Edit category";
        ClientSize = new Size(320, 90);

        categoryColour = new BinaryOfficeColorPickerComboBox
        {
            Location = new Point(12, 12),
            Width = 180,
            ShowColorNameIfKnownColor = true,
            HeadingBackColor = Color.Gainsboro,
            ShowHSBInToolTip = true
        };
        categoryColour.SelectedColorChanged += CategoryColour_SelectedColorChanged;

        preview = new Label { Text = "Client meetings", Location = new Point(206, 15), AutoSize = true };

        Controls.Add(categoryColour);
        Controls.Add(preview);
    }

    private void CategoryColour_SelectedColorChanged(object sender, BinaryColorPickerExtendedEventArgs e)
    {
        // Read the property: e is null when the colour is set in code before the user has chosen one.
        preview.BackColor = categoryColour.SelectedColor;
    }
}

Members at a glance

Constructors
`BinaryOfficeColorPickerComboBox`	Initialises a colour picker with no colour selected; it shows a white swatch and the text "Empty".
Properties
`AlphaBlendFactorForControlPainting`	Gets or sets how strongly the window colour shows in the drop-down button's resting background, while the control has neither the focus nor the pointer.
`AlphaBlendFactorForDropDownPressedColor`	Gets or sets how strongly `CustomPaintingColor` shows in the drop-down button's pressed look.
`AlphaBlendFactorForItemSelectionColor`	Gets or sets how strongly `CustomPaintingColor` shows in the drop-down button and the highlighted face.
`AlphaValue`	Gets or sets the alpha value the control holds: the one the user last chose, from 0 to 255.
`BlendTargetColor`	Gets or sets the colour the chosen colour is mixed with when alpha blending is on.
`BorderColor`	Gets or sets the colour of the line round the drop-down palette.
`CustomColorForRectangleBorder`	Gets or sets the colour of the frame the palette draws round the swatch the user clicks.
`CustomControlBorderColor`	Gets or sets the colour of the control's border while it has the focus or the pointer is over it, or all the time with `ShowBorderAlways`.
`CustomPaintingColor`	Gets or sets the colour the drop-down button and the highlighted face are shaded from.
`EnableSettingAlphaValue`	Gets or sets whether the palette shows the alpha slider and the "Blend with color" swatch.
`HeadingBackColor`	Gets or sets the background of the palette's headings, its "More colors..." strip and its alpha panel.
`HeadingForeColor`	Gets or sets the colour of the palette's heading text and labels.
`RightToLeft`	Gets or sets right-to-left layout, which this control does not support: any value set is stored as `No`.
`SelectedColor`	Gets or sets the colour the control shows – the colour the user chose, mixed with the blend colour when alpha blending is on.
`SelectedColorRectangleBorder`	Gets or sets a colour handed to the palette for the frame round the clicked swatch.
`ShowBorderAlways`	Gets or sets whether the border and the drop-down button are drawn in their highlighted colours all the time, rather than only while the control has the focus or the pointer.
`ShowColorNameIfKnownColor`	Gets or sets whether the control shows a colour's name – "Tomato", "ControlText" – instead of its RGB values when the colour has one.
`ShowHSBInToolTip`	Gets or sets whether the palette's tool tips add each colour's hue, saturation and brightness.
`ShowToolTip`	Gets or sets whether pointing at a swatch in the palette shows its colour's name or RGB values.
Methods
`Dispose`	Releases the resources held by the control.
`DrawComboBoxFace`	Draws the closed control: the background, the colour swatch and the text.
`DrawComboBoxFaceBackground`	Draws the background of the closed control. Override to change it without taking over the swatch, the text and the drop-down button.
`DrawDisabledFace`	Draws the control in its disabled form: an empty swatch outline and the text in `SystemColors.ControlDark`.
`DrawDisabledFaceBackground`	Draws the background, the grey border and the dimmed drop-down button of the disabled control. Override to change the disabled look without taking over the swatch and the text.
`DrawListItem`	Draws one row of the control's own item list: the background, the colour swatch and the text.
`DrawListItemBackground`	Draws the background of one row of the control's own item list. Override to change it without taking over the swatch and the text.
`MeasureTextViaGdi`	Measures a single line of text the way GDI draws it, which can differ from `Graphics.MeasureString`.
`OnDrawItem`	Draws an item of the control's own list with `DrawListItem`. The `ComboBox.DrawItem` event is not raised.
`OnGotFocus`	Raises the `Control.GotFocus` event and draws the border and the drop-down button in their highlighted colours.
`OnHandleCreated`	Removes the Windows visual style from the new window, so the control's own drawing is not fought by the theme, and raises the `Control.HandleCreated` event.
`OnKeyPress`	Raises the `Control.KeyPress` event.
`OnLostFocus`	Raises the `Control.LostFocus` event and, unless `ShowBorderAlways` is set, takes the border away.
`OnMouseEnter`	Raises the `Control.MouseEnter` event and draws the border and the drop-down button in their highlighted colours.
`OnMouseLeave`	Raises the `Control.MouseLeave` event and, unless the control has the focus or `ShowBorderAlways` is set, takes the border away again.
`OnPaint`	Raises the `Control.Paint` event and then draws the face, the border and the drop-down button over the whole control.
`OnSelectedIndexChanged`	Raises the `ComboBox.SelectedIndexChanged` event.
`SetFontHeight`	Sets the control's `Control.FontHeight`, the line height its item layout is based on.
`WndProc`	Processes the control's window messages: a click or double-click opens the palette below the control, or closes it if it is open, instead of opening the standard list; each paint is followed by the control's own drawing.
Events
`SelectedColorChanged`	Occurs when `SelectedColor` is set – by the user clicking a swatch, moving the alpha slider or using a colour dialog in the palette, or by code.
Fields
`DropDownButtonWidth`	The width, in logical pixels, of the shaded drop-down button drawn at the right-hand end of the control: 12.

Constructors

BinaryOfficeColorPickerComboBox

public BinaryOfficeColorPickerComboBox()

Initialises a colour picker with no colour selected; it shows a white swatch and the text "Empty".

Properties

AlphaBlendFactorForControlPainting

public int AlphaBlendFactorForControlPainting

Gets or sets how strongly the window colour shows in the drop-down button's resting background, while the control has neither the focus nor the pointer.

Value: From 0 to 255. The default is 195.

AlphaBlendFactorForDropDownPressedColor

public int AlphaBlendFactorForDropDownPressedColor

Gets or sets how strongly CustomPaintingColor shows in the drop-down button's pressed look.

Value: From 0 to 255. The default is 70.

Remarks

The pressed look is drawn while ComboBox.DroppedDown is true. The palette opens in place of the standard list and does not set ComboBox.DroppedDown, so in normal use this shade is not seen.

AlphaBlendFactorForItemSelectionColor

public int AlphaBlendFactorForItemSelectionColor

Gets or sets how strongly CustomPaintingColor shows in the drop-down button and the highlighted face.

Value: From 0 (plain window colour) to 255 (CustomPaintingColor itself). The default is 70.

AlphaValue

public int AlphaValue

Gets or sets the alpha value the control holds: the one the user last chose, from 0 to 255.

Value: The default is 255.

Remarks

Updated whenever the user changes the colour. Setting it does not move the palette's alpha slider, which the user sets; see BinaryOfficeColorPicker.AlphaValue.

BlendTargetColor

public Color BlendTargetColor

Gets or sets the colour the chosen colour is mixed with when alpha blending is on.

Value: The blend colour. The default is Color.Empty, which leaves the palette's blend swatch the colour of the panel behind it.

Remarks

Updated whenever the user changes the colour, and handed to the palette each time it opens.

BorderColor

public Color BorderColor

Gets or sets the colour of the line round the drop-down palette.

Value: The border colour. The getter returns SystemColors.WindowText until the property is set, while the line is drawn in blue-grey, RGB (133, 155, 183).

CustomColorForRectangleBorder

public Color CustomColorForRectangleBorder

Gets or sets the colour of the frame the palette draws round the swatch the user clicks.

Value: The frame colour. The default is Color.Yellow.

Remarks

Handed to the palette each time it opens.

CustomControlBorderColor

public Color CustomControlBorderColor

Gets or sets the colour of the control's border while it has the focus or the pointer is over it, or all the time with ShowBorderAlways.

Value: The border colour. The default is SystemColors.Highlight.

Remarks

It also outlines the drop-down button and the highlighted face.

CustomPaintingColor

public Color CustomPaintingColor

Gets or sets the colour the drop-down button and the highlighted face are shaded from.

Value: The base colour. The default is SystemColors.Highlight.

Remarks

It is mixed with the window colour by AlphaBlendFactorForItemSelectionColor, so the default gives a pale blue.

EnableSettingAlphaValue

public bool EnableSettingAlphaValue

Gets or sets whether the palette shows the alpha slider and the "Blend with color" swatch.

Value: true to offer alpha blending; the default is false.

Remarks

With blending on, the colour reported is the chosen colour mixed with BlendTargetColor – at an alpha of 255 the chosen colour unchanged, at lower values moved towards the blend colour. The result is always opaque.

HeadingBackColor

public Color HeadingBackColor

Gets or sets the background of the palette's headings, its "More colors..." strip and its alpha panel.

Value: The heading colour. The default is a pale blue-grey, RGB (204, 219, 230).

HeadingForeColor

public Color HeadingForeColor

Gets or sets the colour of the palette's heading text and labels.

Value: The text colour. The default is SystemColors.WindowText.

RightToLeft

public override RightToLeft RightToLeft

Gets or sets right-to-left layout, which this control does not support: any value set is stored as No.

Value: Always No once set.

SelectedColor

public Color SelectedColor

Gets or sets the colour the control shows – the colour the user chose, mixed with the blend colour when alpha blending is on.

Value: The selected colour. The default is Color.Empty, shown as a white swatch with the text "Empty".

Remarks

Setting it updates the swatch and the text and, when the colour differs, raises SelectedColorChanged; the palette opens with this colour in its preview swatch. The text shows the red, green and blue values, or the colour's name with ShowColorNameIfKnownColor.

Example

fontColourPicker.SelectedColor = Color.DarkSlateBlue;
Color textColour = fontColourPicker.SelectedColor;

SelectedColorRectangleBorder

public Color SelectedColorRectangleBorder

Gets or sets a colour handed to the palette for the frame round the clicked swatch.

Value: The default is SystemColors.WindowText.

Remarks

Each time the palette opens, the frame colour is replaced by CustomColorForRectangleBorder, so set that property instead.

ShowBorderAlways

public bool ShowBorderAlways

Gets or sets whether the border and the drop-down button are drawn in their highlighted colours all the time, rather than only while the control has the focus or the pointer.

Value: true for a constant border; the default is false.

ShowColorNameIfKnownColor

public bool ShowColorNameIfKnownColor

Gets or sets whether the control shows a colour's name – "Tomato", "ControlText" – instead of its RGB values when the colour has one.

Value: true to show names; the default is false.

Remarks

A colour has a name when Color.IsKnownColor is true, as for colours set from the Color and SystemColors properties. The change shows from the next time SelectedColor is set.

ShowHSBInToolTip

public bool ShowHSBInToolTip

Gets or sets whether the palette's tool tips add each colour's hue, saturation and brightness.

Value: true to add them; the default is false.

Remarks

The palette reads it when it first loads; set it before the palette is first opened.

ShowToolTip

public bool ShowToolTip

Gets or sets whether pointing at a swatch in the palette shows its colour's name or RGB values.

Value: true to show tool tips; the default is true.

Remarks

The palette reads it when it first loads; set it before the palette is first opened.

Methods

Dispose

protected override void Dispose(bool disposing)

Releases the resources held by the control.

Parameters

disposing: true when called from Dispose; false when called from the finaliser.

DrawComboBoxFace

protected void DrawComboBoxFace(Graphics g, Rectangle bounds, int Index, bool isSelected, bool hasFocus)

Draws the closed control: the background, the colour swatch and the text.

Parameters

g: The surface to draw on.
bounds: The bounds of the control face, in client coordinates.
Index: The index of the selected item.
isSelected: true to draw the face highlighted.
hasFocus: true when the control has the focus.

Remarks

The background is drawn by DrawComboBoxFaceBackground, which a derived class can override.

DrawComboBoxFaceBackground

protected virtual void DrawComboBoxFaceBackground(Graphics g, Rectangle bounds, int Index, bool isSelected, bool hasFocus)

Draws the background of the closed control. Override to change it without taking over the swatch, the text and the drop-down button.

Parameters

g: The surface to draw on.
bounds: The bounds of the control face; the background is drawn 3 pixels inside them.
Index: The index of the selected item.
isSelected: true to draw the face highlighted.
hasFocus: true when the control has the focus.

DrawDisabledFace

protected void DrawDisabledFace()

Draws the control in its disabled form: an empty swatch outline and the text in SystemColors.ControlDark.

Remarks

The background is drawn by DrawDisabledFaceBackground, which a derived class can override.

DrawDisabledFaceBackground

protected virtual void DrawDisabledFaceBackground()

Draws the background, the grey border and the dimmed drop-down button of the disabled control. Override to change the disabled look without taking over the swatch and the text.

DrawListItem

protected void DrawListItem(Graphics g, Rectangle bounds, int Index, bool isSelected, bool hasFocus)

Draws one row of the control's own item list: the background, the colour swatch and the text.

Parameters

g: The surface to draw on.
bounds: The bounds of the row, in client coordinates.
Index: The index of the item being drawn.
isSelected: true when the row is the selected one.
hasFocus: true when the row is the edit area of the combo box.

Remarks

The background is drawn by DrawListItemBackground, which a derived class can override.

DrawListItemBackground

protected virtual void DrawListItemBackground(Graphics g, Rectangle bounds, int Index, bool isSelected, bool hasFocus)

Draws the background of one row of the control's own item list. Override to change it without taking over the swatch and the text.

Parameters

g: The surface to draw on.
bounds: The bounds of the row.
Index: The index of the item being drawn.
isSelected: true when the row is the selected one.
hasFocus: true when the row is the edit area of the combo box.

MeasureTextViaGdi static

protected static Size MeasureTextViaGdi(Graphics graphics, string text, Font font)

Measures a single line of text the way GDI draws it, which can differ from Graphics.MeasureString.

Parameters

graphics: A graphics surface to measure against.
text: The text to measure.
font: The font it will be drawn in.

Returns

The width and height the text occupies, in pixels, or Size.Empty if it cannot be measured.

OnDrawItem

protected override void OnDrawItem(DrawItemEventArgs e)

Draws an item of the control's own list with DrawListItem. The ComboBox.DrawItem event is not raised.

Parameters

e: The item to draw and where.

OnGotFocus

protected override void OnGotFocus(EventArgs e)

Raises the Control.GotFocus event and draws the border and the drop-down button in their highlighted colours.

Parameters

e: The data for the event.

OnHandleCreated

protected override void OnHandleCreated(EventArgs e)

Removes the Windows visual style from the new window, so the control's own drawing is not fought by the theme, and raises the Control.HandleCreated event.

Parameters

e: The data for the event.

Remarks

Also sets Control.BackColor to SystemColors.Window.

OnKeyPress

protected override void OnKeyPress(KeyPressEventArgs e)

Raises the Control.KeyPress event.

Parameters

e: The character typed.

Remarks

An exception thrown by a handler is caught and not passed on.

OnLostFocus

protected override void OnLostFocus(EventArgs e)

Raises the Control.LostFocus event and, unless ShowBorderAlways is set, takes the border away.

Parameters

e: The data for the event.

OnMouseEnter

protected override void OnMouseEnter(EventArgs e)

Raises the Control.MouseEnter event and draws the border and the drop-down button in their highlighted colours.

Parameters

e: The data for the event.

OnMouseLeave

protected override void OnMouseLeave(EventArgs e)

Raises the Control.MouseLeave event and, unless the control has the focus or ShowBorderAlways is set, takes the border away again.

Parameters

e: The data for the event.

OnPaint

protected override void OnPaint(PaintEventArgs pe)

Raises the Control.Paint event and then draws the face, the border and the drop-down button over the whole control.

Parameters

pe: The graphics surface and the area to paint.

OnSelectedIndexChanged

protected override void OnSelectedIndexChanged(EventArgs e)

Raises the ComboBox.SelectedIndexChanged event.

Parameters

e: The data for the event.

Remarks

The control's single item is replaced each time the colour changes, so the event follows each change; SelectedColorChanged is the event to handle.

SetFontHeight

protected void SetFontHeight(int s)

Sets the control's Control.FontHeight, the line height its item layout is based on.

Parameters

s: The height, in pixels.

WndProc

protected override void WndProc(ref Message m)

Processes the control's window messages: a click or double-click opens the palette below the control, or closes it if it is open, instead of opening the standard list; each paint is followed by the control's own drawing.

Parameters

m: The message to process.

Remarks

On opening, the palette is given SelectedColor, AlphaValue, BlendTargetColor, the heading colours, EnableSettingAlphaValue, the tool tip settings and CustomColorForRectangleBorder.

Events

SelectedColorChanged

public event EventHandler<BinaryColorPickerExtendedEventArgs> SelectedColorChanged

Occurs when SelectedColor is set – by the user clicking a swatch, moving the alpha slider or using a colour dialog in the palette, or by code.

Remarks

The event data carries the colour, the alpha value and the blend colour of this change: the palette's when the user changed the colour, the control's own when code set it.

Raised only when the colour changes – also on each step of the alpha slider that changes it. Assigning the colour already selected raises nothing.

Fields

DropDownButtonWidth

protected const int DropDownButtonWidth

The width, in logical pixels, of the shaded drop-down button drawn at the right-hand end of the control: 12.

BinaryOfficeColorPickerComboBox

Remarks

What it is for

How it works

Examples

See also

Members at a glance

Constructors

BinaryOfficeColorPickerComboBox

Properties

AlphaBlendFactorForControlPainting

AlphaBlendFactorForDropDownPressedColor

Remarks

AlphaBlendFactorForItemSelectionColor

AlphaValue

Remarks

BlendTargetColor

Remarks

See also

BorderColor

CustomColorForRectangleBorder

Remarks

CustomControlBorderColor

Remarks

CustomPaintingColor

Remarks

EnableSettingAlphaValue

Remarks

HeadingBackColor

HeadingForeColor

RightToLeft

SelectedColor

Remarks

Example

SelectedColorRectangleBorder

Remarks

ShowBorderAlways

See also

ShowColorNameIfKnownColor

Remarks

ShowHSBInToolTip

Remarks

ShowToolTip

Remarks

Methods

Dispose

Parameters

DrawComboBoxFace

Parameters

Remarks

DrawComboBoxFaceBackground

Parameters

DrawDisabledFace

Remarks

DrawDisabledFaceBackground

DrawListItem

Parameters

Remarks

DrawListItemBackground

Parameters

MeasureTextViaGdi static

Parameters

Returns

OnDrawItem

Parameters

OnGotFocus

Parameters

OnHandleCreated

Parameters

Remarks

OnKeyPress

Parameters

Remarks

OnLostFocus

Parameters

OnMouseEnter

Parameters

OnMouseLeave

Parameters

OnPaint