console

​
Some functions for manipulating the Hammerspoon console.
These functions allow altering the behavior and display of the Hammerspoon console. They should be considered experimental, but have worked well for me.
API Overview
Deprecateds - API features which will be removed in an future release
​asHSDrawing​
​asHSWindow​
Constants - Useful values which cannot be changed
​defaultToolbar​
Functions - API calls offered directly by the extension
​alpha​
​behaviorAsLabels​
​clearConsole​
​consoleCommandColor​
​consoleFont​
​consolePrintColor​
​consoleResultColor​
​darkMode​
​getConsole​
​getHistory​
​hswindow​
​inputBackgroundColor​
​level​
​outputBackgroundColor​
​printStyledtext​
​setConsole​
​setHistory​
​smartInsertDeleteEnabled​
​titleVisibility​
​windowBackgroundColor​
Methods - API calls which can only be made on an object returned by a constructor
​behavior​
​toolbar​
API Documentation
Deprecateds
​asHSDrawing​
Signature
hs.console.asHSDrawing() -> hs.drawing object
Type
Deprecated
Description
Because use of this function can easily lead to a crash, useful methods from hs.drawing have been added to the hs.console module itself. If you believe that a useful method has been overlooked, please submit an issue.
Parameters
None
Returns
a placeholder object
​asHSWindow​
Signature
hs.console.asHSWindow() -> hs.window object
Type
Deprecated
Description
Returns an hs.window object for the console so that you can use hs.window methods on it.
Constants
​defaultToolbar​
Signature
hs.console.defaultToolbar
Type
Constant
Description
Default toolbar for the Console window
Notes
This is an hs.toolbar object that is shown by default in the Hammerspoon Console
You can remove this toolbar by adding hs.console.toolbar(nil) to your config, or you can replace it with your own hs.webview.toolbar object
Functions
​alpha​
Signature
hs.console.alpha([alpha]) -> currentValue
Type
Function
Description
Get or set the alpha level of the console window.
Parameters
alpha - an optional number between 0.0 and 1.0 specifying the new alpha level for the Hammerspoon console.
Returns
the current, possibly new, value.
​behaviorAsLabels​
Signature
hs.console.behaviorAsLabels(behaviorTable) -> currentValue
Type
Function
Description
Get or set the window behavior settings for the console using labels defined in hs.drawing.windowBehaviors.
Parameters
behaviorTable - an optional table of strings and/or numbers specifying the desired window behavior for the Hammerspoon console.
Returns
the current (possibly new) value.
Notes
Window behaviors determine how the console is handled by Spaces and Exposé. See hs.drawing.windowBehaviors for more information.
​clearConsole​
Signature
hs.console.clearConsole() -> nil
Type
Function
Description
Clear the Hammerspoon console output window.
Parameters
None
Returns
None
Notes
This is equivalent to hs.console.setConsole()
​consoleCommandColor​
Signature
hs.console.consoleCommandColor([color]) -> color
Type
Function
Description
Get or set the color that commands displayed in the Hammerspoon console are displayed with.
Parameters
color - an optional table containing color keys as described in hs.drawing.color
Returns
the current color setting as a table
Notes
See the hs.drawing.color entry in the Dash documentation, or type help.hs.drawing.color in the Hammerspoon console to get more information on how to specify a color.
Note this only affects future output -- anything already in the console will remain its current color.
​consoleFont​
Signature
hs.console.consoleFont([font]) -> fontTable
Type
Function
Description
Get or set the font used in the Hammerspoon console.
Parameters
font - an optional string or table describing the font to use in the console. If a string is specified, then the default system font size will be used. If a table is specified, it should contain a name key-value pair and a size key-value pair describing the font to be used.
Returns
the current font setting as a table containing a name key and a size key.
Notes
See the hs.drawing.color entry in the Dash documentation, or type help.hs.drawing.color in the Hammerspoon console to get more information on how to specify a color.
Note this only affects future output -- anything already in the console will remain its current font.
​consolePrintColor​
Signature
hs.console.consolePrintColor([color]) -> color
Type
Function
Description
Get or set the color that regular output displayed in the Hammerspoon console is displayed with.
Parameters
color - an optional table containing color keys as described in hs.drawing.color
Returns
the current color setting as a table
Notes
See the hs.drawing.color entry in the Dash documentation, or type help.hs.drawing.color in the Hammerspoon console to get more information on how to specify a color.
Note this only affects future output -- anything already in the console will remain its current color.
​consoleResultColor​
Signature
hs.console.consoleResultColor([color]) -> color
Type
Function
Description
Get or set the color that function results displayed in the Hammerspoon console are displayed with.
Parameters
color - an optional table containing color keys as described in hs.drawing.color
Returns
the current color setting as a table
Notes
See the hs.drawing.color entry in the Dash documentation, or type help.hs.drawing.color in the Hammerspoon console to get more information on how to specify a color.
Note this only affects future output -- anything already in the console will remain its current color.
​darkMode​
Signature
hs.console.darkMode([state]) -> bool
Type
Function
Description
Set or display whether or not the Console window should display in dark mode.
Parameters
state - an optional boolean which will set whether or not the Console window should display in dark mode.
Returns
A boolean, true if dark mode is enabled otherwise false.
Notes
Enabling Dark Mode for the Console only affects the window background, and doesn't automatically change the Console's Background Color, so you will need to add something similar to: lua if hs.console.darkMode() then hs.console.outputBackgroundColor{ white = 0 } hs.console.consoleCommandColor{ white = 1 } hs.console.alpha(.8) end.
​getConsole​
| Signature | hs.console.getConsole([styled]) -> text | styledText | | -----------------------------------------------------|---------------------------------------------------------------------------------------------------------| | Type | Function | | Description | Get the text of the Hammerspoon console output window. | | Parameters |
styled - an optional boolean indicating whether the console text is returned as a string or a styledText object. Defaults to false.
| | Returns |
The text currently in the Hammerspoon console output window as either a string or an hs.styledtext object.
| | Notes |
If the text of the console is retrieved as a string, no color or style information in the console output is retrieved - only the raw text.
|
​getHistory​
Signature
hs.console.getHistory() -> array
Type
Function
Description
Get the Hammerspoon console history as an array.
Parameters
None
Returns
an array containing the history of commands entered into the Hammerspoon console.
​hswindow​
Signature
hs.console.hswindow() -> hs.window object
Type
Function
Description
Get an hs.window object which represents the Hammerspoon console window
Parameters
None
Returns
an hs.window object
​inputBackgroundColor​
Signature
hs.console.inputBackgroundColor([color]) -> color
Type
Function
Description
Get or set the color for the background of the Hammerspoon Console's input field.
Parameters
color - an optional table containing color keys as described in hs.drawing.color
Returns
the current color setting as a table
Notes
See the hs.drawing.color entry in the Dash documentation, or type help.hs.drawing.color in the Hammerspoon console to get more information on how to specify a color.
​level​
Signature
hs.console.level([theLevel]) -> currentValue
Type
Function
Description
Get or set the console window level
Parameters
theLevel - an optional parameter specifying the desired level as an integer, which can be obtained from hs.drawing.windowLevels.
Returns
the current, possibly new, value
Notes
see the notes for hs.drawing.windowLevels
​outputBackgroundColor​
Signature
hs.console.outputBackgroundColor([color]) -> color
Type
Function
Description
Get or set the color for the background of the Hammerspoon Console's output view.
Parameters
color - an optional table containing color keys as described in hs.drawing.color
Returns
the current color setting as a table
Notes
See the hs.drawing.color entry in the Dash documentation, or type help.hs.drawing.color in the Hammerspoon console to get more information on how to specify a color.
​printStyledtext​
Signature
hs.console.printStyledtext(...) -> none
Type
Function
Description
A print function which recognizes hs.styledtext objects and renders them as such in the Hammerspoon console.
Parameters
Any number of arguments can be specified, just like the builtin Lua print command. If an argument matches the userdata type of hs.styledtext, the text is rendered as defined by its style attributes in the Hammerspoon console; otherwise it is rendered as it would be via the traditional print command within Hammerspoon.
Returns
None
Notes
This has been made as close to the Lua print command as possible. You can replace the existing print command with this by adding the following to your init.lua file:
​setConsole​
Signature
hs.console.setConsole([styledText]) -> none
Type
Function
Description
Clear the Hammerspoon console output window.
Parameters
styledText - an optional hs.styledtext object containing the text you wish to replace the Hammerspoon console output with. If you do not provide an argument, the console is cleared of all content.
Returns
None
Notes
You can specify the console content as a string or as an hs.styledtext object in either userdata or table format.
​setHistory​
Signature
hs.console.setHistory(array) -> nil
Type
Function
Description
Set the Hammerspoon console history to the items specified in the given array.
Parameters
array - the list of commands to set the Hammerspoon console history to.
Returns
None
Notes
You can clear the console history by using an empty array (e.g. hs.console.setHistory({})
​smartInsertDeleteEnabled​
Signature
hs.console.smartInsertDeleteEnabled([flag]) -> bool
Type
Function
Description
Determine whether or not objects copied from the console window insert or delete space around selected words to preserve proper spacing and punctuation.
Parameters
flag - an optional boolean value indicating whether or not "smart" space behavior is enabled when copying from the Hammerspoon console.
Returns
the current value
Notes
this only applies to future copy operations from the Hammerspoon console -- anything already in the clipboard is not affected.
​titleVisibility​
Signature
hs.console.titleVisibility([state]) -> current value
Type
Function
Description
Get or set whether or not the "Hammerspoon Console" text appears in the Hammerspoon console titlebar.
Parameters
state - an optional string containing the text "visible" or "hidden", specifying whether or not the console window's title text appears.
Returns
a string of "visible" or "hidden" specifying the current (possibly changed) state of the window title's visibility.
Notes
When a toolbar is attached to the Hammerspoon console (see the hs.webview.toolbar module documentation), this function can be used to specify whether the Toolbar appears underneath the console window's title ("visible") or in the window's title bar itself, as seen in applications like Safari ("hidden"). When the title is hidden, the toolbar will only display the toolbar items as icons without labels, and ignores changes made with hs.webview.toolbar:displayMode.
​windowBackgroundColor​
Signature
hs.console.windowBackgroundColor([color]) -> color
Type
Function
Description
Get or set the color for the background of the Hammerspoon Console's window.
Parameters
color - an optional table containing color keys as described in hs.drawing.color
Returns
the current color setting as a table
Notes
See the hs.drawing.color entry in the Dash documentation, or type help.hs.drawing.color in the Hammerspoon console to get more information on how to specify a color.
Methods
​behavior​
Signature
hs.console.behavior([behavior]) -> currentValue
Type
Method
Description
Get or set the window behavior settings for the console.
Parameters
behavior - an optional number representing the desired window behaviors for the Hammerspoon console.
Returns
the current, possibly new, value.
Notes
Window behaviors determine how the webview object is handled by Spaces and Exposé. See hs.drawing.windowBehaviors for more information.
​toolbar​
| Signature | hs.console.toolbar([toolbar]) -> toolbarObject | currentValue | | -----------------------------------------------------|---------------------------------------------------------------------------------------------------------| | Type | Method | | Description | Get or attach/detach a toolbar to/from the Hammerspoon console. | | Parameters |
toolbar - if an hs.webview.toolbar object is specified, it will be attached to the Hammerspoon console. If an explicit nil is specified, the current toolbar will be removed from the console.
| | Returns |
if a toolbarObject or explicit nil is specified, returns the toolbarObject; otherwise returns the current toolbarObject or nil, if no toolbar is attached to the console.
| | Notes |
this method is a convenience wrapper for the hs.webview.toolbar.attachToolbar function.
|

Hammerspoon API - Previous

chooser

Next - Hammerspoon API

crash

Last modified 1mo ago

Export as PDF

Copy link

Contents

API Overview

API Documentation

Deprecateds

​asHSDrawing​

​asHSWindow​

Constants

​defaultToolbar​

Functions

​alpha​

​behaviorAsLabels​

​clearConsole​

​consoleCommandColor​

​consoleFont​

​consolePrintColor​

​consoleResultColor​

​darkMode​

​getConsole​

​getHistory​

​hswindow​

​inputBackgroundColor​

​level​

​outputBackgroundColor​

​printStyledtext​

​setConsole​

​setHistory​

​smartInsertDeleteEnabled​

​titleVisibility​

​windowBackgroundColor​

Methods

​behavior​

​toolbar​

asHSDrawing

asHSWindow

defaultToolbar

alpha

behaviorAsLabels

clearConsole

consoleCommandColor

consoleFont

consolePrintColor

consoleResultColor

darkMode

getConsole

getHistory

hswindow

inputBackgroundColor

level

outputBackgroundColor

printStyledtext

setConsole

setHistory

smartInsertDeleteEnabled

titleVisibility

windowBackgroundColor

behavior

toolbar