hs.canvas.md

docs » hs.canvas

---

A different approach to drawing in Hammerspoon

hs.drawing approaches graphical images as independant primitives, each "shape" being a separate drawing object based on the core primitives: ellipse, rectangle, point, line, text, etc. This model works well with graphical elements that are expected to be managed individually and don't have complex clipping interactions, but does not scale well when more complex combinations or groups of drawing elements need to be moved or manipulated as a group, and only allows for simple inclusionary clipping regions.

This module works by designating a canvas and then assigning a series of graphical primitives to the canvas. Included in this assignment list are rules about how the individual elements interact with each other within the canvas (compositing and clipping rules), and direct modification of the canvas itself (move, resize, etc.) causes all of the assigned elements to be adjusted as a group.

The canvas elements are defined in an array, and each entry of the array is a table of key-value pairs describing the element at that position. Elements are rendered in the order in which they are assigned to the array (i.e. element 1 is drawn before element 2, etc.).

Attributes for canvas elements are defined in hs.canvas.attributes. All canvas elements require the type field; all other attributes have default values. Fields required to properly define the element (for example, frame for the rectangle element type) will be copied into the element definition with their default values if they are not specified at the time of creation. Optional attributes will only be assigned in the element definition if they are specified. When the module requires the value for an element's attribute it first checks the element definition itself, then the defaults are looked for in the canvas defaults, and then finally in the module's built in defaults (specified in the descriptions below).

Some examples of how to use this module can be found at https://github.com/asmagill/hammerspoon/wiki/hs.canvas.examples

Submodules

• hs.canvas.matrix

API Overview

• Constants - Useful values which cannot be changed
• compositeTypes
• windowBehaviors
• windowLevels
• Functions - API calls offered directly by the extension
• defaultTextStyle
• elementSpec
• help
• useCustomAccessibilitySubrole
• Constructors - API calls which return an object, typically one that offers API methods
• new
• Fields - Variables which can only be accessed from an object returned by a constructor
• attributes
• object
• percentages
• Methods - API calls which can only be made on an object returned by a constructor
• _accessibilitySubrole
• alpha
• appendElements
• assignElement
• behavior
• behaviorAsLabels
• bringToFront
• canvasDefaultFor
• canvasDefaultKeys
• canvasDefaults
• canvasElements
• canvasMouseEvents
• clickActivating
• copy
• delete
• draggingCallback
• elementAttribute
• elementBounds
• elementCount
• elementKeys
• frame
• hide
• imageFromCanvas
• insertElement
• isOccluded
• isShowing
• isVisible
• level
• minimumTextSize
• mouseCallback
• orderAbove
• orderBelow
• removeElement
• replaceElements
• rotateElement
• sendToBack
• show
• size
• topLeft
• transformation
• wantsLayer

API Documentation

Constants

compositeTypes

Signature	hs.canvas.compositeTypes[]
Type	Constant
Description	A table containing the possible compositing rules for elements within the canvas.

windowBehaviors

Signature	hs.canvas.windowBehaviors[]
Type	Constant
Description	Array of window behavior labels for determining how a canvas or drawing object is handled in Spaces and Exposé

windowLevels

Signature	hs.canvas.windowLevels
Type	Constant
Description	A table of predefined window levels usable with hs.canvas:level
Notes	These key names map to the constants used in CoreGraphics to specify window levels and may not actually be used for what the name might suggest. For example, tests suggest that an active screen saver actually runs at a level of 2002, rather than at 1000, which is the window level corresponding to kCGScreenSaverWindowLevelKey. Each window level is sorted separately and hs.canvas:orderAbove and hs.canvas:orderBelow only arrange windows within the same level. If you use Dock hiding (or in 10.11, Menubar hiding) please note that when the Dock (or Menubar) is popped up, it is done so with an implicit orderAbove, which will place it above any items you may also draw at the Dock (or MainMenu) level.

Functions

defaultTextStyle

Signature	hs.canvas.defaultTextStyle() -> hs.styledtext attributes table
Type	Function
Description	Returns a table containing the default font, size, color, and paragraphStyle used by hs.canvas for text drawing objects.
Parameters	None
Returns	a table containing the default style attributes hs.canvas uses for text drawing objects in the hs.styledtext attributes table format.
Notes	This method is intended to be used in conjunction with hs.styledtext to create styledtext objects that are based on, or a slight variation of, the defaults used by hs.canvas.

