PathState

public final class PathState : NSObject, @unchecked Sendable

This state object is used in conjunction with PathMotion to handle the movement of a point along a path.

  • A point representing the current location along the path during an animation.

    Declaration

    Swift

    public private(set) var currentPoint: CGPoint { get }

  • The percentage complete of the animation along the path. This property is used by the containing PathMotion instance to drive the path animation, and should not be modified directly. Values range from 0.0 to 1.0.

    Declaration

    Swift

    @objc
public var percentageComplete: Double

  • Returns the length of the path.

    Declaration

    Swift

    public var length: CGFloat

  • An array containing pre-calculated points on the path that are used to animate along it, allowing large performance gains compared to looking up points on the path in real-time.

    Declaration

    Swift

    public private(set) var lookupTable: [CGPoint] { get }

  • This value is multiplied by the length of the path to determine how many points are generated in the lookup table. The default value is 2, which gives double the number of points for the path’s length and avoids jitter in most cases.

    Note

    In large paths increasing this number can have significant increases in the lookup table generation time. For animating visual properties, the default value should be enough in most cases.

    Declaration

    Swift

    public var lookupTablePrecision: Int

  • An array of models representing the segments of the path.

    Declaration

    Swift

    public private(set) var pathElements: [PathElement] { get }

  • The CGPath instance to animate along.

    Declaration

    Swift

    public private(set) var path: CGPath { get }

  • An initializer.

    Declaration

    Swift

    public init(path: CGPath, curveLengthGenerationSteps: Int? = nil)

    Parameters

    path

    The path to animate along.
    curveLengthGenerationSteps

    Determines the number of steps used in determining the lengths of curves. The default value of 50 is fine in most cases; higher values can marginally increase accuracy, at the cost of performance.

  • Moves the animation point to a place on the path specified by the percentage value.

    Declaration

    Swift

    public func movePoint(to percentage: Double, startEdge: Double? = nil, endEdge: Double? = nil)

    Parameters

    percentage

    A percentage value from 0.0 to 1.0 which represents a position on the path.

  • Returns a point on the lookup table corresponding to a current percentage along the path.

    Declaration

    Swift

    public func lookupPoint(at percentage: Double) -> CGPoint?

    Parameters

    percentage

    A value representing a current placement along the path. This normal value range is 0.0 to 1.0, but may overshoot in either direction.

    Return Value

    A point in the lookup table corresponding to the specified path location, if one was found.

  • Sets up performance mode, generating an internal lookup table for faster position calculations. To use the performance mode, this method must be used before calling start() on the associated motion class.

    Note

    With large paths, the lookup table generation could take a second or longer to complete. Be aware that the lookup table generation runs synchronously on another dispatch queue, blocking the return of this async call until the generation has completed. Be sure to call this method as early as possible to give the operation time to complete before your motion needs to begin.

    Declaration

    Swift

    public func setupPerformanceMode(lookupCapacity: Int? = nil) async

    Parameters

    lookupCapacity

    An optional capacity that caps the maximum lookup table amount.

  • Returns a point on the path, given a percentage representing the length of the path from 0.0 to 1.0.

    Declaration

    Swift

    public func point(at percent: CGFloat) -> CGPoint?

    Parameters

    percent

    The percentage along the path from 0.0 to 1.0. Values provided outside of that range will return without a point.

    Return Value

    A point along the path, if one was found.

  • Calculates the length of the path based on the provided path elements.

    Declaration

    Swift

    func calculateLength(with elements: [PathElement]) -> CGFloat

    Parameters

    elements

    Path elements used to calculate the total path length.

    Return Value

    The length of the path.