drawing

​
DEPRECATED. Primitives for drawing on the screen in various ways.
hs.drawing is now deprecated and will be removed in a future release. Its functionality is now implemented by hs.canvas and you should migrate your code to using that directly. The API docs for hs.drawing remain here as a convenience.
Submodules
​hs.drawing.color​
API Overview
Constants - Useful values which cannot be changed
​windowBehaviors​
​windowLevels​
Functions - API calls offered directly by the extension
​defaultTextStyle​
​disableScreenUpdates​
​enableScreenUpdates​
​getTextDrawingSize​
Constructors - API calls which return an object, typically one that offers API methods
​appImage​
​arc​
​circle​
​ellipticalArc​
​image​
​line​
​rectangle​
​text​
Methods - API calls which can only be made on an object returned by a constructor
​alpha​
​behavior​
​behaviorAsLabels​
​bringToFront​
​clickCallbackActivating​
​clippingRectangle​
​delete​
​frame​
​getStyledText​
​hide​
​imageAlignment​
​imageAnimates​
​imageFrame​
​imageScaling​
​orderAbove​
​orderBelow​
​rotateImage​
​sendToBack​
​setAlpha​
​setArcAngles​
​setBehavior​
​setBehaviorByLabels​
​setClickCallback​
​setFill​
​setFillColor​
​setFillGradient​
​setFrame​
​setImage​
​setImageASCII​
​setImageFromPath​
​setLevel​
​setRoundedRectRadii​
​setSize​
​setStroke​
​setStrokeColor​
​setStrokeWidth​
​setStyledText​
​setText​
​setTextColor​
​setTextFont​
​setTextSize​
​setTextStyle​
​setTopLeft​
​show​
API Documentation
Constants
​windowBehaviors​
Signature
hs.drawing.windowBehaviors[]
Type
Constant
Description
Array of window behavior labels for determining how an hs.drawing object is handled in Spaces and Exposé
Notes
This table has a __tostring() metamethod which allows listing it's contents in the Hammerspoon console by typing hs.drawing.windowBehaviors.
​windowLevels​
Signature
hs.drawing.windowLevels
Type
Constant
Description
A table of predefined window levels usable with hs.drawing:setLevel(...)
Notes
This table has a __tostring() metamethod which allows listing it's contents in the Hammerspoon console by typing hs.drawing.windowLevels.
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 drawing level is sorted separately and hs.drawing:orderAbove(...) and hs.drawing: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.drawing.defaultTextStyle() -> hs.styledtext attributes table
Type
Function
Description
Returns a table containing the default font, size, color, and paragraphStyle used by hs.drawing for text drawing objects.
Parameters
None
Returns
a table containing the default style attributes hs.drawing uses for text drawing objects in the hs.styledtext attributes table format.
Notes
This method returns the default font, size, color, and paragraphStyle used by hs.drawing for text objects. If you modify a drawing object's defaults with hs.drawing:setColor, hs.drawing:setTextFont, or hs.drawing:setTextSize, the changes will not be reflected by this function.
​disableScreenUpdates​
Signature
hs.drawing.disableScreenUpdates() -> None
Type
Function
Description
Tells the OS X window server to pause updating the physical displays for a short while.
Parameters
None
Returns
None
Notes
This method can be used to allow multiple changes which are being made to the users display appear as if they all occur simultaneously by holding off on updating the screen on the regular schedule.
This method should always be balanced with a call to hs.drawing.enableScreenUpdates when your updates have been completed. Failure to do so will be logged in the system logs.
The window server will only allow you to pause updates for up to 1 second. This prevents a rogue or hung process from locking the systems display completely. Updates will be resumed when hs.drawing.enableScreenUpdates is encountered or after 1 second, whichever comes first.
The underlying OS function for disabling screen updates is deprecated.
​enableScreenUpdates​
Signature
hs.drawing.enableScreenUpdates() -> None
Type
Function
Description
Tells the OS X window server to resume updating the physical displays after a previous pause.
Parameters
None
Returns
None
Notes
In conjunction with hs.drawing.disableScreenUpdates, this method can be used to allow multiple changes which are being made to the users display appear as if they all occur simultaneously by holding off on updating the screen on the regular schedule.
The window server will only allow you to pause updates for up to 1 second. This prevents a rogue or hung process from locking the systems display completely. Updates will be resumed when this function is encountered or after 1 second, whichever comes first.
The underlying OS function for enabling screen updates is deprecated.
​getTextDrawingSize​
| Signature | hs.drawing.getTextDrawingSize(styledTextObject or theText, [textStyle]) -> sizeTable | nil | | -----------------------------------------------------|---------------------------------------------------------------------------------------------------------| | Type | Function | | Description | Get the size of the rectangle necessary to fully render the text with the specified style so that is will be completely visible. | | Parameters |
styledTextObject - an object created with the hs.styledtext module or its table representation (see hs.styledtext).
textStyle - an optional table containing one or more of the following keys to set for the text of the drawing object (if textStyle is nil or missing, the hs.drawing defaults are used):
| | Returns |
sizeTable - a table containing the Height and Width necessary to fully display the text drawing object, or nil if an error occurred
| | Notes |
This function assumes the default values specified for any key which is not included in the provided textStyle.
The size returned is an approximation and may return a width that is off by about 4 points. Use the returned size as a minimum starting point. Sometimes using the "clip" or "truncateMiddle" lineBreak modes or "justified" alignment will fit, but its safest to add in your own buffer if you have the space in your layout.
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.
|
Constructors
​appImage​
Signature
hs.drawing.appImage(sizeRect, bundleID) -> drawingObject or nil
Type
Constructor
Description
Creates a new image object with the icon of a given app
Parameters
sizeRect - A rect-table containing the location/size of the image. If the size values are -1 then the image will be displayed at the icon's native size
bundleID - A string containing the bundle identifier of an app (e.g. "com.apple.Safari")
Returns
An hs.drawing object, or nil if an error occurs
​arc​
Signature
hs.drawing.arc(centerPoint, radius, startAngle, endAngle) -> drawingObject or nil
Type
Constructor
Description
Creates a new arc object
Parameters
centerPoint - A point-table containing the center of the circle used to define the arc
radius - The radius of the circle used to define the arc
startAngle - The starting angle of the arc, measured in degrees clockwise from the y-axis.
endAngle - The ending angle of the arc, measured in degrees clockwise from the y-axis.
Returns
An hs.drawing object, or nil if an error occurs
Notes
This constructor is actually a wrapper for the hs.drawing.ellipticalArc constructor.
​circle​
Signature
hs.drawing.circle(sizeRect) -> drawingObject or nil
Type
Constructor
Description
Creates a new circle object
Parameters
sizeRect - A rect-table containing the location/size of the circle
Returns
An hs.drawing object, or nil if an error occurs
​ellipticalArc​
Signature
hs.drawing.ellipticalArc(sizeRect, startAngle, endAngle) -> drawingObject or nil
Type
Constructor
Description
Creates a new elliptical arc object
Parameters
sizeRect - A rect-table containing the location and size of the ellipse used to define the arc
startAngle - The starting angle of the arc, measured in degrees clockwise from the y-axis.
endAngle - The ending angle of the arc, measured in degrees clockwise from the y-axis.
Returns
An hs.drawing object, or nil if an error occurs
​image​
Signature
hs.drawing.image(sizeRect, imageData) -> drawingObject or nil
Type
Constructor
Description
Creates a new image object
Parameters
sizeRect - A rect-table containing the location/size of the image
imageData - This can be either:
An hs.image object
A string containing a path to an image file
A string beginning with ASCII: which signifies that the rest of the string is interpreted as a special form of ASCII diagram, which will be rendered to an image. See the notes below for information about the special format of ASCII diagram.
Returns
An hs.drawing object, or nil if an error occurs
Paths relative to the PWD of Hammerspoon (typically /.hammerspoon/) will work, but paths relative to the UNIX homedir character, will not
Animated GIFs are supported. They're not super friendly on your CPU, but they work
Notes
To use the ASCII diagram image support, see http://cocoamine.net/blog/2015/03/20/replacing-photoshop-with-nsstring/ and be sure to preface your ASCII diagram with the special string ASCII:
​line​
Signature
hs.drawing.line(originPoint, endPoint) -> drawingObject or nil
Type
Constructor
Description
Creates a new line object
Parameters
originPoint - A point-table containing the co-ordinates of the starting point of the line
endPoint - A point-table containing the co-ordinates of the end point of the line
Returns
An hs.drawing object, or nil if an error occurs
​rectangle​
Signature
hs.drawing.rectangle(sizeRect) -> drawingObject or nil
Type
Constructor
Description
Creates a new rectangle object
Parameters
sizeRect - A rect-table containing the location/size of the rectangle
Returns
An hs.drawing object, or nil if an error occurs
​text​
Signature
hs.drawing.text(sizeRect, message) -> drawingObject or nil
Type
Constructor
Description
Creates a new text object
Parameters
sizeRect - A rect-table containing the location/size of the text
message - A string containing the text to be displayed. May also be any of the types supported by hs.styledtext. See hs.styledtext for more details.
Returns
An hs.drawing object, or nil if an error occurs
Methods
​alpha​
Signature
hs.drawing:alpha() -> number
Type
Method
Description
Get the alpha level of the window containing the hs.drawing object.
Parameters
None
Returns
The current alpha level for the hs.drawing object
​behavior​
Signature
hs.drawing:behavior() -> number
Type
Method
Description
Returns the current behavior of the hs.drawing object with respect to Spaces and Exposé for the object.
Parameters
None
Returns
The numeric representation of the current behaviors for the hs.drawing object
​behaviorAsLabels​
Signature
hs.drawing:behaviorAsLabels() -> table
Type
Method
Description
Returns a table of the labels for the current behaviors of the object.
Parameters
None
Returns
Returns a table of the labels for the current behaviors with respect to Spaces and Exposé for the object.
​bringToFront​
Signature
hs.drawing:bringToFront([aboveEverything]) -> drawingObject
Type
Method
Description
Places the drawing object on top of normal windows
Parameters
aboveEverything - An optional boolean value that controls how far to the front the drawing should be placed. true to place the drawing on top of all windows (including the dock and menubar), false to place the drawing above normal windows, but below the dock and menubar. Defaults to false.
Returns
The drawing object
Notes
As of macOS Sierra and later, if you want a hs.drawing object to appear above full-screen windows you must hide the Hammerspoon Dock icon first using: hs.dockicon.hide()
​clickCallbackActivating​
Signature
hs.drawing:clickCallbackActivating([false]) -> drawingObject or current value
Type
Method
Description
Get or set whether or not clicking on a drawing 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 drawing with a click callback function defined should activate Hammerspoon and bring its windows forward. Defaults to true.
Returns
If a setting value is provided, the drawing object is returned; if no argument is provided, the current setting is returned.
Notes
Setting this to false changes a drawing object's AXsubrole value and may affect the results of filters defined for hs.window.filter, depending upon how they are defined.
​clippingRectangle​
Signature
hs.drawing:clippingRectangle([rect]) -> drawingObject or current value
Type
Method
Description
Set the screen area in which the drawing contents are visible.
Parameters
rect - an optional rectangle specifying the visible area of the screen where the drawing's contents are visible. If an explicit nil is specified, no clipping rectangle is set. Defaults to nil
Returns
if an argument is provided, returns the drawing object; otherwise the current value is returned.
Notes
This method can be used to specify the area of the display where this drawing should be visible. If any portion of the drawing extends beyond this rectangle, the image is clipped so that only the portion within this rectangle is visible.
The rectangle defined by this method is independant of the drawing's actual frame -- if you move the drawing with hs.drawing:setFrame or hs.drawing:setTopLeft, this rectangle retains its current value.
​delete​
Signature
hs.drawing:delete()
Type
Method
Description
Destroys the drawing object
Parameters
None
Returns
None
Notes
This method immediately destroys the drawing object. If you want it to fade out, use :hide() first, with some suitable time, and hs.timer.doAfter() to schedule the :delete() call
​frame​
Signature
hs.drawing:frame() -> hs.geometry object
Type
Method
Description
Gets the frame of a drawingObject in absolute coordinates
Parameters
None
Returns
An hs.geometry object containing the frame of the drawing object
​getStyledText​
Signature
hs.drawing:getStyledText() -> hs.styledtext object
Type
Method
Description
Gets the text of a drawing object as an hs.styledtext object
Parameters
None
Returns
an hs.styledtext object
Notes
This method should only be used on text drawing objects
​hide​
Signature
hs.drawing:hide([fadeOutTime]) -> drawingObject
Type
Method
Description
Hides the drawing object
Parameters
fadeOut - An optional number of seconds over which to fade out the drawing object. Defaults to zero
Returns
The drawing object
​imageAlignment​
Signature
hs.drawing:imageAlignment([type]) -> drawingObject or current value
Type
Method
Description
Get or set the alignment of an image that doesn't fully fill the drawing objects frame.
Parameters
type - an optional string value which should match one of the following (default is center):
topLeft - the image's top left corner will match the drawing frame's top left corner
top - the image's top match the drawing frame's top and will be centered horizontally
topRight - the image's top right corner will match the drawing frame's top right corner
left - the image's left side will match the drawing frame's left side and will be centered vertically
center - the image will be centered vertically and horizontally within the drawing frame
right - the image's right side will match the drawing frame's right side and will be centered vertically
bottomLeft - the image's bottom left corner will match the drawing frame's bottom left corner
bottom - the image's bottom match the drawing frame's bottom and will be centered horizontally
bottomRight - the image's bottom right corner will match the drawing frame's bottom right corner
Returns
If a setting value is provided, the drawing object is returned; if no argument is provided, the current setting is returned.
​imageAnimates​
Signature
hs.drawing:imageAnimates([flag]) -> drawingObject or current value
Type
Method
Description
Get or set whether or not an animated GIF image should cycle through its animation.
Parameters
flag - an optional boolean flag indicating whether or not an animated GIF image should cycle through its animation. Defaults to true.
Returns
If a setting value is provided, the drawing object is returned; if no argument is provided, the current setting is returned.
​imageFrame​
Signature
hs.drawing:imageFrame([type]) -> drawingObject or current value
Type
Method
Description
Get or set what type of frame should be around the drawing frame of the image.
Parameters
type - an optional string value which should match one of the following (default is none):
none - no frame is drawing around the drawingObject's frameRect
photo - a thin black outline with a white background and a dropped shadow.
bezel - a gray, concave bezel with no background that makes the image look sunken.
groove - a thin groove with a gray background that looks etched around the image.
button - a convex bezel with a gray background that makes the image stand out in relief, like a button.
Returns
If a setting value is provided, the drawing object is returned; if no argument is provided, the current setting is returned.
Notes
Apple considers the photo, groove, and button style frames "stylistically obsolete" and if a frame is required, recommend that you use the bezel style or draw your own to more closely match the OS look and feel.
​imageScaling​
Signature
hs.drawing:imageScaling([type]) -> drawingObject or current value
Type
Method
Description
Get or set how an image is scaled within the frame of a drawing object containing an image.
Parameters
type - an optional string value which should match one of the following (default is scaleProportionally):
shrinkToFit - shrink the image, preserving the aspect ratio, to fit the drawing frame only if the image is larger than the drawing frame.
scaleToFit - shrink or expand the image to fully fill the drawing frame. This does not preserve the aspect ratio.
none - perform no scaling or resizing of the image.
scalePropertionally - shrink or expand the image to fully fill the drawing frame, preserving the aspect ration.
Returns
If a setting value is provided, the drawing object is returned; if no argument is provided, the current setting is returned.

