What is the order of NSWindow levels?

If two windows on your macOS desktop overlap, which one gets shown? Sometimes, the user can decide: by clicking on a window, it comes to the front. But windows also have a “level” property, which overrides this user-defined ordering. The _level property of an NSWindow is an integer, and if one window has a higher _level than another, it’s always shown in front.

You can set this raw _level property of an NSWindow like this:

window.level = NSWindow.Level(rawValue: 9)

However, Apple doesn’t recommend using raw integers like this. They prefer that you use their semantic names for different levels. Annoyingly, Apple have two parallel lists of semantic levels: NSWindow.Level and CGWindowLevelKey. Here’s how you use NSWindow.Level:

let window:NSWindow = NSWindow(/* ... */)
window.level = NSWindow.Level.tornOffMenu

And here’s how you use CGWindowLevelKey:

window.level = NSWindow.Level(rawValue: Int(CGWindowLevelForKey(CGWindowLevelKey.tornOffMenuWindow)))

Both lists of semantic names are poorly documented. Most annoyingly, the Apple documentation does not say what the values are for these semantic levels, and does not even say what their relative ordering is. Even more deceivingly, the ordering of the levels listed in the documentation is not the numeric order of the levels!

However, we can find the raw levels by debugging, and they turn out to be as follows, in correct numerical order:

CGWindowLevelForKey(.baseWindow) = -2147483648
CGWindowLevelForKey(.desktopIconWindow) = -2147483603
CGWindowLevelForKey(.minimumWindow) = -2147483643
CGWindowLevelForKey(.desktopWindow) = -2147483623
CGWindowLevelForKey(.backstopMenu) = -20
NSWindow.Level.normal = CGWindowLevelForKey(.normalWindow) = 0
NSWindow.Level.floating = CGWindowLevelForKey(.floatingWindow) = 3
NSWindow.Level.submenu = 3
NSWindow.Level.tornOffMenu = CGWindowLevelForKey(.tornOffMenuWindow) = 3
NSWindow.Level.modalPanel = CGWindowLevelForKey(.modalPanelWindow) = 8
CGWindowLevelForKey(.utilityWindow) = 19
NSWindow.Level.dock = CGWindowLevelForKey(.dockWindow) = 20
NSWindow.Level.mainMenu  = CGWindowLevelForKey(.mainMenuWindow) = 24
NSWindow.Level.statusBar = CGWindowLevelForKey(.statusWindow) = 25
NSWindow.Level.popUpMenu = CGWindowLevelForKey(.popUpMenuWindow) = 101
NSWindow.Level.screenSaver = 101
CGWindowLevelForKey(.overlayWindow) = 102
CGWindowLevelForKey(.helpWindow) = 200
CGWindowLevelForKey(.draggingWindow) = 500
CGWindowLevelForKey(.screenSaverWindow) = 1000
CGWindowLevelForKey(.assistiveTechHighWindow) = 1500
CGWindowLevelForKey(.cursorWindow) = 2147483630
CGWindowLevelForKey(.maximumWindow) = 2147483631

Note some oddities here:

Tagged #programming, #macos.

Similar posts

More by Jim

👋 I'm Jim, a full-stack product engineer. Want to build an amazing product and a profitable business? Read more about me or Get in touch!

This page copyright James Fisher 2020. Content is not associated with my employer. Found an error? Edit this page.