Concepts

Five nouns carry the whole app. Learn them once and the rest follows.

Display spec

A spec describes one virtual display: a name, a pixel size, a refresh rate, whether it advertises HiDPI modes, a rotation, and how much range it has above white. That is everything needed to recreate it.

What a spec deliberately does not hold is the display’s identifier. macOS hands out a CGDirectDisplayID that is not stable across re-creation, so persisting it would produce a group that stops matching its own displays after a reboot. Instead every spec has a UUID, and that UUID is hashed into a serial number stamped on the display when it is created. Live displays are matched back to specs through that serial.

Group

A group is a complete, named display setup: which displays exist, at what spec, arranged how, and which one is main. Complete is the important word. Activating a group is a replacement, not a merge: the machine ends up in the described state whatever state it was in before.

A group also carries the things that are about the group rather than about its displays:

• A symbol, shown in the sidebar and the menu bar.
• A keyboard shortcut, optional, global, and usable through a screen sharing session.
• Activate on launch, which the app applies as part of its launch sequence.
• Include connected displays, which decides whether attached monitors take part in the arrangement, and a resolution for each display it positions.
• Protected displays, whose mode is put back when something else changes it.
• A modified date, which exists so two Macs holding the same group can work out which copy is newer without asking you. See Sync and backups.

Arrangement

macOS lays every display out in one coordinate space. In a group the arrangement is normalised so the main display sits at the origin and every other position is relative to it, which is what makes a group portable: it describes shape, not absolute coordinates on one machine.

macOS itself will accept an arrangement that does not work: displays overlapping, or one stranded where the pointer cannot reach it. MoreDisplays will not. Every arrangement is validated before any configuration begins, so a rejected plan provably never touches the hardware.

Four rules, and the error names the one that was broken:

• Every display has a real, non-empty frame at coordinates macOS can actually take.
• Exactly one display sits at the origin. That is what “main” means to macOS, and without it the menu bar and the coordinate space have no anchor.
• No two displays overlap. Overlapping frames are an undefined arrangement.
• The layout is contiguous. A display separated from the rest by a gap is a display the pointer cannot reach, and the error names which ones were stranded.

Main display

The main display owns the menu bar and the origin of the coordinate space. On a machine you reach remotely it is the display your client sees first, so it is usually the one you want the client to fill.

It can be a virtual display, or, when the group includes physical displays, a connected monitor.

The catalogue

38 real panels, from Apple external displays through MacBook and iMac panels to iPads and the common ultrawide formats. Picking one fills in the pixel size, the refresh rates it offers and whether it does HiDPI, so a display can be defined without looking anything up.

28 of the 38 are marked verified, meaning the numbers were checked against the real panel rather than a spec sheet. Templates and the catalogue covers both the catalogue and building a display that is not in it.

The three ways in

There is one app and three doors into it. They all reach the same engine, and none of them can disagree with the others about what a group is.

The window and the menu bar. Everything the app can do, including editing groups, which is the part the other two deliberately cannot reach.

mdctl. Ten commands over a unix socket in the support directory. It is a client: it hands one request to the running app and prints the reply. Nothing listens on a network port, and there is no privileged helper.

It also describes itself. mdctl docs prints its own grammar as JSON, and every page under CLI reference is generated from that output rather than transcribed from it.

$ mdctl list
Home
Office
MacBook Air 13-inch (M1)

The URL scheme. Two commands only, activate and deactivate, because those are the ones that change state. Read-only commands have no way to return an answer through a URL open, so offering them would only invite confusion.

$ open 'moredisplays://activate?group=Office'

What runs where

Orphaned displays from a crashed previous instance are detected at the next launch and cleaned up, which is why the app stamps its own vendor identifier on everything it creates.

Next

• Headless setup puts all of this together on a machine with no monitor.
• Groups for building and capturing them in detail.