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!
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
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.
Last updated
