Defines classes for selecting a color from a combo-box or a list box.

colorbox.pas contains TColorBox and TColorListBox. TColorBox is a component that displays colors in a combo-box control. TColorListBox is a component that displays colors in a list box control. This file is part of the Lazarus Component Library (LCL).

The following components are added to the Lazarus IDE component palette:

Additional Tab

- TColorBox
- TColorListBox

Default width for the color sample (swatch) in a color combo-box or list box.
Default spacing between the color sample (swatch) and the color name in a combo-box or list box.
Represents the available colors and the name display style used in color controls.

TColorBoxStyles is an enumerated type with values that represent the available colors and the display style used in color controls like TColorBox and TColorListBox. Values from TColorBoxStyles are stored in the TColorBoxStyle set type.

16 standard colors (as defined in graphics.pp).
16 standard colors and 4 extended colors (as defined in graphics.pp).
System colors (as defined in graphics.pp).
Includes clNone in the list of colors.
Includes clDefault in the list of colors.
The first color is customizable.
Uses "pretty" names in the color names instead of the color value; like Red for clRed.
Uses the OnGetColors event handler to get the list of colors.
Set type used to store values from the TColorBoxStyles enumeration.

TColorBoxStyle is a Set type used to store zero or more values from the TColorBoxStyles enumeration. TColorBoxStyle is the type used to implement the TColorBox.Style and TColorListBox.Style properties.

Specifies an event handler used to get the colors in a color control.

TGetColorsEvent is an object procedure type which specifies an event handler used to get the colors names and values used in a color control.

Sender is the control for the event notification and the location where the color values are used.

TGetColorsEvent is the type used for the TColorBox.OnGetColors and TColorListBox.OnGetColors event handlers.

Object for the event notification.
TStrings instance with the color names and values used in the control.
The base class for TColorBox.

TCustomColorBox is a TCustomComboBox descendant which implements the base class for TColorBox. TCustomColorBox displays available colors in a combo-box control. Each item in the control has a small rectangle where the color is displayed (swatch) and the color name.

The Style property is used to configure the list of available colors and their display names. Style may also trigger use of the OnGetColors event handler to get the items displayed in the combo-box control.

The ColorRectWidth and ColorRectOffset properties can be used to control the size and spacing for the color swatch displayed for the list items.

Colors allows indexed access to the TColor values in the list of items. When included in the Style property, colors like clDefault and/or clNone may be included in the list of Colors. The DefaultColorColor and NoneColorColor properties can be used to specify the TColor values used for those color constants.

ColorNames allows indexed access to the names for the values in Colors.

Do not create instances of TCustomColorBox; use the TColorBox descendant instead.

Use TCustomColorListBox / TColorListBox to display color names and values in a list box control.

Gets the value for the indexed Colors property.
Value for the property.
Ordinal position in the list for the color value.
Gets the value for the indexed ColorNames property.
Value for the property.
Ordinal position in the list for the color name.
Implements the storage specifier for the ColorRectWidth property.
True when the property has a value other than the default value.
Draws an item in the combo-box control.

DrawItem is an overridden method used to custom draw an item in the ColorBox.

A color preview is drawn using the value in Colors. For clNone and clDefault, the value in NoneColorColor and DefaultColorColor are used to draw the color preview. The value in State is updated to include odBackgroundPainted in the state flags.

The item rectangle is made smaller and passed to the inherited method to draw the text for the item.

The Brush color and Pen color for the control Canavas are reset to their original values after drawing the item.

TCustomComboBox.DrawItem
Ordinal position for the item drawn in the method.
Rectanlge with the bounds for the item.
Owner draw state for the item.
Loads the list of colors used in the control.

SetColorList is used to fill the Items in the control with the Colors and ColorNames available in the combo-box.

SetColorList clears any existing values in Items, and loads the predefined colors needed for the settings in the Style property. When Style included the value cbCustomColors , the OnGetColors event handler is signalled to load custom colors in the Items, Colors, and ColorNames properties.

The value in Selected is restored prior to exiting from the method.

Performs actions needed when LCL component streaming has been completed.
TWinControl.Loaded
Performs actions need to initial the window Handle for the control.

Updates the combo-box control when its handled is (re-)allocated. Ensures that ItemIndex is updated to reflect the value in Selected.