Signature	`hs.drawing.windowBehaviors[]`
Type	Constant
Description	Array of window behavior labels for determining how an hs.drawing object is handled in Spaces and Exposé
Notes	This table has a __tostring() metamethod which allows listing it's contents in the Hammerspoon console by typing `hs.drawing.windowBehaviors`.

Signature	`hs.drawing.windowLevels`
Type	Constant
Description	A table of predefined window levels usable with `hs.drawing:setLevel(...)`
Notes	This table has a __tostring() metamethod which allows listing it's contents in the Hammerspoon console by typing `hs.drawing.windowLevels`. 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 drawing level is sorted separately and `hs.drawing:orderAbove(...)` and hs.drawing: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.

Signature	`hs.drawing.defaultTextStyle() ->` hs.styledtext `attributes table`
Type	Function
Description	Returns a table containing the default font, size, color, and paragraphStyle used by `hs.drawing` for text drawing objects.
Parameters	None
Returns	a table containing the default style attributes `hs.drawing` uses for text drawing objects in the `hs.styledtext` attributes table format.
Notes	This method returns the default font, size, color, and paragraphStyle used by `hs.drawing` for text objects. If you modify a drawing object's defaults with `hs.drawing:setColor`, `hs.drawing:setTextFont`, or `hs.drawing:setTextSize`, the changes will not be reflected by this function.

