Skip to content
This repository has been archived by the owner on Jan 21, 2023. It is now read-only.
/ spectacle Public archive

Spectacle allows you to organize your windows without using a mouse.

License

Notifications You must be signed in to change notification settings

eczarny/spectacle

Repository files navigation

Spectacle

Build Status

Easily organize windows without using a mouse.

Important Note

This project is not being actively maintained. Unfortunately, after almost a decade of on-and-off development I can no longer dedicate the time needed to be a responsible maintainer of this project. Spectacle will remain available for download but please use at your own risk. The source code will continue to be free and open to anyone, so feel free to make Spectacle your own.

Thanks to all the folks that have made Spectacle the first app they install a new Mac!

Spectacle users have recommended Rectangle as an open source alternative.

System requirements

Spectacle 0.8.6 is the last version to support Mac OS X 10.7; future releases will only support 10.9 or greater. Folks wishing to stay on 10.7 should download 0.8.6. Those looking for a version of Spectacle that supports 10.6 can still download 0.7.

Keyboard Shortcuts

Spectacle makes use of several keyboard shortcuts that trigger specific window actions. A window action is nothing more than a command that tells Spectacle how to change the size and/or position of a particular window.

A keyboard shortcut consists of one or more modifier keys paired with a character key. The common modifier keys Spectacle takes advantage of are:

Symbol Key
Command Key
Control Key
Option Key
Shift Key

The default keyboard shortcuts can be changed at any time. Use new key combinations to trigger window actions, or clear particular keyboard shortcuts to disable window actions entirely.

Basic window actions

To move a window to the center of the screen use the ⌥⌘C keyboard shortcut. Centered windows will not have their size altered. Maximize a window using the ⌥⌘F shortcut.

Windows can be moved to a number of predefined regions of the screen:

  • Move to the left half — ⌥⌘←
  • Move to the right half — ⌥⌘→
  • Move to the top half — ⌥⌘↑
  • Move to the bottom half — ⌥⌘↓

  • Move to the upper left — ⌃⌘←
  • Move to the lower left — ⌃⇧⌘←
  • Move to the upper right — ⌃⌘→
  • Move to the lower right — ⌃⇧⌘→

Windows may also be resized between thirds using any of the shortcuts above. For example, to have a window resized between 1/3 and 2/3 of the left region of the screen simply activate the left half ⌥⌘← keyboard shortcut more than once. Each time the shortcut is activated Spectacle will move the window between 1/3, 2/3, and back to 1/2 of the left side of the screen. This feature also applies to the upper left, lower left, upper right, and lower right shortcuts.

Spectacle can also move windows between horizontal and vertical thirds of the screen. The ⌃⌥→ keyboard shortcut will move a window to the next third of the screen, starting with the horizontal third region on the left of the screen. ⌃⌥← will move a window to the previous third of the screen.

Resizing a window is just as easy. To make a window a bit larger use the ⌃⌥⇧→ keyboard shortcut; ⌃⌥⇧← can be used to make a window smaller. Spectacle will always attempt to maintain contact between the edges of a window and the edges of the screen when resizing.

Multiple displays

The ⌃⌥⌘→ keyboard shortcut will move a window to the next available display. ⌃⌥⌘← can be used to move a window to the previous display.

Window action history

Spectacle remembers where every window was prior to executing a window action. To undo a window action use the ⌥⌘Z keyboard shortcut. Use the ⌥⇧⌘Z shortcut to redo the window action once again.

Common Issues

Spectacle is requesting access to use accessibility features

Apple's OS X Accessibility Protocol makes Spectacle possible. This protocol allows assistive applications to drive the user interface of another application running in OS X. In order to do its job Spectacle must be granted access to use these accessibility features. Instructions to do so will be displayed if Spectacle determines it does not have sufficient privileges.

Spectacle does not resize a particular window as expected

OS X allows applications to place constraints on the size of its windows. This allows application developers to design their user interfaces without needing to worry about supporting every possible window dimension. In these cases Spectacle will not be able to resize those windows to fit into the exact dimensions intended by the shortcut used.

As an example suppose a display has a 2880x1800 resolution and a window is being resized to fit the left half of the display. If the window has specified a minimum allowable width of 1600 pixels Spectacle will not be able to resize the window to fit the expected 1440 pixels. The constraints placed on windows will always be respected despite leading to potentially unexpected results; in this example Spectacle will resize the window's width to 1600 pixels.

Spectacle behaves strangely with Terminal windows

Terminal (and other terminal emulation applications like iTerm 2) place constraints on how windows are resized so entire rows and columns are always visible. This behavior works great since it guarantees no rows or columns are truncated. Unfortunately it does mean that Spectacle needs to do some extra work to make these windows fit.

To work around the limitations imposed on Terminal windows Spectacle will first try to resize a window to match the desired dimensions. If a window cannot be resized to fit Spectacle will immediately try to make the window a little smaller. This process is repeated until the window can be made to fit with its constraints still in place. The result is a window that is centered within the desired dimensions at the cost of a slightly jittery experience.

Spectacle does not work with all applications

Most applications built with the Cocoa frameworks can be readily manipulated via the OS X Accessibility Protocol; allowing Spectacle to interact with nearly every window it encounters. Unfortunately this is not always the case. Spectacle will be unable to manipulate the windows of applications that build their user interfaces in unexpected ways.

Building and running

Spectacle uses Carthage. Before building Spectacle in Xcode run:

$ carthage bootstrap --platform Mac

Once Carthage builds Spectacle's dependencies open the Xcode project:

$ open Spectacle.xcodeproj

After Xcode finishes loading the workspace press ⌘R to run Spectacle.

License

Copyright (c) 2017 Eric Czarny.

Spectacle should be accompanied by a LICENSE file containing the license relevant to this distribution.