iOSLibCanvas - UBogun/Xojo-iosLib GitHub Wiki

Native class: AppleView
inherits from: iOSLibResponder

iOSLibCanvas is the custom control of iOSLib containing an AppleView as object. You should use it whenever you need a Canvas with all available events – in most cases, using the Xojo canvas and employing the iOSControlExtension module will do perfectly fine.
Like all iOSLib custom controls, the control is a wrapper that contains the view and performs translations between Xojo and iOS classes / data types transparently whereever possible.
Like all iOSLib custom controls, if you want to attain maximum performance, you can always address the iOSClass itself via the Controls ID object. The ID object is always the View subclass itself, in this case AppleView. The iOS class expects Apple native objects and data types of course. You can always use the included translation methods to bridge from Xojo types and classes to iOS.

General information

UIVIew Basics

Inspector Properties

Inspector behavior properties of iOSLibCanvas

Properties

AppleView properties not listed here can be accessed via the ID object of the custom control

Alpha As Double: The alpha value / transparency of the object, with 0 being fully transparent and 1 being fully opaque.

AutoResizesSubviews As Boolean: If True, the view resizes its sublayers when its bounds change. Default is True.

AutoResizingMask As AppleAutoResizingMask: The AutoresizingMask determines how a view changes its bounds when its superview’s bound change.

BackgroundColor As Color: The BackgroundColor of the view if it is not filled completely with opaque image data.

Bounds As Xojo.Core.Rect: The bounds are clipping frame limits for the view's content. Resizing the bounds can scale the contents if ContentMode ist set to some fill or fit value or clip the content's borders if not.

CanBecomeFocused As Boolean (read-only): Asks the view whether it is currently capable of being focused. (read-only) Available since iOS 9.0.

Center As Xojo.Core.Point: A normalized point that defines the center on which image manipulations or Transform changes are centered. Normalized means the value is between (0,0) and (1,1) with a default of (0.5,0.5).

ClearsContextBeforeDrawing As Boolean: If True, the view's content is cleared before redrawing it. Setting this property to False may speed up performance but cause redraw errors.

ClipsToBounds As Boolean: If True, the contents will not overlap the view's bounds.

ContentMode As AppleView.UIViewContentMode: Exactly the same as the Xojo contentmode property but with the addition of a Redraw value that causes the view to call the Invalid (setNeedsDisplay) method when its bounds change.

ContentscaleFactor As Double: The scale factor applied to the view. Typical values are 1 for non-Retina, 2 for Retina and 3 for Ultra Retina like iPhone 6.

ExclusiveTouch As Boolean: If True, touch events received by the object will not be forwarded further down the event chain.

Focused As Boolean: A Boolean value that indicates whether the item is currently focused. Available since iOS 9.0. The setter emulates a focus catch (Focused itself is a read-only property).

Frame As Xojo.Core.Rect: The outer dimensions of the object.

HasAmbiguousLayout As Boolean (read-only): very helpful property for debugging your view layouts. Returns True if the constraints attached are conflicting or incomplete. see ExerciseAmbiguityInLayout method.

Height As Double: A shortcut to Frame.Size.Height_ resp. Bounds.Height.

Hidden As Boolean: If True, the receiver is hidden and disabled.

ID As AppleView (read-only): The view object itself. Use it for fast access or for features not implemented in the custom control.

LayoutMargins As UIEdgeInsets: The distance from the edge of the view to its subviews.

Left As Double: Shortcut for Frame.Origin.x.

Mask As AppleView: A optional view that is used for masking out content.

MultipleTouchEnabled As Boolean: If True, the object receives all touch events of a multipleTouch. Otherwise it gets only the first event. Default is False.

Opaque As Boolean: If your view uses no transparency or mask, you can set this property to True to speed up drawing.

PreservesSuperviewLayoutMargins As Boolean: If True, the superview's margins are also considered when laying out content.

SizeThatFits As Xojo.Core.Size (read-only): The calculated size that is needed to display the full content of the view. See SizeToFit.

SuperView As AppleView (read-only): The object's superview if it has one. You attach a view to another by using one of the addSubview methods.

Tag As Integer: An optional identifier you can use to easily find a view. See ViewWithTag method.

TintAdjustmentMode As AppleView.UIVIewTintAdjustmentmode: Lets you change between no, always and automatic dimming of the tintColor if the view is deactivated.

