- Each toolbar item is defined as a table of key-value pairs. The following list describes the valid keys used when describing a toolbar item for this method, the constructor hs.webview.toolbar.new, and the hs.webview.toolbar:modifyItem method. Note that the
id field is required for all three uses.
id - A unique string identifier required for each toolbar item and group. This key cannot be changed after an item has been created.
allowedAlone - a boolean value, default true, specifying whether or not the toolbar item can be added to the toolbar, programmatically or through the customization panel, (true) or whether it can only be added as a member of a group (false).
default - a boolean value, default matching the value of
allowedAlone for this item, indicating whether or not this toolbar item or group should be displayed in the toolbar by default, unless overridden by user customization or a saved configuration (when such options are enabled).
enable - a boolean value, default true, indicating whether or not the toolbar item is active (and can be clicked on) or inactive and greyed out. This field is ignored when applied to a toolbar group; apply it to the group members instead.
fn - a callback function, or false to remove, specific to the toolbar item. This property is ignored if assigned to the button group. This function will override the toolbar callback defined with hs.webview.toolbar:setCallback for this specific item. The function should expect three (four, if the item is a
searchfield) arguments and return none. See hs.webview.toolbar:setCallback for information about the callback's arguments.
groupMembers - an array (table) of strings specifying the toolbar item ids that are members of this toolbar item group. If set to false, this field is removed and the item is reset back to being a regular toolbar item. Note that you cannot change a currently visible toolbar item to or from being a group; it must first be removed from active toolbar with hs.webview.toolbar:removeItem.
image - an
hs.image object, or false to remove, specifying the image to use as the toolbar item's icon when icon's are displayed in the toolbar or customization panel. This key is ignored for a toolbar item group, but not for it's individual members.
label - a string label, or false to remove, for the toolbar item or group when text is displayed in the toolbar or in the customization panel. For a toolbar item, the default is the
id string; for a group, the default is
false. If a group has a label assigned to it, the group label will be displayed for the group of items it contains. If a group does not have a label, the individual items which make up the group will each display their individual labels.
priority - an integer value used to determine toolbar item order and which items are displayed or put into the overflow menu when the number of items in the toolbar exceed the width of the window in which the toolbar is attached. Some example values are provided in the hs.webview.toolbar.itemPriorities table. If a toolbar item is in a group, it's priority is ignored and the item group is ordered by the item group's priority.
searchfield - a boolean (default false) specifying whether or not this toolbar item is a search field. If true, the following additional keys are allowed:
* `searchHistory` - an array (table) of strings, specifying previous searches to automatically include in the search field menu, if `searchPredefinedMenuTitle` is not false
* `searchHistoryAutosaveName` - a string specifying the key name to save search history with in the application deafults (accessible through `hs.settings`). If this value is set, search history will be maintained through restarts of Hammerspoon.
* `searchHistoryLimit` - the maximum number of items to store in the search field history.
* `searchPredefinedMenuTitle` - a string or boolean specifying how a predefined list of search field "response" should be included in the search field menu. If this item is `true`, this list of items specified for `searchPredefinedSearches` will be displayed in a submenu with the title "Predefined Searches". If this item is a string, the list of items will be displayed in a submenu with the title specified by this string value. If this item is `false`, then the search field menu will only contain the items specified in `searchPredefinedSearches` and no search history will be included in the menu.
* `searchPredefinedSearches` - an array (table) of strings specifying the items to be listed in the predefined search submenu. If set to false, any existing menu will be removed and the search field menu will be reset to the default.
* `searchReleaseFocusOnCallback` - a boolean, default false, specifying whether or not focus leaves the search field text box when the callback is invoked. Setting this to true can be useful if you want subsequent keypresses to be caught by the webview after reacting to the value entered into the search field by the user.
* `searchText` - a string specifying the text to display in the search field.
* `searchWidth` - the width of the search field text entry box.
selectable - a boolean value, default false, indicating whether or not this toolbar item is selectable (i.e. highlights, like a selected tab) when clicked on. Only one selectable toolbar item can be highlighted at a time, and you can get or set/reset the selected item with hs.webview.toolbar:selectedItem.
tag - an integer value which can be used for own purposes; has no affect on the visual aspect of the item or its behavior.
tooltip - a string label, or false to remove, which is displayed as a tool tip when the user hovers the mouse over the button or button group. If a button is in a group, it's tooltip is ignored in favor of the group tooltip.