docs » WindowCache

Utility for quickly retrieving windows

Download: https://github.com/adammillerio/Spoons/raw/main/Spoons/WindowCache.spoon.zip

This uses a hs.window.filter to maintain a Least Recently Used cache which can be searched either by window title or application name. This is useful for automations which benefit from quick access to windows.

This was implemented based entirely off of the source of hs_select_window.spoon and split out to be used across other Spoons.

Example Usage (Using SpoonInstall): spoon.SpoonInstall:andUse( "WindowCache", { start = true } )

API Overview

API Documentation

Variables

currentWindows
Signature WindowCache.currentWindows
Type Variable
Description

Table containing the window cache, ordered by the time it was added to the
Source Source/WindowCache.spoon/init.lua line 57
logger
Signature WindowCache.logger
Type Variable
Description

Logger object used within the Spoon. Can be accessed to set the default log
Source Source/WindowCache.spoon/init.lua line 39
logLevel
Signature WindowCache.logLevel
Type Variable
Description

WindowCache specific log level override, see hs.logger.setLogLevel for options.
Source Source/WindowCache.spoon/init.lua line 45
staleWindowCheckInterval
Signature WindowCache.staleWindowCheckInterval
Type Variable
Description

Interval in seconds between checks for "stale" windows to be removed from
Source Source/WindowCache.spoon/init.lua line 33
staleWindowCheckTimer
Signature WindowCache.staleWindowCheckTimer
Type Variable
Description

hs.timer periodically running _checkForStaleWindows every staleWindowCheckInterval.
Source Source/WindowCache.spoon/init.lua line 75
subscribedFunctions
Signature WindowCache.subscribedFunctions
Type Variable
Description

Table containing all subscribed instance callbacks for the window filter, used
Source Source/WindowCache.spoon/init.lua line 63
windowFilter
Signature WindowCache.windowFilter
Type Variable
Description

Main hs.window.filter. This is what is used to enumerate and maintain the window
Source Source/WindowCache.spoon/init.lua line 50
windowsBySpace
Signature WindowCache.windowsBySpace
Type Variable
Description

Table containing per-Space window caches, keyed off of Mission Control Space ID,
Source Source/WindowCache.spoon/init.lua line 69

Methods

findWindowByApp
Signature WindowCache:findWindowByApp(appName[, spaceID])
Type Method
Description

Find the last opened window by application name.
Parameters
  • appName - name of the application to find
  • spaceID - optional ID of Space to access Space-specific cache for
Returns
  • The hs.window object if found, nil otherwise
Source Source/WindowCache.spoon/init.lua line 154
findWindowByTitle
Signature WindowCache:findWindowByTitle(title[, spaceID])
Type Method
Description

Find a window by title.
Parameters
  • title - title of the window to find
  • spaceID - optional ID of Space to access Space-specific cache for
Returns
  • The hs.window object if found, nil otherwise
Source Source/WindowCache.spoon/init.lua line 102
focusWindowByApp
Signature WindowCache:focusWindowByApp(appName[, spaceID])
Type Method
Description

Find the last opened window by application name and focus it.
Parameters
  • appName - name of the application to find
  • spaceID - optional ID of Space to access Space-specific cache for
Returns
  • The hs.window object focused if found, nil otherwise
Source Source/WindowCache.spoon/init.lua line 218
focusWindowByTitle
Signature WindowCache:focusWindowByTitle(title[, spaceID])
Type Method
Description

Find a window by title and focus it.
Parameters
  • title - title of the window to focus
  • spaceID - optional ID of Space to access Space-specific cache for
Returns
  • The hs.window object focused if found, nil otherwise
Source Source/WindowCache.spoon/init.lua line 136
getAppNamesForSpace
Signature WindowCache:getAppNamesForSpace(spaceID)
Type Method
Description

Given a spaceID, get a list of all open app names in the space.
Parameters
  • spaceID - ID of an hs.space to retrieve app names for.
Returns
  • A table representing the names of all app names open in the space, ordered by most recent first.
Notes
  • WindowCache window access history does not persist through Hammerspoon reloads.
Source Source/WindowCache.spoon/init.lua line 236
init
Signature WindowCache:init()
Type Method
Description

Spoon initializer method for WindowCache.
Parameters
  • None
Returns
  • None
Source Source/WindowCache.spoon/init.lua line 80
start
Signature WindowCache:start()
Type Method
Description

Spoon start method for WindowCache.
Parameters
  • None
Returns
  • None
Notes
  • Configures the window filter, initializes the cache with all existing windows, and then subscribes to all window related events to be cached. Also starts the periodic stale window checker.
Source Source/WindowCache.spoon/init.lua line 393
stop
Signature WindowCache:stop()
Type Method
Description

Spoon stop method for WindowCache.
Parameters
  • None
Returns
  • None
Notes
  • Unsubscribes the window filter from all subscribed functions and stops the stale window checker.
Source Source/WindowCache.spoon/init.lua line 438
waitForWindowByApp
Signature WindowCache:waitForWindowByApp(appName, fn[, interval, spaceID])
Type Method
Description

Wait for cached window in appName every interval and run fn when found.
Parameters
  • appName - name of the application to wait for first cached window of
  • fn - function to run when first cached window is found. This function may take a single argument, the timer itself
  • interval - How often to check for cached window, defaults to 1 second.
  • spaceID - optional ID of Space to access Space-specific cache for
Returns
  • The started hs.timer instance.
Source Source/WindowCache.spoon/init.lua line 199