TintColor As Color: Exactly that.

Top As Double: Shortcut for Frame.Origin.Y.

Transform As CGAffineTransform: A CGAffineTransform is a transformation matrix that is used to calculate the visual appaerance of a view's content. When you assign a CGAffineTransform that is not CGAffineTransformidentity, the system uses this structure to add rotation, scale and other calculations before the view is displayed. Check out the iOSControExtension convenience methods and the CoreGraphicsLib framework module (in the latter case the methods starting with "CGAffineTransform") for hints on its use.

TranslatesAutoresizingMaskIntoConstraints As Boolean: If you set this property to True, the AutoresizingMask is analyzed by the object and constraints built from it and added to the AppleView.

UserInteractionEnabled As Boolean: If True, lets the object react to touch events. During an animation this value is disregarded. See the AnimationOptions description in the Animate methods.

Width As Double: A Shortcut for Frame.Size.Width.

Window As AppleWindow (read-only): The view’s window object, or nil if it has none.

Methods

Important: Note on block animations

All Animate… and TransitionWith… Methods are just examples for what can be done. Plase note that the animation and transition methods in itself are class methods. I only implemented them to work like instance methods which will mostly be the wanted thing. But you can implement your own animationblocks in which you assign properties to every view instance you like and have them perform together in only one method call.

AddGestureRecognizer (Recognizer As AppleGestureRecognizer): Allows you to add a GestureRecognizer to the GestureRecognizers property.

AddSubview (aView As AppleView): Adds a view layer to the view (on the deepest layer, which means, behind other existing subviews).

AnimateAlpha (Alpha as Double, Options as AppleViewAnimationOption, opt. Seconds as Double = 0.2, opt. Curve as AppleView.UIVIewAnimationCurve = uiviewanimationcurve.EaseInEaseOut,opt. Delay as double = 0, completion as appleblock = nil): Animates the alpha value with a duration of Seconds, a chosen UIViewAnimationCurve and after a delay of Delay seconds. Uses a block animation for this, enabling you to catch the AnimationFinished Event or perform different things by passing a custom completion block.

