API Docs

HSRect

Type

This is a JavaScript object used to represent a rectangle, as used in various places throughout Hammerspoon's API, particularly where dealing with portions of a display. Behind the scenes it is a wrapper for the CGRect type in Swift/ObjectiveC.

Properties

x

number
An x-axis coordinate for the top-left point of the rectangle
Hammerspoon 2/Engine/Types/HSRect.swift:19

y

number
A y-axis coordinate for the top-left point of the rectangle
Hammerspoon 2/Engine/Types/HSRect.swift:22

w

number
The width of the rectangle
Hammerspoon 2/Engine/Types/HSRect.swift:25

h

number
The height of the rectangle
Hammerspoon 2/Engine/Types/HSRect.swift:28

origin

HSPoint
The "origin" of the rectangle, ie the coordinates of its top left corner, as an HSPoint object
Hammerspoon 2/Engine/Types/HSRect.swift:31

size

HSSize
The size of the rectangle, ie its width and height, as an HSSize object
Hammerspoon 2/Engine/Types/HSRect.swift:34

Methods

constructor(x, y, w, h) -> None

Create a new HSRect object
Declaration
constructor(x, y, w, h) -> None
Parameters
Name Type Description
x number The x-axis coordinate of the top-left corner
y number The y-axis coordinate of the top-left corner
w number The width of the rectangle
h number The height of the rectangle
Returns
None
Hammerspoon 2/Engine/Types/HSRect.swift:42

angleTo(other) -> number

Returns the angle between the positive x axis and the vector from this rect's center to another point or rect's center
Declaration
angleTo(other) -> number
Parameters
Name Type Description
other JSValue An HSPoint, or an HSRect (whose center will be used)
Returns
number
A number containing the angle in radians, or 0 if `other` is not an HSPoint or HSRect
Example
new HSRect(0, 0, 2, 2).angleTo(new HSPoint(2, 2)) // 0.7853981633974483
Hammerspoon 2/Engine/Types/HSRect.swift:51

distance(other) -> number

Finds the distance between this rect's center and another point or rect's center
Declaration
distance(other) -> number
Parameters
Name Type Description
other JSValue An HSPoint, or an HSRect (whose center will be used)
Returns
number
A number containing the distance, or 0 if `other` is not an HSPoint or HSRect
Example
new HSRect(0, 0, 2, 2).distance(new HSPoint(4, 5)) // 5.0
Hammerspoon 2/Engine/Types/HSRect.swift:60

equals(other) -> boolean

Checks if this rect is equal to another rect
Declaration
equals(other) -> boolean
Parameters
Name Type Description
other HSRect An HSRect to compare against
Returns
boolean
`true` if both rects have the same origin and size, otherwise `false`
Example
new HSRect(0, 0, 10, 10).equals(new HSRect(0, 0, 10, 10)) // true
Hammerspoon 2/Engine/Types/HSRect.swift:69

fit(bounds) -> HSRect

Ensures this rect is fully inside `bounds`, scaling it down (preserving aspect ratio) if it's larger, and moving it if necessary
Declaration
fit(bounds) -> HSRect
Parameters
Name Type Description
bounds HSRect An HSRect describing the bounds to fit within
Returns
HSRect
A new HSRect that fits fully inside `bounds`
Example
new HSRect(0, 0, 200, 100).fit(new HSRect(0, 0, 100, 100)) // new HSRect(0, 0, 100, 50)
Hammerspoon 2/Engine/Types/HSRect.swift:78

floor() -> HSRect

Truncates the origin and size of this rect towards negative infinity
Declaration
floor() -> HSRect
Returns
HSRect
A new HSRect with the x, y, w and h values floored to the nearest integer
Example
new HSRect(1.7, 1.2, 10.9, 10.1).floor() // new HSRect(1, 1, 10, 10)
Hammerspoon 2/Engine/Types/HSRect.swift:86

fromUnitRect(frame) -> HSRect

