Multi-Display Order and Dual Row Layout

[waylonwang]

1. Added a "Displays" section with configuration options, allowing users to set ordering rules to determine display sequence when multiple displays are connected. This enhances the original horizontal-axis-only comparison method by supporting both horizontal and vertical axis prioritization with configurable sorting directions. This ensures more precise and stable display arrangement when switching between different external displays on a MacBook.

2. Introduced a "Dual Rows" layout where status icons in the system menu bar are displayed in two rows, significantly improving space efficiency in the status bar area.

3. The space naming dropdown menu now displays more detailed Display and Space/Full Screen identifiers, providing users with clearer reference information when naming spaces during display ordering rule changes.

4. Added visual separators between Spaces from different displays in the right-click context menu, making it easier for users to visually distinguish between them.

[ruittenb]

@waylonwang Thank you very much for your pull request!
I merged the fix for the compilation error and I would love to merge the dual-row setting, but I have some trouble understanding how it works. Please take a look at my screen recording:

Screen.Recording.2025-09-15.at.23.22.58.mov

Could you please explain if this is the intended behavior, and if so, what is the reasoning behind it?

[waylonwang]

@waylonwang Thank you very much for your pull request! I merged the fix for the compilation error and I would love to merge the dual-row setting, but I have some trouble understanding how it works. Please take a look at my screen recording:

Screen.Recording.2025-09-15.at.23.22.58.mov
Could you please explain if this is the intended behavior, and if so, what is the reasoning behind it?

Multi-Display Order

• Priority: Set by Display Order Priority — Horizontal-first or Vertical-first.
• Directions: Horizontal (Left→Right or Right→Left) and Vertical (Top→Bottom or Bottom→Top).
• How it sorts displays: Compares display centers with a small tolerance (≈2pt).
  • Horizontal-first: sort by X using Horizontal direction; ties break by Y using Vertical direction.
  • Vertical-first: sort by Y using Vertical direction; ties break by X using Horizontal direction.
• Examples:
  • Stacked: Vertical-first + Top→Bottom → Top display spaces first; Bottom→Top reverses.
  • Side-by-side: Horizontal-first + Left→Right → Left display spaces first; Right→Left reverses.
  • Grid (e.g., 2×2): Horizontal-first orders columns left→right, then within a column uses Vertical direction; Vertical-first orders rows top→bottom, then within a row uses Horizontal direction.

Dual Row Layout

• Layout by columns in space order; each column places top row first, then bottom. If count is odd, the last column has only a top item.

[ruittenb]

Hello @waylonwang ,

Wow okay, these settings work in a very detailed and specific way.
I understand how it works now, but I am a bit in doubt over whether users would understand how these settings work.
I'm also wondering if this holds any advantages over a simple "invert display ordering" toggle.

Let me think a little bit more about this feature.

[ruittenb]

Hello @waylonwang,
I do have a change request for you. In "Dual Rows" layout, I would like to order the spaces from left to right first, then up-down.

Right now I have:

I would like to have:

Could we implement a toggle for this?

[waylonwang]

Hello @waylonwang ,

Wow okay, these settings work in a very detailed and specific way. I understand how it works now, but I am a bit in doubt over whether users would understand how these settings work. I'm also wondering if this holds any advantages over a simple "invert display ordering" toggle.

Let me think a little bit more about this feature.

The idea of ordering multiple displays came about because my MBP has an external display both at the office and at home, and I place both above my MBP. I want my MBP’s built-in display to be the primary display, while the external display serves as my secondary display. I hope that in the status bar, the MBP’s built-in display appears on the left, and the external display appears on the right. After installing Spaceman, it worked perfectly at the office—the external display appeared to the right of the built-in display in the status bar.

When I returned home and opened my MBP, connecting it to another external display, I noticed that the external display appeared to the left of the built-in display. So, I began investigating the cause. I discovered that although the home display was positioned above the built-in display in macOS’s display arrangement, just like at the office, there was a slight difference in the left-right alignment. Whether the top display was slightly to the left or slightly to the right made a difference in the serial arrangement. The original code of Spaceman only implemented judgment based on the x-axis and did not handle the y-axis. As a result, it behaved just like macOS’s display arrangement, whereas I simply wanted the external display above to always appear to the right of the built-in display in the status bar, regardless of its placement.

Therefore, I modified the code in Spaceman. The result is now stable—no matter how I position the external display in macOS’s display arrangement, as long as it is above the built-in display, it will always appear to the right of the built-in display in the status bar.

If you have any better ideas for configuration to help users understand this setup more clearly, you are very welcome to make adjustments!

[waylonwang]

Hello @waylonwang, I do have a change request for you. In "Dual Rows" layout, I would like to order the spaces from left to right first, then up-down.

Right now I have: I would like to have:

Could we implement a toggle for this?

Since there are only two rows, arranging them from top to bottom and then left to right is straightforward and doesn't require calculating the number of columns, so I handled it this way for simplicity. However, calculating the number of columns is also easy. When the Dual Row layout is selected, I can add an option to determine the priority direction for spatial ordering.

[waylonwang]