TCustomComboBox.InitializeWnd
Performs actions needed to auto-adjust the control using the specified layout policy.

Called when an auto adjust policy is applied for the control. DoAutoAdjustLayout ensures that the item height for the control is scaled using the factor in AYProportion when AMode contains the lapAutoAdjustWithoutHorizontalScrolling or lapAutoAdjustForDPI layout adjustment policy values.

In TCustomColorBox, it ensures that ColorRectWidth is scaled when needed.

DoAutoAdjustLayout is called from the AutoAdjustLayout method.

TControl.DoAutoAdjustLayout
Signals the OnGetColors event handler (when assigned).

Called when the Colors in the control are (re-)loaded after setting a new value in Style. It is called if cbCustomColors has been included in Style.

TCustomComboBox.CloseUp
Selects a custom color using a color dialog.

PickCustomColor is a Boolean function used to select a custom color rather than one of the standard colors in the Colors property.

PickCustomColor is used when cbCustomColor is included in the Style for the control and ItemIndex is set to 0. This position was reserved for a custom color when the list of colors was loaded for the Style settings in the control.

PickCustomColor uses an existing value in ColorDialog when assigned, or creates the ColorDialog when needed. It executes the ColorDialog to get the color selection for the control. The custom color selection is stored as the first TColor value in the Items for the control. When a color is successfully selected using the dialog, the return value is set to True and the control is redrawn.

The color selection dialog is not displayed at design-time, and the return value is always set to False.

True when a custom color was selected in the method.
Constructor for the class instance.

Create is the overridden constructor for TCustomColorBox. It calls the inherited Create method, and sets the Style flags needed for the owner-drawn control. Create sets the default values for properties, including:

- ColorRectWidth
- ColorRectOffset
- Style
- NoneColorColor
- DefaultColorColor
- Selected

Create calls SetColorList to load the colors needed for the control.

TCustomCombobox.Create
Width for the color sample (swatch) displayed for colors in the item list.

ColorRectWidth is an Integer property which contains the number of pixels used to draw the color sample (or swatch) for each of the Colors in the combo-box control. The height is determined using the item height for the combo-box control.

If an explicit value has not been assigned to the property, the value in cDefaultColorRectWidth is scaled to the current display density and used in the property value.

Setting a new value for the property causes the control to be redrawn.

Use ColorRectOffset for the number of pixels used between the color sample and its name.

Number of pixels between the color sample and the color name.

ColorRectOffset is an Integer property with the number of pixels used to separate the color sample (or swatch) and the color name displayed for the Items in the control. The default value for the property is cDefaultColorRectOffset.

Setting a new value for the property causes the control to be redrawn.

Use ColorRectWidth for the width of the color sample displayed in the list items.

Settings which determine the colors available in the control and their display style.

Style is a TColorBoxStyle property with settings to determine the colors available in the control and their display style. Include values from the TColorBoxStyles enumeration to enable a particular setting. For instance:

cbStandardColors
  16 standard colors (as defined in graphics.pp); like cRed, clBlack, et. al.
cbExtendedColors
  4 extended colors (as defined in graphics.pp); like clMoneyGreen, clSkyBlue, et. al.
cbSystemColors
  System colors (as defined in graphics.pp); like clScrollBar, clWindow, clForm, .et. al.
cbIncludeNone
  Includes clNone in the list of colors.
cbIncludeDefault
  Includes clDefault in the list of colors.
cbCustomColor
  The first color is customizable by selection from a dialog.
cbPrettyNames
  Uses "pretty" names in the color names instead of the color value; like Red for clRed.
cbCustomColors
  Uses the OnGetColors event handler to get the list of colors.

The default value for the property is: [cbStandardColors, cbExtendedColors, cbSystemColors]. This enables the corresponding TColor values defined in the graphics.pp unit. By including cbCustomColor in Style, the custom color is stored as the first value in the Colors property.

Setting a new value for the property causes the SetColorList method to be called to reload the color names and values.

Provides indexed access to the TColor value for items in the control.

Colors is an indexed read-only TColor property which provides access to the colors in the control by their ordinal position in the list of Items.

Use ColorNames to access the name for a color at a specific position in the list.

Use Style to determine the colors and names available in the combo-box control.