Signature	`hs.drawing.disableScreenUpdates() -> None`
Type	Function
Description	Tells the OS X window server to pause updating the physical displays for a short while.
Parameters	None
Returns	None
Notes	This method can be used to allow multiple changes which are being made to the users display appear as if they all occur simultaneously by holding off on updating the screen on the regular schedule. This method should always be balanced with a call to hs.drawing.enableScreenUpdates when your updates have been completed. Failure to do so will be logged in the system logs. The window server will only allow you to pause updates for up to 1 second. This prevents a rogue or hung process from locking the systems display completely. Updates will be resumed when hs.drawing.enableScreenUpdates is encountered or after 1 second, whichever comes first. The underlying OS function for disabling screen updates is deprecated.

Signature	`hs.drawing.enableScreenUpdates() -> None`
Type	Function
Description	Tells the OS X window server to resume updating the physical displays after a previous pause.
Parameters	None
Returns	None
Notes	In conjunction with hs.drawing.disableScreenUpdates, this method can be used to allow multiple changes which are being made to the users display appear as if they all occur simultaneously by holding off on updating the screen on the regular schedule. The window server will only allow you to pause updates for up to 1 second. This prevents a rogue or hung process from locking the systems display completely. Updates will be resumed when this function is encountered or after 1 second, whichever comes first. The underlying OS function for enabling screen updates is deprecated.

