Display web content in a window from Hammerspoon
This module uses Apple's WebKit WKWebView class to provide web content display with JavaScript injection support. The objective is to provide a functional interface to the WKWebView and WKUserContentController classes.
This module is not intended to replace a full web browser and does have some limitations to keep in mind:
hs.webview:reload(true)
and by crafting the url for hs.webview:url({...})
as a table -- see the appropriate help entries for more information.Any suggestions or updates to the code to address any of these or other limitations as they may become apparent are welcome at the Hammerspoon github site: https://www.github.com/Hammerspoon/hammerspoon
Signature | hs.webview:asHSDrawing() -> hs.drawing object |
---|---|
Type | Deprecated |
Description | Because use of this method can easily lead to a crash, useful methods from Parameters:
Returns:
|
Signature | hs.webview:asHSWindow() -> hs.window object |
---|---|
Type | Deprecated |
Description | Returns an hs.window object for the webview so that you can use hs.window methods on it. This method is identical to hs.webview:hswindow. It is included for reasons of backwards compatibility, but use of the new name is recommended for clarity. |
Signature | hs.webview:setLevel(theLevel) -> drawingObject |
---|---|
Type | Deprecated |
Description | Deprecated; you should use hs.webview:level instead. Parameters:
Returns:
Notes:
|
Signature | hs.webview.certificateOIDs[] |
---|---|
Type | Constant |
Description | A table of common OID values found in SSL certificates. SSL certificates provided to the callback function for hs.webview:sslCallback or in the results of hs.webview:certificateChain use OID strings as the keys which describe the properties of the certificate and this table can be used to get a more common name for the keys you are most likely to see. This list is based on the contents of OS X's /System/Library/Frameworks/Security.framework/Headers/SecCertificateOIDs.h. |
Signature | hs.webview.windowMasks[] |
---|---|
Type | Constant |
Description | A table containing valid masks for the webview window. Table Keys:
Notes:
|
Signature | hs.webview.new(rect, [preferencesTable], [userContentController]) -> webviewObject |
---|---|
Type | Constructor |
Description | Create a webviewObject and optionally modify its preferences. Parameters:
Returns:
Notes:
|
Signature | hs.webview.newBrowser(rect, [preferencesTable], [userContentController]) -> webviewObject |
---|---|
Type | Constructor |
Description | Create a webviewObject with some presets common to an interactive web browser. Parameters:
Returns:
Notes:
|
Signature | hs.webview:allowGestures([value]) -> webviewObject | current value |
---|---|
Type | Method |
Description | Get or set whether or not the webview will respond to gestures from a trackpad or magic mouse. Default is false. Parameters:
Returns:
Notes:
|
Signature | hs.webview:allowMagnificationGestures([value]) -> webviewObject | current value |
---|---|
Type | Method |
Description | Get or set whether or not the webview will respond to magnification gestures from a trackpad or magic mouse. Default is false. Parameters:
Returns:
|
Signature | hs.webview:allowNewWindows([value]) -> webviewObject | current value |
---|---|
Type | Method |
Description | Get or set whether or not the webview allows new windows to be opened from it by any method. Defaults to true. Parameters:
Returns:
Notes:
|
Signature | hs.webview:allowTextEntry([value]) -> webviewObject | current value |
---|---|
Type | Method |
Description | Get or set whether or not the webview can accept keyboard for web form entry. Defaults to false. Parameters:
Returns:
|
Signature | hs.webview:alpha([alpha]) -> webviewObject | currentValue |
---|---|
Type | Method |
Description | Get or set the alpha level of the window containing the hs.webview object. Parameters:
Returns:
|
Signature | hs.webview:attachedToolbar([toolbar | nil]) -> webviewObject | currentValue |
---|---|
Type | Method |
Description | Get or attach/detach a toolbar to/from the webview. Parameters:
Returns:
Notes:
|
Signature | hs.webview:behavior([behavior]) -> webviewObject | currentValue |
---|---|
Type | Method |
Description | Get or set the window behavior settings for the webview object. Parameters:
Returns:
Notes:
|
Signature | hs.webview:behaviorAsLabels(behaviorTable) -> webviewObject | currentValue |
---|---|
Type | Method |
Description | Get or set the window behavior settings for the webview object using labels defined in Parameters:
Returns:
Notes:
|
Signature | hs.webview:bringToFront([aboveEverything]) -> webviewObject |
---|---|
Type | Method |
Description | Places the drawing object on top of normal windows Parameters:
Returns:
|
Signature | hs.webview:certificateChain() -> table | nil |
---|---|
Type | Method |
Description | Returns the certificate chain for the most recently committed navigation of the webview. Parameters:
Returns:
Notes:
|
Signature | hs.webview:children() -> array |
---|---|
Type | Method |
Description | Returns an array of webview objects which have been opened as children of this webview. Parameters:
Returns:
|
Signature | hs.webview:closeOnEscape([flag]) -> webviewObject | current value |
---|---|
Type | Method |
Description | If the webview is closable, this will get or set whether or not the Escape key is allowed to close the webview window. Parameters:
Returns:
Notes:
|
Signature | hs.webview:darkMode([state]) -> bool |
---|---|
Type | Method |
Description | Set or display whether or not the Parameters:
Returns:
|
Signature | hs.webview:delete([propagate], [fadeOutTime]) -> none |
---|---|
Type | Method |
Description | Destroys the webview object, optionally fading it out first (if currently visible). Parameters:
Returns:
Notes:
|
Signature | hs.webview:deleteOnClose([value]) -> webviewObject | current value |
---|---|
Type | Method |
Description | Get or set whether or not the webview should delete itself when its window is closed. Parameters:
Returns:
Notes:
|
Signature | hs.webview:estimatedProgress() -> number |
---|---|
Type | Method |
Description | Returns the estimated percentage of expected content that has been loaded. Will equal 1.0 when all content has been loaded. Parameters:
Returns:
|
Signature | hs.webview:evaluateJavaScript(script, [callback]) -> webviewObject |
---|---|
Type | Method |
Description | Execute JavaScript within the context of the current webview and optionally receive its result or error in a callback function. Parameters:
Returns:
|
Signature | hs.webview:examineInvalidCertificates([flag]) -> webviewObject | current value |
---|---|
Type | Method |
Description | Get or set whether or not invalid SSL server certificates that are approved by the ssl callback function are accepted as valid for browsing with the webview. Parameters:
Returns:
Notes:
|
Signature | hs.webview:frame([rect]) -> webviewObject | currentValue |
---|---|
Type | Method |
Description | Get or set the frame of the webview window. Parameters:
Returns:
Notes:
|
Signature | hs.webview:goBack() -> webviewObject |
---|---|
Type | Method |
Description | Move to the previous page in the webview's history, if possible. Parameters:
Returns:
|
Signature | hs.webview:goForward() -> webviewObject |
---|---|
Type | Method |
Description | Move to the next page in the webview's history, if possible. Parameters:
Returns:
|
Signature | hs.webview:hide([fadeOutTime]) -> webviewObject |
---|---|
Type | Method |
Description | Hides the webview object Parameters:
Returns:
|
Signature | hs.webview:historyList() -> historyTable |
---|---|
Type | Method |
Description | Returns the URL history for the current webview as an array. Parameters:
Returns:
|
Signature | hs.webview:hswindow() -> hs.window object |
---|---|
Type | Method |
Description | Returns an hs.window object for the webview so that you can use hs.window methods on it. Parameters:
Returns:
Notes:
|
Signature | hs.webview:html(html,[baseURL]) -> webviewObject, navigationIdentifier |
---|---|
Type | Method |
Description | Render the given HTML in the webview with an optional base URL for relative links. Parameters:
Returns:
Notes:
|
Signature | hs.webview:isOnlySecureContent() -> bool |
---|---|
Type | Method |
Description | Returns a boolean value indicating if all content current displayed in the webview was loaded over securely encrypted connections. Parameters:
Returns:
|
Signature | hs.webview:level([theLevel]) -> drawingObject | currentValue |
---|---|
Type | Method |
Description | Get or set the window level Parameters:
Returns:
Notes:
|
Signature | hs.webview:loading() -> boolean |
---|---|
Type | Method |
Description | Returns a boolean value indicating whether or not the vebview is still loading content. Parameters:
Returns:
|
Signature | hs.webview:magnification([value]) -> webviewObject | current value |
---|---|
Type | Method |
Description | Get or set the webviews current magnification level. Default is 1.0. Parameters:
Returns:
|
Signature | hs.webview:orderAbove([webview2]) -> webviewObject |
---|---|
Type | Method |
Description | Moves webview object above webview2, or all webview objects in the same presentation level, if webview2 is not given. Parameters:
Returns:
Notes:
|
Signature | hs.webview:orderBelow([webview2]) -> webviewObject |
---|---|
Type | Method |
Description | Moves webview object below webview2, or all webview objects in the same presentation level, if webview2 is not given. Parameters:
Returns:
Notes:
|
Signature | hs.webview:parent() -> webviewObject | nil |
---|---|
Type | Method |
Description | Get the parent webview object for the calling webview object, or nil if the webview has no parent. Parameters:
Returns:
|
Signature | hs.webview:policyCallback(fn) -> webviewObject |
---|---|
Type | Method |
Description | Sets a callback to approve or deny web navigation activity. Parameters:
Returns:
Notes:
|
Signature | hs.webview:privateBrowsing() -> boolean |
---|---|
Type | Method |
Description | Returns whether or not the webview browser is set up for private browsing (i.e. uses a non-persistent datastore) Parameters:
Returns:
Notes:
|
Signature | hs.webview:reload([validate]) -> webviewObject, navigationIdentifier |
---|---|
Type | Method |
Description | Reload the page in the webview, optionally performing end-to-end revalidation using cache-validating conditionals if possible. Parameters:
Returns:
|
Signature | hs.webview:sendToBack() -> webviewObject |
---|---|
Type | Method |
Description | Places the webview object behind normal windows, between the desktop wallpaper and desktop icons Parameters:
Returns:
|
Signature | hs.webview:shadow([value]) -> webviewObject | current value |
---|---|
Type | Method |
Description | Get or set whether or not the webview window has shadows. Default to false. Parameters:
Returns:
|
Signature | hs.webview:show([fadeInTime]) -> webviewObject |
---|---|
Type | Method |
Description | Displays the webview object Parameters:
Returns:
|
Signature | hs.webview:size([size]) -> webviewObject | currentValue |
---|---|
Type | Method |
Description | Get or set the size of a webview window Parameters:
Returns:
Notes:
|
Signature | hs.webview:sslCallback(fn) -> webviewObject |
---|---|
Type | Method |
Description | Sets a callback to examine an invalid SSL certificate and determine if an exception should be granted. Parameters:
Returns:
Notes:
|
Signature | hs.webview:stopLoading() -> webviewObject |
---|---|
Type | Method |
Description | Stop loading content if the webview is still loading content. Does nothing if content has already completed loading. Parameters:
Returns:
|
Signature | hs.webview:title() -> title |
---|---|
Type | Method |
Description | Get the title of the page displayed in the webview. Parameters:
Returns:
|
Signature | hs.webview:topLeft([point]) -> webviewObject | currentValue |
---|---|
Type | Method |
Description | Get or set the top-left coordinate of the webview window Parameters:
Returns:
Notes:
|
Signature | hs.webview:transparent([value]) -> webviewObject | current value |
---|---|
Type | Method |
Description | Get or set whether or not the webview background is transparent. Default is false. Parameters:
Returns:
Notes:
|
Signature | hs.webview:url([URL]) -> webviewObject, navigationIdentifier | url |
---|---|
Type | Method |
Description | Get or set the URL to render for the webview. Parameters:
Returns:
Notes:
|
Signature | hs.webview:urlParts() -> table |
---|---|
Type | Method |
Description | Returns a table of keys containing the individual components of the URL for the webview. Parameters:
Returns:
Notes:
|
Signature | hs.webview:userAgent([agent]) -> webviewObject | current value |
---|---|
Type | Method |
Description | Get or set the webview's user agent string Parameters:
Returns:
Notes:
|
Signature | hs.webview:windowCallback(fn) -> webviewObject |
---|---|
Type | Method |
Description | Set or clear a callback for updates to the webview window Parameters:
Returns:
|
Signature | hs.webview:windowStyle(mask) -> webviewObject | currentMask |
---|---|
Type | Method |
Description | Get or set the window display style Parameters:
Returns:
|
Signature | hs.webview:windowTitle([title]) -> webviewObject |
---|---|
Type | Method |
Description | Sets the title for the webview window. Parameters:
Returns:
Notes:
|