HSImage

Type

Bridge type for working with images in JavaScript

HSImage provides a comprehensive API for loading, manipulating, and saving images. It supports various image sources including files, system icons, app bundles, and URLs.

Loading Images

// Load from file
const img = HSImage.fromPath("/path/to/image.png")

// Load system image
const icon = HSImage.fromName("NSComputer")

// Load app icon
const appIcon = HSImage.fromAppBundle("com.apple.Safari")

// Load from URL (asynchronous with Promise)
HSImage.fromURL("https://example.com/image.png")
    .then(image => console.log("Image loaded:", image.size()))
    .catch(err => console.error("Failed to load image:", err))

// Or with async/await
const image = await HSImage.fromURL("https://example.com/image.png")

Image Manipulation

const img = HSImage.fromPath("/path/to/image.png")

// Get size
const size = img.size()  // Returns HSSize

// Resize image
const resized = img.setSize({w: 100, h: 100}, false)  // Proportional

// Crop image
const cropped = img.croppedCopy({x: 10, y: 10, w: 50, h: 50})

// Save to file
img.saveToFile("/path/to/output.png")

Properties

This type has no properties.

Methods

static HSImage.fromPath(path)

Load an image from a file path

Hammerspoon 2/Engine/Types/HSImage.swift:65

Parameters

  • path string

    Path to the image file

Returns

HSImage - An HSImage object, or null if the file couldn't be loaded

static HSImage.fromName(name)

Load a system image by name

Hammerspoon 2/Engine/Types/HSImage.swift:70

Parameters

  • name string

    Name of the system image (e.g., "NSComputer", "NSFolder")

Returns

HSImage - An HSImage object, or null if the image couldn't be found

static HSImage.fromAppBundle(bundleID)

Load an app's icon by bundle identifier

Hammerspoon 2/Engine/Types/HSImage.swift:75

Parameters

  • bundleID string

    Bundle identifier of the application

Returns

HSImage - An HSImage object, or null if the app couldn't be found

static HSImage.iconForFile(path)

Get the icon for a file

Hammerspoon 2/Engine/Types/HSImage.swift:80

Parameters

  • path string

    Path to the file

Returns

HSImage - An HSImage object representing the file's icon

static HSImage.iconForFileType(fileType)

Get the icon for a file type

Hammerspoon 2/Engine/Types/HSImage.swift:85

Parameters

  • fileType string

    File extension or UTI (e.g., "png", "public.png")

Returns

HSImage - An HSImage object representing the file type's icon

static HSImage.fromURL(url)

Load an image from a URL (asynchronous)

Hammerspoon 2/Engine/Types/HSImage.swift:90

Parameters

  • url string

    URL string of the image

Returns

Promise<HSImage> - A Promise that resolves to the loaded image, or rejects on error

size(size)

Get or set the image size

Hammerspoon 2/Engine/Types/HSImage.swift:95

Parameters

  • size JSValue

    Optional HSSize to set (if provided, returns a resized copy)

Returns

JSValue - The current size as HSSize, or a resized copy if size was provided

name(name)

Get or set the image name

Hammerspoon 2/Engine/Types/HSImage.swift:100

Parameters

  • name JSValue

    Optional name to set

Returns

string - The current or new name

setSize(size, absolute)

Create a resized copy of the image

Hammerspoon 2/Engine/Types/HSImage.swift:107

Parameters

  • size JSValue

    Target size as HSSize

  • absolute boolean

    If true, resize exactly to specified dimensions. If false, maintain aspect ratio

Returns

HSImage - A new resized HSImage

copyImage()

Create a copy of the image

Hammerspoon 2/Engine/Types/HSImage.swift:111

Parameters

None

Returns

HSImage - A new HSImage copy

croppedCopy(rect)

Create a cropped copy of the image

Hammerspoon 2/Engine/Types/HSImage.swift:116

Parameters

  • rect JSValue

    HSRect defining the crop area

Returns

HSImage - A new cropped HSImage, or null if cropping failed

saveToFile(path)

Save the image to a file

Hammerspoon 2/Engine/Types/HSImage.swift:121

Parameters

  • path string

    Destination file path (extension determines format: png, jpg, tiff, bmp, gif)

Returns

boolean - true if saved successfully, false otherwise

template(state)

Get or set the template image flag

Hammerspoon 2/Engine/Types/HSImage.swift:126

Parameters

  • state JSValue

    Optional boolean to set template state

Returns

boolean - Current template state

set(value)

Replace the image with a new one, triggering a re-render if bound to a UI element

Hammerspoon 2/Engine/Types/HSImage.swift:130

Parameters

  • value JSValue

    New image as an HSImage object or a file path string

Returns

Nothing