ArtisanKit Module
This module provides a number of classes, methods, and extension methods useful in custom control authoring.
Classes
Methods
Function ArtisanKit.BlendColors (Color1 As Color, Color2 As Color, Color2Opacity As Double = 1) As Color
This method blends Color1 with Color2 at the ratio specified in Color2Opacity. An opacity of 1 means 100% Color2 and 0% Color1. An opacity of 0.5 means 50% Color2 and 50% Color1.
Function ArtisanKit.ColorBrightness (C As Color) As Integer
Estimates the perceived brightness of a color. Experimentation will be necessary, though generally a value less than 170 should be considered dark. This is useful for custom background colors, so the foreground/text color can be switched from black to white to provide clear contrast.
Function ArtisanKit.ColorIsBright (Source As Color) As Boolean
Uses the brightness and luminance of a color to determine wether or not a color appears light on the screen.
Function ArtisanKit.ColorLuminance (Source As Color) As Double
Calculates the relative luminance of a color. Returns a value between 0 and 1. Values greater than 0.65 should be considered light colors. Luminance is most useful for calculating the contrast between two colors.
Function ArtisanKit.FullKeyboardAccessEnabled () As Boolean
In OS X Keyboard Preferences, under Shortcuts there is a setting called "Full Keyboard Access." This method returns True when this option is set to "All controls." The control will automatically accept tabs if the user is tabbing through controls, and the user should be able to use the keyboard to interact with the control.
On other platforms, this method always returns True.
Function NearestMultiple(Value As Double, Factor As Double) As Double
See Precise Drawing with Doubles for a demonstration of what this method does and why it's useful. The high level overview is that drawing a line at half a pixel works well on 2x screens, but looks blurry on 1x and 3x screens. This method computes a value that will produce a nice sharp line at any scaling factor.
Extension Methods
Function Color.AtOpacity (Extends SourceColor As Color, Opacity As Double) As Color
Reduces the opacity of a color. Colors with alpha channels are respected. For example, the color #00000080 (100% black at 50% opacity) will become #00000040 (100% black at 25% opacity) if the Opacity parameter is 0.5. An opacity of 1.0 means the color is unchanged, 0.5 is 50% opacity, and 0.0 is fully transparent.
Function Graphics.CapHeight (Extends G As Graphics) As Double
A font's CapHeight is the measurement from the baseline to the top of a capital letter. This is similar to Graphics.TextAscent, but the ascent of the font includes space for diacritical marks. This method uses system declares on OS X, but must rely on guesswork on Windows and Linux.
When trying to vertically center some text, the CapHeight will produce a much more visually pleasing result than TextAscent or TextHeight.
Sub Graphics.DrawStretchedPicture (Extends G As Graphics, Source As Picture, Destination As REALbasic.Rect, StretchVertical As Boolean = True, StretchHorizontal As Boolean = True)
Stretches the Source picture to fill the Destination rect. If StretchVertical is True, the picture will be vertically divided into 3 equal parts, with the middle stretching to fill the height, the first and third parts used to "cap" the fill. StretchHorizonal does the same for the width. The width must be a multiple of 3 when StretchHorizontal is True, the height must be a multiple of 3 when StrechVertical is True. The Destination dimensions must be greater than the Source dimensions.
Sub Graphics.FillWithPattern (Extends G As Graphics, Source As Picture, Area As REALbasic.Rect, SourcePortion As REALbasic.Rect = Nil)
Pattern fills the area given by Area with the Source picture. The SourcePortion rect can be added to use only a portion of the Source picture for the fill.
Function Graphics.NewPicture (Extends G As Graphics, Width As Integer, Height As Integer) As Picture
Xojo makes it annoying to create a picture object with settings to match another Graphics object. Graphics.NewPicture will take care of that for you. It simply creates a picture of the correct pixel dimensions with the required scaling and resolution properties.