docs » hs.chooser

Graphical, interactive tool for choosing/searching data

Notes:

API Overview

API Documentation

Variables

globalCallback
Signature hs.chooser.globalCallback
Type Variable
Description A global callback function used for various hs.chooser events
Notes
Source extensions/chooser/init.lua

Constructors

new
Signature hs.chooser.new(completionFn) -> hs.chooser object
Type Constructor
Description Creates a new chooser object
Parameters
  • completionFn - A function that will be called when the chooser is dismissed. It should accept one parameter, which will be nil if the user dismissed the chooser window, otherwise it will be a table containing whatever information you supplied for the item the user chose.
Returns
  • An hs.chooser object
Notes
  • As of macOS Sierra and later, if you want a hs.chooser object to appear above full-screen windows you must hide the Hammerspoon Dock icon first using: hs.dockicon.hide()
Source extensions/chooser/internal.m

Methods

attachedToolbar
Signature hs.chooser:attachedToolbar([toolbar]) -> hs.chooser object | currentValue
Type Method
Description Get or attach/detach a toolbar to/from the chooser.
Parameters
  • toolbar - An hs.webview.toolbar object to be attached to the chooser. If nil is supplied, the current toolbar will be removed
Returns
  • if a toolbarObject or explicit nil is specified, returns the hs.chooser object; otherwise returns the current toolbarObject or nil, if no toolbar is attached to the chooser.
Notes
  • this method is a convenience wrapper for the hs.webview.toolbar.attachToolbar function.
Source extensions/chooser/init.lua
bgDark
Signature hs.chooser:bgDark([beDark]) -> hs.chooser object or boolean
Type Method
Description Sets the background of the chooser between light and dark
Parameters
  • beDark - A optional boolean, true to be dark, false to be light. If this parameter is omitted, the current setting will be returned
Returns
  • The hs.chooser object or a boolean, true if the window is dark, false if it is light
Notes
  • The text colors will not automatically change when you toggle the darkness of the chooser window, you should also set appropriate colors with hs.chooser:fgColor() and hs.chooser:subTextColor()
Source extensions/chooser/internal.m
cancel
Signature hs.chooser:cancel() -> hs.chooser object
Type Method
Description Cancels the chooser
Parameters
  • None
Returns
  • The hs.chooser object
Source extensions/chooser/internal.m
choices
Signature hs.chooser:choices(choices) -> hs.chooser object
Type Method
Description Sets the choices for a chooser
Parameters
  • choices - Either a function to call when the list of choices is needed, or nil to remove any existing choices/callback, or a table containing static choices.
Returns
  • The hs.chooser object
Notes
  • The table of choices (be it provided statically, or returned by the callback) must contain at least the following keys for each choice:
    • text - A string or hs.styledtext object that will be shown as the main text of the choice
  • Each choice may also optionally contain the following keys:
    • subText - A string or hs.styledtext object that will be shown underneath the main text of the choice
    • image - An hs.image image object that will be displayed next to the choice
    • valid - A boolean that defaults to true, if set to false selecting the choice will invoke the invalidCallback method instead of dismissing the chooser
  • Any other keys/values in each choice table will be retained by the chooser and returned to the completion callback when a choice is made. This is useful for storing UUIDs or other non-user-facing information, however, it is important to note that you should not store userdata objects in the table - it is run through internal conversion functions, so only basic Lua types should be stored.
  • If a function is given, it will be called once, when the chooser window is displayed. The results are then cached until this method is called again, or hs.chooser:refreshChoicesCallback() is called.
  • If you're using a hs.styledtext object for text or subText choices, make sure you specify a color, otherwise your text could appear transparent depending on the bgDark setting.
Source extensions/chooser/internal.m
delete
Signature hs.chooser:delete()
Type Method
Description Deletes a chooser
Parameters
  • None
Returns
  • None