Converts a unit rect (coordinates and dimensions between 0 and 1) within a given frame into absolute coordinates
Declaration
fromUnitRect(frame) -> HSRect
Parameters
Name Type Description
frame HSRect An HSRect describing the frame this unit rect is relative to
Returns
HSRect
A new HSRect with coordinates and dimensions converted from the 0-1 range into absolute values within `frame`
Example
new HSRect(0.5, 0.5, 0.5, 0.5).fromUnitRect(new HSRect(0, 0, 100, 100)) // new HSRect(50, 50, 50, 50)
Hammerspoon 2/Engine/Types/HSRect.swift:95

inside(rect) -> boolean

Checks if this rect lies fully inside another rect
Declaration
inside(rect) -> boolean
Parameters
Name Type Description
rect HSRect An HSRect to check against
Returns
boolean
`true` if this rect lies fully within the bounds of `rect`, otherwise `false`
Example
new HSRect(1, 1, 5, 5).inside(new HSRect(0, 0, 10, 10)) // true
Hammerspoon 2/Engine/Types/HSRect.swift:104

intersect(rect) -> HSRect

Returns the intersection of this rect and another rect
Declaration
intersect(rect) -> HSRect
Parameters
Name Type Description
rect HSRect An HSRect to intersect with
Returns
HSRect
A new HSRect describing the overlapping area, or a zero-sized HSRect if they don't overlap
Example
new HSRect(0, 0, 10, 10).intersect(new HSRect(5, 5, 10, 10)) // new HSRect(5, 5, 5, 5)
Hammerspoon 2/Engine/Types/HSRect.swift:113

move(offset) -> HSRect

Moves this rect by an offset
Declaration
move(offset) -> HSRect
Parameters
Name Type Description
offset JSValue An HSPoint (using its x/y), or an HSSize (using its w/h)
Returns
HSRect
A new HSRect moved by the given offset, or an unchanged copy of this rect if `offset` is not an HSPoint or HSSize
Example
new HSRect(0, 0, 10, 10).move(new HSPoint(5, 5)) // new HSRect(5, 5, 10, 10)
Hammerspoon 2/Engine/Types/HSRect.swift:122

scale(factor) -> HSRect

Scales the size of this rect, keeping its center constant
Declaration
scale(factor) -> HSRect
Parameters
Name Type Description
factor JSValue A number to scale both dimensions uniformly, or an HSSize/HSPoint to scale the width and height independently
Returns
HSRect
A new HSRect scaled by the given factor, or an unchanged copy of this rect if `factor` is not a positive number, HSSize or HSPoint
Example
new HSRect(0, 0, 10, 10).scale(2) // new HSRect(-5, -5, 20, 20)
Hammerspoon 2/Engine/Types/HSRect.swift:131

toUnitRect(frame) -> HSRect

Converts this rect into a unit rect (coordinates and dimensions between 0 and 1) within a given frame
Declaration
toUnitRect(frame) -> HSRect
Parameters
Name Type Description
frame HSRect An HSRect describing the frame this rect is relative to
Returns
HSRect
A new HSRect with coordinates and dimensions normalized to the 0-1 range within `frame`
Example
new HSRect(50, 50, 50, 50).toUnitRect(new HSRect(0, 0, 100, 100)) // new HSRect(0.5, 0.5, 0.5, 0.5)
Hammerspoon 2/Engine/Types/HSRect.swift:140

union(rect) -> HSRect

Returns the smallest rect that encloses both this rect and another rect
Declaration
union(rect) -> HSRect
Parameters
Name Type Description
rect HSRect An HSRect to union with
Returns
HSRect
A new HSRect that fully encloses both rects
Example
new HSRect(0, 0, 10, 10).union(new HSRect(5, 5, 10, 10)) // new HSRect(0, 0, 15, 15)
Hammerspoon 2/Engine/Types/HSRect.swift:149

vector(other) -> HSPoint

Returns the vector from this rect's center to another point or rect's center
Declaration
vector(other) -> HSPoint
Parameters
Name Type Description
other JSValue An HSPoint, or an HSRect (whose center will be used)
Returns
HSPoint
A new HSPoint representing the vector, or `new HSPoint(0, 0)` if `other` is not an HSPoint or HSRect
Example
new HSRect(0, 0, 2, 2).vector(new HSPoint(4, 5)) // new HSPoint(3, 4)
Hammerspoon 2/Engine/Types/HSRect.swift:158