Ordinal position for the property value in the list of items.
Provides indexed access to the names for the Colors used in the control

ColorNames is a read-only String property which provides indexed access to the names for the values stored in Colors property.

Use Colors to get the TColor value for one the Items in the control.

Use Style to determine the colors and names available in the combo-box control.

Ordinal position for the color name accessed in the Items for the control.
The TColor value for the selected item in the combo-box control.

Selected is a TColor property with the color for the selected item in combo-box control. The default value for the property is clBlack.

Selected contains the value in Colors found at the position in ItemIndex. If ItemIndex is -1 (for no selection) or the handle for the control has not been assigned, the existing TColor value in the member is returned as the property value.

Setting a new value for the property causes the values in Colors to be searched, and the ItemIndex is set to the location for the color value. If the new value is not in Colors, ItemIndex is set to -1. The inherited Change method is called to signal the OnChange event handler (when assigned).

TColor TCustomComboBox.ItemIndex TCustomComboBox.Change TCustomComboBox.OnChange
TColor used for the clDefault color constant.

DefaultColorColor is a TColor property with the value used for the clDefault color constant.

clDefault does not have any meaning without a context where it is applied. The default color is a different value for Forms, Buttons, Windows, etc. This property allows clDefault to be resolved to an actual TColor value when needed.

The default value for the property is clBlack.

Changing the value for the property causes the control to be redrawn.

DefaultColorColor is used in the DrawItem method to resolve the clDefault color constant when drawing items in the control.

Use NoneColorColor for the TColor value used for the clNone color constant.

Use Style to include or exclude the clDefault and clNone color constants in the Colors for the control.

TColor used for the clNone color constant.

NoneColorColor is a TColor property with the color value used for the clNone color constant.

Like clDefault, clNone does not have any meaning without a context where it is applied. Its actual value is different for Forms, Buttons, Windows, etc. This property allows clNone to be resolved to an actual TColor value when needed.

The default value for the property is clBlack.

Changing the value for the property causes the control to be redrawn.

NoneColorColor is used in the DrawItem method to resolve the clNone color constant when drawing items in the control.

Use DefaultColorColor for the TColor value used for the clDefault color constant.

Use Style to include or exclude the clDefault and clNone color constants in the Colors for the control.

OnGetColors
- event handler for the instruction to get colors.

OnGetColors is a TGetColorsEvent property with the event handler signalled to get custom colors used in the combo-box control.

An application must implement and assign an object procedure using the signature in TGetColorsEvent to respond to the notification. Sender is the TCustomColorBox control for the event notification. Items is the TStrings instance with the existing color names and values stored in the control.

The event handler can perform any actions needed to populate the list of Items. This can include clearing the Items, adding or removing selected names and color values, or using color names and/or values not defined as color constants in the graphics.pp unit. It could also be used to implement a custom color palette with specific pre-defined color combinations.

Some common operations:

Clear the list of ltems:

Items.Clear;

Add a specific color:

Items.AddObject(rsSkyBlueColorCaption, TObject(PtrInt(clSkyBlue)));

Delete a specific color:

iPos := Items.IndexOf(rsSkyBlueColorCaption); if iPos <> -1 then Items.Delete(iPos);

OnGetColors is signalled (when assigned) when the color list is loaded for the control, and cbCustomColors has been included in the Style for the control. This occurs when a new value is assigned to the Style property.

TCustomComboBox.Items
Dialog displayed to select a custom color for the control.

ColorDialog is a TColorDialog property with the dialog displayed to select a custom color for the control. Its value can be assigned directly to the control, or it can be created and freed at run-time when the PickCustomColor method is called.

TColorDialog
Implements combo-box control used to select a color name or value.

TColorBox is a TCustomColorBox descendant which implements the a combo-box control used to display and select available color names and values. Each item in the control has a small rectangle where the color is displayed (swatch) and the color name.

The Style property is used to configure the list of available colors and their display names. Style may also trigger use of the OnGetColors event handler to get the items displayed in the combo-box control.

The ColorRectWidth and ColorRectOffset properties can be used to control the size and spacing for the color swatch displayed for the list items.

