Overview
HandleEvents calls [NSApp run] to start the app and monitor events via the Objective-C/Cocoa runtime.
Once the Cocoa runtime/event monitoring is initiated, HandleEvents ends (but the runloop it initiated continues on!);
the runloop (i.e. Cocoa runtime) now traps all your app's events invisibly and sends them to your app for consideration.
Where to put it and how often to execute it
HandleEvents should execute only ONCE at app startup - acceptable positions for statement placement are:
In a project put it in the '.main' source file (make a new project file in FB to see an example)
In a single source file put it last in the file but make sure it executes if background tasks are used
With the HandleEvents call positioned as the last line, it's possible for lots of code to execute before the runtime is ready to process it. This can result in apps clocking and going unresponsive. Too much unresponsive behavior will result in macOS terminating the app.
This can happen if earlier code executes long-running tasks either on the main thread or a background thread
If a long-running task is planned, the on appevent vectors allow HandleEvents to execute before those tasks are started. See below:
That's it, you're done! Intercepting the events your app needs is a different coding effort and not specific to coding the HandleEvents statement.
For event interception look at the "See also"links below and Appendix N: Events.