NSColorAddition

A module containing dynamic system colors for macOS and Windows and color manipulation methods, mainly for macOS

Module

Overview

Methods

Overview
AddSystemEffect	BlendColor
ChangeAlpha	Draw
FillRectangle	Highlight
MultiplyColor	RegisterForSystemColorChangeNotification
ScrubberTexturedBackgroundColor	SetColor
SetFillColor	SetStrokeColor
Shadow	SystemVersionIsAtLeast

Properties

The macOS colors are also available as methods returning the Ptr to the NSColor representation of the color. To avoid confusions with the Xojo built-in colors, the module’s Xojo colors are named with an underline before "Color" while the methods are protected module methods and don’t use an underscore in their name. The exception is ScrubberTexturedBackgroundColor which has no Xojo color translation. It is a macOS only NSColor made of a repeating image.

Overview
AlternateSelectedControlText_Color	AlternatingContentBackground_Color0
AlternatingContentBackground_Color1	Clear_Color
ControlAccent_Color	ControlBackground_Color
ControlText_Color	Control_Color
CurrentControl_Tint	DisabledControlText_Color
FindHighlight_Color	Grid_Color
HeaderText_Color	Highlight_Color
KeyboardFocusIndicator_Color	Label_Color
Link_Color	PlaceholderText_Color
QuaternaryLabel_Color	ScrollBar_Color
SecondaryLabel_Color	SelectedContentBackground_Color
SelectedControlText_Color	SelectedControl_Color
SelectedMenuItemText_Color	SelectedMenuItem_Color
SelectedTextBackground_Color	SelectedText_Color
Separator_Color	Shadow_Color
SystemBlue_Color	SystemBrown_Color
SystemGray_Color	SystemGreen_Color
SystemOrange_Color	SystemPink_Color
SystemPurple_Color	SystemRed_Color
SystemYellow_Color	TertiaryLabel_Color
TextBackground_Color	Text_Color
UnderPageBackground_Color	UnemphasizedSelectedContentBackground_Color
UnemphasizedSelectedTextBackground_Color	UnemphasizedSelectedText_Color
WindowBackground_Color	WindowFrameText_Color
WindowFrame_Color
WIN_ButtonHighlight_Color	WIN_CaptionText_Color
WIN_Desktop_Color	WIN_GradientActiveCaption_Color
WIN_GradientInactiveCaption_Color	WIN_Infotext_Color
WIN_MenubarBackground_Color	WIN_MenuText_Color
WIN_WindowBackground_Color

Enumerations

Overview
NSColorSystemEffect	NSControlTint

Interfaces

Overview
SystemColorChangeReceiver

High Sierra dynamic colors when selection color is Blue and appearance set to Graphite.

Mojave dynamic colors in Light Mode with AccentColor green + SelectionColor blue

Mojave dynamic colors in Dark Mode with AccentColor green + SelectionColor blue

Dynamic system colors under Windows 10 with standard setting (SelectionColor Blue)

Windows colors without a direct Mac equivalent

Documentation

Methods

AddSystemEffect(extends c As Color, effect As NSColorAddition.NSColorsystemEffect) As Color

macOS only!

Returns a new color that represents the current color modified to include the specified visual effect. Available since macOS 10.14. Returns the original color on systems below Mojave or on Windows.

BlendColor(extends c As color, BlendColor As Color, Fraction As Double) As Color

Blends the current color with the specified fraction of BlendColor and returns the result as a new color. Uses the natvie NSColor method on macOS and a Xojo calculation on other systems.

ChangeAlpha(extends c As Color, alpha As Double/Integer) As Color

Changes the alpha value to the new value and returns the color. Uses alpha between 0.0 and 1.0 for Doubles like macOS or values between 0 and 255 for Integers.

Draw(extends c As Color, optional g As Graphics, x As Double, y As Double, w As Double, h As Double)

Draws the color in a rect of the current context. Inverts y if you pass the graphics context. Method without context is macOS only!

FillRectangle(extends g as graphics, x as double, y as double, w as double, h as double)

macOS only!

Fills the specified rectangle of the current graphics context with the currently set FillColor. See SetColor, SetFillColor.

