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
If you wish to test out the hs.drawing
wrapper which may eventually replace the original hs.drawing
module entirely, check out hs.canvas.drawingWrapper.
Signature | hs.canvas.compositeTypes[] |
---|---|
Type | Constant |
Description | A table containing the possible compositing rules for elements within the canvas. Compositing rules specify how an element assigned to the canvas is combined with the earlier elements of the canvas. The default compositing rule for the canvas is The available types are as follows:
In each equation, R is the resulting (premultiplied) color, S is the source color, D is the destination color, Sa is the alpha value of the source color, and Da is the alpha value of the destination color. The |
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é
Only one of these may be active at a time:
The following have no effect on Only one of these may be active at a time:
Only one of these may be active at a time:
Only one of these may be active at a time (Available in OS X 10.11 and later):
|
Signature | hs.canvas.windowLevels |
---|---|
Type | Constant |
Description | A table of predefined window levels usable with hs.canvas:level Predefined levels are:
Notes:
|
Signature | hs.canvas.defaultTextStyle() -> |
---|---|
Type | Function |
Description | Returns a table containing the default font, size, color, and paragraphStyle used by Parameters:
Returns:
Notes:
|
Signature | hs.canvas.disableScreenUpdates() -> None |
---|---|
Type | Function |
Description | Tells the OS X window server to pause updating the physical displays for a short while. Parameters:
Returns:
Notes:
|
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:
Returns:
Notes:
|
Signature | hs.canvas.enableScreenUpdates() -> None |
---|---|
Type | Function |
Description | Tells the OS X window server to resume updating the physical displays after a previous pause. Parameters:
Returns:
Notes:
|
Signature | hs.canvas.help([attribute]) -> string |
---|---|
Type | Function |
Description | Provides specification information for the recognized attributes, or the specific attribute specified. Parameters:
Returns:
|
Signature | hs.canvas.new(rect) -> canvasObject |
---|---|
Type | Constructor |
Description | Create a new canvas object at the specified coordinates Parameters:
Returns:
Notes:
|
Signature | hs.canvas.attributes |
---|---|
Type | Field |
Description | Canvas Element Attributes
|
Signature | hs.canvas.object[index] |
---|---|
Type | Field |
Description | An array-like method for accessing the attributes for the canvas element at the specified index Metamethods are assigned to the canvas object so that you can refer to individual elements of the canvas as if the canvas object was an array. Each element is represented by a table of key-value pairs, where each key represents an attribute for that element. Valid index numbers range from 1 to hs.canvas:elementCount() when getting an element or getting or setting one of its attributes, and from 1 to hs.canvas:elementCount() + 1 when assign an element table to an index in the canvas. For example: c = require("hs.canvas")
a = c.new{ x = 100, y = 100, h = 100, w = 100 }:show()
a:insertElement({ type = "rectangle", id = "part1", fillColor = { blue = 1 } })
a:insertElement({ type = "circle", id = "part2", fillColor = { green = 1 } })
can also be expressed as: c = require("hs.canvas")
a = c.new{ x = 100, y = 100, h = 100, w = 100 }:show()
a[1] = { type = "rectangle", id = "part1", fillColor = { blue = 1 } }
a[2] = { type = "circle", id = "part2", fillColor = { green = 1 } }
You can change a canvas element's attributes using this same style: The canvas defaults can also be accessed with the Attributes which have a string specified as their It is important to note that these methods are a convenience and that the canvas object is not a true table. The tables are generated dynamically as needed; as such Attributes which allow using a string to specify a percentage (see percentages) can also be retrieved as their actual number for the canvas's current size by appending Because the canvas object is actually a Lua userdata, and not a real table, you cannot use the You can, however, remove the last element with To print out all of the elements in the canvas with: |
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. Percentages may be assigned to the following attributes:
Percentages are assigned to these fields as a string. If the number in the string ends with a percent sign (%), then the percentage is the whole number which precedes the percent sign. If no percent sign is present, the percentage is expected in decimal format (e.g. "1.0" is the same as "100%"). Because a shadow applied to a canvas element is not considered as part of the element's bounds, you can also set the |
Signature | hs.canvas:alpha([alpha]) -> canvasObject | currentValue |
---|---|
Type | Method |
Description | Get or set the alpha level of the window containing the canvasObject. Parameters:
Returns:
|
Signature | hs.canvas:appendElements(element, ...) -> canvasObject |
---|---|
Type | Method |
Description | Appends the elements specified to the canvas. Parameters:
Returns:
Notes:
|
Signature | hs.canvas:assignElement(elementTable, [index]) -> canvasObject |
---|---|
Type | Method |
Description | Assigns a new element to the canvas at the specified index. Parameters:
Returns:
Notes:
|
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:
Returns:
|
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:
Returns:
|
Signature | hs.canvas:bringToFront([aboveEverything]) -> canvasObject |
---|---|
Type | Method |
Description | Places the canvas object on top of normal windows Parameters:
Returns:
Notes:
|
Signature | hs.canvas:canvasDefaultFor(keyName, [newValue]) -> canvasObject | currentValue |
---|---|
Type | Method |
Description | Get or set the element default specified by keyName. Parameters:
Returns:
Notes:
|
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:
Returns:
|
Signature | hs.canvas:canvasDefaults([module]) -> table |
---|---|
Type | Method |
Description | Get a table of the default key-value pairs which apply to the canvas. Parameters:
Returns:
Notes:
|
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:
Returns:
|
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:
Returns:
Notes:
|
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:
Returns:
Notes:
|
Signature | hs.canvas:copy() -> canvasObject |
---|---|
Type | Method |
Description | Creates a copy of the canvas. Parameters:
Returns:
Notes:
|
Signature | hs.canvas:delete([fadeOutTime]) -> none |
---|---|
Type | Method |
Description | Destroys the canvas object, optionally fading it out first (if currently visible). Parameters:
Returns:
Notes:
|
Signature | hs.canvas:draggingCallback(fn | nil) -> canvasObject |
---|---|
Type | Method |
Description | Sets or remove a callback for accepting dragging and dropping items onto the canvas. Parameters:
Returns:
Notes:
|
Signature | hs.canvas:elementAttribute(index, key, [value]) -> canvasObject | current value |
---|---|
Type | Method |
Description | Get or set the attribute Parameters:
Returns:
|
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:
Returns:
Notes:
|
Signature | hs.canvas:elementCount() -> integer |
---|---|
Type | Method |
Description | Returns the number of elements currently defined for the canvas object. Parameters:
Returns:
|
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:
Returns:
Notes:
|
Signature | hs.canvas:frame([rect]) -> canvasObject | currentValue |
---|---|
Type | Method |
Description | Get or set the frame of the canvasObject. Parameters:
Returns:
Notes:
|
Signature | hs.canvas:hide([fadeOutTime]) -> canvasObject |
---|---|
Type | Method |
Description | Hides the canvas object Parameters:
Returns:
|
Signature | hs.canvas:imageFromCanvas() -> hs.image object |
---|---|
Type | Method |
Description | Returns an image of the canvas contents as an Parameters:
Returns:
Notes:
|
Signature | hs.canvas:insertElement(elementTable, [index]) -> canvasObject |
---|---|
Type | Method |
Description | Insert a new element into the canvas at the specified index. Parameters:
Returns:
Notes:
|
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:
Returns:
Notes:
|
Signature | hs.canvas:isShowing() -> boolean |
---|---|
Type | Method |
Description | Returns whether or not the canvas is currently being shown. Parameters:
Returns:
Notes:
|
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:
Returns:
Notes:
|
Signature | hs.canvas:level([level]) -> canvasObject | currentValue |
---|---|
Type | Method |
Description | Sets the window level more precisely than sendToBack and bringToFront. Parameters:
Returns:
|
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:
Returns:
Notes:
|
Signature | hs.canvas:mouseCallback(mouseCallbackFn) -> canvasObject |
---|---|
Type | Method |
Description | Sets a callback for mouse events with respect to the canvas Parameters:
Returns:
Notes:
|
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:
Returns:
Notes:
|
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:
Returns:
Notes:
|
Signature | hs.canvas:removeElement([index]) -> canvasObject |
---|---|
Type | Method |
Description | Insert a new element into the canvas at the specified index. Parameters:
Returns:
|
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:
Returns:
Notes:
|
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:
Returns:
Notes:
|
Signature | hs.canvas:sendToBack() -> canvasObject |
---|---|
Type | Method |
Description | Places the canvas object behind normal windows, between the desktop wallpaper and desktop icons Parameters:
Returns:
|
Signature | hs.canvas:show([fadeInTime]) -> canvasObject |
---|---|
Type | Method |
Description | Displays the canvas object Parameters:
Returns:
Notes:
|
Signature | hs.canvas:size([size]) -> canvasObject | currentValue |
---|---|
Type | Method |
Description | Get or set the size of a canvas object Parameters:
Returns:
Notes:
|
Signature | hs.canvas:topLeft([point]) -> canvasObject | currentValue |
---|---|
Type | Method |
Description | Get or set the top-left coordinate of the canvas object Parameters:
Returns:
Notes:
|
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:
Returns:
Notes:
|
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:
Returns:
Notes:
|