docs » hs.webview

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:

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

Submodules

API Overview

API Documentation

Deprecateds

asHSDrawing
Signature hs.webview:asHSDrawing() -> hs.drawing object
Type Deprecated
Description Because use of this method can easily lead to a crash, useful methods from `hs.drawing` have been added to the `hs.webview` module itself. If you believe that a useful method has been overlooked, please submit an issue.
Source extensions/webview/init.lua
asHSWindow
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.
Source extensions/webview/init.lua
setLevel
Signature hs.webview:setLevel(theLevel) -> drawingObject
Type Deprecated
Description Deprecated; you should use [hs.webview:level](#level) instead.
Notes
Source extensions/webview/init.lua

Constants

certificateOIDs
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](#sslCallback) or in the results of [hs.webview:certificateChain](#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.
Source extensions/webview/internal.m
windowMasks
Signature hs.webview.windowMasks[]
Type Constant
Description A table containing valid masks for the webview window.
Notes
Source extensions/webview/internal.m

Functions

titleVisibility
Signature hs.webview:titleVisibility([state]) -> webviewObject | string
Type Function
Description Get or set whether or not the title text appears in the webview window.
Parameters
  • state - an optional string containing the text "visible" or "hidden", specifying whether or not the webview's title text appears when webview's window style includes "titled".
Returns
  • if a value is provided, returns the webview object; otherwise returns the current value.
Notes
Source extensions/webview/internal.m

Constructors

new
Signature hs.webview.new(rect, [preferencesTable], [userContentController]) -> webviewObject
Type Constructor
Description Create a webviewObject and optionally modify its preferences.
Parameters
  • rect - a rectangle specifying where the webviewObject should be displayed.
  • preferencesTable - an optional table which can include one of more of the following keys:
    • javaEnabled - java is enabled (default false)
    • javaScriptEnabled - JavaScript is enabled (default true)
    • javaScriptCanOpenWindowsAutomatically - can JavaScript open windows without user intervention (default true)
    • minimumFontSize - minimum font size (default 0.0)
    • plugInsEnabled - plug-ins are enabled (default false)
    • developerExtrasEnabled - include "Inspect Element" in the context menu
    • suppressesIncrementalRendering - suppresses content rendering until fully loaded into memory (default false)
    • The following additional preferences may also be set under OS X 10.11 or later (they will be ignored with a warning printed if used under OS X 10.10): applicationName - a string specifying an application name to be listed at the end of the browser's USER-AGENT header. Note that this is only appended to the default user agent string; if you set a custom one with hs.webview:userAgent, this value is ignored. allowsAirPlay - a boolean specifying whether media playback within the webview can play through AirPlay devices. datastore - an hs.webview.datastore object specifying where website data such as cookies, cacheable content, etc. is to be stored. privateBrowsing - a boolean (default false) specifying that the datastore should be set to a new, empty and non-persistent datastore. Note that this will override the datastore key if both are specified and this is set to true.
  • userContentController - an optional hs.webview.usercontent object to provide script injection and JavaScript messaging with Hammerspoon from the webview.
Returns
  • The webview object
Notes
  • To set the initial URL, use the hs.webview:url method before showing the webview object.
  • Preferences can only be set when the webview object is created. To change the preferences of an open webview, you will need to close it and recreate it with this method.
Source extensions/webview/internal.m
newBrowser
Signature hs.webview.newBrowser(rect, [preferencesTable], [userContentController]) -> webviewObject
Type Constructor
Description Create a webviewObject with some presets common to an interactive web browser.
Parameters
  • rect - a rectangle specifying where the webviewObject should be displayed.
  • preferencesTable - an optional table which specifies special settings for the webview object.
  • userContentController - an optional hs.webview.usercontent object to provide script injection and JavaScript messaging with Hammerspoon from the webview.
Returns
  • The webview object
Notes
  • The parameters are the same as for hs.webview.new -- check there for more details
  • This constructor is just a short-hand for hs.webview.new(...):allowTextEntry(true):allowGestures(true):windowStyle(15), which specifies a webview with a title bar, title bar buttons (zoom, close, minimize), and allows form entry and gesture support for previous and next pages.
Source extensions/webview/init.lua

Methods

allowGestures
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
  • value - an optional boolean value indicating whether or not the webview should respond gestures.
Returns
  • If a value is provided, then this method returns the webview object; otherwise the current value
Notes
  • This is a shorthand method for getting or setting both hs.webview:allowMagnificationGestures and hs.webview:allowNavigationGestures.
  • This method will set both types of gestures to true or false, if given an argument, but will only return true if both gesture types are currently true; if either or both gesture methods are false, then this method will return false.
Source extensions/webview/init.lua
allowMagnificationGestures
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
  • value - an optional boolean value indicating whether or not the webview should respond to magnification gestures.
Returns
  • If a value is provided, then this method returns the webview object; otherwise the current value
Source extensions/webview/internal.m
allowNavigationGestures
Signature hs.webview:allowNavigationGestures([value]) -> webviewObject | current value
Type Method
Description Get or set whether or not the webview will respond to the navigation gestures from a trackpad or magic mouse. Default is false.
Parameters
  • value - an optional boolean value indicating whether or not the webview should respond to navigation gestures.
Returns
  • If a value is provided, then this method returns the webview object; otherwise the current value
Source extensions/webview/internal.m
allowNewWindows
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
  • value - an optional boolean value indicating whether or not the webview should allow new windows to be opened from it.
Returns
  • If a value is provided, then this method returns the webview object; otherwise the current value
Notes
  • This method allows you to prevent a webview from being able to open a new window by any method. This includes right-clicking on a link and selecting "Open in a New Window", JavaScript pop-ups, links with the target of "__blank", etc.
  • If you just want to prevent automatic JavaScript windows, set the preference value javaScriptCanOpenWindowsAutomatically to false when creating the web view - this method blocks all methods.
Source extensions/webview/internal.m
allowTextEntry
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
  • value - an optional boolean value which sets whether or not the webview will accept keyboard input.
Returns
  • If a value is provided, then this method returns the webview object; otherwise the current value
Source extensions/webview/internal.m
alpha
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
  • alpha - an optional number between 0.0 and 1.0 specifying the new alpha level for the webview.
Returns
  • If a parameter is provided, returns the webview object; otherwise returns the current value.
Source extensions/webview/internal.m
attachedToolbar
Signature hs.webview:attachedToolbar([toolbar]) -> webviewObject | currentValue
Type Method
Description Get or attach/detach a toolbar to/from the webview.
Parameters
  • toolbar - if an hs.webview.toolbar object is specified, it will be attached to the webview. If an explicit nil is specified, the current toolbar will be removed from the webview.
Returns
  • if a toolbarObject or explicit nil is specified, returns the webviewObject; otherwise returns the current toolbarObject or nil, if no toolbar is attached to the webview.
Notes
  • this method is a convenience wrapper for the hs.webview.toolbar.attachToolbar function.
Source extensions/webview/init.lua
behavior
Signature hs.webview:behavior([behavior]) -> webviewObject | currentValue
Type Method
Description Get or set the window behavior settings for the webview object.
Parameters
  • behavior - an optional number representing the desired window behaviors for the webview object.
Returns
  • If an argument is provided, the webview object; otherwise the current value.
Notes
  • Window behaviors determine how the webview object is handled by Spaces and Exposé. See hs.drawing.windowBehaviors for more information.
Source extensions/webview/internal.m
behaviorAsLabels
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 `hs.drawing.windowBehaviors`.
Parameters
  • behaviorTable - an optional table of strings and/or numbers specifying the desired window behavior for the webview object.
Returns
  • If an argument is provided, the webview object; otherwise the current value.
Notes
  • Window behaviors determine how the webview object is handled by Spaces and Exposé. See hs.drawing.windowBehaviors for more information.
Source extensions/webview/init.lua
bringToFront
Signature hs.webview:bringToFront([aboveEverything]) -> webviewObject
Type Method
Description Places the drawing object on top of normal windows
Parameters
  • aboveEverything - An optional boolean value that controls how far to the front the webview should be placed. True to place the webview on top of all windows (including the dock and menubar and fullscreen windows), false to place the webview above normal windows, but below the dock, menubar and fullscreen windows. Defaults to false.
Returns
  • The webview object
Source extensions/webview/internal.m
certificateChain
Signature hs.webview:certificateChain() -> table | nil
Type Method
Description Returns the certificate chain for the most recently committed navigation of the webview.
Parameters
  • None
Returns
  • a table containing the certificates that make up the SSL certificate chain securing the most recent committed navigation. Each certificate is described in a table with the following keys:
    • commonName - the common name for the certificate; most commonly this will be a string matching the server portion of the URL request or other descriptor of the certificate's purpose.
    • values - a table containing key-value pairs describing the certificate. The keys will be certificate OIDs. Common OIDs and their meaning can be found in hs.webview.certificateOIDs. The value for each key will be a table with the following keys:
      • label - a description or label for the entry
      • localized label - a localized version of label
      • type - a description of the data type for this value
      • value - the value
Notes
  • This method is only supported by OS X 10.11 and newer
  • A navigation which was performed via HTTP instead of HTTPS will return an empty array.
Source extensions/webview/internal.m
children
Signature hs.webview:children() -> array
Type Method
Description Returns an array of webview objects which have been opened as children of this webview.
Parameters
  • None
Returns
  • an array containing the webview objects of all child windows opened from this webview.
Source extensions/webview/internal.m
closeOnEscape
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
  • flag - an optional boolean value which indicates whether a webview, when it's style includes Closable (see hs.webview:windowStyle), should allow the Escape key to be a shortcut for closing the webview window. Defaults to false.
Returns
  • If a value is provided, then this method returns the webview object; otherwise the current value
Notes
  • If this is set to true, Escape will only close the window if no other element responds to the Escape key first (e.g. if you are editing a text input field, the Escape will be captured by the text field, not by the webview Window.)
Source extensions/webview/internal.m
darkMode
Signature hs.webview:darkMode([state]) -> bool
Type Method
Description Set or display whether or not the `hs.webview` window should display in dark mode.
Parameters
  • state - an optional boolean which will set whether or not the hs.webview window should display in dark mode.
Returns
  • A boolean, true if dark mode is enabled otherwise false.
Source extensions/webview/internal.m
delete
Signature hs.webview:delete([propagate], [fadeOutTime]) -> none
Type Method
Description Destroys the webview object, optionally fading it out first (if currently visible).
Parameters
  • propagate - an optional boolean, default false, which indicates whether or not the child windows of this webview should also be deleted.
  • fadeOutTime - an optional number of seconds over which to fade out the webview object. Defaults to zero.
Returns
  • None
Notes
  • This method is automatically called during garbage collection, notably during a Hammerspoon termination or reload, with a fade time of 0.
Source extensions/webview/init.lua
deleteOnClose
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
  • value - an optional boolean value which sets whether or not the webview will delete itself when its window is closed by any method. Defaults to false for a window created with hs.webview.new and true for any webview windows created by the main webview (user selects "Open Link in New Window", etc.)
Returns
  • If a value is provided, then this method returns the webview object; otherwise the current value
Notes
  • If set to true, a webview object will be deleted when the user clicks on the close button of a titled and closable webview (see hs.webview.windowStyle).
  • Children of an explicitly created webview automatically have this attribute set to true. To cause closed children to remain after the user closes the parent, you can set this to false with a policy callback function when it receives the "newWindow" action.
Source extensions/webview/internal.m
estimatedProgress
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
  • None
Returns
  • a numerical value between 0.0 and 1.0 indicating the percentage of expected content which has been loaded.
Source extensions/webview/internal.m
evaluateJavaScript
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
  • script - the JavaScript to execute within the context of the current webview's display
  • callback - an optional function which should accept two parameters as the result of the executed JavaScript. The function parameters are as follows:
    • result - the result of the executed JavaScript code or nil if there was no result or an error occurred.
    • error - an NSError table describing any error that occurred during the JavaScript execution or nil if no error occurred.
Returns
  • the webview object
Source extensions/webview/internal.m
examineInvalidCertificates
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
  • flag - an optional boolean, default false, specifying whether or not an invalid SSL server certificate should be accepted if it is approved by the ssl callback function.
Returns
  • If a value is provided, then this method returns the webview object; otherwise the current value
Notes
  • In order for this setting to have any effect, you must also register an ssl callback function with hs.webview:sslCallback which should return true if the certificate should be granted an exception or false if it should not. For a certificate to be granted an exception, both this method and the result of the callback must be true.
Source extensions/webview/internal.m
frame
Signature hs.webview:frame([rect]) -> webviewObject | currentValue
Type Method
Description Get or set the frame of the webview window.
Parameters
  • rect - An optional rect-table containing the co-ordinates and size the webview window should be moved and set to
Returns
  • If an argument is provided, the webview object; otherwise the current value.
Notes
  • a rect-table is a table with key-value pairs specifying the new top-left coordinate on the screen of the webview window (keys x and y) and the new size (keys h and w). The table may be crafted by any method which includes these keys, including the use of an hs.geometry object.
Source extensions/webview/init.lua
goBack
Signature hs.webview:goBack() -> webviewObject
Type Method
Description Move to the previous page in the webview's history, if possible.
Parameters
  • None
Returns
  • The webview Object
Source extensions/webview/internal.m
goForward
Signature hs.webview:goForward() -> webviewObject
Type Method
Description Move to the next page in the webview's history, if possible.
Parameters
  • None
Returns
  • The webview Object
Source extensions/webview/internal.m
hide
Signature hs.webview:hide([fadeOutTime]) -> webviewObject
Type Method
Description Hides the webview object
Parameters
  • fadeOutTime - An optional number of seconds over which to fade out the webview. Defaults to zero
Returns
  • The webview object
Source extensions/webview/internal.m
historyList
Signature hs.webview:historyList() -> historyTable
Type Method
Description Returns the URL history for the current webview as an array.
Parameters
  • None
Returns
  • A table which is an array of the URLs viewed within this webview and a key named current which is equal to the index corresponding to the currently visible entry. Each array element will be a table with the following keys:
    • URL - the URL of the web page
    • initialURL - the URL of the initial request that led to this item
    • title - the web page title
Source extensions/webview/internal.m
hswindow
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
  • None
Returns
  • an hs.window object
Notes
  • hs.window:minimize only works if the webview is minimizable (see hs.webview.windowStyle)
  • hs.window:setSize only works if the webview is resizable (see hs.webview.windowStyle)
  • hs.window:close only works if the webview is closable (see hs.webview.windowStyle)
  • hs.window:maximize will reposition the webview to the upper left corner of your screen, but will only resize the webview if the webview is resizable (see hs.webview.windowStyle)
Source extensions/webview/internal.m
html
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
  • html - the html to be rendered in the webview
  • baseURL - an optional Base URL to use as the starting point for any relative links within the provided html.
Returns
  • The webview Object
Notes
  • Web Pages generated in this manner are not added to the webview history list
Source extensions/webview/internal.m
isOnlySecureContent
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
  • None
Returns
  • true if all content current displayed in the web view was loaded over securely encrypted connections; otherwise false.
Source extensions/webview/internal.m
isVisible
Signature hs.webview:isVisible() -> boolean
Type Method
Description Checks to see if a webview window is visible or not.
Parameters
  • None
Returns
  • true if the webview window is visible, otherwise false
Source extensions/webview/internal.m
level
Signature hs.webview:level([theLevel]) -> drawingObject | currentValue
Type Method
Description Get or set the window level
Parameters
  • theLevel - an optional parameter specifying the desired level as an integer, which can be obtained from hs.drawing.windowLevels.
Returns
  • if a parameter is specified, returns the webview object, otherwise the current value
Notes
  • see the notes for hs.drawing.windowLevels
Source extensions/webview/internal.m
loading
Signature hs.webview:loading() -> boolean
Type Method
Description Returns a boolean value indicating whether or not the vebview is still loading content.
Parameters
  • None
Returns
  • true if the content is still being loaded, or false if it has completed.
Source extensions/webview/internal.m
magnification
Signature hs.webview:magnification([value]) -> webviewObject | current value
Type Method
Description Get or set the webviews current magnification level. Default is 1.0.
Parameters
  • value - an optional number specifying the webviews magnification level.
Returns
  • If a value is provided, then this method returns the webview object; otherwise the current value
Source extensions/webview/internal.m
orderAbove
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
  • webview2 -An optional webview object to place the webview object above.
Returns
  • The webview object
Notes
  • If the webview object and webview2 are not at the same presentation level, this method will will move the webview object as close to the desired relationship without changing the webview object's presentation level. See hs.webview.level.
Source extensions/webview/internal.m
orderBelow
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
  • webview2 -An optional webview object to place the webview object below.
Returns
  • The webview object
Notes
  • If the webview object and webview2 are not at the same presentation level, this method will will move the webview object as close to the desired relationship without changing the webview object's presentation level. See hs.webview.level.
Source extensions/webview/internal.m
parent
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
  • None
Returns
  • the parent webview object for the calling webview object, or nil if the webview has no parent
Source extensions/webview/internal.m
policyCallback
Signature hs.webview:policyCallback(fn) -> webviewObject
Type Method
Description Sets a callback to approve or deny web navigation activity.
Parameters
  • fn - the function to be called to approve or deny web navigation activity. To disable the callback function, explicitly specify nil. The callback function will accept three or four arguments and must return 1 argument which will determine if the action is approved or denied. The first argument will specify the type of policy request and will determine the second and third arguments as follows:
Returns
  • The webview object
Notes
  • With the newWindow action, the navigationCallback and policyCallback are automatically replicated for the new window from its parent. If you wish to disable these for the new window or assign a different set of callback functions, you can do so before returning true in the callback function with the webview argument provided.
Source extensions/webview/internal.m
privateBrowsing
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
  • None
Returns
  • a boolean value indicating whether or not the datastore is non-persistent.
Notes
  • This method is only supported by OS X 10.11 and newer
Source extensions/webview/internal.m
reload
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
  • validate - an optional boolean indicating whether or not an attempt to perform end-to-end revalidation of cached data should be performed. Defaults to false.
Returns
  • The webview Object
Source extensions/webview/internal.m
sendToBack
Signature hs.webview:sendToBack() -> webviewObject
Type Method
Description Places the webview object behind normal windows, between the desktop wallpaper and desktop icons
Parameters
  • None
Returns
  • The drawing object
Source extensions/webview/internal.m
shadow
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
  • value - an optional boolean value indicating whether or not the webview should have shadows.
Returns
  • If a value is provided, then this method returns the webview object; otherwise the current value
Source extensions/webview/internal.m
show
Signature hs.webview:show([fadeInTime]) -> webviewObject
Type Method
Description Displays the webview object
Parameters
  • fadeInTime - An optional number of seconds over which to fade in the webview. Defaults to zero
Returns
  • The webview object
Source extensions/webview/internal.m
size
Signature hs.webview:size([size]) -> webviewObject | currentValue
Type Method
Description Get or set the size of a webview window
Parameters
  • size - An optional size-table specifying the width and height the webview window should be resized to
Returns
  • If an argument is provided, the webview object; otherwise the current value.
Notes
  • a size-table is a table with key-value pairs specifying the size (keys h and w) the webview should be resized to. The table may be crafted by any method which includes these keys, including the use of an hs.geometry object.
Source extensions/webview/internal.m
sslCallback
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
  • fn - the function to be called to examine the SSL certificate to determine if an exception should be granted. To disable the callback function, explicitly specify nil. The callback function will accept two arguments and must return 1 argument which will determine if the action is approved or denied. The first argument will be the webview this request originates from. The second argument will be a table containing the protection space details and may include the following keys:
Returns
  • The webview object
Notes
  • even if this callback returns true, the certificate will only be granted an exception if hs.webview:examineInvalidCertificates has also been set to true.
  • once an invalid certificate has been granted an exception, the exception will remain in effect until the webview object is deleted.
  • the callback is only invoked for invalid certificates -- if a certificate is valid, or once an exception has been granted, the callback will not (no longer) be called for that certificate.
Source extensions/webview/internal.m
stopLoading
Signature hs.webview:stopLoading() -> webviewObject
Type Method
Description Stop loading additional content for the webview.
Parameters
  • None
Returns
  • The webview object
Notes
  • this method does not stop the loading of the primary content for the page at the specified URL
  • if hs.webview:loading would return true, this method does nothing -- see notes:
    • The documentation from Apple is unclear and experimentation has shown that if this method is applied before the content of the specified URL has loaded, it can cause the webview to lock up; however it appears to stop the loading of addiional resources specified for the content (external script files, external style files, AJAX queries, etc.) and should be used in this context.
Source extensions/webview/internal.m
title
Signature hs.webview:title() -> title
Type Method
Description Get the title of the page displayed in the webview.
Parameters
  • None
Returns
  • the title
Source extensions/webview/internal.m
topLeft
Signature hs.webview:topLeft([point]) -> webviewObject | currentValue
Type Method
Description Get or set the top-left coordinate of the webview window
Parameters
  • point - An optional point-table specifying the new coordinate the top-left of the webview window should be moved to
Returns
  • If an argument is provided, the webview object; otherwise the current value.
Notes
  • a point-table is a table with key-value pairs specifying the new top-left coordinate on the screen of the webview (keys x and y). The table may be crafted by any method which includes these keys, including the use of an hs.geometry object.
Source extensions/webview/internal.m
transparent
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
  • value - an optional boolean value indicating whether or not the webview should be transparent.
Returns
  • If a value is provided, then this method returns the webview object; otherwise the current value
Notes
  • When enabled, the webview's background color is equal to the body's background-color (transparent by default)
  • Setting background-color:rgba(0, 225, 0, 0.3) on <body> will give a translucent green webview background
Source extensions/webview/internal.m
url
Signature hs.webview:url([URL]) -> webviewObject, navigationIdentifier | url
Type Method
Description Get or set the URL to render for the webview.
Parameters
  • URL - an optional string or table representing the URL to display. If you provide a table, it should contain one or more of the following keys (note that URL is the only required key):
    • URL - the URL of the desired content
    • mainDocumentURL - the URL of the main document, if it differs. This usually only matters for cookie negotiation and currently has no effect in this module.
    • HTTPBody - the message body of the request, as in an HTTP POST request
    • HTTPMethod - the HTTP Method of the request, default GET.
    • timeoutInterval - the timeout interval for the request in seconds, default 60.0.
    • HTTPShouldHandleCookies - whether or not cookies should be managed automatically, default true. Currently there is no support for the manual handling of cookies, though this may change in the future.
    • HTTPShouldUsePipelining - whether or not the request can continue to transmit data before receiving a response from the remote server. Default false.
    • cachePolicy - a string value representing the cache policy for the request. It should match one of the following: protocolCachePolicy - (default) the cache policy defined as the default for the protocol of the URL request ignoreLocalCache - ignore any locally cached content and request all content from the remote server returnCacheOrLoad - return cached data, regardless of its age or expiration date. If there is no existing data in the cache corresponding to the request, load data from the originating source. returnCacheDontLoad - treat the request as if offline - return cached data, regardless of its age or expiration date. If there is no existing data in the cache corresponding to the request, the load is considered to have failed.
    • networkServiceType - a string value representing the network service type of the request. It should match one of the following: default - (default) standard network traffic. You should rarely use a value other than this as it can affect the responsiveness of your computer and other applications. VoIP - with the VoIP service type, the kernel continues to listen for incoming traffic while your app is in the background, then wakes up your app whenever new data arrives. This should be used only for connections that are used to communicate with a VoIP service. video - specifies that this is video traffic background - use this for data if your are performing a download that was not requested by the user — for example, prefetching content so that it will be available when the user chooses to view it. * voice - specifies that this is voice traffic
    • HTTPHeaderFields - a table containing key-value pairs corresponding to additional headers you wish to include in your request. Because the HTTP specification requires that both keys and values are strings, any key which is not a string is ignored, and any value which is not a string or number is also ignored. In addition, the following keys are handled automatically behind the scenes and will be ignored if you specify them: Authorization Connection Host WWW-Authenticate * Content-Length
Returns
  • If a URL is specified, then this method returns the webview Object; otherwise it returns the current url being displayed.
Notes
  • The networkServiceType field of the URL request table is a hint to the operating system about what the underlying traffic is used for. This hint enhances the system's ability to prioritize traffic, determine how quickly it needs to wake up the Wi-Fi radio, and so on. By providing accurate information, you improve the ability of the system to optimally balance battery life, performance, and other considerations. Likewise, inaccurate information can have a deleterious effect on your system performance and battery life.
Source extensions/webview/internal.m
urlParts
Signature hs.webview:urlParts() -> table
Type Method
Description Returns a table of keys containing the individual components of the URL for the webview.
Parameters
  • None
Returns
  • a table containing the keys for the webview's URL. See the function hs.http.urlParts for a description of the possible keys returned in the table.
Notes
  • This method is a wrapper to the hs.http.urlParts function wich uses the OS X APIs, based on RFC 1808.
  • You may also want to consider the hs.httpserver.hsminweb.urlParts function for a version more consistent with RFC 3986.
Source extensions/webview/init.lua
userAgent
Signature hs.webview:userAgent([agent]) -> webviewObject | current value
Type Method
Description Get or set the webview's user agent string
Parameters
  • agent - an options string specifying the user agent string to include in all URL requests made by the webview object.
Returns
  • if a parameter is specified, returns the webviewObject, otherwise returns the current value
Notes
  • This method is only supported by OS X 10.11 and newer
Source extensions/webview/internal.m
windowCallback
Signature hs.webview:windowCallback(fn) -> webviewObject
Type Method
Description Set or clear a callback for updates to the webview window
Parameters
  • fn - the function to be called when the webview window is moved or closed. Specify an explicit nil to clear the current callback. The function should expect 2 or 3 arguments and return none. The arguments will be one of the following:
Returns
  • The webview object
Source extensions/webview/internal.m
windowStyle
Signature hs.webview:windowStyle(mask) -> webviewObject | currentMask
Type Method
Description Get or set the window display style
Parameters
  • mask - if present, this mask should be a combination of values found in hs.webview.windowMasks describing the window style. The mask should be provided as one of the following:
    • integer - a number representing the style which can be created by combining values found in hs.webview.windowMasks with the logical or operator.
    • string - a single key from hs.webview.windowMasks which will be toggled in the current window style.
    • table - a list of keys from hs.webview.windowMasks which will be combined to make the final style by combining their values with the logical or operator.
Returns
  • if a mask is provided, then the webviewObject is returned; otherwise the current mask value is returned.
Source extensions/webview/init.lua
windowTitle
Signature hs.webview:windowTitle([title]) -> webviewObject
Type Method
Description Sets the title for the webview window.
Parameters
  • title - if specified and not nil, the title to set for the webview window. If this parameter is not present or is nil, the title will follow the title of the webview's content.
Returns
  • The webview Object
Notes
  • The title will be hidden unless the window style includes the "titled" style (see hs.webview.windowStyle and hs.webview.windowMasks)
Source extensions/webview/internal.m