handlesExternalEvents
Specifies the external events that the view's scene handles if the scene is already open.
Declaration
compose().handlesExternalEvents({
preferring: string[],
allowing: string[],
})nonisolated func handlesExternalEvents(
preferring: Set<String>,
allowing: Set<String>
) -> some ViewParameters
options.preferring*string[]A set of strings that SwiftUI compares against the incoming user activity or URL to see if the view's scene prefers to handle the external event.
options.allowing*string[]A set of strings that SwiftUI compares against the incoming user activity or URL to see if the view's scene can handle the exernal event.
Return value
A view whose enclosing scene --- if already open --- handles incoming external events.
Discussion
Apply this modifier to a view to indicate whether an open scene that contains the view handles specified user activities or URLs that your app receives. Specify two sets of string identifiers to distinguish between the kinds of events that the scene prefers to handle and those that it can handle. You can dynamically update the identifiers in each set to reflect changing app state.
When your app receives an event on a platform that supports multiple simultaneous scenes, SwiftUI sends the event to the first open scene it finds that prefers to handle the event. Otherwise, it sends the event to the first open scene it finds that can handle the event. If it finds neither --- including when you don't add this view modifier --- SwiftUI creates a new scene for the event.
On platforms that support only a single scene, SwiftUI ignores this modifier and sends all external events to the one open scene.
Matching an event
To find an open scene that handles a particular external event, SwiftUI
compares a property of the event against the strings that you specify
in the preferring and allowing sets. SwiftUI examines the
following event properties to perform the comparison:
- For an
doc://com.apple.documentation/documentation/Foundation/NSUserActivity,
like when your app handles Handoff, SwiftUI uses the activity's
doc://com.apple.documentation/documentation/Foundation/NSUserActivity/targetContentIdentifier
property, or if that's
nil, its doc://com.apple.documentation/documentation/Foundation/NSUserActivity/webpageURL property rendered as an doc://com.apple.documentation/documentation/Foundation/URL/absoluteString. - For a doc://com.apple.documentation/documentation/Foundation/URL, like when another process opens a URL that your app handles, SwiftUI uses the URL's doc://com.apple.documentation/documentation/Foundation/URL/absoluteString.
For both parameter sets, an empty set of strings never matches.
Similarly, empty strings never match. Conversely, as a special case,
the string that contains only an asterisk (*) matches anything.
The modifier performs string comparisons that are case and
diacritic insensitive.
If you specify multiple instances of this view modifier inside a single
scene, the scene uses the union of the respective preferring and
allowing sets from all the modifiers.
Handling a user activity in an open scene
As an example, the following view --- which participates in Handoff
through the View.userActivity(_:isActive:_:) and
View.onContinueUserActivity(_:perform:) methods --- updates its
preferring set according to the current selection. The enclosing
scene prefers to handle an event for a contact that's already selected,
but doesn't volunteer itself as a preferred scene when no contact is
selected:
private struct ContactList: View {
var store: ContactStore
@State private var selectedContact: UUID?
var body: some View {
NavigationSplitView {
List(store.contacts, selection: $selectedContact) { contact in
NavigationLink(contact.name) {
Text(contact.name)
}
}
} detail: {
Text("Select a contact")
}
.handlesExternalEvents(
preferring: selectedContact == nil
? []
: [selectedContact!.uuidString],
allowing: selectedContact == nil
? ["*"]
: []
)
.onContinueUserActivity(Contact.userActivityType) { activity in
if let identifier = activity.targetContentIdentifier {
selectedContact = UUID(uuidString: identifier)
}
}
.userActivity(
Contact.userActivityType,
isActive: selectedContact != nil
) { activity in
activity.title = "Contact"
activity.targetContentIdentifier = selectedContact?.uuidString
activity.isEligibleForHandoff = true
}
}
}The above code also updates the allowing set to indicate that the
scene can handle any incoming event when there's no current selection,
but that it can't handle any event if the view already displays a
contact. The preferring set takes precedence in the special case
where the incoming event exactly matches the currently selected contact.
See also
More in Input and interaction.
- allowsHitTestingConfigures whether this view participates in hit test operations.
- allowsWindowActivationEventsConfigures whether gestures in this view hierarchy can handle events that activate the containing window.
- buttonRepeatBehaviorSets whether buttons in this view should repeatedly trigger their actions on prolonged interactions.
- disabledAdds a condition that controls whether someone can interact with this view.
- helpAdds help text to a view using a localized string resource that you provide.
- invalidatableContentMark the receiver as their content might be invalidated.
- keyboardShortcutAssigns a keyboard shortcut to the modified control.
- scrollClipDisabledSets whether a scroll view clips its content to its bounds.
- scrollDisabledDisables or enables scrolling in scrollable views.
- scrollDismissesKeyboardConfigures the behavior in which scrollable content interacts with the software keyboard.
- sensoryFeedbackPlays the specified feedback when the provided trigger value changes.
- userActivityAdvertises a user activity type.