Highlight(extends c As Color, Level As Double) As Color

Creates a new color that represents a blend between the current color and the highlight color. On Windows multiplies c with Highlight_Color.

MultiplyColor(extends c As Color, Level As Double = 1.0) As Color

Multiplies the current color with the specified fraction of MultiplyColor and returns the result as a new color.

RegisterForSystemColorChangeNotification(Receiver As NSColorAddition.SystemColorChangeReceiver)

Allows a control that incorporates the SystemColorChangeReceiver interface to register for system color changes. Auto-unregisters (no need to unregister the control).

On macOS, changes of Dark Mode trigger a refresh of all controls automatically, as well as changing the tint in eralier macOS versions. A change of the selection color anyhow does not trigger an update. When a control registers on this method, the interface’s SystemColorsChanged method will be called even on selection changes. On current Windows, changes of the Windows Dark Mode are not registered. Changes to system color palette and high contrast modes are.

ScrubberTexturedBackgroundColor As Ptr

macOS only! Please note that macOS has Ptrs like this for all the dynamic system colors.

The patterned color to use for the background of a scrubber control. Available since macOS 10.12. Nil below. Has no Xojo conversion.

SetColor(extends c As Color)

macOS only!

Sets the color to be used in subsequent cgcontext draw commands.

SetFillColor(extends c As Color)

macOS only!

Sets the color to be used as fill color in subsequent cgcontext draw commands.

SetFillColor(extends g As Graphics, value As Ptr)

macOS only!

Sets the color to be used as fill color in subsequent cgcontext draw commands. Useful for the NSColorPtrs – see ScrubberTexturedBackgroundColor.

SetStrokeColor(extends c As Color)

macOS only!

Sets the color to be used as stroke color in subsequent cgcontext draw commands.

Shadow(extends c As Color, Level As Double) As Color

Creates a new color that represents a blend between the current color and the Shadow color. On Windows multiplies c with Shadow_Color.

SystemVersionIsAtLeast(majorversion As Integer, minorversion A sInteger = 0, patchversion As Integer = 0) As Boolean

Returns a Boolean that indicates if the current system version is equal or higher than the specified version. Compares the Service Pack Major Number as Patchversion on Windows. A check for Mojave would be

Dim b as Boolean = SystemVersionIsAtLeast(10, 14)

On Windows, thies method returns the result against the system the app is manifested for. If you do not use a valid Windows 10 manifest, this method will check against Windows 8 minor version 2.

Properties

See also the hint at the Overview. These, with the exception of Current_Tint, are all read-only-properties of type Color. They can change their values whenever the user changes a system color or Dark Mode, so use them directly in the context of a Paint event. Do not cache them longer than one redraw cycle.

AlternateSelectedControlText_Color As Color

The color to use for text in a selected control. (Mac + Win) Returns SelectedControlText_Color on Windows.

AlternatingContentBackground_Color0 As Color

The base color to use for alternating content, typically found in table views and collection views. (Mac + Win) Returns ColorActiveBorder on Windows.

If you want a table to color its rows rather blueish on standard Windows systems, use WIN_GradientActiveCaption_Color and WIN_GradientInactiveCaptionColor instead of Alternating…Color0 and 1.

AlternatingContentBackground_Color1 As Color

The alternating color to use for alternating content, typically found in table views and collection views. (Mac + Win) Returns ColorInactiveBorder on Windows.

Clear_Color As Color

An invisible color. (All platforms)

ControlAccent_Color As Color

The user's current accent color preference. (Mac + Win) Available since macOS 10.14. Makes a fallback to controlTintColor(CurrentControlTint) on systems below. Returns DisabledControlText_Color on Windows.

ControlBackground_Color as Color

The color to use for the background of large controls, such as scroll views or table views. (Mac + Win) Returns Highlight_Color on Windows.

ControlText_Color As Color

The color to use for text on enabled controls. (Mac + Win) Returns ColorButtonText on Windows.

Control_Color As Color

The color to use for the flat surfaces of a control. (Mac + Win) Returns ColorButtonFace on Windows.

CurrentControl_Tint As NSControlTint