Source extensions/chooser/internal.m
fgColor
Signature hs.chooser:fgColor(color) -> hs.chooser object
Type Method
Description Sets the foreground color of the chooser
Parameters
  • color - An optional table containing a color specification (see hs.drawing.color), or nil to restore the default color. If this parameter is omitted, the existing color will be returned
Returns
  • The hs.chooser object or a color table
Source extensions/chooser/internal.m
hide
Signature hs.chooser:hide() -> hs.chooser object
Type Method
Description Hides the chooser
Parameters
  • None
Returns
  • The hs.chooser object
Source extensions/chooser/internal.m
hideCallback
Signature hs.chooser:hideCallback([fn]) -> hs.chooser object
Type Method
Description Sets/clears a callback for when the chooser window is hidden
Parameters
  • fn - An optional function that will be called when the chooser window is hidden. If this parameter is omitted, the existing callback will be removed.
Returns
  • The hs.chooser object
Notes
  • This callback is called after the chooser is hidden.
  • This callback is called after hs.chooser.globalCallback.
Source extensions/chooser/internal.m
invalidCallback
Signature hs.chooser:invalidCallback([fn]) -> hs.chooser object
Type Method
Description Sets/clears a callback for invalid choices
Parameters
  • fn - An optional function that will be called whenever the user select an choice set as invalid. If this parameter is omitted, the existing callback will be removed.
Returns
  • The hs.chooser object
Notes
  • The callback may accept one argument, it will be a table containing whatever information you supplied for the item the user chose.
  • To display a context menu, see hs.menubar, specifically the :popupMenu() method
Source extensions/chooser/internal.m
isVisible
Signature hs.chooser:isVisible() -> boolean
Type Method
Description Checks if the chooser is currently displayed
Parameters
  • None
Returns
  • A boolean, true if the chooser is displayed on screen, false if not
Source extensions/chooser/internal.m
placeholderText
Signature hs.chooser:placeholderText([placeholderText]) -> hs.chooser object or string
Type Method
Description Sets/gets placeholder text that is shown in the query text field when no other text is present
Parameters
  • placeholderText - An optional string for placeholder text. If this parameter is omitted, the existing placeholder text will be returned.
Returns
  • The hs.chooser object, or the existing placeholder text
Source extensions/chooser/internal.m
query
Signature hs.chooser:query([queryString]) -> hs.chooser object or string
Type Method
Description Sets/gets the search string
Parameters
  • queryString - An optional string to search for, or an explicit nil to clear the query. If omitted, the current contents of the search box are returned
Returns
  • The hs.chooser object or a string
Notes
  • You can provide an explicit nil or empty string to clear the current query string.
Source extensions/chooser/internal.m
queryChangedCallback
Signature hs.chooser:queryChangedCallback([fn]) -> hs.chooser object
Type Method
Description Sets/clears a callback for when the search query changes
Parameters
  • fn - An optional function that will be called whenever the search query changes. If this parameter is omitted, the existing callback will be removed.
Returns
  • The hs.chooser object
Notes
  • As the user is typing, the callback function will be called for every keypress. You may wish to do filtering on each call, or you may wish to use a delayed hs.timer object to only react when they have finished typing.
  • The callback function should accept a single argument:
    • A string containing the new search query
Source extensions/chooser/internal.m
refreshChoicesCallback
Signature hs.chooser:refreshChoicesCallback([reload]) -> hs.chooser object
Type Method
Description Refreshes the choices data from a callback
Parameters
  • reload - An optional parameter that reloads the chooser results to take into account the current query string (defaults to false)
Returns
  • The hs.chooser object
Notes
  • This method will do nothing if you have not set a function with hs.chooser:choices()
Source extensions/chooser/internal.m
rightClickCallback
Signature hs.chooser:rightClickCallback([fn]) -> hs.chooser object
Type Method
Description Sets/clears a callback for right clicking on choices
Parameters
  • fn - An optional function that will be called whenever the user right clicks on a choice. If this parameter is omitted, the existing callback will be removed.
