<!--
{
  "availability" : [
    "macOS: 10.6.0 -"
  ],
  "documentType" : "symbol",
  "framework" : "AppKit",
  "identifier" : "/documentation/AppKit/NSEvent/addLocalMonitorForEvents(matching:handler:)",
  "metadataVersion" : "0.1.0",
  "role" : "Type Method",
  "symbol" : {
    "kind" : "Type Method",
    "modules" : [
      "AppKit"
    ],
    "preciseIdentifier" : "c:objc(cs)NSEvent(cm)addLocalMonitorForEventsMatchingMask:handler:"
  },
  "title" : "addLocalMonitorForEvents(matching:handler:)"
}
-->

# addLocalMonitorForEvents(matching:handler:)

Installs an event monitor that receives copies of events the system posts to this app prior to their dispatch.

```
class func addLocalMonitorForEvents(matching mask: NSEvent.EventTypeMask, handler block: @escaping (NSEvent) -> NSEvent?) -> Any?
```

## Parameters

`mask`

An event mask specifying which events you wish to monitor. See [`NSEvent.EventTypeMask`](/documentation/AppKit/NSEvent/EventTypeMask) for possible values.

`block`

The event handler block object. It is passed the event to monitor. You can return the event unmodified, create and return a new NSEvent object, or return nil to stop the dispatching of the event.

## Return Value

An event handler object.

## Discussion

Your handler will not be called for events that are consumed by nested event-tracking loops such as control tracking, menu tracking, or window dragging; only events that are dispatched through the applications [`sendEvent(_:)`](/documentation/AppKit/NSApplication/sendEvent(_:)) method will be passed to your handler.

> Note:
> The monitor Block is called for all future events that match `mask`. You must call ``doc://com.apple.appkit/documentation/AppKit/NSEvent/removeMonitor(_:)`` to stop the monitor.

### Special Considerations

In OS X v 10.6, event monitors are only able to monitor the following event types:

- [`NSFlagsChanged`](/documentation/AppKit/NSFlagsChanged)
- [`NSLeftMouseDragged`](/documentation/AppKit/NSLeftMouseDragged)
- [`NSRightMouseDragged`](/documentation/AppKit/NSRightMouseDragged)
- [`NSOtherMouseDragged`](/documentation/AppKit/NSOtherMouseDragged)
- [`NSLeftMouseUp`](/documentation/AppKit/NSLeftMouseUp)
- [`NSRightMouseUp`](/documentation/AppKit/NSRightMouseUp)
- [`NSOtherMouseUp`](/documentation/AppKit/NSOtherMouseUp)
- [`NSLeftMouseDown`](/documentation/AppKit/NSLeftMouseDown)
- [`NSRightMouseDown`](/documentation/AppKit/NSRightMouseDown)
- [`NSOtherMouseDown`](/documentation/AppKit/NSOtherMouseDown)
- [`NSMouseMoved`](/documentation/AppKit/NSMouseMoved)
- [`NSFlagsChanged`](/documentation/AppKit/NSFlagsChanged)
- [`NSScrollWheel`](/documentation/AppKit/NSScrollWheel)
- [`NSTabletPoint`](/documentation/AppKit/NSTabletPoint)
- [`NSTabletProximity`](/documentation/AppKit/NSTabletProximity)
- [`NSKeyDown`](/documentation/AppKit/NSKeyDown) (Key repeats are determined using the [`isARepeat`](/documentation/AppKit/NSEvent/isARepeat) property.)

---

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)