macOS only!

The current system control tint color.

DisabledControlText_Color As Color

The color to use for text on disabled controls. (Mac + Win) Returns ColorInactiveCaption on Windows.

FindHighlight_Color As Color

The highlight color to use for the bubble that shows inline search result values. (Mac + Win) Available since macOS 10.13. Makes a fallback to HighlightColor below. Returns ColorInfoBackground on Windows.

Grid_Color As Color

The color to use for the optional gridlines, such as those in a table view. (Mac + Win) Returns ColorButtonShadow on Windows.

HeaderText_Color As Color

The color to use for text in header cells in table views and outline views. (Mac + Win) Returns Text_Color on Windows.

Highlight_Color As Color

The color to use as a virtual light source on the screen. (Mac + Win) Returns Color3DLight on Windows.

Do not confuse Hightlight_Color with Xojo’s HighlightColor where this represents rather the Accent or SelectionColor.

KeyboardFocusIndicator_Color As Color

The color to use for the keyboard focus ring around controls. (Mac + Win) Returns ColorMenuHighlight on Windows.

Label_Color As Color

The color to use for text labels. (Mac + Win) Returns Text_Color with an alpha of .85 on Windows.

Link_Color As Color

The color to use for links. (Mac + Win) Returns HotLightColor on Windows.

PlaceholderText_Color As Color

The color to use for placeholder text in controls or text views. (Mac + Win) Returns ColorDisabledText on Windows.

QuaternaryLabel_Color As Color

The quaternary color to use for text labels. (All platforms) Returns Text_Color.ChangeAlpha(0.35) on non-Mac.

ScrollBar_Color As Color

The system color used for scroll “bars”—that is, for the groove in which a scroller’s knob moves (Mac + Win). Deprecated on macOS 10.14. Use an NSScroller instead.

SecondaryLabel_Color As Color

The secondary color to use for text labels. (All platforms) Returns Text_Color.ChangeAlpha(0.75) on non-Mac.

SelectedContentBackground_Color As Color

The color to use for the background of selected and emphasized content. (Mac + Win) Available since macOS 10.14. Makes a fallback to SelectedControl_Color below. Returns SelectedMenuItem_Color on Windows.

SelectedControlText_Color As Color

The color to use for text in a selected control—that is, a control being clicked or dragged. (Mac + Win) Returns ColorHighlightText on Windows.

SelectedControl_Color As Color

The color to use for the face of a selected control—that is, a control that has been clicked or is being dragged. (Mac + Win) Returns ColorHighlightControl on Windows.

SelectedMenuItemText_Color As Color

The color to use for the text in selected menu items. (Mac + Win) Returns ColorActiveCaption on Windows.

SelectedMenuItem_Color As Color

The color to use for the face of selected menu items. (Mac + Win). Deprecated on macOS 10.14. Use an NSVisualEffectView instead. Returns ColorMenuHighlight on Windows.

SelectedTextBackground_Color As Color

The color to use for the background of selected text. (Mac + Win) Returns SelectedMenuItem_Color on Windows.

SelectedText_Color As Color

The color to use for selected text. (Mac + Win) Returns ColorActiveCaption on Windows.

Separator_Color As Color

The color to use for separators between different sections of content. (Mac + Win) Available since macOS 10.14. Makes a fallback to Grid_Color on systems below. Returns ColorMDIBackground on Windows.

Shadow_Color As Color

The color to use for virtual shadows cast by raised objects on the screen. (Mac + Win) Returns Color3DDarkShadow on Windows.

SystemBlue_Color, SystemBrown_Color, SystemGray_Color, SystemGreen_Color, SystemOrange_Color, SystemPink_Color, SystemPurple_Color, SystemRed_Color, SystemYellow_Color As Color

A color for the respectively named color that automatically adapts to vibrancy and accessibility settings. (all platforms). Returns the normal color of that name on non-Mac systems, with the exception of Color.Magenta for SystemPink_Color.

TertiaryLabel_Color As Color

The tertiary color to use for text labels. (All platforms) Returns Text_Color.ChangeAlpha(0.55) on non-Mac systems.

