ArtisanKit.Control
ArtisanKit.Control is the workhorse of the module. It handles features like automatic double-buffering, high resolution, appearance state, focus rings, and simple animation.
Events
Event AnimationStep (Key As String, Value As Double, Finished As Boolean)
After having started an animation, this event will fire as necessary to instruct the control the value being animated as changed. For example, animating a value from 1.0 to 2.0 might fire the event 10 times: 1.1, 1.2, 1.3, etc. The Finished parameter is true on the final step of the animation.
Event MouseWheel (MouseX As Integer, MouseY As Integer, PixelsX As Integer, PixelsY As Integer, WheelData As ArtisanKit.ScrollEvent) As Boolean
Based on the built-in MouseWheel event, this version automatically uses pixels instead of lines. PixelsX and PixelsY will set to the number of pixels that should be adjusted, instead of the traditional DeltaX and DeltaY which describe the number of lines that should be adjusted.
The WheelData parameter is an instance of ArtisanKit.ScrollEvent which contains additional details about the scrolling action. Usage of this object is completely optional, but does provide the information necessary to implement "snap-back" scrolling that is now familiar to OS X and iOS.
Event Paint (G As Graphics, Areas() As REALbasic.Rect, ScalingFactor As Double, Highlighted As Boolean)
The standard Paint event has two additional parameters: ScalingFactor and Highlighted.
ScalingFactor is a measurement by which drawing should be multiplied to produce nice results on the screen. However, this is only relevant when creating or loading a Picture, since the Xojo graphics object handles scaling automatically.
For example, if you wanted to create an picture that is 32x32 inside your Paint event, you probably need to draw it like so:
Dim Pic As New Picture(32 * ScalingFactor, 32 * ScalingFactor)
Pic.ForeColor = &c00FF00
Pic.FillRect(0, 0, Pic.Width, Pic.Height)
G.DrawPicture(Pic, 0, 0, Pic / ScalingFactor, Pic / ScalingFactor, 0, 0, Pic.Width, Pic.Height)
Highlighted will be true when the control should be drawn in the foreground/active window.
Properties
Backdrop As Picture = Nil // Read Only
The Backdrop property has been shadowed and cannot be set. This control is for custom controls, and should not be used for simple bitmap display.
HasFocus As Boolean = False
Indicates wether or not the control has the focus. Setting to True will grab the focus, setting to False pushes the focus to the parent window.
NeedsFullKeyboardAccessForFocus As Boolean = True
Some controls, such as text fields, should be able to get the focus without the user's Full Keyboard Access being enabled. Other controls, such as check boxes, should only get the focus if Full Keyboard Access is enabled. Set to false to accept focus even if Full Keyboard Access is disabled.
ScrollSpeed As Integer = 20
The number of pixels a single "step" of a traditional scroll wheel should move the content. This value is identical to the ScrollBar.LineHeight property.
Methods
Protected Sub BeginFocusRing (G As Graphics)
Begin drawing a focus ring. Each future Graphics action will create a new focus ring, until stopped. It is best advised to begin a focus ring, draw the control's backdrop, and end the focus ring.
Protected Sub CancelAnimation (Key As String, Finish As Boolean = False)
Stops the animation with key Key. If Finish is True, a final AnimationStep event will be triggered with the ending value. Otherwise, the value will remain in its last state.
Protected Sub EndFocusRing (G As Graphics)
Stops drawing focus rings around each Graphics action.
Function Render (Width As Integer, Height As Integer) As ArtisanKit.RetinaPicture
Creates a ArtisanKit.RetinaPicture object with the control drawn at the given Width and Height. This will cause two Paint events, one with a ScalingFactor of 1.0 and the other with 2.0.
Protected Sub StartAnimation (Key As String, StartValue As Double, EndValue As Double, Duration As Double, Ease As Boolean = True)
Begin an animation. Key is used to identify multiple animations to prevent collisions. StartValue is the value to begin animating from, EndValue is the value to animate to. Duration is the number of seconds the animation should require to complete. If the Ease parameter is true, the animation will have a slight weight to it. It will start faster and slow down towards the end. If Ease is false, the rate of animation will be steady.
Subclassing
The Graphics property will always return Nil. It is impossible to try to draw to the control from outside the Paint event.
Invalidate, Refresh, and RefreshRect will always use an EraseBackground value of False no matter what is passed to them. EraseBackground causes flicker, so it cannot be used.