elementSpec

Signature	hs.canvas.elementSpec() -> table
Type	Function
Description	Returns the list of attributes and their specifications that are recognized for canvas elements by this module.
Parameters	None
Returns	A table containing the attributes and specifications defined for this module.
Notes	This is primarily for debugging purposes and may be removed in the future.

help

Signature	hs.canvas.help([attribute]) -> string
Type	Function
Description	Provides specification information for the recognized attributes, or the specific attribute specified.
Parameters	attribute - an optional string specifying an element attribute. If this argument is not provided, all attributes are listed.
Returns	a string containing some of the information provided by the hs.canvas.elementSpec in a manner that is easy to reference from the Hammerspoon console.

useCustomAccessibilitySubrole

Signature	hs.canvas.useCustomAccessibilitySubrole([state]) -> boolean
Type	Function
Description	Get or set whether or not canvas objects use a custom accessibility subrole for the contaning system window.
Parameters	state - an optional boolean, default true, specifying whether or not canvas containers should use a custom accessibility subrole.
Returns	the current, possibly changed, value as a boolean
Notes	Under some conditions, it has been observed that Hammerspoon's hs.window.filter module will misidentify Canvas and Drawing objects as windows of the Hammerspoon application that it should consider when evaluating its filters. To eliminate this, hs.canvas objects (and previously hs.drawing objects, which are now deprecated and pass through to hs.canvas) were given a nonstandard accessibilty subrole to prevent them from being included. This has caused some issues with third party tools, like Yabai, which also use the accessibility subroles for determining what actions it may take with Hammerspoon windows.

Constructors

new

Signature	hs.canvas.new(rect) -> canvasObject
Type	Constructor
Description	Create a new canvas object at the specified coordinates
Parameters	rect - A rect-table containing the co-ordinates and size for the canvas object
Returns	a new, empty, canvas object, or nil if the canvas cannot be created with the specified coordinates
Notes	The size of the canvas defines the visible area of the canvas -- any portion of a canvas element which extends past the canvas's edges will be clipped. a rect-table is a table with key-value pairs specifying the top-left coordinate on the screen for the canvas (keys x and y) and the size (keys h and w) of the canvas. The table may be crafted by any method which includes these keys, including the use of an hs.geometry object.

Fields

attributes

Signature	hs.canvas.attributes
Type	Field
Description	Canvas Element Attributes

object

Signature	hs.canvas.object[index]
Type	Field
Description	An array-like method for accessing the attributes for the canvas element at the specified index

percentages

Signature	hs.canvas.percentages
Type	Field
Description	Canvas attributes which specify the location and size of canvas elements can be specified with an absolute position or as a percentage of the canvas size.

Methods

_accessibilitySubrole

| Signature | hs.canvas:_accessibilitySubrole([subrole]) -> canvasObject | current value | | -----------------------------------------------------|---------------------------------------------------------------------------------------------------------| | Type | Method | | Description | Get or set the accessibility subrole returned by hs.canvas objects. | | Parameters |

• subrole - an optional string or explicit nil wihch specifies what accessibility subrole value should be returned when canvas objects are queried through the macOS accessibility framework. See Notes for a discussion of how this value is interpreted. Defaults to nil.

| | Returns |

• If an argument is specified, returns the canvasObject; otherwise returns the current value.

| | Notes |

• Most people will probably not need to use this method; See hs.canvas.useCustomAccessibilitySubrole for a discussion as to why this method may be of use when Hammerspoon is being controlled through the accessibility framework by other applications.

|

alpha

| Signature | hs.canvas:alpha([alpha]) -> canvasObject | currentValue | | -----------------------------------------------------|---------------------------------------------------------------------------------------------------------| | Type | Method | | Description | Get or set the alpha level of the window containing the canvasObject. | | Parameters |

• alpha - an optional number specifying the new alpha level (0.0 - 1.0, inclusive) for the canvasObject

| | Returns |

• If an argument is provided, the canvas object; otherwise the current value.

|

appendElements

Signature	hs.canvas:appendElements(element...) -> canvasObject
Type	Method
Description	Appends the elements specified to the canvas.
Parameters	element - a table containing key-value pairs that define the element to be appended to the canvas. You can specify one or more elements and they will be appended in the order they are listed.
Returns	the canvas object
Notes	You can also specify multiple elements in a table as an array, where each index in the table contains an element table, and use the array as a single argument to this method if this style works better in your code.

