EnlightenIris

@objc
open class EnlightenIris : NSObject

A class that encapsulates the behavior of the spotlight for a particular view.

Static Public Stored Properties

popoverMaxWidth
The default popover maximum width.
Declaration
Swift

public static var popoverMaxWidth: CGFloat

Public Type Aliases

MarkdownFilename
A CommonMark Markdown filename.
Declaration
Swift

public typealias MarkdownFilename = String


                    
                    
                    ProfileSpotDrawingHandler

A closure that draws the contents of view that should be masked for the focused profile spot.

Because the closure is not called until needed, it is executed on the same thread on which the image itself is drawn, which can be any thread of your app. Therefore, the closure must be safe to call from any thread.

Declaration

Swift

public typealias ProfileSpotDrawingHandler = (_ drawingRect: NSRect, _ cgContext: CGContext) -> Void

Parameters

`drawingRect`	The destination rectangle in which to draw. The rectangle passed in is the `bounds` of `view`. The coordinates of this rectangle are specified in points.
`cgContext`	The graphics context to use to draw.


                    
                    
                    AnimationHandler

A closure containing animations for a transaction group.

Declaration

Swift

public typealias AnimationHandler = (_ animationContext: NSAnimationContext) -> Void

Parameters


                                animationContext

The thread’s current NSAnimationContext to configure properties of the animation.

Public Stored Properties

doesWaitForFocusAnimationCompletion
Whether the spotlight controller disables navigation until the focus animation finishes.

This property has a default value of false.

Note
This property should only be true if the animation will take longer than the spotlight controller’s EnlightenSpotlightController.profileSpotFocusDuration instance property.
Declaration
Swift

public var doesWaitForFocusAnimationCompletion: Bool
view
The view of the iris.
Declaration
Swift

public unowned var view: NSView
stages
The iris’ stages, individually rendered in the popover.
Declaration
Swift

public var stages: [EnlightenIrisStage]
popoverMaxWidth
The popover width.

A non-nil value overrides the default EnlightenIris.popoverMaxWidth.
Declaration
Swift

public var popoverMaxWidth: CGFloat?
preferredPopoverEdge
The edge of view the popover should prefer to be anchored to.

When nil, a heuristic is used to determine the best anchor edge for the view based on its location in the window.
Declaration
Swift

public var preferredPopoverEdge: NSRectEdge?
doesCenterAlignContent
Whether the Markdown content should be center aligned.

This property has a default value of false.
Declaration
Swift

public var doesCenterAlignContent: Bool
profileSpotDrawingHandler
A closure for drawing a custom profile spot mask.

By default, the view‘s layer is used to create the image mask; however, in certain situations where the view is transparent, this may not be wanted (e.g. radio buttons).

See ProfileSpotDrawingHandler for more information.
Declaration
Swift

public var profileSpotDrawingHandler: EnlightenIris.ProfileSpotDrawingHandler?
focusAnimationGroup
A closure containing a group of animations to execute upon focusing on view.

The closure is called regardless of the controller’s configuration.
Declaration
Swift

public var focusAnimationGroup: EnlightenIris.AnimationHandler?
unfocusAnimationGroup
A closure containing a group of animations to execute upon unfocusing view.

The closure is called regardless of the controller’s configuration.
Declaration
Swift

public var unfocusAnimationGroup: EnlightenIris.AnimationHandler?

Initializers


                    
                    
                    init(view:stages:popoverMaxWidth:)

Initializes a new iris from the provided stages.

Important

Errors thrown during the loading of the Markdown strings are passed to the spotlight controller’s delegate’s EnlightenSpotlightControllerDelegate.spotlightControllerFailedToLoad(markdownString:for:with:) method.

Note

If using this initializer directly, the iris must still be added to the controller.

Declaration

Swift

public init(view: NSView,
            stages: [EnlightenIrisStage],
            popoverMaxWidth: CGFloat? = nil)

Parameters

`view`	The view to spotlight for the stages of this iris.
`stages`	The stages of this iris.
`popoverMaxWidth`	The popover’s maximum width. A non-nil value overrides the default `EnlightenIris.popoverMaxWidth`.


                    
                    
                    init(view:stage:popoverMaxWidth:)

Initializes a new iris from the provided stage.

Important

Note

If using this initializer directly, the iris must still be added to the controller.

Declaration

Swift

public convenience init(view: NSView,
                        stage: EnlightenIrisStage,
                        popoverMaxWidth: CGFloat? = nil)

Parameters

`view`	The view to spotlight for the stages of this iris.
`stage`	The stage of this iris.
`popoverMaxWidth`	The popover’s maximum width. A non-nil value overrides the default `EnlightenIris.popoverMaxWidth`.


                    
                    
                    init(view:markdownStrings:popoverMaxWidth:)

Initializes a new iris from CommonMark Markdown strings.

Important

Note

If using this initializer directly, the iris must still be added to the controller.

Declaration

Swift

public convenience init(view: NSView,
                        markdownStrings: [String],
                        popoverMaxWidth: CGFloat? = nil)

Parameters

`view`	The view to spotlight for the stages of this iris.
`markdownStrings`	The CommonMark Markdown strings displayed as individual stages.
`popoverMaxWidth`	The popover’s maximum width. A non-nil value overrides the default `EnlightenIris.popoverMaxWidth`.


                    
                    
                    init(view:markdownString:popoverMaxWidth:)