Colors allows indexed access to the TColor values in the list of items. When included in the Style property, colors like clDefault and/or clNone may be included in the list of Colors. The DefaultColorColor and NoneColorColor properties can be used to specify the TColor values used for those color constants.

ColorNames allows indexed access to the names for the values in Colors.

Use TCustomColorListBox / TColorListBox to display color names and values in a list box control.

Specifies an event handler signalled to get the available colors for a TColorListBox control.

TLBGetColorsEvent is the type used to implement the OnGetColors property in TCustomColorListBox.

GetColorValues
Object for the event notification.
TStrings instance where the available color captions and values captions are stored.
Implements the base class for TColorListBox.

TCustomColorListBox is a TCustomListBox descendant which implements a list box control used to display and select color names and values. TCustomColorListBox is the base class for the TColorListBox control. Each item in the control has a small rectangle where the color is displayed (swatch) and the color name.

The Style property is used to configure the list of available colors and their display names. Style may also trigger use of the OnGetColors event handler to get the items displayed in the combo-box control.

The ColorRectWidth and ColorRectOffset properties can be used to control the size and spacing for the color swatch displayed for the list items.

Colors allows indexed access to the TColor values in the list of items. When included in the Style property, colors like clDefault and/or clNone may be included in the list of Colors. The DefaultColorColor and NoneColorColor properties can be used to specify the TColor values used for those color constants.

ColorNames allows indexed access to the names for the values in Colors.

Do not create instances of TCustomColorListBox; use the TColorL:istBox descendant instead.

Use TCustomColorBox / TColorBox to display color names and values in a combo-box control.

Implements the storage specifier for the ColorRectWidth property.
True when the property has a value other than the default.
Draws the color preview and name for an item in list box control.

DrawItem is an overridden method used to custom draw an item in the control.

A color preview is drawn using the value in Colors. For clNone and clDefault, the value in NoneColorColor and DefaultColorColor are used to draw the color preview. The value in State is updated to include odBackgroundPainted in the state flags.

The item rectangle is made smaller and passed to the inherited method to draw the text for the item.

The Brush color and Pen color for the control Canavas are reset to their original values after drawing the item.

TCustomListBox.DrawItem
Loads the list of colors used in the control.

SetColorList is used to fill the Items in the control with the Colors and ColorNames available in the list box.

SetColorList clears any existing values in Items, and loads the predefined colors needed for the settings in the Style property. When Style included the value cbCustomColors , the OnGetColors event handler is signalled to load custom colors in the Items, Colors, and ColorNames properties.

The value in Selected is restored prior to exiting from the method.

Performs actions needed when LCL component streaming has been completed.
TWinControl.Loaded
Performs actions needed when the window handle for the control is created.

Updates the value in Selected to force ItemIndex to be updated.

TCustomListBox.ItemIndex TCustomListBox.InitializeWnd TWincontrol.InitializeWnd
Performs actions needed to auto-adjust the control using the specified layout policy.

DoAutoAdjustLayout is an overridden method used to apply the specified auto-adjust layout policy to the control. DoAutoAdjustLayout calls the inherited method on entry.

DoAutoAdjustLayout ensures that the value in ColorRectWidth is adjusted by the scaling factor in AXProportion when AMode contains lapAutoAdjustWithoutHorizontalScrolling or lapAutoAdjustForDPI. The control is redrawn after ColorRectWidth is updated.

DoAutoAdjustLayout is called from the AutoAdjustLayout method.

TCustomListBox.DoAutoAdjustLayout TControl.DoAutoAdjustLayout
Layout adjustment policy applied in the method.
Horizontal scaling factor for the policy.
Vertical scaling factor for the policy.
Signals the OnGetColors event handler (when assigned).

Called when the Colors in the control are (re-)loaded after setting a new value in Style. It is called if cbCustomColors has been included in Style.

Performs actions needed when the selection in the control is changed.

DoSelectionChange is an overridden method used to perform actions needed when the value in the ItemIndex property is changed.

The User parameter indicates the origin of the change. When User is True, the change occurred due to user interaction with the control. When User is False, the change occurred when the ItemIndex property was updated by another method in the control.

When User is True, the Style property is examined to see if a custom color can be used in the Colors for the control. When Style includes the value cbCustomColor, and ItemIndex is set to 0, the PickCustomColor method is called to select a custom color using a color dialog. If a custom color was successfully selected, the TColor value in Colors for the ItemIndex is stored in the Selected property.

