SwiftEntryKit Documentation

SwiftEntryKit is a versatile content presenter for iOS written in Swift. It allows you to display 'Entries' (banners, pop-ups, toasts, etc.) inside a separate UIWindow (of type EKWindow). This design enables users to continue navigating your app freely while entries are displayed in a non-intrusive manner.

Key capabilities include:

• Positioning: Top, center, or bottom of the screen.
• Styling: Borders, drop-shadows, rounded corners, and various background styles (blur, dim, color, or gradient).
• Customization: Highly configurable transition animations, user interaction interception, and lifecycle event injection.
• Precedence: Support for enqueuing entries or overriding previous ones using precedence and display priority attributes.

To display a view or view controller, create your view and initialize an EKAttributes struct to describe its appearance and behavior. Then, call SwiftEntryKit.display(entry:using:).

Note: The kit replaces the application's main window with an EKWindow instance to display the entry.

To integrate SwiftEntryKit using Carthage, add the following line to your Cartfile:

github "huri000/SwiftEntryKit" == 2.0.0

Ensure you have Carthage installed via Homebrew before running the build command.

Accio is a dependency manager driven by SwiftPM. To use SwiftEntryKit with Accio, add it to your Package.swift manifest:

.package(url: "https://github.com/huri000/SwiftEntryKit", .exact("2.0.0"))

After specifying the dependency, run accio install.

To integrate SwiftEntryKit into your Xcode project using CocoaPods, add the following to your Podfile:

source 'https://github.com/cocoapods/specs.git'
platform :ios, '9.0'
use_frameworks!

pod 'SwiftEntryKit', '2.0.0'

Then, execute pod install in your terminal.

SwiftEntryKit provides pre-configured presets like topFloat and topToast. To use a preset:

1. Create EKAttributes using a preset (e.g., EKAttributes.topFloat).
2. Create the content (e.g., EKNotificationMessage).
3. Create the view (e.g., EKNotificationMessageView) and inject the content.
4. Display using SwiftEntryKit.display(entry:using:).

SwiftEntryKit handles multiple simultaneous entries using precedence and display priority.

Precedence Types

• Override: If the new entry's priority is $\ge$ the current entry, it replaces it. Use attributes.precedence = .override(priority: .max, dropEnqueuedEntries: false).
  • dropEnqueuedEntries: true: Flushes the existing queue.
  • dropEnqueuedEntries: false: Keeps enqueued entries to show after the new one is dismissed.
• Enqueue: Adds the entry to a queue. Use attributes.precedence = .enqueue(priority: .normal).

Queueing Heuristics

You can set how the queue is sorted globally (run once before displaying entries):

• .priority: Sorted by display priority, then chronologically.
• .chronological: Standard FIFO queue.

EKAttributes.Precedence.QueueingHeuristic.value = .priority

Use SwiftEntryKit.dismiss() to remove entries. You can specify which entries to dismiss using the following options:

• .displayed: Dismiss the currently visible entry.
• .all: Dismiss the current entry and flush the entire queue.
• .queue: Only flush the queue, leaving the current entry to finish its lifecycle.
• .specific(entryName: "Name"): Dismiss all entries (displayed or enqueued) with a matching name.
• .prioritizedLowerOrEqualTo(priority: .normal): Dismiss any entry with priority $\le$ the specified level.

You can also provide a completion handler to execute code after dismissal.

Use positionConstraints to define the entry's size and relationship to the screen.

Size Constraints

• Width/Height: Use .ratio(value:) for screen ratios or .intrinsic to follow the view's content height/width.
• Example: attributes.positionConstraints.size = .init(width: .ratio(value: 0.9), height: .intrinsic)
• Max Size: Use attributes.positionConstraints.maxSize to prevent entries from growing too large during orientation changes.

Safe Area and Offsets

• Safe Area: Use .empty(fillSafeArea: false) to keep safe area insets outside the entry.
• Vertical Offset: Apply an additional offset via attributes.positionConstraints.verticalOffset.
• Keyboard Relation: Bind the entry to the keyboard using .bind(offset:) to ensure it stays visible when the keyboard appears.

The EKAttributes struct is the primary descriptor for an entry. Use it to define:

• Identification: Set name (String?) to refer to specific entries later.
• Display: Set windowLevel (e.g., .normal, .statusBar), position (.top, .center, .bottom), and displayDuration (seconds or .infinity).
• Precedence: Manage multiple entries using .override(priority:dropEnqueuedEntries:) or .enqueue(priority:).
• Theme & Style: Configure displayMode (.light, .dark, .inferred), entryBackground, screenBackground, shadow, roundCorners, border, and statusBar appearance.
• Animations: Define entranceAnimation, exitAnimation, and popBehavior (how an entry behaves when overridden by a higher priority entry).
• Lifecycle: Inject closures into lifecycleEvents (willAppear, didAppear, willDisappear, didDisappear).

User Interaction

Control how the entry and screen respond to touches:

• Entry Interaction: .dismiss (tap to dismiss), .delayExit(by: seconds), or .absorbTouches (swallow taps).
• Screen Interaction: .dismiss (tap screen to dismiss) or .forward (pass taps to the underlying window).
• Custom Actions: Append closures to attributes.entryInteraction.customTapActions.

Scroll Behavior

Enable swipe-to-dismiss gestures with rubber-banding effects:

• .disabled: Disables pan/swipe.
• .enabled(swipeable: true, pullbackAnimation: .jolt): Swipe with a jolt effect.
• .enabled(swipeable: true, pullbackAnimation: .easeOut): Swipe with an ease-out effect.
• .edgeCrossingDisabled(swipeable: true): Enables swipe but disables the stretch effect.

Use these methods to query the current state of the kit:

• SwiftEntryKit.isCurrentlyDisplaying: Returns true if any entry is visible.
• SwiftEntryKit.isCurrentlyDisplaying(entryNamed: "Name"): Returns true if a specific named entry is visible.
• SwiftEntryKit.isQueueEmpty: Returns true if no entries are waiting in the queue.
• SwiftEntryKit.queueContains(entryNamed: "Name"): Returns true if a specific named entry is in the queue.