MACROS: Cycling Window Manager

Macro Library
1

keyboard-maestro-cycling-window-manager

A cycling window manager partially inspired by Raycast, but with extra unique features such as undo and compound hotkeys.

Why use this over the new window management features in MacOS 15 Sequoia?

  1. Cycling behavior gives quick access to more window positions without having to remember as many hotkeys
  2. Compound hotkeys provide an intuitive visual/spatial set of key combinations that are easy to remeber
  3. Undo functionality

—Cycling Window Manager—

Written by @gaufde

—Features—

The point of this macro group is to make it easy to size and move window on multiple screens.

These macros support:

  1. Any number of monitors/screens
  2. Move the front window to any half of the screen with a hotkey command
  3. Move the front window to any quarter of the screen, or fill the screen with a compound hotkey command (similar to the WinMover macros by @cfriend)
  4. Move the front window to any third of the screen by repeatedly cycling the hotkey commands (similar to how Raycast does it)
  5. Move the front window to the center of the screen
  6. Move the front window to the center of the screen without resizing
  7. Move the front window to the previous size and position to “undo” a move.
  8. Throw the front window to the next/previous screen (maintaining relative size and position)

—Requirements—

These macros were written and tested in KM 11.0.3 on MacOS 13.7.

—Example Usage—

⌃⌥⌘← = left column (first cycle)
⌃⌥⌘← = left third (second cycle)
⌃⌥⌘← = left two-thirds (third cycle)
⌃⌥⌘← = middle third (fourth cycle)

Note: Similar behavior is available for →,↓, and ↑. Also, despite the animation of the window motion being slower in KM 11.0.2+, I have put work into making sure that the cycling can handle fast inputs. Simply count the number of key-presses and the window should ultimately end up in the correct position!

⌃⌥⌘. = Center window on current screen without resizing

⌃⌥⌘ + / = center half size (first cycle)
⌃⌥⌘/ = center 5/8 size (second cycle)
⌃⌥⌘/ = center 3/4 size (third cycle)
⌃⌥⌘/ = full screen (fourth cycle)

⌃⌥⌘←↑ = top left quadrant of the screen

Note: similar behavior is available for ↑→,←↓, and ↓→.

⌃⌥⌘←→ = full screen
⌃⌥⌘↓↑ = full screen

Note: these compound hotkeys are most reliable if you hold the keys down for just a moment longer than you would a normal press.

⌃⌥⌘Z = cycle through the previous window frames for the current window.

⌃⌥← = Throw window to previous screen
⌃⌥→ = Throw window to next screen

—Installation—

Download the .kmmacros file and double click it to install in Keyboard Maestro. The macro group will be disabled by default, so right click and choose enable. That’s it, all the hotkeys should now work!

—Parameters—

You can adjust the timeout before the cycling resets in the CWM-SUB: Init macro.

If you want, you can remove the animation delay that KM added in 11.0.2. Simply run the CWM-HELPER: Set WindowSetFrameAnimationTime macro using the “Try” button in the KM GUI. If you have issues with windows moving unreliably, then use the CWM-HELPER: Reset WindowSetFrameAnimationTime macro to revert back to the default settings.

—Extending—

It should be relatively easy to extend these macros if you want to customize them or add functionality.

The existing macros should serve as a guide. Duplicate the one most similar to what you want and edit it from there.

That said, here are a couple of important guidelines:

  1. Use your own window_cycle_namespace for new functionality. The namespaces currently used are up, down, left, right, center, undo, and reset. You will choose a namespace when calling CWM-SUB: Calculate cycling index, or you can write to the dictionary directly. If you need to force the cycle to reset, then set window_cycle_namespace in the dictionary to reset directly.

  2. When using CWM-SUB: Move window to position, the last parameter allows you to choose between passing coefficients only, or passing the values directly. Coefficients are easiest when working with fractions of the screen size, but sometime more flexibility is needed. See CWM Window Center Move Only for an example of passing values directly.

—Change Log—

1.0.0
First public release

Download

Cycling Window Manager 1.0.0 Macros.kmmacros (160.5 KB)

3 Likes
2

Special thanks to:

I'm trying out releasing the code on GitHub because I think it will be nicer to see different versions over time. That way, anyone can go see what the latest version is or download a previous version if needed. For those unfamiliar with GitHub, use the green code button to download the macros:

image
image1920×1083 109 KB

1 Like
3

Congrats on the release! And while Github is fine, I encourage you to also post the initial version here—just in case your Github account ever vanishes, or users are uncomfortable going there for whatever reason.

-rob.

2 Likes
4

Noted! I've updated the main post :blush:

5

This is very cool and super helpful to understand subroutines a bit better as well seeing something so complex. It looks like the GetHub version and the version up top are slightly different.

I also am not getting the results

⌃⌥⌘←→ = full screen
⌃⌥⌘↓↑ = full screen

Note: these compound hotkeys are most reliable if you hold the keys down for just a moment longer than you would a normal press.

Thanks for sharing.

6

What differences are you seeing? It's possible I made a mistake since I ended up making multiple changes to the README. The actual macros themselves should be identical though...unless something went really wrong!

The full-screen compound hotkeys are not working for you? Does the window move at all when you do this? How about the quadrants feature (for example *⌃⌥⌘↓ →)?

Also, I'd recommend testing the functionality with a Finder window, since sometimes certain windows will have a min or a max size.

7

I am guessing I just misunderstood what was meant by full screen. It did got the width and half of the full screen and then pressing it a second time made it about a 3rd of that size. There is no full screen shortcut right now as part of it right?

8

The window should fill all of the available screen but not be in Apple's "Full Screen" mode that hijacks your desktop/space:

image
image1920×1241 140 KB

That sounds like you are activating the up or down direction repeatedly and cycling from the first option (full width, half height), to the second option (full width, 1/3 height).

No, there is, but because it is a compound shortcut you should press and hold the keys down for a moment longer than normal. It doesn't have to be a full press-and-hold type of thing, but tapping the keys really quickly can be unreliable. The key combination I favor to go directly to full screen is ⌃⌥⌘←→ = full screen. Just press both arrow keys simultaneously and pause a moment.

1 Like
9

Oh my goodness, this is awesome and so much I am learning from these macros. I didn't realize you press them both at the same time that is a new one to me. The only thing I am use to holding at the same time is modifiers, this works amazingly well and so many goodies in here I am learning with Dictionaries, and reminders about repeated presses. I went down that path years ago and haven't used that for a while. Thank you for work on this and your post!

I need to learn more about GetHub and all the forks. I keep coming back to that again and again but just need to get over that hurdle. Finally, diving into RegEx deeper.

So I was looking at this further and was going to update and modify it to be able to put the windows in the corners. I love that you included this, my new windows manager and love that I can consolidate more things into Keyboard Maestro. Such and amazing group of shortcuts you made with the multipress options. Thank you again for making and sharing this!!

1 Like