AppleCALayer - UBogun/Xojo-iosLib GitHub Wiki

Inherits from AppleResponder
Status: Partially completed
Memoryleak test: passed

This is an implementation of CALayer, the CoreAnimation layer behind every view. While you have to install a CALayer on OSX explicitely, under iOS no view comes without one. On iOS, you can imagine a CALayer being the core of a view, while the view itself is a delegate for the layer. While you can influence some of the layer properties via view properties and methods, the CALayer class itself offers many more very powerful features for transforming the visual representation of the view's content without changing the content itself, including transformations in 3D space and a lot of GPU driven animations.
You can always create further sublayers for an existing layer, therefore a constructor exists.

Constructor

Constructor (): Creates a new, free AppleCALayer.
Constructor (ALayer As AppleCALayer): Returns a copy of the layer. Must be a sublayer of the layer, not another layer in a different view hierarchy.

Properties

AffineTransform As CGAffineTransform: The CGAffineTransform Structure for 2D transformations. The CATransform3D structure which is only available for CALayers, not for views, is much more powerful. See Transform property.

AnchorPoint As NSPoint: Defines the anchor point of the layer's bounds. Manipulations like transformations take this as center point. Default is [0.5, 0,5].

AnchorPointZ As Double: The AnchorPoint in Z axis, measured as distance from the Z axis base. Default is 0. If you want to send a layer down the view hiearchy, lower this value (can be negative). And vice versa raise it to move it up to the front.

AnimationKeys As AppleArray of CFStringRef: An array containing the names of animations attached to the layer. see AnimationKeyStrings method.

AutoResizingMask As AppleAutoResizingMask: Basically an Integer value that holds the locking information for the layer.

BackgroundColor As AppleCGColor: The BackgroundColor of the layer if it is not filled with opaque image data completely. Default is NIL.

BackgroundFilters As AppleArray of AppleCIFilters: An array of filters to apply to the content behind the layer. Not yet implemented

BorderColor As AppleCGColor: The border color of the layer if BorderWidth > 0. Default is black.

BorderWidth As Double: Exactly that.

Bounds As NSRect: The position and size of the layer in its own coordinate space.

CompositingFilter As AppleCIFilter. not yet implemented

Constraints As AppleArray of AppleCAConstraints (read-only): not yet implemented.

Contents As AppleGeneralObject: In case of a static image, can be set to an AppleCGImage to display this image.

ContentsCenter As NSRect: With this, you can divide the layer into a 3 x 3 grid. this is useful for images that have a frame that should be scaled correctly. See Apple's Docs for further information.

ContentsFlipped As Boolean: Inverts the Y axis.

ContentsPositioning As CALayerContentPosition: Lets you chose different scaling and positioning presets for the layer's content. Very much the same like the Xojo iOSImageView’s ContentMode.

ContentsRect As NSRect: A Rectangle that defines the portion of the content in unit coordinate space (0,0,1,1) that should be used. If pixels outside this rectangle are requested, the border pixels are stretched.

ContentsScale As Double: The scale factor applied to the layer.

CornerRadius As Double: The corner radius. Anything above 0.0 will draw round corners. This is usually ony so for the border and backgroundcolor, but with MasksToBounds set to True the content image will be clipped too.

DelegateAppleView As AppleView: The AppleView that is the CALayer’s delegate. You should not try to change this property for layers created automatically with a View.

DoubleSided As Boolean: If True, draws the layer (image) even when it is transformed to show its back side.

DrawsAsynchronously As Boolean: If True, drawing commands to the layer are executed in a background thread. Can speed up processing but does not necessarily have to.

EdgeAntialiasing As Boolean: Whether boundaries of the layer that are not on exact pixel places are dran antialiased. Default is False.

EdgeAntiAliasingMask As AppleEdgeAntiAliasingMask: A bitmap (in this case, a helper class) to define which edges of the layer are antialiased. Default is true for all.

Filters As MacOSArray of CIFIlters: CIFilters you can combine that are attached to the layer.

Frame As NSRect: Position and size of the layer in relation to its superlayer's coordinates.

GeometryFlipped As Boolean: if True, the Y axis of the layer and its sublayers are flipped.

GroupOpacity As Boolean: If True, the layer inherits the opacity from its superlayer.

Height As Double: Shortcut to _Bounds.size.Height

Hidden As Boolean: Makes the layer invisible and deactivates it. Very handy if you find yourself often typing "visible = xx, enabled = xx".