The following methods follow the same scheme and are all block animation implementations:
AnimateBounds (NewBounds as Xojo.Core.Rect, Options as AppleViewAnimationOption, Seconds as Double = 0.2, Curve as UIVIewAnimationCurve = UIViewAnimationCurve.EaseInEaseOut, delay as double = 0, completion as appleblock = nil): Block animation for the view's Bounds.
AnimateCenter (NewCenter as xojo.core.point, Options as [AppleViewAnimationOption](https://github.com/UBogun/Xojo-iosLib/wiki/AppleView AnimationOption), Seconds as Double = 0.2, Curve as UIVIewAnimationCurve = UIViewAnimationCurve.EaseInEaseOut, delay as double = 0, completion as appleblock = nil): Block animation for the view's Center.
AnimateColor (NewColor as Color, Options as [AppleViewAnimationOption](https://github.com/UBogun/Xojo-iosLib/wiki/AppleView AnimationOption), Seconds as Double = 0.2, Curve as UIVIewAnimationCurve = UIViewAnimationCurve.EaseInEaseOut, delay as double = 0, completion as appleblock = nil): Block animation for the view's Backgroundcolor.
AnimateFrame (NewFrame as xojo.core.rect, Options as AppleViewAnimationOption, Seconds as Double = 0.2, Curve as UIVIewAnimationCurve = UIViewAnimationCurve.EaseInEaseOut, delay as double = 0, completion as appleblock = nil): Block animation for the view's Frame.
AnimateTransform (NewTransform as CGAffineTransform, Options as [AppleViewAnimationOption](https://github.com/UBogun/Xojo-iosLib/wiki/AppleView AnimationOption), Seconds as Double = 0.2, Curve as UIVIewAnimationCurve = UIViewAnimationCurve.EaseInEaseOut, delay as double = 0, completion as appleblock = nil): Block animation for the view's Transform.
For fully customized animations, create an own AppleBlock that modifies the properties of your desires views and pass it to the method
AnimateBlock (ChangeBlock as AppleBlock, options as AppleViewAnimationOption, Seconds as Double = 0.2, Curve as appleview.UIVIewAnimationCurve = appleview.uiviewanimationcurve.EaseInEaseOut, delay as double = 0, completion as appleblock = nil, completion as appleblock = nil): Starts a custom method from a block which you can use to change different properties of views using the specified duration, delay, options, and completion handler. Please note the animate block methods run on a class method, so you are not limited to the properties of the current view inside the changeblock method.

BringSubviewToFront (aView as AppleView): brings the subview to the furthermost layer of the view hierarchy.

CombineTransformations (Transform1 as CGAffineTransform, Transform2 as CGAffineTransform): Sets the Transform property to the concatenation of both supplied CGAffineTransforms.

ConvertPointfromView (aPoint As Xojo.Core.Point, aView As AppleView) As Xojo.Core.Point: Converts a Point from the coodinate system of aView to the coordinate system of the current AppleView. The same, just vice versa, is
ConvertPointfromView (aPoint As Xojo.Core.Point, aView As AppleView) As Xojo.Core.Point

ConvertRectfromView (aRect As Xojo.Core.Rect, aView As AppleView) As Xojo.Core.Rect: This is the same as above, just for NSRects. And there is Also the counterpart
ConvertRecttoView (aRect As Xojo.Core.Rect, aView As AppleView) As Xojo.Core.Rect

Copy() As AppleView: Returns a copy of the current view.

DrawViewHierarchy (ARect as Xojo.Core.Rect, AfterScreenUpdates) As Boolean: Renders a snapshot of the complete view hierarchy 8or a part of it) as visible onscreen into the current context. Returns Success. Pass Bounds for a fullsize capture.

EndEditing (optional enforce As Boolean): Causes the view (or one of its embedded text fields) to resign the first responder status. If enforced, regardless of what the view currently is doing.

ExchangeSubviews (Index1 As Integer, Index2 As Integer): Swaps the subviews at view hierarchy position index1 with that from index2.

ExerciseAmbiguityInLayout(): If your object has an ambigous layout (see respective property), this method call changes the conflicting constraints so you can easily see where the constraint problems are. Very useful for debugging.

GestureRecognizers() As AppleGestureRecognizers: An array of the AppleGestureRecognizers attached to this view.

HitTest (Point as xojo.core.point, anEvent As AppleNSEvent = nil) As AppleView: Checks to see if point is contained in a subview of the view and returns the furthest descendant of the view that fulfills this query. If you do not check from inside a touch or similar event, pass NIL as anEvent. See also PointInside

InsertSubviewAbove (aView as AppleView, aboveView as AppleView): Inserts aView above the view hierarchy position of aboveView.

InsertSubviewAtIndex (aView as AppleView, Index as integer): Inserts aView into view hierarchy position Index.

InsertSubviewBelow (aView as AppleView, BelowView as AppleView): Inserts aView below the view hierarchy position of BelowView.

Invalidate(): The equivalent of a Xojo invalidate method call.
Invalidate(Rect as Xojo.Core.Rect): Like above, but only for a certain rectangle.

InvalidateLayout(): Invalidates the current layout of the receiver and triggers a layout update during the next update cycle.

InvertTransform(): Performs a CGAffineTransformationInvert call on Transform, in other words, inverts it.

IsDescendantOfView (aView As AppleView) as Boolean (read-only): Returns True if the object is a subview of aView.

PointInside (Point as Xojo.Core.Point, anEvent As AppleNSEvent = nil) As Boolean: Checks to see if point is contained in a subview of the view. If you do not check from inside a touch or similar event, pass NIL as anEvent. See also HitTest

Refresh(): Lays out the subviews immediately.

RefreshFocus(): Tells the focus engine to force a focus update immediately. Available since iOS 9.1.

RemoveFromSuperview(): Removes the view from its superview. If it is not held by another owner (or is treated with a Retain call), it will go out of scope.

RemoveGestureRecognizer (Recognizer As AppleGestureRecognizer): Allows you to remove a GestureRecognizer from the GestureRecognizers property.

ResetTransform(): Resets the Transform property (sets it to CGAffineTransform.Identity).

Rotate (Degrees As Double): Performs a CGAffineTransformRotate method call on Transform. Please note this method expects the angle in degrees. If you prefer to use radians, use the MathExtension.RadianToDegree method on a Double.

Scale (Xfactor as Double, opt. YFactor as Double = 0): Performs a CGAffineTransformScale method call on Transform. If YFactor is 0, uses XFactor for both dimensions, in other words, scales proportionally.

SendSubviewToBack (Aview As AppleView): Sends aView straight down the view hierarchy.

SetRotation (Degrees As Double): Performs a CGAffineMakeRotate method call on Transform. Please note this method expects the angle in degrees. If you prefer to use radians, use the MathExtension.RadianToDegree method on a Double.
_All 3 following Set… methods are similar. The difference between the Rotate, Scale etc. calls is these methods do not modify the existing Transform property but overwrite it with a new one.

SetScale (Xfactor as Double, opt. YFactor as Double = 0): See Scale and the sentence above.

SetTranslation (DeltaX as Double, DeltaY as Double): Moves the visual representation of the view by adding a CGAffineTransform. See Translate.

SizeThatFits (aSize as FoundationFramework.NSSize) As FoundationFramework.NSSize: Asks the view to calculate and return the size that best fits the specified size.

SizeToFIt(): Modifies the frame of the view to display its contents fully. Very useful for localized buttons!

Snapshot (opt. AfterUpdate As Boolean = False) As AppleView: Creates a snapshot of the current visual appearance of the view. If AfterUpdate is true, does so after the next redraw to make sure to capture recent changes to it.

SpringAnimate_XXX: The SpringAnimate methods are all block animation methods like the Animate_XXX methods, with the exception that the animation is performed with a timing curve like a physical spring. For this effect, the SpringAnimate methods expect two additional (optional) Double values: Velocity and DampingRatio. A velocity value of 1 corresponds to the animation distance traveled in 1 second. A DampingRatio of 1 creates a smooth damping effect. If you want the values to bounce more, reduce it. Be aware that a high Velocity with a low DampingRatio will shoot the animation over the defined bounds.
The Springanimation methods are:
SpringAnimateAlpha (Newalpha as Double, options as AppleView AnimationOption, DampingRatio As Double = 1, Velocity As Double = 0.5, Seconds as Double = 0.2, Curve as UIVIewAnimationCurve = uiviewanimationcurve.EaseInEaseOut, delay as double = 0, completion as appleBlock = nil): Animates the Alpha value.
SpringAnimateBounds (NewBounds As xojo.core.rect, options as AppleView AnimationOption, DampingRatio As Double = 1, Velocity As Double = 0.5, Seconds as Double = 0.2, Curve as UIVIewAnimationCurve = uiviewanimationcurve.EaseInEaseOut, delay as double = 0, completion as appleBlock = nil): Animates the bounds.
SpringAnimateCenter (NewCenter As Xojo.Core.Point, options as AppleView AnimationOption, DampingRatio As Double = 1, Velocity As Double = 0.5, Seconds as Double = 0.2, Curve as UIVIewAnimationCurve = uiviewanimationcurve.EaseInEaseOut, delay as double = 0, completion as appleBlock = nil): Animates the Center property.
SpringAnimateColor (NewColor As Color, options as AppleView AnimationOption, DampingRatio As Double = 1, Velocity As Double = 0.5, Seconds as Double = 0.2, Curve as UIVIewAnimationCurve = uiviewanimationcurve.EaseInEaseOut, delay as double = 0, completion as appleBlock = nil): Animates the BackgroundColor.
SpringAnimateFrame (NewFrame As Xojo.Core.Rect, options as AppleView AnimationOption, DampingRatio As Double = 1, Velocity As Double = 0.5, Seconds as Double = 0.2, Curve as UIVIewAnimationCurve = uiviewanimationcurve.EaseInEaseOut, delay as double = 0, completion as appleBlock = nil): Animates the view's frame.
SpringAnimateTransform (NewTransform As CGAffineTransform, options as AppleView AnimationOption, DampingRatio As Double = 1, Velocity As Double = 0.5, Seconds as Double = 0.2, Curve as UIVIewAnimationCurve = uiviewanimationcurve.EaseInEaseOut, delay as double = 0, completion as appleBlock = nil): Animates the Transform property.
Like with the Animate block methods, you can define a fully customized method and send it as a block to
SpringAnimateBlock (Changeblock As Appleblock, options as AppleView AnimationOption, DampingRatio As Double = 1, Velocity As Double = 0.5, Seconds as Double = 0.2, Curve as UIVIewAnimationCurve = uiviewanimationcurve.EaseInEaseOut, delay as double = 0, completion as appleBlock = nil): Performs a spring animation on a custom block that runs on class level, so it can change the animatable properties of several views at once.

Subviews() As AppleView: The control’s immediate subviews. Use Addsubview and RemoveSubview to modify.

toImage() As iOSImage: Returns the current look of the Canvas as image.

Transition (Transition as UIViewAnimationTransition, options as AppleViewAnimationOption, Seconds as Double = 0.2, Curve as UIVIewAnimationCurve = uiviewanimationcurve.EaseInEaseOut) TransitionWithAlpha (NewAlpha as Double, Transition as UIViewAnimationTransition, Options as [AppleView AnimationOption](https://github.com/UBogun/Xojo-iosLib/wiki/AppleView AnimationOption), Seconds as Double = 0.2, Curve as UIVIewAnimationCurve = uiviewanimationcurve.EaseInEaseOut): This, like all the TransitionWith methods, is a function very similar to the Animate… methods. They all use a block animation too and the passed properties are almost identical. The differences are:

• You can use one of the UIViewAnimationTransition enumeration values to make the view flip from one side to the other or use a curl up/down effect on it.
• There is no Delay value, therefore the animation starts instantaneously.

Please refer to the Animate methods for a description.
The other TransitionWith methods are:
TransitionWithBounds (newBounds as xojo.core.rect, transition as uiviewanimationtransition, options as [AppleView AnimationOption](https://github.com/UBogun/Xojo-iosLib/wiki/AppleView AnimationOption), Seconds as Double = 0.2, Curve as UIVIewAnimationCurve = uiviewanimationcurve.EaseInEaseOut): Bounds animation with transition.
TransitionWithCenter (NewCenter as xojo.core.point, Transition as UIViewAnimationTransition, options as [AppleView AnimationOption](https://github.com/UBogun/Xojo-iosLib/wiki/AppleView AnimationOption), Seconds as Double = 0.2, Curve as UIVIewAnimationCurve = uiviewanimationcurve.EaseInEaseOut): Center animation.
TransitionWithColor (newColor as Color, Transition As UIViewAnimationTransition, options as [AppleView AnimationOption](https://github.com/UBogun/Xojo-iosLib/wiki/AppleView AnimationOption), Seconds as Double = 0.2, Curve as UIVIewAnimationCurve = uiviewanimationcurve.EaseInEaseOut): Backgroundcolor animation.
TransitionWithFrame (newFrame as xojo.core.rect, Transition as uiviewanimationtransition, options as [AppleView AnimationOption](https://github.com/UBogun/Xojo-iosLib/wiki/AppleView AnimationOption), Seconds as Double = 0.2, Curve as UIVIewAnimationCurve = uiviewanimationcurve.EaseInEaseOut): Frame animation.
TransitionWithTransform (NewTransform as CGAffineTransform, Transition as uiviewanimationtransition, options as [AppleView AnimationOption](https://github.com/UBogun/Xojo-iosLib/wiki/AppleView AnimationOption), Seconds as Double = 0.2, Curve as UIVIewAnimationCurve = uiviewanimationcurve.EaseInEaseOut): Transform animation.

Translate (DeltaX as Double, DeltaY as Double): Performs a CGAffineTransformTranslate operation on Transform, in other words, moves the visual appearance.

InvalidateFocus(): Submits a request to the focus engine for a focus update in this environment. Available since iOS 9.1.

ViewTransition (fromview as appleview, toView as Appleview, Transition as appleview.UIViewAnimationTransition, options as AppleViewAnimationOption, Seconds as Double = 0.2, Curve as appleview.UIVIewAnimationCurve = appleview.uiviewanimationcurve.EaseInEaseOut, completion as appleblock = nil): Performs a transition between two views on their superview.

ViewWithTag (Tag As Integer) As AppleView: Returns the view you tagged with the matching Tag property value.

Shared Properties

EnableAnimations As Boolean: If Set to False, following block animations will not be animated anymore.

InheritedAnimationDuration As Double: The inherited duration of the current animation. Only works within UIView animation blocks. (read-ony). Available since iOS 9.0.

RequiresConstraintBasedLayout As Boolean (read-only): True if the object must be child of a ViewController/Window using constaint based layout to function properly.

Events

It may be difficult to catch an event from a programmatical instantiated Xojo view. For this purpose, the AppleViewControl class exists that is a custom control view implementation you can use in conjunction with its (still to add) convenience method and its ViewObject property to catch events forwarded from the view.
To give you a full overview, AppleResponder event definitions have been included in this list too:

AddedSubview (View As AppleView): Fires when a subview was added to the view, returning the new subview.

AnimationFinished (completion as Boolean): Fires when a blockanimation method finishes.

BecameSubview(): The view was attached to its superview. This is a good place for initializations that need information about the view's frame because in the open event this property is not yet defined.

Draw (Rect As NSRect): The view is about to draw a portion of itself. Unlike in Xojo, you do not get the GraphicsContext delivered from this event. To perfom your own drawings, start with dim context as AppleCGContext = AppleCGContext.CurrentContext and perform your drawing routines on this object.

EstimatedPropertiesUpdated (Touchset As AppleSet): Fires when the estimated properties of a touch event change, which means the force of a touch event. Available since iOS 9.1.

Resized(): The view is about to send layout orders to its subviews. This usually happens after a view resize, so here's a good place to react on device orientation changes and the like.

Shown(): Another option for initialization, making it clearer that the view was attached to a new UIWindow/iOSView instead of just to some view that may not be visible or attached anywhere.

MotionBegan (type as AppleNSEvent.UIEventSubtype, anEvent as AppleNSEvent): (An Event of the AppleResponder class): Some kind of device motion was started. You can get information about it by examining the Event properties.

MotionCancelled (type as AppleNSEvent.UIEventSubtype, anEvent as AppleNSEvent): (An Event of the AppleResponder class): Some kind of device motion was cancelled. You can get information about it by examining the Event properties.

MotionEnded (type as AppleNSEvent.UIEventSubtype, anEvent as AppleNSEvent): (An Event of the AppleResponder class): Some kind of device motion was finished. You can get information about it by examining the Event properties.

PressesBegan (Touchset As AppleSet, anEvent as ApplePressesEvent): Fires when a physical button is pressed in the associated view. Available since iOS 9.

PressesCancelled (Touchset As AppleSet, anEvent as ApplePressesEvent): Fires when a system event cancels a press event. Available since iOS 9.

PressesChanged (Touchset As AppleSet, anEvent as ApplePressesEvent): Fires when the force of a press changed. Available since iOS 9.

PressesEnded (Touchset As AppleSet, anEvent as ApplePressesEvent): Fires when a press event has finished. Available since iOS 9.

TintColorChanged(): Fires when the tintcolor changed.

TraitCollectionChanged (PreviousCollection As AppleTraitCollection): Fires when the trait collection has changed, like when the device orientation changed.

TouchesBegan (Touchset as AppleSet, anEvent as AppleNSEvent): (An Event of the AppleResponder class): The user has begun touching the view. You can get information about the touch by examining the Event properties. The touchset may contain more than only one touch. If you want finer event registration, use custom AppleGestureRecognizers.

TouchesCancelled (Touchset as AppleSet, anEvent as AppleNSEvent): (An Event of the AppleResponder class): A user touch was cancelled. You can get information about the touch by examining the Event properties. The touchset may contain more than only one touch. If you want finer event registration, use custom AppleGestureRecognizers.

TouchesEnded (Touchset as AppleSet, anEvent as AppleNSEvent): (An Event of the AppleResponder class): The user finished touching the view. You can get information about the touch by examining the Event properties. The touchset may contain more than only one touch. If you want finer event registration, use custom AppleGestureRecognizers.

TouchesMoved (Touchset as AppleSet, anEvent as AppleNSEvent): (An Event of the AppleResponder class): One or more fingers connected to a begun touch have moved. You can get information about the touch by examining the Event properties. The touchset may contain more than only one touch. If you want finer event registration, use custom AppleGestureRecognizers.

WillBecomeSubview (view as AppleView): Fires before the view attaches itself to the other view.

WillRemoveSubview (view as AppleView): Fires before the current view will remove the subview it presents you.

WillShow (Window as AppleWindow): Fires before the view attaches itself to a UIWindow (resp. in that case a viewcontroller).