assignElement

Signature	hs.canvas:assignElement(elementTable, [index]) -> canvasObject
Type	Method
Description	Assigns a new element to the canvas at the specified index.
Parameters	elementTable - a table containing key-value pairs that define the element to be added to the canvas. index - an optional integer between 1 and the canvas element count + 1 specifying the index position to put the new element. Any element currently at that index will be replaced. Defaults to the canvas element count + 1 (i.e. after the end of the currently defined elements).
Returns	the canvasObject
Notes	When the index specified is the canvas element count + 1, the behavior of this method is the same as hs.canvas:insertElement; i.e. it adds the new element to the end of the currently defined element list.

behavior

| Signature | hs.canvas:behavior([behavior]) -> canvasObject | currentValue | | -----------------------------------------------------|---------------------------------------------------------------------------------------------------------| | Type | Method | | Description | Get or set the window behavior settings for the canvas object using labels defined in hs.canvas.windowBehaviors. | | Parameters |

• behavior - if present, the behavior should be a combination of values found in hs.canvas.windowBehaviors describing the window behavior. The behavior should be specified as one of the following:
• integer - a number representing the behavior which can be created by combining values found in hs.canvas.windowBehaviors with the logical or operator.
• string - a single key from hs.canvas.windowBehaviors which will be toggled in the current window behavior.
• table - a list of keys from hs.canvas.windowBehaviors which will be combined to make the final behavior by combining their values with the logical or operator.

| | Returns |

• if an argument is provided, then the canvasObject is returned; otherwise the current behavior value is returned.

|

behaviorAsLabels

| Signature | hs.canvas:behaviorAsLabels(behaviorTable) -> canvasObject | currentValue | | -----------------------------------------------------|---------------------------------------------------------------------------------------------------------| | Type | Method | | Description | Get or set the window behavior settings for the canvas object using labels defined in hs.canvas.windowBehaviors. | | Parameters |

• behaviorTable - an optional table of strings and/or integers specifying the desired window behavior for the canvas object.

| | Returns |

• If an argument is provided, the canvas object; otherwise the current value as a table of strings.

|

bringToFront

Signature	hs.canvas:bringToFront([aboveEverything]) -> canvasObject
Type	Method
Description	Places the canvas object on top of normal windows
Parameters	aboveEverything - An optional boolean value that controls how far to the front the canvas should be placed. Defaults to false. if true, place the canvas on top of all windows (including the dock and menubar and fullscreen windows). if false, place the canvas above normal windows, but below the dock, menubar and fullscreen windows.
Returns	The canvas object
Notes	As of macOS Sierra and later, if you want a hs.canvas object to appear above full-screen windows you must hide the Hammerspoon Dock icon first using: hs.dockicon.hide()

canvasDefaultFor

| Signature | hs.canvas:canvasDefaultFor(keyName, [newValue]) -> canvasObject | currentValue | | -----------------------------------------------------|---------------------------------------------------------------------------------------------------------| | Type | Method | | Description | Get or set the element default specified by keyName. | | Parameters |

• keyName - the element default to examine or modify
• value - an optional new value to set as the default fot his canvas when not specified explicitly in an element declaration.

| | Returns |

• If an argument is provided, the canvas object; otherwise the current value.

| | Notes |

• Not all keys will apply to all element types.
• Currently set and built-in defaults may be retrieved in a table with hs.canvas:canvasDefaults.

|

canvasDefaultKeys

Signature	hs.canvas:canvasDefaultKeys([module]) -> table
Type	Method
Description	Returns a list of the key names for the attributes set for the canvas defaults.
Parameters	module - an optional boolean flag, default false, indicating whether the key names for the module defaults (true) should be included in the list. If false, only those defaults which have been explicitly set for the canvas are included.
Returns	a table containing the key names for the defaults which are set for this canvas. May also optionally include key names for all attributes which have a default value defined by the module.

canvasDefaults

Signature	hs.canvas:canvasDefaults([module]) -> table
Type	Method
Description	Get a table of the default key-value pairs which apply to the canvas.
Parameters	module - an optional boolean flag, default false, indicating whether module defaults (true) should be included in the table. If false, only those defaults which have been explicitly set for the canvas are returned.
Returns	a table containing key-value pairs for the defaults which apply to the canvas.
Notes	Not all keys will apply to all element types. To change the defaults for the canvas, use hs.canvas:canvasDefaultFor.

