2023/10/1 -- This module is being archived. A replacement is in the works and can be found at hs._asm.uitk.
This module provides a window or panel which can be used to display a variety of graphical elements defined in the submodules or other Hammerspoon modules.
In the macOS, all visual elements are contained within a "window", though many of these windows have no extra decorations (title bar, close button, etc.). This module and its submodules is an attempt to provide a generic toolkit so that you can develop whatever type of visual interface you wish from a single set of tools rather then replicating code across multiple modules. Ultimately this module should be able to replace the other drawing or user interface modules and allow you to mix their components or even create completely new ones.
By itself, this module just creates the "window" and its methods describe how (or if) it should be visible, movable, etc. and provides a notification callback for potentially interesting events, for example when the "window" becomes visible, is moved, etc.
See hs._asm.guitk.manager
for more information on how to populate a guitkObject with visual elements and hs._asm.guitk.element
for a description of the currently supported visual elements which can included in a guitk window.
See https://github.com/asmagill/hammerspoon_asm/blob/master/README.md for details about building this module as a Universal library
A precompiled version of this module and its submodules can be found in this directory with a name along the lines of guitk-v0.x.tar.gz
. This can be installed by downloading the file and then expanding it as follows:
$ cd ~/.hammerspoon # or wherever your Hammerspoon init.lua file is located
$ tar -xzf ~/Downloads/guitk-v0.x.tar.gz # or wherever your downloads are located
If you wish to build this module and its submodules yourself, and have XCode installed on your Mac, the best way (you are welcome to clone the entire repository if you like, but no promises on the current state of anything) is to do the following:
$ svn export https://github.com/asmagill/hammerspoon_asm/trunk/guitk
$ cd guitk
$ [HS_APPLICATION=/Applications] [PREFIX=~/.hammerspoon] make docs install
$ cd manager
$ [HS_APPLICATION=/Applications] [PREFIX=~/.hammerspoon] make docs install
$ cd ../element
$ [HS_APPLICATION=/Applications] [PREFIX=~/.hammerspoon] make docs install
If your Hammerspoon application is located in /Applications
, you can leave out the HS_APPLICATION
environment variable, and if your Hammerspoon files are located in their default location, you can leave out the PREFIX
environment variable. For most people it will be sufficient to just type make docs install
in each of the directories specified above.
As always, whichever method you chose, if you are updating from an earlier version it is recommended to fully quit and restart Hammerspoon after installing this module to ensure that the latest version of the module is loaded into memory.
Examples of this module and some of the elements can be found in the Examples subdirectory.
guitk = require("hs._asm.guitk")
- guitk:accessibilitySubrole([label | nil]) -> guitkObject | string | nil
- guitk:activeElement([view | nil]) -> boolean | userdata
- guitk:allowTextEntry([value]) -> guitkObject | boolean
- guitk:alpha([alpha]) -> guitkObject | number
- guitk:animationBehavior([behavior]) -> guitkObject | string
- guitk:animationDuration([duration | nil]) -> guitkObject | number | nil
- guitk:appearance([appearance]) -> guitkObject | string
- guitk:backgroundColor([color]) -> guitkObject | color table
- guitk:bringToFront([aboveEverything]) -> guitkObject
- guitk:closeOnEscape([flag]) -> guitkObject | boolean
- guitk:collectionBehavior([behaviorMask]) -> guitkObject | integer
- guitk:contentManager([view | nil]) -> guitkObject | manager/element userdata
- guitk:delete([fadeOut]) -> none
- guitk:deleteOnClose([value]) -> guitkObject | boolean
- guitk:frame([rect], [animated]) -> guitkObject | rect-table
- guitk:hasShadow([state]) -> guitkObject | boolean
- guitk:hide([fadeOut]) -> guitkObject
- guitk:ignoresMouseEvents([state]) -> guitkObject | boolean
- guitk:isOccluded() -> boolean
- guitk:isShowing() -> boolean
- guitk:isVisible() -> boolean
- guitk:level([theLevel]) -> guitkObject | integer
- guitk:notificationCallback([fn | nil]) -> guitkObject | fn
- guitk:notificationMessages([notifications, [replace]]) -> guitkObject | table
- guitk:opaque([state]) -> guitkObject | boolean
- guitk:orderAbove([guitk2]) -> guitkObject
- guitk:orderBelow([guitk2]) -> guitkObject
- guitk:passthroughCallback([fn | nil]) -> guitkObject | fn | nil
- guitk:sendToBack() -> guitkObject
- guitk:show([fadeIn]) -> guitkObject
- guitk:simplifiedWindowCallback([fn]) -> guitkObject
- guitk:size([size], [animated]) -> guitkObject | rect-table
- guitk:styleMask([mask]) -> guitkObject | integer
- guitk:title([title]) -> guitkObject | string
- guitk:titlebarAppearsTransparent([state]) -> guitkObject | boolean
- guitk:titleVisibility([state]) -> guitkObject | currentValue
- guitk:topLeft([point], [animated]) -> guitkObject | rect-table
guitk.new(rect, [styleMask]) -> guitkObject
Creates a new empty guitk window.
Parameters:
rect
- a rect-table specifying the initial location and size of the guitk window.styleMask
- an optional integer specifying the style mask for the window as a combination of logically or'ed values from the hs._asm.guitk.masks table. Defaults totitled | closable | resizable | miniaturizable
(a standard macOS window with the appropriate titlebar and decorations).
Returns:
- the guitk object, or nil if there was an error creating the window.
Notes:
- a rect-table is a table with key-value pairs specifying the top-left coordinate on the screen of the guitk window (keys
x
andy
) and the size (keysh
andw
). The table may be crafted by any method which includes these keys, including the use of anhs.geometry
object.
guitk.newCanvas([rect]) -> guitkObject
Creates a new empty guitk window that is transparent and has no decorations.
Parameters:
rect
- an optional rect-table specifying the initial location and size of the guitk window.
Returns:
- the guitk object, or nil if there was an error creating the window.
Notes:
-
a rect-table is a table with key-value pairs specifying the top-left coordinate on the screen of the guitk window (keys
x
andy
) and the size (keysh
andw
). The table may be crafted by any method which includes these keys, including the use of anhs.geometry
object. -
this constructor creates an "invisible" container which is intended to display visual information only and does not accept user interaction by default, similar to an empty canvas created with
hs.canvas.new
. This is a shortcut for the following:
hs._asm.guitk.new(rect, hs._asm.guitk.masks.borderless):backgroundColor{ alpha = 0 }
:opaque(false)
:hasShadow(false)
:ignoresMouseEvents(true)
:allowTextEntry(false)
:animationBehavior("none")
:level(hs._asm.guitk.levels.screenSaver)
- If you do not specify
rect
, then the window will have no height or width and will not be able to display its contents; make sure to adjust this with hs._asm.guitk:frame or hs._asm.guitk:size once content has been assigned to the window.
guitk:accessibilitySubrole([label | nil]) -> guitkObject | string | nil
Get or set the accessibility subrole value this window will report via the Accessibility API when queried.
Parameters:
label
- an optional string or nil, default nil, specifying the accessibility subrole value this guitk window should report. See the notes below.
Returns:
- If an argument is provided, the guitk object; otherwise the current value.
Notes:
-
The subrole value of a window may be used by accessibility aware applications and Hammerspoon's own
hs.window.filter
to make decisions about how to treat the window. -
If you specify a non-empty string for this value, the value provided will be reported when this window's subrole is queried.
-
If you specify an empty string (e.g. ""), the default value for this window based upon its properties will be returned when queried.
-
If you specify nil (the default), then the default value for this window based upon its properties will have ".Hammerspoon" appended to the string and this combined value will be returned when queried.
guitk:activeElement([view | nil]) -> boolean | userdata
Get or set the active element for the guitk window.
Parameters:
view
- a userdata representing an element in the guitk window to make the active element, or an explcit nil to make no element active.
Returns:
- If an argument is provided, returns true or false indicating whether or not the current active element (if any) relinquished focus; otherwise the current value.
Notes:
-
The active element of a window is the element which is currently receiving mouse or keyboard activity from the user when the window is focused.
-
Not all elements can become the active element, for example textfield elements which are neither editable or selectable. If you try to make such an element active, the content manager or guitk window itself will become the active element.
-
Passing an explicit nil to this method will make the content manager or guitk window itself the active element.
- Making the content manager or guitk window itself the active element has the visual effect of making no element active but leaving the window focus unchanged.
guitk:allowTextEntry([value]) -> guitkObject | boolean
Get or set whether or not the guitk object can accept keyboard entry. Defaults to true.
Parameters:
value
- an optional boolean, default true, which sets whether or not the guitk will accept keyboard input.
Returns:
- If a value is provided, then this method returns the guitk object; otherwise the current value
Notes:
- Most controllable elements require keybaord focus even if they do not respond directly to keyboard input.
guitk:alpha([alpha]) -> guitkObject | number
Get or set the alpha level of the window representing the guitk object.
Parameters:
alpha
- an optional number, default 1.0, specifying the alpha level (0.0 - 1.0, inclusive) for the window.
Returns:
- If an argument is provided, the guitk object; otherwise the current value.
guitk:animationBehavior([behavior]) -> guitkObject | string
Get or set the macOS animation behavior used when the guitk window is shown or hidden.
Parameters:
behavior
- an optional string specifying the animation behavior. The string should be one of the following:- "default" - The automatic animation that’s appropriate to the window type.
- "none" - No automatic animation used. This is the default which makes window appearance immediate unless you use the fade time argument with hs._asm.guitk:show, hs._asm.guitk:hide, or hs._asm.guitk:delete.
- "documentWindow" - The animation behavior that’s appropriate to a document window.
- "utilityWindow" - The animation behavior that’s appropriate to a utility window.
- "alertPanel" - The animation behavior that’s appropriate to an alert window.
Returns:
- If an argument is provided, the guitk object; otherwise the current value.
Notes:
- This animation is separate from the fade-in and fade-out options provided with the hs._asm.guitk:show, hs._asm.guitk:hide, and hs._asm.guitk:delete methods and is provided by the macOS operating system itself.
guitk:animationDuration([duration | nil]) -> guitkObject | number | nil
Get or set the macOS animation duration for smooth frame transitions used when the guitk window is moved or resized.
Parameters:
duration
- a number or nil, default nil, specifying the time in seconds to move or resize by 150 pixels when theanimated
flag is set for hs._asm.guitk:frame, hs._asm.guitk:topLeft, or hs._asm.guitk:size. An explicitnil
defaults to the macOS default, which is currently 0.2.
Returns:
- If an argument is provided, the guitk object; otherwise the current value.
guitk:appearance([appearance]) -> guitkObject | string
Get or set the appearance name applied to the window decorations for the guitk window.
Parameters:
appearance
- an optional string specifying the name of the appearance style to apply to the window frame and decorations. Should be one of "aqua", "light", or "dark".
Returns:
- If an argument is provided, the guitk object; otherwise the current value.
Notes:
- Other string values are allowed for forwards compatibility if Apple or third party software adds additional themes.
- The built in labels are actually shortcuts:
- "aqua" is shorthand for "NSAppearanceNameAqua" and is the default.
- "light" is shorthand for "NSAppearanceNameVibrantLight"
- "dark" is shorthand for "NSAppearanceNameVibrantDark" and can be used to mimic the macOS dark mode.
- This method will return an error if the string provided does not correspond to a recognized appearance theme.
guitk:backgroundColor([color]) -> guitkObject | color table
Get or set the color for the background of guitk window.
Parameters:
color
- an optional table containing color keys as described inhs.drawing.color
Returns:
- If an argument is provided, the guitk object; otherwise the current value.
guitk:bringToFront([aboveEverything]) -> guitkObject
Places the guitk window on top of normal windows
Parameters:
aboveEverything
- An optional boolean value that controls how far to the front the guitk window should be placed. True to place the window on top of all windows (including the dock and menubar and fullscreen windows), false to place the webview above normal windows, but below the dock, menubar and fullscreen windows. Defaults to false.
Returns:
- The webview object
Notes:
- Recent versions of macOS have made significant changes to the way full-screen apps work which may prevent placing Hammerspoon elements above some full screen applications. At present the exact conditions are not fully understood and no work around currently exists in these situations.
guitk:closeOnEscape([flag]) -> guitkObject | boolean
If the guitk window is closable, this will get or set whether or not the Escape key is allowed to close the guitk window.
Parameters:
flag
- an optional boolean value which indicates whether the guitk window, when it's style includesclosable
(see hs._asm.guitk:styleMask), should allow the Escape key to be a shortcut for closing the window. Defaults to false.
Returns:
- If a value is provided, then this method returns the guitk object; otherwise the current value
Notes:
- If this is set to true, Escape will only close the window if no other element responds to the Escape key first (e.g. if you are editing a textfield element, the Escape will be captured by the text field, not by the guitk window.)
guitk:collectionBehavior([behaviorMask]) -> guitkObject | integer
Get or set the guitk window collection behavior with respect to Spaces and Exposé.
Parameters:
behaviorMask
- if present, this mask should be a combination of values found in hs._asm.guitk.behaviors describing the collection behavior. The mask should be provided as one of the following:- integer - a number representing the desired behavior which can be created by combining values found in hs._asm.guitk.behaviors with the logical or operator (e.g.
value1 | value2 | ... | valueN
). - string - a single key from hs._asm.guitk.behaviors which will be toggled in the current collection behavior.
- table - a list of keys from hs._asm.guitk.behaviors which will be combined to make the final collection behavior by combining their values with the logical or operator.
- integer - a number representing the desired behavior which can be created by combining values found in hs._asm.guitk.behaviors with the logical or operator (e.g.
Returns:
- if a parameter is specified, returns the guitk object, otherwise the current value
Notes:
- Collection behaviors determine how the guitk window is handled by Spaces and Exposé. See hs._asm.guitk.behaviors for more information.
guitk:contentManager([view | nil]) -> guitkObject | manager/element userdata
Get or set the content manager for the guitk window.
Parameters:
view
- a userdata representing a content manager or content element, or an explcit nil to remove, to assign to the guitk window.
Returns:
- If an argument is provided, the guitk object; otherwise the current value.
Notes:
-
This module provides the window or "frame" for displaying visual or user interface elements, however the content itself is provided by other modules. This method allows you to assign a manager or single element directly to the window for display and user interaction.
-
A manager allows for attaching multiple elements to the same window, for example a series of buttons and text fields for user input. Currently the only supported manager is found in
hs._asm.guitk.manager
and you should review this module for details on how to assign multiple elements to the window for display. -
If the window is being used to display a single element, you can by skip using the manager and assign the element directly with this method. This works especially well for fully contained elements like
hs._asm.guitk.element.avplayer
orhs.canvas
, but may be useful at times with other elements as well. The following should be kept in mind when not using a manager:- The element's size is the window's size -- you cannot specify a specific location for the element within the window or make it smaller than the window to give it a visual border.
- Only one element can be assigned at a time. For canvas, which has its own methods for handling multiple visual elements, this isn't necessarily an issue.
guitk:delete([fadeOut]) -> none
Destroys the guitk object, optionally fading it out first (if currently visible).
Parameters:
fadeOut
- An optional number of seconds over which to fade out the guitk object. Defaults to zero (i.e. immediate).
Returns:
- None
Notes:
- This method is automatically called during garbage collection, notably during a Hammerspoon termination or reload, with a fade time of 0.
guitk:deleteOnClose([value]) -> guitkObject | boolean
Get or set whether or not the guitk window should delete itself when its window is closed.
Parameters:
value
- an optional boolean, default false, which sets whether or not the guitk will delete itself when its window is closed by any method.
Returns:
- If a value is provided, then this method returns the guitk object; otherwise the current value
Notes:
- setting this to true allows Lua garbage collection to release the window resources when the user closes the window.
guitk:frame([rect], [animated]) -> guitkObject | rect-table
Get or set the frame of the guitk window.
Parameters:
rect
- An optional rect-table containing the co-ordinates and size the guitk window should be moved and set toanimated
- an optional boolean, default false, indicating whether the frame change should be performed with a smooth transition animation (true) or not (false).
Returns:
- If an argument is provided, the guitk 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 guitk window (keys
x
andy
) and the new size (keysh
andw
). The table may be crafted by any method which includes these keys, including the use of anhs.geometry
object. -
See also hs._asm.guitk:animationDuration.
guitk:hasShadow([state]) -> guitkObject | boolean
Get or set whether the guitk window displays a shadow.
Parameters:
state
- an optional boolean, default true, specifying whether or not the window draws a shadow.
Returns:
- If an argument is provided, the guitk object; otherwise the current value.
guitk:hide([fadeOut]) -> guitkObject
Hides the guitk object
Parameters:
fadeOut
- An optional number of seconds over which to fade out the guitk object. Defaults to zero (i.e. immediate).
Returns:
- The guitk object
guitk:ignoresMouseEvents([state]) -> guitkObject | boolean
Get or set whether the guitk window ignores mouse events.
Parameters:
state
- an optional boolean, default false, specifying whether or not the window receives mouse events.
Returns:
- If an argument is provided, the guitk object; otherwise the current value.
Notes:
- Setting this to true will prevent elements in the window from receiving mouse button events or mouse movement events which affect the focus of the window or its elements. For elements which accept keyboard entry, this may also prevent the user from focusing the element for keyboard input unless the element is focused programmatically with hs._asm.guitk:activeElement.
- Mouse tracking events (see
hs._asm.guitk.manager:mouseCallback
) will still occur, even if this is true; however if two windows at the same level (see hs._asm.guitk:level) both occupy the current mouse location and one or both of the windows have this attribute set to false, spurious and unpredictable mouse callbacks may occur as the "frontmost" window changes based on which is acting on the event at that instant in time.
guitk:isOccluded() -> boolean
Returns whether or not the guitk window is currently occluded (hidden by other windows, off screen, etc).
Parameters:
- None
Returns:
- a boolean indicating whether or not the guitk window is currently being occluded.
Notes:
- If any part of the window is visible (even if that portion of the window does not contain any elements), then the window is not considered occluded.
- a window which is completely covered by one or more opaque windows is considered occluded; however, if the windows covering the guitk window are not opaque, then the window is not occluded.
- a window that is currently hidden or that has a height of 0 or a width of 0 is considered occluded.
- See also hs._asm.guitk:isShowing.
guitk:isShowing() -> boolean
Returns whether or not the guitk window is currently being shown.
Parameters:
- None
Returns:
- a boolean indicating whether or not the guitk window is currently being shown (true) or is currently hidden (false).
Notes:
- This method only determines whether or not the window is being shown or is hidden -- it does not indicate whether or not the window is currently off screen or is occluded by other objects.
- See also hs._asm.guitk:isOccluded.
guitk:isVisible() -> boolean
Returns whether or not the guitk window is currently showing and is (at least partially) visible on screen.
Parameters:
- None
Returns:
- a boolean indicating whether or not the guitk window is currently visible.
Notes:
- This is syntactic sugar for
not hs._asm.guitk:isOccluded()
. - See hs._asm.guitk:isOccluded for more details.
guitk:level([theLevel]) -> guitkObject | integer
Get or set the guitk window level
Parameters:
theLevel
- an optional parameter specifying the desired level as an integer or as a string matching a label in hs._asm.guitk.levels
Returns:
- if a parameter is specified, returns the guitk object, otherwise the current value
Notes:
-
See the notes for hs._asm.guitk.levels for a description of the available levels.
-
Recent versions of macOS have made significant changes to the way full-screen apps work which may prevent placing Hammerspoon elements above some full screen applications. At present the exact conditions are not fully understood and no work around currently exists in these situations.
guitk:notificationCallback([fn | nil]) -> guitkObject | fn
Get or set the notification callback for the guitk window.
Parameters:
fn
- a function, or explicit nil to remove, that should be invoked whenever a registered notification concerning the guitk window occurs. See hs._asm.guitk:notificationMessages for information on registering for specific notifications.
Returns:
- If an argument is provided, the guitk object; otherwise the current value.
Notes:
- The function should expect two arguments: the guitkObject itself and a string specifying the type of notification. See hs._asm.guitk:notificationMessages and hs._asm.guitk.notifications.
- hs._asm.guitk:simplifiedWindowCallback provides a wrapper to this method which conforms to the window notifications currently offered by
hs.webview
.
guitk:notificationMessages([notifications, [replace]]) -> guitkObject | table
Get or set the specific notifications which should trigger a callback set with hs._asm.guitk:notificationCallback.
Parameters:
notifications
- a string, to specify one, or a table of strings to specify multiple notifications which are to trigger a callback when they occur.replace
- an optional boolean, default false, specifying whether the notifications listed should be added to the current set (false) or replace the existing set with new values (true).
Returns:
- If an argument is provided, the guitk object; otherwise the current value.
Notes:
- When a new guitkObject is created, the messages are initially set to
{ "didBecomeKey", "didResignKey", "didResize", "didMove" }
- See hs._asm.guitk.notifications for possible notification messages that can be watched for.
guitk:opaque([state]) -> guitkObject | boolean
Get or set whether the guitk window is opaque.
Parameters:
state
- an optional boolean, default true, specifying whether or not the window is opaque.
Returns:
- If an argument is provided, the guitk object; otherwise the current value.
guitk:orderAbove([guitk2]) -> guitkObject
Moves the guitk window above guitk2, or all guitk windows in the same presentation level, if guitk2 is not given.
Parameters:
guitk2
-An optional guitk window object to place the guitk window above.
Returns:
- The guitk object
Notes:
- If the guitk window and guitk2 are not at the same presentation level, this method will will move the window as close to the desired relationship as possible without changing the object's presentation level. See hs._asm.guitk.level.
guitk:orderBelow([guitk2]) -> guitkObject
Moves the guitk window below guitk2, or all guitk windows in the same presentation level, if guitk2 is not given.
Parameters:
guitk2
-An optional guitk window object to place the guitk window below.
Returns:
- The guitk object
Notes:
- If the guitk window and guitk2 are not at the same presentation level, this method will will move the window as close to the desired relationship as possible without changing the object's presentation level. See hs._asm.guitk.level.
guitk:passthroughCallback([fn | nil]) -> guitkObject | fn | nil
Get or set the pass through callback for the guitk window.
Parameters:
fn
- a function, or an explicit nil to remove, specifying the callback to invoke for elements which do not have their own callbacks assigned.
Returns:
- If an argument is provided, the guitk object; otherwise the current value.
Notes:
-
The pass through callback should expect one or two arguments and return none.
-
The pass through callback is designed so that elements which trigger a callback based on user interaction which do not have a specifically assigned callback can still report user interaction through a common fallback.
-
The arguments received by the pass through callback will be organized as follows:
- the guitk window userdata object
- a table containing the arguments from the content manager or element.
- if a content manager is in place, this array will contain the following arguments:
- the content manager userdata object
- a table containing the arguments provided by the elements callback itself, usually the element userdata followed by any additional arguments as defined for the element's callback function.
- if no content manager is in place and the element is directly assigned to the guitk window, then this table will contain the arguments provided by the elements callback itself, usually the element userdata followed by any additional arguments as defined for the element's callback function.
- if a content manager is in place, this array will contain the following arguments:
-
Note that elements which have a callback that returns a response cannot use this common pass through callback method; in such cases a specific callback must be assigned to the element directly as described in the element's documentation.
guitk:sendToBack() -> guitkObject
Places the guitk window behind normal windows, between the desktop wallpaper and desktop icons
Parameters:
- None
Returns:
- The guitk object
guitk:show([fadeIn]) -> guitkObject
Displays the guitk object
Parameters:
fadeIn
- An optional number of seconds over which to fade in the guitk object. Defaults to zero (i.e. immediate).
Returns:
- The guitk object
guitk:simplifiedWindowCallback([fn]) -> guitkObject
Set or clear a callback for updates to the guitk window using a simplified subset of the available notifications
Parameters:
-
fn
- the function to be called when the guitk window is moved or closed. Specify an explicit nil to clear the current callback. The function should expect 2 or 3 arguments and return none. The arguments will be one of the following:-
"closing", guitkObject - specifies that the guitk window is being closed, either by the user or with the hs._asm.guitk:delete method.
action
- in this case "closing", specifying that the guitk window is being closedguitkObject
- the guitk window that is being closed
-
"focusChange", guitkObject, state - indicates that the guitk window has either become or stopped being the focused window
action
- in this case "focusChange", specifying that the guitk window has changed focusguitkObject
- the guitk window which has changed focusstate
- a boolean, true if the guitk window has become the focused window, or false if it has lost focus
-
"frameChange", guitkObject, frame - indicates that the guitk window has been moved or resized
action
- in this case "frameChange", specifying that the guitk window's frame has changedguitkObject
- the guitk window which has had its frame changedframe
- a rect-table containing the new co-ordinates and size of the guitk window
-
Returns:
- The guitk object
Notes:
-
This method is a wrapper to the hs._asm.guitk:notificationCallback method which mimics the behavior for window changes first introduced with
hs.webview
. Setting or clearing a callback with this method is equivalent to doing the same with hs._asm.guitk:notificationCallback directly. -
Setting a callback function with this method will reset the currently watched notifications to "willClose", "didBecomeKey", "didResignKey", "didResize", and "didMove". You can add additional notifications after setting the callback function with hs._asm.guitk:notificationMessages and the following arguments will be passed to the callback when the additional notifications occur:
- "other", guitkObject, message
action
- in this case "other" indicating that the notification is for something not recognized by the simplified wrapper.guitkObject
- the guitk window for which the notification has occurred.message
- the name of the notification which has been triggered. See hs._asm.guitk.notifications.
- "other", guitkObject, message
guitk:size([size], [animated]) -> guitkObject | rect-table
Get or set the size of the guitk window.
Parameters:
size
- an optional size-table specifying the width and height the guitk window should be resized toanimated
- an optional boolean, default false, indicating whether the frame change should be performed with a smooth transition animation (true) or not (false).
Returns:
- If an argument is provided, the guitk object; otherwise the current value.
Notes:
-
a size-table is a table with key-value pairs specifying the size (keys
h
andw
) the guitk window should be resized to. The table may be crafted by any method which includes these keys, including the use of anhs.geometry
object. -
See also hs._asm.guitk:animationDuration.
guitk:styleMask([mask]) -> guitkObject | integer
Get or set the window display style
Parameters:
mask
- if present, this mask should be a combination of values found in hs._asm.guitk.masks describing the window style. The mask should be provided as one of the following:- integer - a number representing the style which can be created by combining values found in hs._asm.guitk.masks with the logical or operator (e.g.
value1 | value2 | ... | valueN
). - string - a single key from hs._asm.guitk.masks which will be toggled in the current window style.
- table - a list of keys from hs._asm.guitk.masks which will be combined to make the final style by combining their values with the logical or operator.
- integer - a number representing the style which can be created by combining values found in hs._asm.guitk.masks with the logical or operator (e.g.
Returns:
- if a parameter is specified, returns the guitk object, otherwise the current value
guitk:title([title]) -> guitkObject | string
Get or set the guitk window's title.
Parameters:
title
- an optional string specifying the title to assign to the guitk window.
Returns:
- If an argument is provided, the guitk object; otherwise the current value.
guitk:titlebarAppearsTransparent([state]) -> guitkObject | boolean
Get or set whether the guitk window's title bar draws its background.
Parameters:
state
- an optional boolean, default true, specifying whether or not the guitk window's title bar draws its background.
Returns:
- If an argument is provided, the guitk object; otherwise the current value.
guitk:titleVisibility([state]) -> guitkObject | currentValue
Get or set whether or not the title is displayed in the guitk window titlebar.
Parameters:
state
- an optional string containing the text "visible" or "hidden", specifying whether or not the guitk window's title text appears.
Returns:
- If an argument is provided, the guitk object; otherwise the current value.
Notes:
- NOT IMPLEMENTED YET - When a toolbar is attached to the guitk window (see the
hs.webview.toolbar
module documentation), this function can be used to specify whether the Toolbar appears underneath the window's title ("visible") or in the window's title bar itself, as seen in applications like Safari ("hidden").
guitk:topLeft([point], [animated]) -> guitkObject | rect-table
Get or set the top left corner of the guitk window.
Parameters:
point
- An optional point-table specifying the new coordinate the top-left of the guitk window should be moved toanimated
- an optional boolean, default false, indicating whether the frame change should be performed with a smooth transition animation (true) or not (false).
Returns:
- If an argument is provided, the guitk 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 guitk (keys
x
andy
). The table may be crafted by any method which includes these keys, including the use of anhs.geometry
object. -
See also hs._asm.guitk:animationDuration.
guitk.levels
A table of predefined window levels usable with hs._asm.guitk:level
Predefined levels are:
- _MinimumWindowLevelKey - lowest allowed window level
- desktop
- desktopIcon - hs._asm.guitk:sendToBack is equivalent to this level - 1
- normal - normal application windows
- tornOffMenu
- floating - equivalent to hs._asm.guitk:bringToFront(false); where "Always Keep On Top" windows are usually set
- modalPanel - modal alert dialog
- utility
- dock - level of the Dock
- mainMenu - level of the Menubar
- status
- popUpMenu - level of a menu when displayed (open)
- overlay
- help
- dragging
- screenSaver - equivalent to hs._asm.guitk:bringToFront(true)
- assistiveTechHigh
- cursor
- _MaximumWindowLevelKey - highest allowed window 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._asm.guitk:orderAbove and hs._asm.guitk: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.
-
Recent versions of macOS have made significant changes to the way full-screen apps work which may prevent placing Hammerspoon elements above some full screen applications. At present the exact conditions are not fully understood and no work around currently exists in these situations.
guitk.masks[]
A table containing valid masks for the guitk window.
Table Keys:
borderless
- The window has no border decorationstitled
- The window title bar is displayedclosable
- The window has a close buttonminiaturizable
- The window has a minimize buttonresizable
- The window is resizabletexturedBackground
- The window has a texturized backgroundfullSizeContentView
- If titled, the titlebar is within the frame size specified at creation, not above it. Shrinks actual content area by the size of the titlebar, if present.utility
- If titled, the window shows a utility panel titlebar (thinner than normal)nonactivating
- If the window is activated, it won't bring other Hammerspoon windows forward as wellHUD
- Requires utility; the window titlebar is shown dark and can only show the close button and title (if they are set)
The following are still being evaluated and may require additional support or specific methods to be in effect before use. Use with caution.
unifiedTitleAndToolbar
-fullScreen
-docModal
-
Notes:
-
The Maximize button in the window title is enabled when Resizable is set.
-
The Close, Minimize, and Maximize buttons are only visible when the Window is also Titled.
-
Not all combinations of masks are valid and will through an error if set with hs._asm.guitk:mask.
guitk.notifications[]
An array containing all of the notifications which can be enabled with hs._asm.guitk:notificationMessages.
Array values:
didBecomeKey
- The window has become the key window; controls or elements of the window can now be manipulated by the user and keyboard entry (if appropriate) will be captured by the relevant elements.didBecomeMain
- The window has become the main window of Hammerspoon. In most cases, this is equivalent to the window becoming key and both notifications may be sent if they are being watched for.didChangeBackingProperties
- The backing properties of the window have changed. This will be posted if the scaling factor of color space for the window changes, most likely because it moved to a different screen.didChangeOcclusionState
- The window's occlusion state has changed (i.e. whether or not at least part of the window is currently visible)didChangeScreen
- Part of the window has moved onto or off of the current screensdidChangeScreenProfile
- The screen the window is on has changed its properties or color profiledidDeminiaturize
- The window has been de-miniaturizeddidEndLiveResize
- The user resized the windowdidEndSheet
- The window has closed an attached sheetdidEnterFullScreen
- The window has entered full screen modedidEnterVersionBrowser
- The window will enter version browser modedidExitFullScreen
- The window has exited full screen modedidExitVersionBrowser
- The window will exit version browser modedidExpose
- Posted whenever a portion of a nonretained window is exposed - may not be applicable to the way Hammerspoon manages windows; will have to evaluate furtherdidFailToEnterFullScreen
- The window failed to enter full screen modedidFailToExitFullScreen
- The window failed to exit full screen modedidMiniaturize
- The window was miniaturizeddidMove
- The window was moveddidResignKey
- The window has stopped being the key windowdidResignMain
- The window has stopped being the main windowdidResize
- The window did resizedidUpdate
- The window received an update message (a request to redraw all content and the content of its subviews)willBeginSheet
- The window is about to open an attached sheetwillClose
- The window is about to close; the window has not closed yet, so its userdata is still valid, even if it's set to be deleted on close, so do any clean up at this time.willEnterFullScreen
- The window is about to enter full screen mode but has not done so yetwillEnterVersionBrowser
- The window will enter version browser mode but has not done so yetwillExitFullScreen
- The window will exit full screen mode but has not done so yetwillExitVersionBrowser
- The window will exit version browser mode but has not done so yetwillMiniaturize
- The window will miniaturize but has not done so yetwillMove
- The window will move but has not done so yetwillStartLiveResize
- The window is about to be resized by the user
Notes:
- Not all of the notifications here are currently fully supported and the specific details and support will change as this module and its submodules evolve and get fleshed out. Some may be removed if it is determined they will never be supported by this module while others may lead to additions when the need arises. Please post an issue or pull request if you would like to request specific support or provide additions yourself.
guitk.windowBehaviors[]
Array of window behavior labels for determining how an guitk is handled in Spaces and Exposé
default
- The window can be associated to one space at a time.canJoinAllSpaces
- The window appears in all spaces. The menu bar behaves this way.moveToActiveSpace
- Making the window active does not cause a space switch; the window switches to the active space.
Only one of these may be active at a time:
managed
- The window participates in Spaces and Exposé. This is the default behavior if windowLevel is equal to NSNormalWindowLevel.transient
- The window floats in Spaces and is hidden by Exposé. This is the default behavior if windowLevel is not equal to NSNormalWindowLevel.stationary
- The window is unaffected by Exposé; it stays visible and stationary, like the desktop window.
Only one of these may be active at a time:
participatesInCycle
- The window participates in the window cycle for use with the Cycle Through Windows Window menu item.ignoresCycle
- The window is not part of the window cycle for use with the Cycle Through Windows Window menu item.
Only one of these may be active at a time:
fullScreenPrimary
- A window with this collection behavior has a fullscreen button in the upper right of its titlebar.fullScreenAuxiliary
- Windows with this collection behavior can be shown on the same space as the fullscreen window.
Only one of these may be active at a time (Available in OS X 10.11 and later):
fullScreenAllowsTiling
- A window with this collection behavior be a full screen tile window and does not have to havefullScreenPrimary
set.fullScreenDisallowsTiling
- A window with this collection behavior cannot be made a fullscreen tile window, but it can havefullScreenPrimary
set. You can use this setting to prevent other windows from being placed in the window’s fullscreen tile.
The MIT License (MIT)
Copyright (c) 2017 Aaron Magill
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.