Learn more about Russian war crimes in Ukraine.

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:

What can computers do? What are the limits of mathematics? And just how busy can a busy beaver be? This year, I’m writing Busy Beavers, a unique interactive book on computability theory. You and I will take a practical and modern approach to answering these questions — or at least learning why some questions are unanswerable!

It’s only $19, and you can get 50% off if you find the discount code ... Not quite. Hackers use the console!

After months of secret toil, I and Andrew Carr released Everyday Data Science, a unique interactive online course! You’ll make the perfect glass of lemonade using Thompson sampling. You’ll lose weight with differential equations. And you might just qualify for the Olympics with a bit of statistics!

It’s $29, but you can get 50% off if you find the discount code ... Not quite. Hackers use the console!

More by Jim

Tagged #programming, #macos. All content copyright James Fisher 2020. This post is not associated with my employer. Found an error? Edit this page.