canvasElements

Signature	hs.canvas:canvasElements() -> table
Type	Method
Description	Returns an array containing the elements defined for this canvas. Each array entry will be a table containing the key-value pairs which have been set for that canvas element.
Parameters	None
Returns	an array of element tables which are defined for the canvas.

canvasMouseEvents

| Signature | hs.canvas:canvasMouseEvents([down], [up], [enterExit], [move]) -> canvasObject | current values | | -----------------------------------------------------|---------------------------------------------------------------------------------------------------------| | Type | Method | | Description | Get or set whether or not regions of the canvas which are not otherwise covered by an element with mouse tracking enabled should generate a callback for mouse events. | | Parameters |

• down - an optional boolean, or nil placeholder, specifying whether or not the mouse button being pushed down should generate a callback for the canvas areas not otherwise covered by an element with mouse tracking enabled.
• up - an optional boolean, or nil placeholder, specifying whether or not the mouse button being released should generate a callback for the canvas areas not otherwise covered by an element with mouse tracking enabled.
• enterExit - an optional boolean, or nil placeholder, specifying whether or not the mouse pointer entering or exiting the canvas bounds should generate a callback for the canvas areas not otherwise covered by an element with mouse tracking enabled.
• move - an optional boolean, or nil placeholder, specifying whether or not the mouse pointer moving within the canvas bounds should generate a callback for the canvas areas not otherwise covered by an element with mouse tracking enabled.

| | Returns |

• If any arguments are provided, returns the canvas Object, otherwise returns the current values as four separate boolean values (i.e. not in a table).

| | Notes |

• Each value that you wish to set must be provided in the order given above, but you may specify a position as nil to indicate that whatever it's current state, no change should be applied. For example, to activate a callback for entering and exiting the canvas without changing the current callback status for up or down button clicks, you could use: hs.canvas:canvasMouseTracking(nil, nil, true).

|

clickActivating

| Signature | hs.canvas:clickActivating([flag]) -> canvasObject | currentValue | | -----------------------------------------------------|---------------------------------------------------------------------------------------------------------| | Type | Method | | Description | Get or set whether or not clicking on a canvas with a click callback defined should bring all of Hammerspoon's open windows to the front. | | Parameters |

• flag - an optional boolean indicating whether or not clicking on a canvas with a click callback function defined should activate Hammerspoon and bring its windows forward. Defaults to true.

| | Returns |

• If an argument is provided, returns the canvas object; otherwise returns the current setting.

| | Notes |

• Setting this to false changes a canvas object's AXsubrole value and may affect the results of filters used with hs.window.filter, depending upon how they are defined.

|

copy

Signature	hs.canvas:copy() -> canvasObject
Type	Method
Description	Creates a copy of the canvas.
Parameters	None
Returns	a copy of the canvas
Notes	The copy of the canvas will be identical in all respectes except: The new canvas will not have a callback function assigned, even if the original canvas does. The new canvas will not initially be visible, even if the original is. The new canvas is an independant entity -- any subsequent changes to either canvas will not be reflected in the other canvas.

delete

Signature	hs.canvas:delete([fadeOutTime]) -> none
Type	Method
Description	Destroys the canvas object, optionally fading it out first (if currently visible).
Parameters	fadeOutTime - An optional number of seconds over which to fade out the canvas object. Defaults to zero.
Returns	None
Notes	This method is automatically called during garbage collection, notably during a Hammerspoon termination or reload, with a fade time of 0.

draggingCallback

Signature	hs.canvas:draggingCallback(fn) -> canvasObject
Type	Method
Description	Sets or remove a callback for accepting dragging and dropping items onto the canvas.
Parameters	fn - A function, can be nil, that will be called when an item is dragged onto the canvas. An explicit nil, the default, disables drag-and-drop for this canvas.
Returns	The canvas object
Notes	The callback function should expect 3 arguments and optionally return 1: the canvas object itself, a message specifying the type of dragging event, and a table containing details about the item(s) being dragged. The key-value pairs of the details table will be the following: pasteboard - the name of the pasteboard that contains the items being dragged sequence - an integer that uniquely identifies the dragging session. mouse - a point table containing the location of the mouse pointer within the canvas corresponding to when the callback occurred. operation - a table containing string descriptions of the type of dragging the source application supports. Potentially useful for determining if your callback function should accept the dragged item or not.