Signature	`hs.drawing.appImage(sizeRect, bundleID) -> drawingObject or nil`
Type	Constructor
Description	Creates a new image object with the icon of a given app
Parameters	sizeRect - A rect-table containing the location/size of the image. If the size values are -1 then the image will be displayed at the icon's native size bundleID - A string containing the bundle identifier of an app (e.g. "com.apple.Safari")
Returns	An `hs.drawing` object, or nil if an error occurs

Signature	`hs.drawing.arc(centerPoint, radius, startAngle, endAngle) -> drawingObject or nil`
Type	Constructor
Description	Creates a new arc object
Parameters	centerPoint - A point-table containing the center of the circle used to define the arc radius - The radius of the circle used to define the arc startAngle - The starting angle of the arc, measured in degrees clockwise from the y-axis. endAngle - The ending angle of the arc, measured in degrees clockwise from the y-axis.
Returns	An `hs.drawing` object, or nil if an error occurs
Notes	This constructor is actually a wrapper for the `hs.drawing.ellipticalArc` constructor.

Signature	`hs.drawing.circle(sizeRect) -> drawingObject or nil`
Type	Constructor
Description	Creates a new circle object
Parameters	sizeRect - A rect-table containing the location/size of the circle
Returns	An `hs.drawing` object, or nil if an error occurs

