docs » hs.window.highlight

Highlight the focused window

This module can be useful to spatially keep track of windows if you have large and/or multiple screens, and are therefore likely to have several windows visible at any given time. It highlights the currently focused window by covering other windows and the desktop with either a subtle ("overlay" mode) or opaque ("isolate" mode) overlay; additionally it can highlight windows as they're shown or hidden via a brief flash, to help determine their location intuitively (to avoid having to studiously scan all your screens when, for example, you know you triggered a dialog but it didn't show up where you expected it).

By default, overlay mode is disabled - you can enable it with hs.window.highlight.ui.overlay=true - and so are the window shown/hidden flashes - enable those with hs.window.highlight.ui.flashDuration=0.3 (or whatever duration you prefer). Isolate mode is always available and can be toggled manually via hs.window.highlight.toggleIsolate() or automatically by passing an appropriate windowfilter (or a list of apps) to hs.window.highlight.start().

API Overview

API Documentation



Signature hs.window.highlight.ui
Type Variable
Description Allows customization of the highlight overlays and behaviour.



Signature hs.window.highlight.start([windowfilterIsolate[, windowfilterOverlay]])
Type Function
Description Starts the module
  • windowfilterIsolate - (optional) an `hs.window.filter` instance that automatically enable "isolate" mode
  • whenever one of the allowed windows is focused; alternatively, you can just provide a list of application
  • names and a windowfilter will be created for you that enables isolate mode whenever one of these apps is focused;
  • if omitted or nil, isolate mode won't be toggled automatically, but you can still toggle it manually via
  • `hs.window.higlight.toggleIsolate()`
  • windowfilterOverlay - (optional) an `hs.window.filter` instance that determines which windows to consider
  • for "overlay" mode when focused; if omitted or nil, the default windowfilter will be used
  • None
  • overlay mode is disabled by default - see `hs.window.highlight.ui.overlayColor`


Signature hs.window.highlight.stop()
Type Function
Description Stops the module and disables focused window highlighting (both "overlay" and "isolate" mode)
  • None
  • None


Signature hs.window.highlight.toggleIsolate([v])
Type Function
Description Sets or clears the user override for "isolate" mode.
  • v - (optional) a boolean; if true, enable isolate mode; if false, disable isolate mode,
  • even when `windowfilterIsolate` passed to `.start()` would otherwise enable it; if omitted or nil,
  • toggle the override, i.e. clear it if it's currently enforced, or set it to the opposite of the current
  • isolate mode status otherwise.
  • None

results matching ""

    No results matching ""