Returns
  • The hs.chooser object
Notes
  • The callback may accept one argument, the row the right click occurred in or 0 if there is currently no selectable row where the right click occurred. To determine the location of the mouse pointer at the right click, see hs.mouse.
  • To display a context menu, see hs.menubar, specifically the :popupMenu() method
Source extensions/chooser/internal.m
rows
Signature hs.chooser:rows([numRows]) -> hs.chooser object or number
Type Method
Description Gets/Sets the number of rows that will be shown
Parameters
  • numRows - An optional number of choices to show (i.e. the vertical height of the chooser window). If this parameter is omitted, the current value will be returned
Returns
  • The hs.chooser object or a number
Source extensions/chooser/internal.m
searchSubText
Signature hs.chooser:searchSubText([searchSubText]) -> hs.chooser object or boolean
Type Method
Description Gets/Sets whether the chooser should search in the sub-text of each item
Parameters
  • searchSubText - An optional boolean, true to search sub-text, false to not search sub-text. If this parameter is omitted, the current configuration value will be returned
Returns
  • The hs.chooser object if a value was set, or a boolean if no parameter was passed
Notes
  • This should be used before a chooser has been displayed
Source extensions/chooser/internal.m
select
Signature hs.chooser:select([row]) -> hs.chooser object
Type Method
Description Closes the chooser by selecting the specified row, or the currently selected row if not given
Parameters
  • row - an optional integer specifying the row to select.
Returns
  • The hs.chooser object
Source extensions/chooser/internal.m
selectedRow
Signature hs.chooser:selectedRow([row]) -> number
Type Method
Description Get or set the currently selected row
Parameters
  • row - an optional integer specifying the row to select.
Returns
  • If an argument is provided, returns the hs.chooser object; otherwise returns a number containing the row currently selected (i.e. the one highlighted in the UI)
Source extensions/chooser/internal.m
selectedRowContents
Signature hs.chooser:selectedRowContents([row]) -> table
Type Method
Description Returns the contents of the currently selected or specified row
Parameters
  • row - an optional integer specifying the specific row to return the contents of
Returns
  • a table containing whatever information was supplied for the row currently selected or an empty table if no row is selected or the specified row does not exist.
Source extensions/chooser/internal.m
show
Signature hs.chooser:show([topLeftPoint]) -> hs.chooser object
Type Method
Description Displays the chooser
Parameters
  • An optional hs.geometry point object describing the absolute screen co-ordinates for the top left point of the chooser window. Defaults to centering the window on the primary screen
Returns
  • The hs.chooser object
Source extensions/chooser/internal.m
showCallback
Signature hs.chooser:showCallback([fn]) -> hs.chooser object
Type Method
Description Sets/clears a callback for when the chooser window is shown
Parameters
  • fn - An optional function that will be called when the chooser window is shown. If this parameter is omitted, the existing callback will be removed.
Returns
  • The hs.chooser object
Notes
  • This callback is called after the chooser is shown. To execute code just before it's shown (and/or after it's removed) see hs.chooser.globalCallback
Source extensions/chooser/internal.m
subTextColor
Signature hs.chooser:subTextColor(color) -> hs.chooser object or hs.color object
Type Method
Description Sets the sub-text color of the chooser
Parameters
  • color - An optional table containing a color specification (see hs.drawing.color), or nil to restore the default color. If this parameter is omitted, the existing color will be returned
Returns
  • The hs.chooser object or a color table
Source extensions/chooser/internal.m
width
Signature hs.chooser:width([percent]) -> hs.chooser object or number
Type Method
Description Gets/Sets the width of the chooser
Parameters
  • percent - An optional number indicating the percentage of the width of the screen that the chooser should occupy. If this parameter is omitted, the current width will be returned
Returns
  • The hs.chooser object or a number
Notes
  • This should be used before a chooser has been displayed
Source extensions/chooser/internal.m