Signature	`hs.drawing.ellipticalArc(sizeRect, startAngle, endAngle) -> drawingObject or nil`
Type	Constructor
Description	Creates a new elliptical arc object
Parameters	sizeRect - A rect-table containing the location and size of the ellipse used to define the arc startAngle - The starting angle of the arc, measured in degrees clockwise from the y-axis. endAngle - The ending angle of the arc, measured in degrees clockwise from the y-axis.
Returns	An `hs.drawing` object, or nil if an error occurs

Signature	`hs.drawing.image(sizeRect, imageData) -> drawingObject or nil`
Type	Constructor
Description	Creates a new image object
Parameters	sizeRect - A rect-table containing the location/size of the image imageData - This can be either: An `hs.image` object A string containing a path to an image file A string beginning with `ASCII:` which signifies that the rest of the string is interpreted as a special form of ASCII diagram, which will be rendered to an image. See the notes below for information about the special format of ASCII diagram.
Returns	An `hs.drawing` object, or nil if an error occurs Paths relative to the PWD of Hammerspoon (typically /.hammerspoon/) will work, but paths relative to the UNIX homedir character, will not Animated GIFs are supported. They're not super friendly on your CPU, but they work
Notes	To use the ASCII diagram image support, see http://cocoamine.net/blog/2015/03/20/replacing-photoshop-with-nsstring/ and be sure to preface your ASCII diagram with the special string `ASCII:`

