Append one or more elements to the end of the canvas
Element frame/center/coordinates values are y-down (y = 0 at the top of
the canvas) -- a different sense from the canvas window's own x/y position,
which is unflipped AppKit screen coordinates. See hs.canvas's module-level docs
for the full explanation.
Array of element dictionaries (each needs at least a type)
Self for chaining
Replace the element at an index, or append if the index equals the current element count
The replacement element dictionary
The index to replace
Self for chaining
Set the window's Spaces/Exposé collection behavior to a single named behavior
A behavior name from hs.canvas.windowBehaviors (e.g. "canJoinAllSpaces")
Self for chaining
Set the window's Spaces/Exposé collection behavior to a combination of named behaviors
Behavior names from hs.canvas.windowBehaviors, combined together
Self for chaining
Set the window's Spaces/Exposé collection behavior to a raw bitmask
A raw NSWindow.CollectionBehavior bitmask
Self for chaining
All elements currently on the canvas
Array of element dictionaries
Enable whole-canvas mouse tracking for regions not covered by any individually
tracked element. Delivered through mouseCallback() with id "_canvas".
all six flags, so omitting this turns right mouse-down tracking off
six flags, so omitting this turns right mouse-up tracking off
Track mouse-down events
Track mouse-up events
Track mouse enter/exit events
Track mouse-move events
OptionalrightDown: booleanTrack right mouse-down events (defaults to false). Every call sets
OptionalrightUp: booleanTrack right mouse-up events (defaults to false). Every call sets all
Self for chaining
Set whether clicking the canvas activates the Hammerspoon app
Pass false to prevent clicks on the canvas from bringing the app forward
Self for chaining
Destroy the canvas window and release its resources
Named destroy() rather than v1's delete() -- delete cannot be used as a
JavaScriptCore-exported method name in this codebase's bridging layer.
Set a callback fired when files or text are dropped onto the canvas
Called with the dropped file paths, or a single-element array containing dropped text
Self for chaining
Create an independent copy of this canvas, with the same frame, elements, and
window configuration
Named duplicate() rather than v1's copy() -- this codebase's conventions
forbid method names starting with copy (an ARC/ObjC hazard), the same rule
that renamed new() to create().
A new HSCanvas
Get a single attribute value from an element
Returns Any? (mirroring hs.userdefaults.get()) rather than a concrete Swift
type because an element attribute's value is genuinely heterogeneous -- a
string, number, boolean, nested object, or array, matching v1's dynamically-typed
Lua table values.
The element index
The attribute key
The attribute's current value, or null if not set
The smallest rectangle enclosing an element's rendered shape
The element index
A {x, y, w, h} dictionary
The number of elements on the canvas
The current element count
The attribute keys present on an element
The element index
Array of attribute key names
The canvas window's current position and size
A {x, y, w, h} dictionary, in the same unflipped AppKit screen coordinates as create()
Hide the canvas window (keeps it in memory; elements and window config are preserved)
Self for chaining
Set whether the canvas window ignores all mouse events, passing clicks through to whatever is behind it
This is a capability beyond v1's hs.canvas API surface (not a literal v1 method
name) -- v1 has no direct equivalent for full click pass-through.
Pass true to make the canvas fully click-through
Self for chaining
Render the canvas's current contents to an image
An HSImage snapshot of the canvas, or null if it could not be rendered
Insert an element at a specific index
The element dictionary to insert
The index to insert at (clamped to the valid range)
Self for chaining
Whether the canvas is hidden behind other windows, or off-screen entirely
true if the canvas is showing but fully occluded or off-screen
Whether the canvas window is currently ordered onto the screen
true if the canvas has been shown and not hidden or destroyed
Whether the canvas is showing AND at least partially visible (not fully occluded or off-screen)
true if the canvas is showing and at least partially on-screen
Set the window level by name
A level name from hs.canvas.windowLevels (e.g. "floating", "screenSaver")
Self for chaining
Set the window level to a raw numeric value
Split out from level(_:) (rather than accepting a string-or-number union)
because JSExport parameters must have a single concrete type -- see
hs.canvas.windowLevels, which exposes raw numeric values (not opaque name
strings) so scripts can do arithmetic on them, matching v1 behavior.
A raw numeric window level
Self for chaining
The smallest size that can fully render a string of text, using a text element's
font attributes (textFont/textSize/textWeight/textDesign/textItalic)
Mirrors v1's hs.canvas:minimumTextSize(). Multi-line strings (separated by \n)
are measured correctly -- the height covers every line and the width is the longest
line's width, not a fixed single-line size.
The index of a text element in the canvas whose font attributes to measure with
The string to measure -- it doesn't need to match the element's own text
A {w, h} dictionary, or {} if index is out of bounds
Set the callback fired for tracked mouse events
Fires for elements with trackMouseDown/trackMouseUp/trackMouseEnterExit/
trackMouseMove/trackRightMouseDown/trackRightMouseUp set to true in their
element dictionary, and for whole-canvas regions enabled via canvasMouseEvents()
(delivered with id "_canvas"). mouseDown/mouseUp are the left button only;
the right button (or a Ctrl-click, the standard macOS secondary click) is reported
separately as rightMouseDown/rightMouseUp.
A JavaScript function called with the canvas, the event name ("mouseDown"/"mouseUp"/"rightMouseDown"/"rightMouseUp"/"mouseEnter"/"mouseExit"/"mouseMove"), the tracked element's id, and the event's x/y coordinates
Self for chaining
Remove the element at a specific index
The index to remove
Self for chaining
Remove a single attribute from an element
The element index
The attribute key to remove
Self for chaining
Replace all elements on the canvas
The new full element list
Self for chaining
Rotate an element about its own bounding-box center
The element index
The rotation angle, in degrees
Self for chaining
Rotate an element about a specific point
The element index
The rotation angle, in degrees
A {x, y} dictionary giving the pivot point
Self for chaining
Set the accessibility subrole reported for this canvas's window
The accessibility subrole string
Self for chaining
Set a single attribute value on an element
The element index
The attribute key
The value to assign
Self for chaining
Apply a raw 2D affine transformation matrix to a single element
The element index
A {m11, m12, m21, m22, tX, tY} matrix dictionary
Self for chaining
Move and/or resize the canvas window
A {x, y, w, h} dictionary. Any keys left out keep their current value
Self for chaining
Resize the canvas window without moving its top-left corner
A {w, h} dictionary. Any keys left out keep their current value
Self for chaining
Move the canvas window without changing its size
An {x, y} dictionary giving the new top-left corner. Any keys left out keep their current value
Self for chaining
Apply a raw 2D affine transformation matrix to the whole canvas
A {m11, m12, m21, m22, tX, tY} matrix dictionary
Self for chaining
The canvas window's current size
A {w, h} dictionary
The canvas window's current top-left corner
the point at the window's highest y (its screen-visual top), not y = 0.
An {x, y} dictionary
HSCanvas
A single canvas window: an absolutely-positioned, low-level drawing surface mirroring v1 Hammerspoon's
hs.canvas. Elements are plain JS objects (matching v1's Lua tables) added withappendElements()and mutated in place withsetElementAttribute()/elementAttribute(). Supports the samefill/stroke/strokeAndFill/clip/build/skipaction pipeline as v1, including thebuild+clip+reversePathtechnique used to punch holes in shapes (seehs.canvas.windowLevels/hs.canvas.windowBehaviorsfor the window-level/Spaces controls needed alongside this for overlay-style canvases).Example