NSColorAddition

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

Module

Overview

Methods

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.

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.