The color dialog is not displayed, and Selected is not updated when User is set to False.

DoSelectionChange calls the inherited method prior to exit.

TCustomListBox.DoSelectionChange
Selects a custom color using a color dialog.

PickCustomColor is a Boolean function used to select a custom color rather than one of the standard colors in the Colors property.

PickCustomColor is used when cbCustomColor is included in the Style for the control and ItemIndex is set to 0. This position was reserved for a custom color when the list of colors was loaded for the Style settings in the control.

PickCustomColor uses an existing value in ColorDialog when available, or creates and executes a TColorDialog to get the color selection for the control. The custom color selection is stored as the first TColor value in the Items for the control. When a color is successfully selected using the dialog, the return value is set to True and the control is redrawn.

The color selection dialog is not displayed at design-time, and the return value is always set to False.

True when a custom color was selected in the color dialog.
Constructor for the class instance.

Create is the overridden constructor for TCustomColorListBox. Create calls the inherited Create method, and sets the Style flags needed for the owner-drawn control. It also sets the default values for properties in the class instance, including:

- ColorRectWidth
- ColorRectOffset
- Style
- NoneColorColor
- DefaultColorColor
- Selected

Create calls SetColorList to load the colors needed for the control.

TCustomListBox.Create
Width for the color sample (swatch) displayed for colors in the item list.

ColorRectWidth is an Integer property which contains the number of pixels used to draw the color sample (or swatch) for each of the Colors in the list box control. The height for the list Item is in the ItemHeight property.

If an explicit value has not been assigned to ColorRectWidth, the value in cDefaultColorRectWidth is scaled to the current display density and used as the property value.

Setting a new value for the property causes the control to be redrawn.

Use ColorRectOffset for the number of pixels used between the color sample and its color name.

Number of pixels between the color sample and the color name.

ColorRectOffset is an Integer property with the number of pixels used to separate the color sample (or swatch) and the color name displayed for the Items in the control. The default value for the property is cDefaultColorRectOffset.

Setting a new value for the property causes the control to be redrawn.

Use ColorRectWidth for the width of the color sample displayed in the list items.

Settings which determine the colors available in the control and their display style.

Style is a TColorBoxStyle property with settings to determine the colors available in the control and their display style. Include values from the TColorBoxStyles enumeration to enable a particular setting. For instance:

cbStandardColors
  16 standard colors (as defined in graphics.pp); like cRed, clBlack, et. al.
cbExtendedColors
  4 extended colors (as defined in graphics.pp); like clMoneyGreen, clSkyBlue, et. al.
cbSystemColors
  System colors (as defined in graphics.pp); like clScrollBar, clWindow, clForm, .et. al.
cbIncludeNone
  Includes clNone in the list of colors.
cbIncludeDefault
  Includes clDefault in the list of colors.
cbCustomColor
  The first color is customizable by selection from a dialog.
cbPrettyNames
  Uses "pretty" names in the color names instead of the color value; like Red for clRed.
cbCustomColors
  Uses the OnGetColors event handler to get the list of colors.

The default value for the property is: [cbStandardColors, cbExtendedColors, cbSystemColors]. This enables the corresponding TColor values defined in the graphics.pp unit. By including cbCustomColor in Style, the custom color is stored as the first value in the Colors property.

Setting a new value for the property causes the SetColorList method to be called to reload the color names and values.

TCustomListBox.Style
Provides indexed access to the TColor value for items in the control.

Colors is an indexed TColor property which provides access to the colors in the control by their ordinal position in the list of Items. Setting a new TColor value in the indexed property causes the control to be redrawn.

Values in Colors and ColorNames are used in the DrawItem method when the color sample and the color name for an item is drawn on the control Canvas.

Use ColorNames to access the name for the color at a specific position in the Items for the control.

Use Style to determine the colors and names available in the list box control.

Ordinal position in Items for the color value.
Provides indexed access to the names for the Colors used in the control

ColorNames is a String property which provides indexed access to the names for the values stored in Colors property. Setting a new value for the indexed property causes the control to be redrawn.

Values in Colors and ColorNames are used in the DrawItem method when the color sample and the color name for an item is drawn on the control Canvas.

