<!--
{
  "availability" : [
    "macOS: -"
  ],
  "documentType" : "symbol",
  "framework" : "AppKit",
  "identifier" : "/documentation/AppKit/NSApplication/nextEvent(matching:until:inMode:dequeue:)",
  "metadataVersion" : "0.1.0",
  "role" : "Instance Method",
  "symbol" : {
    "kind" : "Instance Method",
    "modules" : [
      "AppKit"
    ],
    "preciseIdentifier" : "c:objc(cs)NSApplication(im)nextEventMatchingMask:untilDate:inMode:dequeue:"
  },
  "title" : "nextEvent(matching:until:inMode:dequeue:)"
}
-->

# nextEvent(matching:until:inMode:dequeue:)

Returns the next event matching a given mask, or `nil` if no such event is found before a specified expiration date.

```
func nextEvent(matching mask: NSEvent.EventTypeMask, until expiration: Date?, inMode mode: RunLoop.Mode, dequeue deqFlag: Bool) -> NSEvent?
```

## Parameters

`mask`

Contains one or more flags indicating the types of events to return. The constants section of the [`NSEvent`](/documentation/AppKit/NSEvent) class defines the constants you can add together to create this mask. The [`discardEvents(matching:before:)`](/documentation/AppKit/NSApplication/discardEvents(matching:before:)) method also lists several of these constants.

`expiration`

The expiration date for the current event request. Specifying nil for this parameter is equivalent to returning a date object using the <doc://com.apple.documentation/documentation/Foundation/NSDate/distantPast> method.

`mode`

The run loop mode in which to run while looking for events. The mode you specify also determines which timers and run-loop observers may fire while the app waits for the event.

`deqFlag`

Specify <doc://com.apple.documentation/documentation/Swift/true> if you want the event removed from the queue.

## Return Value

The event object whose type matches one of the event types specified by the `mask` parameter.

## Discussion

You can use this method to short circuit normal event dispatching and get your own events. For example, you may want to do this in response to a mouse-down event in order to track the mouse while its button is down. (In such an example, you’d pass the appropriate event types for mouse-dragged and mouse-up events to the `mask` parameter and specify the `NSEventTrackingRunLoopMode` run loop mode). Events that don’t match one of the specified event types are left in the queue.

You can specify one of the run loop modes defined by AppKit or a custom run loop mode used specifically by your app. AppKit defines the following run-loop modes:

- `NSDefaultRunLoopMode`
- `NSEventTrackingRunLoopMode`
- `NSModalPanelRunLoopMode`
- `NSConnectionReplyMode`

## See Also

[`runModal(for:)`](/documentation/AppKit/NSApplication/runModal(for:))

Starts a modal event loop for the specified window.


---

Copyright &copy; 2026 Apple Inc. All rights reserved. | [Terms of Use](https://www.apple.com/legal/internet-services/terms/site.html) | [Privacy Policy](https://www.apple.com/privacy/privacy-policy)