u32), to fix the problem whereby windows don't reappear and don't appear
on top on startup.
The window restoration feature in Mac OS X from Lion onward prevents
windows from appearing until restoration is complete and the app is
launched. Internally, the persistent UI restorer detects the app launch
by listening to the Carbon event `kAEOpenApplication`, which, as an
Apple event, has the event class `kEventClassAppleEvent`.
Like `-[NSApplication run]` does, Glutin uses the method
`-[NSApplication nextEventMatchingMask:untilDate:inMode:dequeue:]` to
pump the application event loop. The event mask provided is an
`NSEventMask`; events that do not match this mask are filtered out. When
pumping the Carbon event loop, the Cocoa framework internally converts
this `NSEventMask` to a Carbon event mask. The logic to perform this
conversion proceeds in two steps:
1. If the provided `NSEventMask` is exactly equal to `NSAnyEventMask`,
then the rest of the logic is skipped and the resulting Carbon event
mask is a null mask--i.e. a mask that matches all events.
2. Otherwise, the framework constructs a blank Carbon mask--that is, a
mask that matches no events at all. The various bits of the
`NSEventMask` are examined, translated to their Carbon equivalents, and
added to the mask. Then that Carbon mask is returned.
In Glutin prior to this patch, our definition of `NSAnyEventMask` was a
mask that effectively matched all events but was not equal to the real
`NSAnyEventMask` that, for example, `-[NSApplication run]` supplies to
`-[NSApplication nextEventMatchingMask:untilDate:inMode:dequeue:]`. This
means that our code causes the system to take path (2) above, whereas
standard Cocoa apps take path (1). Now it might seem that these paths
are equivalent, but in fact they are very different. This is because
*there are classes of Carbon events that do not correspond to Cocoa
events selectable via `NSEventMask`*. One of these Carbon-only event
types is Apple events.
This fact is what made Glutin apps prior to this patch go wrong. The
Carbon framework would deliver the `kAEOpenApplication` event to the
application, but it was always masked out and ignored because the
`NSEventMask` we supplied to `-[NSApplication
nextEventMatchingMask:untilDate:inMode:dequeue:]` did not translate to a
Carbon event mask that included Apple events. This, in turn, caused the
persistent UI restorer to never notice that the app finished launching.
Thus the flag that inhibited windows from appearing would never be
cleared, and all windows would end up invisible.
This patch fixes the issue by lengthening `NSAnyEventMask` to its true
64-bit value, allowing the expected Carbon event filter to be used
during app startup and enabling the app startup event to be handled
properly.
Added ability to call [[NSRunningApplication currentApplication]
activateWithOptions: NSApplicationActivateIgnoringOtherApps]
which is used in the example to fix the missing menu bar when
the example app starts.
Oluseyi Sonaiya