Signature	`hs.drawing.line(originPoint, endPoint) -> drawingObject or nil`
Type	Constructor
Description	Creates a new line object
Parameters	originPoint - A point-table containing the co-ordinates of the starting point of the line endPoint - A point-table containing the co-ordinates of the end point of the line
Returns	An `hs.drawing` object, or nil if an error occurs

Signature	`hs.drawing.rectangle(sizeRect) -> drawingObject or nil`
Type	Constructor
Description	Creates a new rectangle object
Parameters	sizeRect - A rect-table containing the location/size of the rectangle
Returns	An `hs.drawing` object, or nil if an error occurs

Signature	`hs.drawing.text(sizeRect, message) -> drawingObject or nil`
Type	Constructor
Description	Creates a new text object
Parameters	sizeRect - A rect-table containing the location/size of the text message - A string containing the text to be displayed. May also be any of the types supported by `hs.styledtext`. See `hs.styledtext` for more details.
Returns	An `hs.drawing` object, or nil if an error occurs

Signature	`hs.drawing:alpha() -> number`
Type	Method
Description	Get the alpha level of the window containing the hs.drawing object.
Parameters	None
Returns	The current alpha level for the hs.drawing object

Signature	`hs.drawing:behavior() -> number`
Type	Method
Description	Returns the current behavior of the hs.drawing object with respect to Spaces and Exposé for the object.
Parameters	None
Returns	The numeric representation of the current behaviors for the hs.drawing object

Signature	`hs.drawing:behaviorAsLabels() -> table`
Type	Method
Description	Returns a table of the labels for the current behaviors of the object.
Parameters	None
Returns	Returns a table of the labels for the current behaviors with respect to Spaces and Exposé for the object.

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

Signature	`hs.drawing:clickCallbackActivating([false]) -> drawingObject or current value`
Type	Method
Description	Get or set whether or not clicking on a drawing 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 drawing with a click callback function defined should activate Hammerspoon and bring its windows forward. Defaults to true.
Returns	If a setting value is provided, the drawing object is returned; if no argument is provided, the current setting is returned.
Notes	Setting this to false changes a drawing object's AXsubrole value and may affect the results of filters defined for hs.window.filter, depending upon how they are defined.

Signature	`hs.drawing:clippingRectangle([rect]) -> drawingObject or current value`
Type	Method
Description	Set the screen area in which the drawing contents are visible.
Parameters	rect - an optional rectangle specifying the visible area of the screen where the drawing's contents are visible. If an explicit `nil` is specified, no clipping rectangle is set. Defaults to nil
Returns	if an argument is provided, returns the drawing object; otherwise the current value is returned.
Notes	This method can be used to specify the area of the display where this drawing should be visible. If any portion of the drawing extends beyond this rectangle, the image is clipped so that only the portion within this rectangle is visible. The rectangle defined by this method is independant of the drawing's actual frame -- if you move the drawing with hs.drawing:setFrame or hs.drawing:setTopLeft, this rectangle retains its current value.

Signature	`hs.drawing:delete()`
Type	Method
Description	Destroys the drawing object
Parameters	None
Returns	None
Notes	This method immediately destroys the drawing object. If you want it to fade out, use `:hide()` first, with some suitable time, and `hs.timer.doAfter()` to schedule the `:delete()` call

Signature	`hs.drawing:frame() -> hs.geometry object`
Type	Method
Description	Gets the frame of a drawingObject in absolute coordinates
Parameters	None
Returns	An `hs.geometry` object containing the frame of the drawing object

