Add-ons
  • Welcome
  • StackView
    • Version 2
      • How it works
      • How to use it
      • The Details
        • ScrollController
        • StackController
        • ViewController
      • Tips & Tricks
      • General Information
    • Version 3
      • How it works
      • How to use it
      • The Details
        • ScrollController
        • StackController
        • ViewController
      • Tips & Tricks
      • General Information
    • Changelogs
    • Purchase
  • FTC Word-Exporter
    • How to use it
    • General Information
  • CSTrueColors
    • Documentation
      • NSColorAddition
      • AppKitAddition
        • VisualEffectView
      • User32Addition
      • Template Images
      • The Demo Project
    • Changelog
  • Android
  • Open Source Projects
    • Android Design Extensions
  • Xojo Language Guide
    • The Basics
Powered by GitBook
On this page
  • Overview
  • Methods
  • Properties
  • Enumerations
  • Interfaces
  • Documentation
  • Methods
  • Properties
  • Enumerations
  • Interfaces
  1. CSTrueColors
  2. Documentation

NSColorAddition

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

Module

Overview

Methods

Overview

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

Enumerations

Overview

Interfaces

Overview

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!

Highlight(extends c As Color, Level As Double) As 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!

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

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

ControlBackground_Color as Color

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

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

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

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

UnemphasizedSelectedTextBackground_Color As Color

UnemphasizedSelectedText_Color As Color

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

WIN_CaptionText_Color As Color

WIN_Desktop_Color As Color

WIN_GradientActiveCaption_Color As Color

WIN_GradientInactiveCaption_Color As Color

WIN_Infotext_Color As Color

WIN_MenubarBackground_Color As Color

WIN_MenuText_Color As Color

WIN_Menu_Color As Color

Enumerations

NSColorSystemEffect

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

Value

Definition

Default

The current default tint setting.

Blue

Aqua control tint.

Graphite

Graphite control tint.

Clear

Clear control tint.

Interfaces

SystemColorChangeReceiver

SystemColorChanged()

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

PreviousDocumentationNextAppKitAddition

Last updated 8 months ago

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

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

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

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

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

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

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

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 on Windows.

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

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

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 on Windows.

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 on Windows.

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

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

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

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 on Mac.

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 on Mac.

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

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

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

Windows menu color. Returns on Mac.

Values for the mac-only method:

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

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

SetColor
SetFillColor
Highlight_Color
ScrubberTexturedBackgroundColor
SelectedControlText_Color
DisabledControlText_Color
Highlight_Color
Text_Color
SelectedMenuItem_Color
SelectedMenuItem_Color
SelectedContentBackground_Color
SelectedTextBackground_Color
SelectedText_Color
Highlight_Color
ControlText_color
UnderPageBackground_Color
AlternatingContentBackground_Color0
AlternatingContentBackground_Color1
Label_Color
Control_Color
Text_Color
ControlBackground_Color
AddSystemEffect
CurrentControl_Tint
RegisterForSystemColorChangeNotification
AddSystemEffect
BlendColor
ChangeAlpha
Draw
FillRectangle
Highlight
MultiplyColor
RegisterForSystemColorChangeNotification
ScrubberTexturedBackgroundColor
SetColor
SetFillColor
SetStrokeColor
Shadow
SystemVersionIsAtLeast
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
NSColorSystemEffect
NSControlTint
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