Left As Double: Shortcut to Position.X

MagnifyFilter As ResizeFilters: Lets you chose between Linear, Nearest neighbor and trilinear interpolation. Not yet implemented

Mask As AppleCALayer: An optional layer with a bitmap mask for the contents of the layer.

MasksToBounds As Boolean: If True, Sublayers are clipped by the layer's bounds.

MinificatonFilterBias As Single: Influences the MinifyFilter when set to trilinear. Not yet implemented

MinifyFilter As ResizeFilters: like MagnifyFilter, but for minifications and modifiable when set to trilinear interpolation. Not yet implemented

ModelLayer As AppleCALayer: A layer instance representing the underlying model layer. This method returns a value only when a transaction involving changes to the presentation layer is in progress.

Name As CFstringRef: An optional identifier you can set.

NeedsDisplayOnBoundsChange As Boolean: If True, the layer's contents are updated when its superlayer's bounds change. Default False.

Opacity As Single: 0 is transparent, 1 is fully opaque.

Opaque As Boolean: Set this to true if you layer is filled completely with an opaque image or color to speed up image composition.

Position As NSPoint: The NSPoint value of the Frame Property.

PreferredFrameSize As NSSize (read-only): Returns the preferred frame size of the layer in the coordinate space of its SuperLayer.

PresentationLayer As AppleCALayer: A copy of the current layer's state. If an animation is in progress, you can take snapshots of the layer this way.

RasterizationScale As Double: The scale of rasterization if ShouldRasterize is True. 1 = current scale, larger values magnify, smaller minify.

ShadowColor As AppleCGColor: The color if the shadow. Default is opaque black.

ShadowOffset as NSSize: The offset of the shadow from the object.

ShadowOpacity As Single: The opacity of the shadow. Default is 0 (transparent). When you change this value, the shadow appears.

ShadowRadius As Double: The blur radius (in points) of the shadow.

ShouldRasterize As Boolean: If True, the layer is rendered as a bitmap and then composited to its view.

Style As AppleDictionary: An optional dictionary to store properties that are not explicitely declared in the layer. Can be used to override property methods.

SubLayers As AppleArray of CALayers: An array of CaLayers – the sublayers in order front to back. PLease note that layers you add here must not have a superlayer property!

SublayerTransform As CATransform3D: The transform to apply to the sublayers. Usually used for adding perspective.

SuperLayer As AppleCALayer (read-only): The Superlayer if the layer has one.

Top As Double: Shortcut to Position.Y.

Transform As CATransform3D: A transformation matrix for the layer, relative to its AnchorPoint.

Width As Double: Shortcut to Bounds.Size_.Width

ZPosition As Double: The layer's position on the Z axis. Default 0.

Methods

AddAnimation (Animation As AppleCAAnimation, opt. Key as CFStringRef = ""): Adds a AppleCAAnimation to the layer. Using the optional Key, you can assing it a custom identifier – only one animation per Identifier is allowed, which means a new animation with thesame identifier overrides a further value. Not yet implemented: You can also use the shared properties AnimationOrderIn or AnimationOrderOut to make the animation appear when the layer is switched from hidden to visible or when the layer is removed from the view. The Key AnimationTransition is set automatically to key for transition animations.

AddSubLayer (ALayer As AppleCALAyer): Adds a layer to the SubLayers property array.

Animation (aKey As CFStringRef) As AppleCAAnimation: Returns the animation object registered under Key for this layer.

AnimationKeyStrings() As Text(): An array of the animation key names attached to the layer. Convenience shortcut for the AnimationKeys Array.

Invalidate(): Marks the layer for redraw.

InsertSublayer(NewLayer as AppleCALayer, Position as LayerOrderingMode): Inserts NewLayer below or above OldLayer the current layer replaces it (position = Replace).
InsertSubLayer (NewLayer As AppleCALAyer, Index As UInt32): Inserts NewLayer at position index into the SubLayers Array.

LayoutIfNeeded(): The equivalent to a Xojo invalidate call on the layer.

LayoutSublayers(): Invalidates all sublayers too.

RemoveAllAnimations(): Removes all AppleCAAnimations from the layer.

RemoveAnimation (Key As CFString): Removes the AppleCAAnimation registered under key. see AddAnimation.

RemoveFromSuperlayer(): Removes the layer and its sublayers from its SuperLayer and sets its SuperLayer property to NIL.