Signature	`hs.drawing:getStyledText() ->` hs.styledtext `object`
Type	Method
Description	Gets the text of a drawing object as an `hs.styledtext` object
Parameters	None
Returns	an `hs.styledtext` object
Notes	This method should only be used on text drawing objects

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

Signature	`hs.drawing:imageAlignment([type]) -> drawingObject or current value`
Type	Method
Description	Get or set the alignment of an image that doesn't fully fill the drawing objects frame.
Parameters	type - an optional string value which should match one of the following (default is center): topLeft - the image's top left corner will match the drawing frame's top left corner top - the image's top match the drawing frame's top and will be centered horizontally topRight - the image's top right corner will match the drawing frame's top right corner left - the image's left side will match the drawing frame's left side and will be centered vertically center - the image will be centered vertically and horizontally within the drawing frame right - the image's right side will match the drawing frame's right side and will be centered vertically bottomLeft - the image's bottom left corner will match the drawing frame's bottom left corner bottom - the image's bottom match the drawing frame's bottom and will be centered horizontally bottomRight - the image's bottom right corner will match the drawing frame's bottom right corner
Returns	If a setting value is provided, the drawing object is returned; if no argument is provided, the current setting is returned.

Signature	`hs.drawing:imageAnimates([flag]) -> drawingObject or current value`
Type	Method
Description	Get or set whether or not an animated GIF image should cycle through its animation.
Parameters	flag - an optional boolean flag indicating whether or not an animated GIF image should cycle through its animation. Defaults to true.
Returns	If a setting value is provided, the drawing object is returned; if no argument is provided, the current setting is returned.

drawing

Submodules

API Overview

API Documentation

Constants

​windowBehaviors​

​windowLevels​

Functions

​defaultTextStyle​

​disableScreenUpdates​

​enableScreenUpdates​

​getTextDrawingSize​

Constructors

​appImage​

​arc​

​circle​

​ellipticalArc​

​image​

​line​

​rectangle​

​text​

Methods

​alpha​

​behavior​

​behaviorAsLabels​

​bringToFront​

​clickCallbackActivating​

​clippingRectangle​

​delete​

​frame​

​getStyledText​

​hide​

​imageAlignment​

​imageAnimates​

​imageFrame​

​imageScaling​

windowBehaviors

windowLevels

defaultTextStyle

disableScreenUpdates

enableScreenUpdates

getTextDrawingSize

appImage

arc

circle

ellipticalArc

image

line

rectangle

text

alpha

behavior

behaviorAsLabels

bringToFront

clickCallbackActivating

clippingRectangle

delete

frame

getStyledText

hide

imageAlignment

imageAnimates

imageFrame

imageScaling

Signature	`hs.drawing:imageFrame([type]) -> drawingObject or current value`
Type	Method
Description	Get or set what type of frame should be around the drawing frame of the image.
Parameters	type - an optional string value which should match one of the following (default is none): none - no frame is drawing around the drawingObject's frameRect photo - a thin black outline with a white background and a dropped shadow. bezel - a gray, concave bezel with no background that makes the image look sunken. groove - a thin groove with a gray background that looks etched around the image. button - a convex bezel with a gray background that makes the image stand out in relief, like a button.
Returns	If a setting value is provided, the drawing object is returned; if no argument is provided, the current setting is returned.
Notes	Apple considers the photo, groove, and button style frames "stylistically obsolete" and if a frame is required, recommend that you use the bezel style or draw your own to more closely match the OS look and feel.

Signature	`hs.drawing:imageScaling([type]) -> drawingObject or current value`
Type	Method
Description	Get or set how an image is scaled within the frame of a drawing object containing an image.
Parameters	type - an optional string value which should match one of the following (default is scaleProportionally): shrinkToFit - shrink the image, preserving the aspect ratio, to fit the drawing frame only if the image is larger than the drawing frame. scaleToFit - shrink or expand the image to fully fill the drawing frame. This does not preserve the aspect ratio. none - perform no scaling or resizing of the image. scalePropertionally - shrink or expand the image to fully fill the drawing frame, preserving the aspect ration.
Returns	If a setting value is provided, the drawing object is returned; if no argument is provided, the current setting is returned.