elementAttribute

| Signature | hs.canvas:elementAttribute(index, key, [value]) -> canvasObject | current value | | -----------------------------------------------------|---------------------------------------------------------------------------------------------------------| | Type | Method | | Description | Get or set the attribute key for the canvas element at the specified index. | | Parameters |

• index - the index of the canvas element whose attribute is to be retrieved or set.
• key - the key name of the attribute to get or set.
• value - an optional value to assign to the canvas element's attribute.

| | Returns |

• if a value for the attribute is specified, returns the canvas object; otherwise returns the current value for the specified attribute.

|

elementBounds

Signature	hs.canvas:elementBounds(index) -> rectTable
Type	Method
Description	Returns the smallest rectangle which can fully contain the canvas element at the specified index.
Parameters	index - the index of the canvas element to get the bounds for
Returns	a rect table containing the smallest rectangle which can fully contain the canvas element.
Notes	For many elements, this will be the same as the element frame. For items without a frame (e.g. segments, circle, etc.) this will be the smallest rectangle which can fully contain the canvas element as specified by it's attributes.

elementCount

Signature	hs.canvas:elementCount() -> integer
Type	Method
Description	Returns the number of elements currently defined for the canvas object.
Parameters	None
Returns	the number of elements currently defined for the canvas object.

elementKeys

Signature	hs.canvas:elementKeys(index, [optional]) -> table
Type	Method
Description	Returns a list of the key names for the attributes set for the canvas element at the specified index.
Parameters	index - the index of the element to get the assigned key list from. optional - an optional boolean, default false, indicating whether optional, but unset, keys relevant to this canvas object should also be included in the list returned.
Returns	a table containing the keys that are set for this canvas element. May also optionally include keys which are not specifically set for this element but use inherited values from the canvas or module defaults.
Notes	Any attribute which has been explicitly set for the element will be included in the key list (even if it is ignored for the element type). If the optional flag is set to true, the additional attribute names added to the list will only include those which are relevant to the element type.

frame

| Signature | hs.canvas:frame([rect]) -> canvasObject | currentValue | | -----------------------------------------------------|---------------------------------------------------------------------------------------------------------| | Type | Method | | Description | Get or set the frame of the canvasObject. | | Parameters |

• rect - An optional rect-table containing the co-ordinates and size the canvas object should be moved and set to

| | Returns |

• If an argument is provided, the canvas object; otherwise the current value.

| | Notes |

• a rect-table is a table with key-value pairs specifying the new top-left coordinate on the screen of the canvas (keys x and y) and the new size (keys h and w). The table may be crafted by any method which includes these keys, including the use of an hs.geometry object.

|

hide

Signature	hs.canvas:hide([fadeOutTime]) -> canvasObject
Type	Method
Description	Hides the canvas object
Parameters	fadeOutTime - An optional number of seconds over which to fade out the canvas object. Defaults to zero.
Returns	The canvas object

imageFromCanvas

Signature	hs.canvas:imageFromCanvas() -> hs.image object
Type	Method
Description	Returns an image of the canvas contents as an hs.image object.
Parameters	None
Returns	an hs.image object
Notes	The canvas does not have to be visible in order for an image to be generated from it.

insertElement

Signature	hs.canvas:insertElement(elementTable, [index]) -> canvasObject
Type	Method
Description	Insert a new element into the canvas at the specified index.
Parameters	elementTable - a table containing key-value pairs that define the element to be added to the canvas. index - an optional integer between 1 and the canvas element count + 1 specifying the index position to put the new element. Any element currently at that index, and those that follow, will be moved one position up in the element array. Defaults to the canvas element count + 1 (i.e. after the end of the currently defined elements).
Returns	the canvasObject
Notes	see also hs.canvas:assignElement.

isOccluded

Signature	hs.canvas:isOccluded() -> boolean
Type	Method
Description	Returns whether or not the canvas is currently occluded (hidden by other windows, off screen, etc).
Parameters	None
Returns	a boolean indicating whether or not the canvas is currently being occluded.
Notes	If any part of the canvas is visible (even if that portion of the canvas does not contain any canvas elements), then the canvas is not considered occluded. a canvas which is completely covered by one or more opaque windows is considered occluded; however, if the windows covering the canvas are not opaque, then the canvas is not occluded. a canvas that is currently hidden or with a height of 0 or a width of 0 is considered occluded. See also hs.canvas:isShowing.

