Positioning & Resizing Windows, Dialogs, and Lists Using WindowArgs

[_jims]

---

Background

Keyboard Maestro includes powerful actions, functions, and tokens that can be used to move and resize existing windows. A similar action can be used to position and, in some cases, size of the next engine window. This includes Display Text windows, Prompt For User Input dialogs, Prompt With List lists, and Custom HTML Prompt windows/dialogs.

The action menus include some presets that can be selected to automatically enter x0, y0, Width, and Height for common positions and sizes.

The windows wiki page includes some very useful information related to these actions, functions, and tokens.

---

Introduction to WindowArgs

The purpose of this tutorial is to share a method to easily leverage the power of the native Keyboard Maestro window-related actions and functions using a simple text string that includes five arguments (four required, one optional). This text string, dubbed WindowArgs, has the following characteristics and capability:

• Window Positions and Sizes can be specified using:

  • Screen Percentages (width and/or height)
  • Screen Points (i.e., nominal resolution pixels)
  • Units can be mixed, e.g., width could be in points and height in percent of screen height.

• Windows can be left-, top-, right- and/or bottom-justified.

• Windows can be centered and mixed with justification. For example, a window could be centered horizontally and bottom-justified.

• The position of the macOS menubar and dock are considered when centering and justifying windows.

• Can be used to position and size application windows and Keyboard Maestro gui elements, i.e., Display Text windows, Prompt For User Input dialogs, Prompt With List lists, and Custom HTML Prompt windows/dialogs.

• Can correct an inconsistency with Custom HTML Prompt (Has Title enabled) window positioning and sizing. For more information, see Position & Size of 'Custom HTML Prompt' Windows Measure Differently Than Other Windows.

---

WindowArgs Syntax

WindowArgs include four required and one optional arguments: X Y W H F

X : If it is a:

1. number, then it is an absolute value in points (i.e., nominal resolution pixels)
2. number%, it is a percentage of SCREENVISIBLE(Main,Width)
3. | (vertical bar), the window should be centered horizontally
4. > (greater than), the right edge of the window should at SCREENVISIBLE(Main,Right)

Y : If it is a:

1. number, then it is an absolute value in points (i.e., nominal resolution pixels)
2. number%, it is a percentage of SCREENVISIBLE(Main,Height)
3. - (dash), the window should be centered vertically
4. v (letter v), the bottom edge of the window should at SCREENVISIBLE(Main,Bottom)

W : If it is a:

1. number, then it is an absolute value in points (i.e., nominal resolution pixels)
2. number%, it is a percentage of SCREENVISIBLE(Main,Width)

H : If it is a:

1. number, then it is an absolute value in points (i.e., nominal resolution pixels)
2. number%, it is a percentage of SCREENVISIBLE(Main,Height)

F : Is optional and should be null unless the conversion is for a Custom HTML Prompt (Has Title checked) window (in which case F can be x or any non-null value). For more information, see Position & Size of 'Custom HTML Prompt' Windows Measure Differently Than Other Windows.

Here are six examples of WindowArgs:

0 0 50% 75%
10% 20 1000 90%
| - 60% 700
> - 50% 60%
> v 850 40%
> v 850 40% x

---

WindowArgs Macro Code

Below are three flavors of macro code to position and resize windows via WindowArgs.

1. Move & Resize a Window using WindowArgs X Y W H

2. Move & Resize a Window using WindowArgs X Y W H (w/ check+correction)

3. s.𝘄𝗶𝗻𝗱𝗼𝘄⇾WindowArgs X Y W H F to WindowFrame

The first two are Groups of Actions that can be added to Favorite Actions (Action > Add to Favorites). By default, the two groups will position and resize the foreground window. Implementation is trivial: simply insert one of the two groups after the macro action(s) that create a window (e.g., a Finder window; a browser window) and then change the WindowArgs arguments based on the desired requirements.

The second group includes some extra logic to handle situations when the width and/or height within the WindowArgs are not achievable because the window being resized has some built-in constraints (e.g., minimum width and/or minimum height). Note that neither of these groups will have any affect on Display Text windows, Prompt For User Input dialogs, Prompt With List lists, and Custom HTML Prompt windows/dialogs because the Keyboard Maestro Manipulate a Window action does not recognize these as windows.

The third is a macro subroutine that converts a WindowArgs string to a WindowFrame. This subroutine can be used several ways some of which will be demonstrated below. Converted WindowArgs coupled with the Set Next Engine Window Position action, can position and, in some cases, size the Keyboard Maestro gui objects, i.e., Display Text windows, Prompt For User Input dialogs, Prompt With List lists, and Custom HTML Prompt windows/dialogs.