Initializes a new iris from a CommonMark Markdown string.

Important

Errors thrown during the loading of the Markdown string are passed to the spotlight controller’s delegate’s EnlightenSpotlightControllerDelegate.spotlightControllerFailedToLoad(markdownString:for:with:) method.

Note

If using this initializer directly, the iris must still be added to the controller.

Declaration

Swift

public convenience init(view: NSView, markdownString: String, popoverMaxWidth: CGFloat? = nil)

Parameters

`view`	The view to spotlight for the stages of this iris.
`markdownString`	The CommonMark Markdown string displayed.
`popoverMaxWidth`	The popover’s maximum width. A non-nil value overrides the default `EnlightenIris.popoverMaxWidth`.


                    
                    
                    init(view:markdownFilenames:in:popoverMaxWidth:)

Initializes a new iris from CommonMark Markdown files.

Important

Warning

Asserts the existence of the Markdown files in ‘Debug’ builds, while failing silently in ‘Release’ builds (by returning an empty string).

Note

If using this initializer directly, the iris must still be added to the controller.

Throws

Throws an error if the contents of a file in markdownFilenames cannot be read.

Declaration

Swift

public convenience init(view: NSView,
                        markdownFilenames: [MarkdownFilename],
                        in bundle: Bundle,
                        popoverMaxWidth: CGFloat? = nil) throws

Parameters

`view`	The view to spotlight for the stages of this iris.
`markdownFilenames`	The names of the CommonMark Markdown files in the provided bundle that will be displayed as individual stages.
`bundle`	The bundle that contains the Markdown files in `markdownFilenames`.
`popoverMaxWidth`	The popover’s maximum width. A non-nil value overrides the default `EnlightenIris.popoverMaxWidth`.


                    
                    
                    init(view:markdownFilename:in:popoverMaxWidth:)

Initializes a new iris from a CommonMark Markdown file.

Important

Warning

Asserts the existence of the Markdown file in ‘Debug’ builds, while failing silently in ‘Release’ builds (by returning an empty string).

Note

If using this initializer directly, the iris must still be added to the controller.

Throws

Throws an error if the contents of the file markdownFilename cannot be read.

Declaration

Swift

public convenience init(view: NSView,
                        markdownFilename: MarkdownFilename,
                        in bundle: Bundle,
                        popoverMaxWidth: CGFloat? = nil) throws

Parameters

`view`	The view to spotlight for the stages of this iris.
`markdownFilename`	The name of the CommonMark Markdown file in the provided bundle that will be displayed.
`bundle`	The bundle that contains the Markdown file named `markdownFilename`.
`popoverMaxWidth`	The popover’s maximum width. A non-nil value overrides the default `EnlightenIris.popoverMaxWidth`.

Public Configuration Methods


                    
                    
                    addAdditional(stages:)

Adds additional stages to the iris.

Important

Declaration

Swift

public func addAdditional(stages: [EnlightenIrisStage])

Parameters


                                stages

The stages to add.


                    
                    
                    addAdditional(stage:)

Adds an additional stage to the iris.

Important

Declaration

Swift

public func addAdditional(stage: EnlightenIrisStage)

Parameters


                                stage

The stage to add.


                    
                    
                    addAdditionalStages(using:)

Adds additional stages for CommonMark Markdown strings to the iris.

Important

Declaration

Swift

public func addAdditionalStages(using markdownStrings: [String])

Parameters


                                markdownStrings

The Markdown strings to render in the popover as additional individual stages.


                    
                    
                    addAdditionalStage(using:)

Adds an additional stage for a CommonMark Markdown string to the iris.

Important

Declaration

Swift

public func addAdditionalStage(using markdownString: String)

Parameters


                                markdownString

The Markdown string to render in the popover.


                    
                    
                    addAdditionalStages(from:in:)

Adds additional stages from the contents of CommonMark Markdown files to the iris.

Important

Warning

Asserts the existence of the Markdown files in ‘Debug’ builds, while failing silently in ‘Release’ builds (by returning an empty string).

Throws

Throws an error if the contents of a file in markdownFilenames cannot be read.

Declaration

Swift

public func addAdditionalStages(from markdownFilenames: [MarkdownFilename], in bundle: Bundle) throws

Parameters

`markdownFilename`	The names of the CommonMark Markdown files in the provided bundle to add as additional individual stages.
`bundle`	The bundle that contains the files in `markdownFilenames`.


                    
                    
                    addAdditionalStage(from:in:)

Adds an additional stage from the contents of a CommonMark Markdown file to the iris.

Important

Warning

Asserts the existence of the Markdown file in ‘Debug’ builds, while failing silently in ‘Release’ builds (by returning an empty string).

Throws

Throws an error if the contents of the file markdownFilename cannot be read.

Declaration

Swift

public func addAdditionalStage(from markdownFilename: MarkdownFilename, in bundle: Bundle) throws

Parameters

`markdownFilename`	The name of the CommonMark Markdown file in the provided bundle to add.
`bundle`	The bundle that contains the file named `markdownFilename`.

Stage Retrieval Methods


                    
                    
                    stage(index:)

Returns the stage for a one-based stage index.

Note

The stage indices are one-based (e.g. the first stage’s index is 1).

Declaration

Swift

func stage(index: Int) -> EnlightenIrisStage?

Parameters


                                index

The one-based stage index to retrieve.

Return Value

Returns the stage for index.