Hello @waylonwang, I do have a change request for you. In "Dual Rows" layout, I would like to order the spaces from left to right first, then up-down.

Right now I have: I would like to have:

Could we implement a toggle for this?

I've added an option in my fork to configure the fill order (Row first/Column first) when using Dual Row layout. After this PR is merged, I'll submit another PR to implement this feature.

[ruittenb]

@waylonwang Thank you so much for implementing this "fill order" toggle! I merged the individual changes to my main branch.
I am going to do a bit of research on ordering desktops and I will get back to you about that.

[ruittenb]

The idea of ordering multiple displays came about because my MBP has an external display both at the office and at home, and I place both above my MBP. I want my MBP’s built-in display to be the primary display, while the external display serves as my secondary display. I hope that in the status bar, the MBP’s built-in display appears on the left, and the external display appears on the right. After installing Spaceman, it worked perfectly at the office—the external display appeared to the right of the built-in display in the status bar.

When I returned home and opened my MBP, connecting it to another external display, I noticed that the external display appeared to the left of the built-in display. So, I began investigating the cause. I discovered that although the home display was positioned above the built-in display in macOS’s display arrangement, just like at the office, there was a slight difference in the left-right alignment. Whether the top display was slightly to the left or slightly to the right made a difference in the serial arrangement. The original code of Spaceman only implemented judgment based on the x-axis and did not handle the y-axis. As a result, it behaved just like macOS’s display arrangement, whereas I simply wanted the external display above to always appear to the right of the built-in display in the status bar, regardless of its placement.

img alt=macosDisplaysArrange

Therefore, I modified the code in Spaceman. The result is now stable—no matter how I position the external display in macOS’s display arrangement, as long as it is above the built-in display, it will always appear to the right of the built-in display in the status bar.

If you have any better ideas for configuration to help users understand this setup more clearly, you are very welcome to make adjustments!

I tested the setup on my own MacBook.

I clicked "Arrange..." and positioned the screens one above the other, with the top display slightly to the left. Spaceman (and the Displays settings panel) then showed the top display on the left.
If I position the top display slightly to the right, Spaceman and the Displays settings panel show the top display on the right.

But when I disconnect the external screen in either configuration, reconnecting it restores the display to the same position.

That is why I'm wondering if your issue can be solved by changing the arrangement in the System Settings.

I suggest opening the Display Settings, clicking "Arrange..." and moving the top display slightly to the right; and doing this twice, once for each external screen. I would expect that macOS then remembers the horizontal positioning for each screen correctly, and the alignment should be consistent.

Would you be kind enough to try this out?

screen-positioning.mov

[waylonwang]

Display Settings, clicking "Arrange..."

The "Arrange..." option in the system's Display Settings can affect the order of displays in Spaceman. However, I feel that this influence is imperceptible to most users. It was only after in-depth analysis that I discovered the rules behind how the macOS system arranges multiple displays. Therefore, I suggest not requiring users to understand how the operating system sorts displays. Instead, the approach should be based on the user's own perception. For example: "Hmm, the monitor I placed above should appear on the right in Spaceman." To make this requirement and configuration more user-friendly and easier to understand, the configuration options could be optimized with clearer descriptions:

1. For horizontally arranged displays, the arrangement should be completely straightforward. Since the display areas in the status bar are already arranged horizontally, the sorting should follow the x-axis order. There should be no inconsistency between the virtual arrangement and the physical setup.

2. For vertically arranged displays, the configuration should allow users to intuitively choose whether the top monitor appears on the left or right in the status bar.

3. For mixed arrangements involving multiple displays, the situation is relatively complex. I haven’t yet determined the best way to handle this scenario.

[ruittenb]

Hello @waylonwang ,

I have a proposal. I distinguish between four situations:

From left to right:

1. both displays are next to each other, roughly at the same height (margin to be determined)
2. both displays touch at their sides, but are not at the same height
3. both displays touch at their top and bottom edges, but are not exactly aligned horizontally
4. both displays one above the other, roughly horizontally aligned (margin to be determined)

In situations 1 and 2, we always want to follow macOS’s horizontal ordering.
In situations 3 and 4, I consider them sufficiently “stacked” to allow for separate vertical sorting rules.

This also gives us an unambiguous criterion: if the side edges touch, we call it “side by side”; if the top and bottom edges touch, we call it “stacked”. We can determine whether the top and bottom edges touch by comparing the display1.centerY and display2.centerY which should be within a tolerance margin of the sum of half of the heights of the displays.

I propose to make one setting which can toggle between: "default order", “top goes left”, or “top goes right”.

When the above criterion determines that the displays are vertically stacked, then the value of the new setting will be taken into account. If it determines that the displays are side by side, Spaceman should always use the default macOS order.

I have done some preliminary work on this, and that seems to work correctly.

[ruittenb]

Hello @waylonwang , please try https://github.com/ruittenb/Spaceman/releases/tag/v1.12.8-alpha
I would appreciate your feedback.

[ruittenb]

Hello @waylonwang ,
I implemented my proposal in 1.12.8.
I have confidence that this strikes the right balance: it's both complete and intuitive without being overly complex.

[ruittenb]

Implemented, albeit in a different form