Note that as a subroutine, WindowArgs includes an optional fifth argument, F, which is used to flag that the conversion is for a Custom HTML Prompt (Has Title enabled) window.

---

Primary Downloads

---

Download: Move & Resize a Window using WindowArgs X Y W H.kmmacros (46 KB)

Macro-Image

---

Macro-Notes

• Macros are always disabled when imported into the Keyboard Maestro Editor.
  • The user must ensure the macro is enabled.
  • The user must also ensure the macro's parent macro-group is enabled.

---

System Information

• macOS 14.4.1 (23E224)
• Keyboard Maestro v11.0.2

---

Download: Move & Resize a Window using WindowArgs X Y W H (w- check+correction).kmmacros (67 KB)

Macro-Image

---

Macro-Notes

• Macros are always disabled when imported into the Keyboard Maestro Editor.
  • The user must ensure the macro is enabled.
  • The user must also ensure the macro's parent macro-group is enabled.

---

System Information

• macOS 14.4.1 (23E224)
• Keyboard Maestro v11.0.2

---

Download: s.𝘄𝗶𝗻𝗱𝗼𝘄⇾WindowArgs X Y W H F to WindowFrame.kmmacros (46 KB)

Macro Subroutine-Image

---

Macro Subroutine-Notes

• Macros are always disabled when imported into the Keyboard Maestro Editor.
  • The user must ensure the macro is enabled.
  • The user must also ensure the macro's parent macro-group is enabled.

---

System Information

• macOS 14.3.1 (23D60)
• Keyboard Maestro v11.0.2

---

Example Uses of the WindowArgs Subroutine

As stated above, the macro subroutine, s.𝘄𝗶𝗻𝗱𝗼𝘄⇾WindowArgs X Y W H F to WindowFrame, can be used in a variety of ways. Five examples are provided in this section.

---

Download: Ex 1–Display Text Windows.kmmacros (46 KB)

Macro-Image

---

Download: Ex 2–Prompt for User Input Dialogs.kmmacros (42 KB)

Macro-Image

---

Download: Ex 3–Prompt With List Lists.kmmacros (44 KB)

Macro-Image

---

Download: Ex 4–Custom HTML Prompt Windows.kmmacros (43 KB)

Macro-Image

---

Download: Ex 5–Custom HTML Prompt Windows (data-kmwindow).kmmacros (41 KB)

Macro-Image

---

Window-Related Tools

Some of the macros above use the following macro tools. They are not only required for some of the examples, but can be useful when developing macros that position and size windows and next engine objects.

---

Download: WindowTool 0–Get Window Absolute WindowArgs.kmmacros (37 KB)

Macro-Image

---

Download: WindowTool 1–Get Display Text Absolute WindowArgs.kmmacros (38 KB)

Macro-Image

---

Download: WindowTool 2–Get Prompt for User Input Dialog Absolute WindowArgs.kmmacros (40 KB)

Macro-Image

---

Download: WindowTool 3–Get Prompt with List Absolute WindowArgs.kmmacros (40 KB)

Macro-Image

---

Download: WindowTool 4–Get Custom HTML Prompt Absolute WindowArgs.kmmacros (40 KB)

Macro-Image

---

Window-Related Forum Threads

The forum includes several other threads related to this topic. This is far from exhaustive, but here are a few that you might find helpful. Please comment below if there are others that you would like to share.

• Window-resizing, works on any resolution, by @tantramar.

• WinMover - Rearrange Windows in Halves and Quadrants, or Move to another Screen, by @cfriend

• Understanding SCREENVISIBLE(Main,Right) - Questions & Suggestions - Keyboard Maestro Discourse, by @amb

• Window resize works inconsistently (dependent on App and Mac) - Questions & Suggestions - Keyboard Maestro Discourse, by @goat

• SUBROUTINE: Vertical Alignment of Windows Using Percentages—SCREEN, SCREENVISIBLE, MENUBARHEIGHT, by @_jims

• Repeatedly Position a Window (For Machines That Suffer From the Window Positioning Bug), by @cdthomer

• WindowDual: Move and Resize windows with one or two screens - Macro Library - Keyboard Maestro Discourse, by @jonathonl

[cfriend]

This looks great! My tool has been feeling a bit unresponsive recently. I’m looking forward to trying yours. Thanks for such a detailed write up.

[_jims]

I've updated the OP with Version 2.0 for two of the downloads:

1. Move & Resize a Window using WindowArgs X Y W H, and

2. Move & Resize a Window using WindowArgs X Y W H (w/ check+correction)

To help circumvent a well-known macOS issue with window positioning and resizing, added a repeat to enclose the Manipulate a Window action. For more information, see: Bug report: Window positioning + resize failing in KM11, by @cdthomer.