hs.webview
objects which have a title bar (see hs.webview.windowMasks
and hs.webview:windowStyle
). Toolbars are identified by a unique identifier which is used by OS X to identify information which can be auto saved in the application's user defaults to reflect changes the user has made to the toolbar button order or active button list (this requires setting hs.webview.toolbar:autosaves and hs.webview.toolbar:canCustomize both to true).hs.webview
is not. To load this module directly, use require("hs.webview.toolbar")
instead of relying on module auto-loading.hs.webview.toolbar.itemPriorities
hs.webview.toolbar.systemToolbarItems
hs.webview.toolbar.attachToolbar([obj1], [obj2]) -> obj1
hs.webview
and hs.chooser
object metatables so that it may be invoked as hs.webview:attachedToolbar([toolbarObject
hs.webview.toolbar:inTitleBar([state]) -> toolbarObject | boolean
| | -----------------------------------------------------|---------------------------------------------------------------------------------------------------------| | Type | Function | | Description | Get or set whether or not the toolbar appears in the containing window's titlebar, similar to Safari. | | Parameters |state
- an optional boolean specifying whether or not the toolbar should appear in the window's titlebar.hs.webview.toolbar.uniqueName(toolbarName) -> boolean
true
if the name is unique otherwise false
hs.webview.toolbar.new(toolbarName, [toolbarTable]) -> toolbarObject
hs.webview.toolbar:addItems(toolbarTable) -> toolbarObject
toolbarTable
- a table describing a single toolbar item, or an array of tables, each describing a separate toolbar item, to be added to the toolbar.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 falsesearchHistoryAutosaveName
- 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.hs.webview.toolbar:allowedItems() -> array
hs.webview.toolbar:autosaves([bool]) -> toolbarObject | bool
| | -----------------------------------------------------|---------------------------------------------------------------------------------------------------------| | Type | Method | | Description | Get or set whether or not the toolbar autosaves changes made to the toolbar. | | Parameters |hs.webview.toolbar:canCustomize([bool]) -> toolbarObject | bool
| | -----------------------------------------------------|---------------------------------------------------------------------------------------------------------| | Type | Method | | Description | Get or set whether or not the user is allowed to customize the toolbar with the Customization Panel. | | Parameters |hs.webview.toolbar:copy() -> toolbarObject
hs.webview.toolbar:customizePanel() -> toolbarObject
hs.webview.toolbar:delete() -> none
hs.webview.toolbar:deleteItem(identifier) -> toolbarObject
identifier
- the toolbar item's identifierhs.webview.toolbar:displayMode([mode]) -> toolbarObject
hs.webview.toolbar:identifier() -> identifier
hs.webview.toolbar:insertItem(id, index) -> toolbarObject
hs.webview.toolbar:isAttached() -> boolean
hs.webview.toolbar:isCustomizing() -> bool
hs.webview.toolbar:itemDetails(id) -> table
privateCallback
which will be a boolean indicating whether or not this toolbar item has a private callback function assigned (true) or uses the toolbar's general callback function (false).toolbar
- the toolbar object the item belongs tosubItems
- if the toolbar item is actually a group, this will contain a table with basic information about the members of the group. If you wish to get the full details for each sub-member, you may iterate on the identifiers provided in groupMembers
.hs.webview.toolbar:items() -> array
hs.webview.toolbar:modifyItem(table) -> toolbarObject
id
hs.webview.toolbar:notifyOnChange([bool]) -> toolbarObject | bool
| | -----------------------------------------------------|---------------------------------------------------------------------------------------------------------| | Type | Method | | Description | Get or set whether or not the global callback function is invoked when a toolbar item is added or removed from the toolbar. | | Parameters |hs.webview.toolbar:removeItem(index | identifier) -> toolbarObject
| | -----------------------------------------------------|---------------------------------------------------------------------------------------------------------| | Type | Method | | Description | Remove the toolbar item at the index position specified, or with the specified identifier, if currently present in the toolbar. | | Parameters |index
- the numerical position of the toolbar item to remove.identifier
- the identifier of the toolbar item to remove, if currently active in the toolbarhs.webview.toolbar:savedSettings() -> table
hs.webview.toolbar:selectedItem([item]) -> toolbarObject | item
| | -----------------------------------------------------|---------------------------------------------------------------------------------------------------------| | Type | Method | | Description | Get or set the selected toolbar item | | Parameters |selectable
when created with hs.webview.toolbar.new can be selected with this method.hs.webview.toolbar:selectSearchField([identifier]) -> toolbarObject | false
| | -----------------------------------------------------|---------------------------------------------------------------------------------------------------------| | Type | Method | | Description | Programmatically focus the search field for keyboard input. | | Parameters |hs.webview.toolbar:separator([bool]) -> toolbarObject | bool
| | -----------------------------------------------------|---------------------------------------------------------------------------------------------------------| | Type | Method | | Description | Get or set whether or not the toolbar shows a separator between the toolbar and the main window contents. | | Parameters |hs.webview.toolbar:setCallback(fn) -> toolbarObject
hs.webview.toolbar:sizeMode([size]) -> toolbarObject
hs.webview.toolbar:visible([bool]) -> toolbarObject | bool
| | -----------------------------------------------------|---------------------------------------------------------------------------------------------------------| | Type | Method | | Description | Get or set whether or not the toolbar is currently visible in the window it is attached to. | | Parameters |hs.webview.toolbar:visibleItems() -> array