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

How do I change the resolution on macOS?
To get more screen real-estate, go to System Preferences > Displays, and select “More Space” . 2016-11-18
devices(for:) was deprecated in macOS 10.15: Use AVCaptureDeviceDiscoverySession instead
Use AVCaptureDeviceDiscoverySession instead of the deprecated AVCaptureDevice.devices(for:) to discover video capture devices. 2020-07-31
How to resolve “the app shows no response upon launch” in App Review
To resolve “the app shows no response upon launch” in App Review, identify and handle potential sources of fatal errors, such as uncaught exceptions, force-unwrapping nil values, unsafe downcasts, and out-of-bounds array access. Display a helpful error message instead of crashing. 2020-04-24
What system calls does macOS have?
All system calls on macOS 10.12, categorized by the functionality they provide, such as process management, file operations, memory management, etc. 2017-01-31
How do I create the AppIcon for my app?
To fix misconfigured App Icons, create properly-sized PNG files and update the Contents.json file to reference the correct image files. 2017-03-01
How to write an assembly ‘hello world’ on macOS
A “Hello, world!” program in x86-64 assembly for macOS, using the NASM assembler and system calls for writing to stdout and exiting. 2017-02-20

More by Jim

What does the dot do in JavaScript?
foo.bar, foo.bar(), or foo.bar = baz - what do they mean? A deep dive into prototypical inheritance and getters/setters. 2020-11-01
Smear phishing: a new Android vulnerability
Trick Android to display an SMS as coming from any contact. Convincing phishing vuln, but still unpatched. 2020-08-06
A probabilistic pub quiz for nerds
A “true or false” quiz where you respond with your confidence level, and the optimal strategy is to report your true belief. 2020-04-26
Time is running out to catch COVID-19
Simulation shows it’s rational to deliberately infect yourself with COVID-19 early on to get treatment, but after healthcare capacity is exceeded, it’s better to avoid infection. Includes interactive parameters and visualizations. 2020-03-14
The inception bar: a new phishing method
A new phishing technique that displays a fake URL bar in Chrome for mobile. A key innovation is the “scroll jail” that traps the user in a fake browser. 2019-04-27
The hacker hype cycle
I got started with simple web development, but because enamored with increasingly esoteric programming concepts, leading to a “trough of hipster technologies” before returning to more productive work. 2019-03-23
Project C-43: the lost origins of asymmetric crypto
Bob invents asymmetric cryptography by playing loud white noise to obscure Alice’s message, which he can cancel out but an eavesdropper cannot. This idea, published in 1944 by Walter Koenig Jr., is the forgotten origin of asymmetric crypto. 2019-02-16
How Hacker News stays interesting
Hacker News buried my post on conspiracy theories in my family due to overheated discussion, not censorship. Moderation keeps the site focused on interesting technical content. 2019-01-26
My parents are Flat-Earthers
For decades, my parents have been working up to Flat-Earther beliefs. From Egyptology to Jehovah’s Witnesses to theories that human built the Moon billions of years in the future. Surprisingly, it doesn’t affect their successful lives very much. For me, it’s a fun family pastime. 2019-01-20
The dots do matter: how to scam a Gmail user
Gmail’s “dots don’t matter” feature lets scammers create an account on, say, Netflix, with your email address but different dots. Results in convincing phishing emails. 2018-04-07
The sorry state of OpenSSL usability
OpenSSL’s inadequate documentation, confusing key formats, and deprecated interfaces make it difficult to use, despite its importance. 2017-12-02
I hate telephones
I hate telephones. Some rational reasons: lack of authentication, no spam filtering, forced synchronous communication. But also just a visceral fear. 2017-11-08
The Three Ts of Time, Thought and Typing: measuring cost on the web
Businesses often tout “free” services, but the real costs come in terms of time, thought, and typing required from users. Reducing these “Three Ts” is key to improving sign-up flows and increasing conversions. 2017-10-26
Granddad died today
Granddad died. The unspoken practice of death-by-dehydration in the NHS. The Liverpool Care Pathway. Assisted dying in the UK. The importance of planning in end-of-life care. 2017-05-19
How do I call a program in C, setting up standard pipes?
A C function to create a new process, set up its standard input/output/error pipes, and return a struct containing the process ID and pipe file descriptors. 2017-02-17
Your syntax highlighter is wrong
Syntax highlighters make value judgments about code. Most highlighters judge that comments are cruft, and try to hide them. Most diff viewers judge that code deletions are bad. 2014-05-11
👋 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.

Jim Fisher
CV
Speaking
Blogroll
RSS
TigYog
Kickabout