TextBackground_Color As Color

The color to use for the background area behind text. (Mac + Win) Returns Color_WindowBackground on Windows.

Text_Color As Color

The color to use for plain text. (Mac + Win) Returns ColorWindowText on Windows.

UnderPageBackground_Color As Color

The color to use in the area beneath your window's views. (Mac + Win) Returns ColorMDIBackground on Windows.

UnemphasizedSelectedContentBackground_Color As Color

The color to use for selected and unemphasized content. (Mac + Win) Available since macOS 10.14. Makes a fallback to ControlContent_Color below. Returns SelectedContentBackground_Color on Windows.

UnemphasizedSelectedTextBackground_Color As Color

The color to use for the text background in an unemphasized context. (Mac + Win) Available since macOS 10.14. Makes a fallback to SelectedTextBackground_Color below. Returns SelectedTextBackground_Color on Windows.

UnemphasizedSelectedText_Color As Color

The color to use for selected text in an unemphasized context. (Mac + Win) Available since macOS 10.14. Makes a fallback to SelectedText_Color on systems below. Returns SelectedText_Color on Windows.

WindowBackground_Color As Color

The color to use for the window background. (Mac + Win)

Please note that the system color for the window background on standard Windows 10 for example is white, not the light gray color that Xojo uses for the standard background.

WindowFrameText_Color As Color

The color to use for text in a window's frame. (Mac + Win) Returns ColorWindowText on Windows.

WindowFrame_Color As Color

The system color used for window frames, except for their text. (Mac + Win). Deprecated on macOS 10.14. Use an NSVisualEffectView with the NSVisualEffectMaterialTitlebar material instead. Returns ColorWindowFrame on Windows.

The following properties are Window color properties that could not easily be mapped to existing NSColor Mac properties. You can use them xplatform as well.

WIN_ButtonHighlight_Color As Color

Highlight color for three-dimensional display elements (for edges facing the light source.) (Win + Mac) Returns Highlight_Color on Mac.

WIN_CaptionText_Color As Color

Text in caption, size box, and scroll bar arrow box. (Win + Mac) Returns ControlText_color on Mac.

WIN_Desktop_Color As Color

The desktop color. As this is usually a picture, often returns black. (WIn + Mac) Returns UnderPageBackground_Color on Mac.

WIN_GradientActiveCaption_Color As Color

Right side color in the color gradient of an active window's title bar. Also good for Alternating Content together with WIN_InactiveGradientColor (Win + Mac) Returns AlternatingContentBackground_Color0 on Mac.

WIN_GradientInactiveCaption_Color As Color

Left side color in the color gradient of an inactive window's title bar. Also good for Alternating Content together with WIN_ActiveGradientColor (Win + Mac) Returns AlternatingContentBackground_Color1 on Mac.

WIN_Infotext_Color As Color

Text color for tooltip controls. (Win + Mac) Returns Label_Color on Mac.

WIN_MenubarBackground_Color As Color

The background color for the menu bar when menus appear as flat menus. (Win + Mac) Returns Control_Color on Mac.

WIN_MenuText_Color As Color

Text color in Menus (Win + Mac) Returns Text_Color on Mac.

WIN_Menu_Color As Color

Windows menu color. Returns ControlBackground_Color on Mac.

Enumerations

NSColorSystemEffect

Values for the mac-only AddSystemEffect method:

Value	Definition
None	no additional effect
Pressed	The color that indicates the item was pressed.
DeepPressed	The color that indicates the item received a deep press.
Disabled	The color that indicates the item is disabled.
RollOver	The color that indicates the mouse rolled over the item.

NSControlTint

Values for the deprecated CurrentControl_Tint property. Necessary for the fallback on older Mac systems than Mojave. Values:

Value	Definition
Default	The current default tint setting.
Blue	Aqua control tint.
Graphite	Graphite control tint.
Clear	Clear control tint.

Interfaces

SystemColorChangeReceiver

Any class incorporating this interface can use the RegisterForSystemColorChangeNotification method. If done so, on each system color change the instances’

SystemColorChanged()

method will be triggered. Use it to update custom, mode-dependend content.