# hs.webview.toolbar

Create and manipulate toolbars which can be attached to the Hammerspoon console or hs.webview objects.

Toolbars are attached to titled windows and provide buttons which can be used to perform various actions within the application. Hammerspoon can use this module to add toolbars to the console or 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).

Multiple copies of the same toolbar can be made with the hs.webview.toolbar:copy method so that multiple webview windows use the same toolbar, for example. If the user customizes a copied toolbar, changes to the active buttons or their order will be reflected in all copies of the toolbar.

Example:

t = require("hs.webview.toolbar")
a = t.new("myConsole", {
        { id = "select1", selectable = true, image = hs.image.imageFromName("NSStatusAvailable") },
        { id = "NSToolbarSpaceItem" },
        { id = "select2", selectable = true, image = hs.image.imageFromName("NSStatusUnavailable") },
        { id = "notShown", default = false, image = hs.image.imageFromName("NSBonjour") },
        { id = "NSToolbarFlexibleSpaceItem" },
        { id = "navGroup", label = "Navigation", groupMembers = { "navLeft", "navRight" }},
        { id = "navLeft", image = hs.image.imageFromName("NSGoLeftTemplate"), allowedAlone = false },
        { id = "navRight", image = hs.image.imageFromName("NSGoRightTemplate"), allowedAlone = false },
        { id = "NSToolbarFlexibleSpaceItem" },
        { id = "cust", label = "customize", fn = function(t, w, i) t:customizePanel() end, image = hs.image.imageFromName("NSAdvanced") }
    }):canCustomize(true)
      :autosaves(true)
      :selectedItem("select2")
      :setCallback(function(...)
                        print("a", inspect(table.pack(...)))
                   end)

t.attachToolbar(a)

Notes:

• This module is supported in OS X versions prior to 10.10 (for the Hammerspoon console only), even though its parent hs.webview is not. To load this module directly, use require("hs.webview.toolbar") instead of relying on module auto-loading.
• Toolbar items are rendered in the order they are supplied, although if the toolbar is marked as customizable, the user may have changed the order.

Constants - Useful values which cannot be changed

• itemPriorities
• systemToolbarItems

Functions - API calls offered directly by the extension

• attachToolbar
• inTitleBar
• uniqueName

Constructors - API calls which return an object, typically one that offers API methods

• new

Methods - API calls which can only be made on an object returned by a constructor

• addItems
• allowedItems
• autosaves
• canCustomize
• copy
• customizePanel
• delete
• deleteItem
• displayMode
• identifier
• insertItem
• isAttached
• isCustomizing
• itemDetails
• items
• modifyItem
• notifyOnChange
• removeItem
• savedSettings
• selectedItem
• selectSearchField
• separator
• setCallback
• sizeMode
• toolbarStyle
• visible
• visibleItems

| | | | --------------------------------------------|-------------------------------------------------------------------------------------| | Signature | hs.webview.toolbar.attachToolbar([obj1], [obj2]) -> obj1 | | Type | Function | | Description | Get or attach/detach a toolbar to the webview, chooser, or console. | | Parameters |

• obj1 - An optional toolbarObject
• obj2 - An optional toolbarObject if no arguments are present, this function returns the current toolbarObject for the Hammerspoon console, or nil if one is not attached. if one argument is provided and it is a toolbarObject or nil, this function will attach or detach a toolbarObject to/from the Hammerspoon console. if one argument is provided and it is an hs.webview or hs.chooser object, this function will return the current toolbarObject for the object, or nil if one is not attached. if two arguments are provided and the first is an hs.webview or hs.chooser object and the second is a toolbarObject or nil, this function will attach or detach a toolbarObject to/from the object.

• if the function is used to attach/detach a toolbar, then the first object provided (the target) will be returned ; if this function is used to get the current toolbar object for a webview, chooser, or console, then the toolbarObject or nil will be returned.

• This function is not expected to be used directly (though it can be) -- it is added to the hs.webview and hs.chooser object metatables so that it may be invoked as hs.webview:attachedToolbar([toolbarObject | nil])/hs.chooser:attachedToolbar([toolbarObject | nil]) and to the hs.console module so that it may be invoked as hs.console.toolbar([toolbarObject | nil]).
• If the toolbar is currently attached to another window when this function is called, it will be detached from the original window and attached to the new one specified by this function.