isShowing

Signature	hs.canvas:isShowing() -> boolean
Type	Method
Description	Returns whether or not the canvas is currently being shown.
Parameters	None
Returns	a boolean indicating whether or not the canvas is currently being shown (true) or is currently hidden (false).
Notes	This method only determines whether or not the canvas is being shown or is hidden -- it does not indicate whether or not the canvas is currently off screen or is occluded by other objects. See also hs.canvas:isOccluded.

isVisible

Signature	hs.canvas:isVisible() -> boolean
Type	Method
Description	Returns whether or not the canvas is currently showing and is (at least partially) visible on screen.
Parameters	None
Returns	a boolean indicating whether or not the canvas is currently visible.
Notes	This is syntactic sugar for not hs.canvas:isOccluded(). See hs.canvas:isOccluded for more details.

level

| Signature | hs.canvas:level([level]) -> canvasObject | currentValue | | -----------------------------------------------------|---------------------------------------------------------------------------------------------------------| | Type | Method | | Description | Sets the window level more precisely than sendToBack and bringToFront. | | Parameters |

• level - an optional level, specified as a number or as a string, specifying the new window level for the canvasObject. If it is a string, it must match one of the keys in hs.canvas.windowLevels.

| | Returns |

• If an argument is provided, the canvas object; otherwise the current value.

|

minimumTextSize

Signature	hs.canvas:minimumTextSize([index], text) -> table
Type	Method
Description	Returns a table specifying the size of the rectangle which can fully render the text with the specified style so that is will be completely visible.
Parameters	index - an optional index specifying the element in the canvas which contains the text attributes which should be used when determining the size of the text. If not provided, the canvas defaults will be used instead. Ignored if text is an hs.styledtext object. text - a string or hs.styledtext object specifying the text.
Returns	a size table specifying the height and width of a rectangle which could fully contain the text when displayed in the canvas
Notes	Multi-line text (separated by a newline or return) is supported. The height will be for the multiple lines and the width returned will be for the longest line.

mouseCallback

Signature	hs.canvas:mouseCallback(mouseCallbackFn) -> canvasObject
Type	Method
Description	Sets a callback for mouse events with respect to the canvas
Parameters	mouseCallbackFn - A function, can be nil, that will be called when a mouse event occurs within the canvas, and an element beneath the mouse's current position has one of the trackMouse... attributes set to true.
Returns	The canvas object
Notes	The callback function should expect 5 arguments: the canvas object itself, a message specifying the type of mouse event, the canvas element id (or index position in the canvas if the id attribute is not set for the element), the x position of the mouse when the event was triggered within the rendered portion of the canvas element, and the y position of the mouse when the event was triggered within the rendered portion of the canvas element. See also hs.canvas:canvasMouseEvents for tracking mouse events in regions of the canvas not covered by an element with mouse tracking enabled.

orderAbove

Signature	hs.canvas:orderAbove([canvas2]) -> canvasObject
Type	Method
Description	Moves canvas object above canvas2, or all canvas objects in the same presentation level, if canvas2 is not given.
Parameters	canvas2 -An optional canvas object to place the canvas object above.
Returns	The canvas object
Notes	If the canvas object and canvas2 are not at the same presentation level, this method will will move the canvas object as close to the desired relationship as possible without changing the canvas object's presentation level. See hs.canvas.level.

orderBelow

Signature	hs.canvas:orderBelow([canvas2]) -> canvasObject
Type	Method
Description	Moves canvas object below canvas2, or all canvas objects in the same presentation level, if canvas2 is not given.
Parameters	canvas2 -An optional canvas object to place the canvas object below.
Returns	The canvas object
Notes	If the canvas object and canvas2 are not at the same presentation level, this method will will move the canvas object as close to the desired relationship as possible without changing the canvas object's presentation level. See hs.canvas.level.

removeElement

Signature	hs.canvas:removeElement([index]) -> canvasObject
Type	Method
Description	Insert a new element into the canvas at the specified index.
Parameters	index - an optional integer between 1 and the canvas element count specifying the index of the canvas element to remove. Any elements that follow, will be moved one position down in the element array. Defaults to the canvas element count (i.e. the last element of the currently defined elements).
Returns	the canvasObject

replaceElements