Use Colors to get the TColor value for one the Items in the control.

Use Style to determine the colors and names available in the combo-box control.

Ordinal position in Items for the color name.
The TColor value for the selected item in the list box control.

Selected is a TColor property with the color for the selected item in list box control. The default value for the property is clBlack.

Selected contains the value in Colors found at the position in ItemIndex. If ItemIndex is -1 (for no selection) or the handle for the control has not been assigned, the existing TColor value in the member is returned as the property value.

Setting a new value for the property causes the values in Colors to be searched, and the ItemIndex is set to the location for the color value. If the new value is not in Colors, ItemIndex is set to -1.

TCustomListBox.Selected
TColor used for the clDefault color constant.

DefaultColorColor is a TColor property with the value used for the clDefault color constant.

clDefault does not have any meaning without a context where it is applied. The default color is a different value for Forms, Buttons, Windows, etc. This property allows clDefault to be resolved to an actual TColor value when needed.

The default value for the property is clBlack.

Changing the value for the property causes the control to be redrawn.

DefaultColorColor is used in the DrawItem method to resolve the clDefault color constant when drawing items in the control.

Use NoneColorColor for the TColor value used for the clNone color constant.

Use Style to include or exclude the clDefault and clNone color constants in the Colors for the control.

TColor used for the clNone color constant.

NoneColorColor is a TColor property with the color value used for the clNone color constant.

Like clDefault, clNone does not have any meaning without a context where it is applied. Its actual value is different for Forms, Buttons, Windows, etc. This property allows clNone to be resolved to an actual TColor value when needed.

The default value for the property is clBlack.

Changing the value for the property causes the control to be redrawn.

NoneColorColor is used in the DrawItem method to resolve the clNone color constant when drawing items in the control.

Use DefaultColorColor for the TColor value used for the clDefault color constant.

Use Style to include or exclude the clDefault and clNone color constants in the Colors for the control.

OnGetColors
- event handler for the instruction to get colors.

OnGetColors is a TGetColorsEvent property with the event handler signalled to get custom colors used in the list box control.

An application must implement and assign an object procedure using the signature in TGetColorsEvent to respond to the notification. Sender is the TCustomColorBox control for the event notification. Items is the TStrings instance with the existing color names and values stored in the control.

The event handler can perform any actions needed to populate the list of Items. This can include clearing the Items, adding or removing selected names and color values, or using color names and/or values not defined as color constants in the graphics.pp unit. It could also be used to implement a custom color palette with specific pre-defined color combinations.

Some common operations:

Clear the list of ltems:

Items.Clear;

Add a specific color:

Items.AddObject(rsSkyBlueColorCaption, TObject(PtrInt(clSkyBlue)));

Delete a specific color:

iPos := Items.IndexOf(rsSkyBlueColorCaption); if iPos <> -1 then Items.Delete(iPos);

OnGetColors is signalled (when assigned) when the color list is loaded for the control, and cbCustomColors has been included in the Style for the control. This occurs when a new value is assigned to the Style property.

Dialog displayed to select a custom color for the control.

ColorDialog is a TColorDialog property with the dialog displayed to select a custom color for the control. It can be assigned directly to the control, or it can be created at run-time when the PickCustomColor method is called.

TColorDialog
Implements a list box control used to display and select color names and values.

TColorListBox is a TCustomColorListBox descendant which implements a list box control used to display and select color names and values. Each item in the control has a small rectangle where the color is displayed (swatch) and the color name.

The Style property is used to configure the list of available colors and their display names. Style may also trigger use of the OnGetColors event handler to get the items displayed in the list box control.

The ColorRectWidth and ColorRectOffset properties can be used to control the size and spacing for the color swatch displayed for the list items.

Colors allows indexed access to the TColor values in the list of items. When included in the Style property, colors like clDefault and/or clNone may be included in the list of Colors. The DefaultColorColor and NoneColorColor properties can be used to specify the TColor values used for those color constants.

ColorNames allows indexed access to the names for the values in Colors.

Use TCustomColorBox / TColorBox to display color names and values in a combo-box control.

Register components for use in the Lazarus IDE.

The following components are added to the Lazarus IDE component palette:

Additional Tab

- TColorBox
- TColorListBox