Signature	hs.canvas:replaceElements(element...) -> canvasObject
Type	Method
Description	Replaces all of the elements in the canvas with the elements specified. Shortens or lengthens the canvas element count if necessary to accomodate the new canvas elements.
Parameters	element - a table containing key-value pairs that define the element to be assigned to the canvas. You can specify one or more elements and they will be appended in the order they are listed.
Returns	the canvas object
Notes	You can also specify multiple elements in a table as an array, where each index in the table contains an element table, and use the array as a single argument to this method if this style works better in your code.

rotateElement

Signature	hs.canvas:rotateElement(index, angle, [point], [append]) -> canvasObject
Type	Method
Description	Rotates an element about the point specified, or the elements center if no point is specified.
Parameters	index - the index of the element to rotate angle - the angle to rotate the object in a clockwise direction point - an optional point table, defaulting to the elements center, specifying the point around which the object should be rotated append - an optional boolean, default false, specifying whether or not the rotation transformation matrix should be appended to the existing transformation assigned to the element (true) or replace it (false).
Returns	the canvas object
Notes	a point-table is a table with key-value pairs specifying a coordinate in the canvas (keys x and y). The table may be crafted by any method which includes these keys, including the use of an hs.geometry object. The center of the object is determined by getting the element's bounds with hs.canvas:elementBounds. If the third argument is a boolean value, the point argument is assumed to be the element's center and the boolean value is used as the append argument.

sendToBack

Signature	hs.canvas:sendToBack() -> canvasObject
Type	Method
Description	Places the canvas object behind normal windows, between the desktop wallpaper and desktop icons
Parameters	None
Returns	The canvas object

show

Signature	hs.canvas:show([fadeInTime]) -> canvasObject
Type	Method
Description	Displays the canvas object
Parameters	fadeInTime - An optional number of seconds over which to fade in the canvas object. Defaults to zero.
Returns	The canvas object
Notes	if the canvas is in use as an element in another canvas, this method will result in an error.

size

| Signature | hs.canvas:size([size]) -> canvasObject | currentValue | | -----------------------------------------------------|---------------------------------------------------------------------------------------------------------| | Type | Method | | Description | Get or set the size of a canvas object | | Parameters |

• size - An optional size-table specifying the width and height the canvas object should be resized to

| | Returns |

• If an argument is provided, the canvas object; otherwise the current value.

| | Notes |

• a size-table is a table with key-value pairs specifying the size (keys h and w) the canvas should be resized to. The table may be crafted by any method which includes these keys, including the use of an hs.geometry object.

|

topLeft

| Signature | hs.canvas:topLeft([point]) -> canvasObject | currentValue | | -----------------------------------------------------|---------------------------------------------------------------------------------------------------------| | Type | Method | | Description | Get or set the top-left coordinate of the canvas object | | Parameters |

• point - An optional point-table specifying the new coordinate the top-left of the canvas object should be moved to

| | Returns |

• If an argument is provided, the canvas object; otherwise the current value.

| | Notes |

• a point-table is a table with key-value pairs specifying the new top-left coordinate on the screen of the canvas (keys x and y). The table may be crafted by any method which includes these keys, including the use of an hs.geometry object.

|

transformation

| Signature | hs.canvas:transformation([matrix]) -> canvasObject | current value | | -----------------------------------------------------|---------------------------------------------------------------------------------------------------------| | Type | Method | | Description | Get or set the matrix transformation which is applied to every element in the canvas before being individually processed and added to the canvas. | | Parameters |

• matrix - an optional table specifying the matrix table, as defined by the hs.canvas.matrix module, to be applied to every element of the canvas, or an explicit nil to reset the transformation to the identity matrix.

| | Returns |

• if an argument is provided, returns the canvasObject, otherwise returns the current value

| | Notes |

• An example use for this method would be to change the canvas's origin point { x = 0, y = 0 } from the lower left corner of the canvas to somewhere else, like the middle of the canvas.

|

wantsLayer

| Signature | hs.canvas:wantsLayer([flag]) -> canvasObject | currentValue | | -----------------------------------------------------|---------------------------------------------------------------------------------------------------------| | Type | Method | | Description | Get or set whether or not the canvas object should be rendered by the view or by Core Animation. | | Parameters |

• flag - optional boolean (default false) which indicates whether the canvas object should be rendered by the containing view (false) or by Core Animation (true).

| | Returns |

• If an argument is provided, the canvas object; otherwise the current value.

| | Notes |

• This method can help smooth the display of small text objects on non-Retina monitors.

|