WebKitGTK+ Reference Manual: WebKitWebSettings

## WebKitWebSettings WebKitWebSettings — Control the behaviour of a WebKitWebView |

## Synopsis

                        WebKitWebSettings;
    enum                WebKitEditingBehavior;
    WebKitWebSettings * webkit_web_settings_copy            (WebKitWebSettings *web_settings);
    WebKitWebSettings * webkit_web_settings_new             (void);
    const gchar *       webkit_web_settings_get_user_agent  (WebKitWebSettings *web_settings);

## Object Hierarchy

      GObject
       +----WebKitWebSettings

## Properties

      "auto-load-images"         gboolean              : Read / Write / Construct
      "auto-resize-window"       gboolean              : Read / Write / Construct
      "auto-shrink-images"       gboolean              : Read / Write / Construct
      "cursive-font-family"      gchar*                : Read / Write / Construct
      "default-encoding"         gchar*                : Read / Write / Construct
      "default-font-family"      gchar*                : Read / Write / Construct
      "default-font-size"        gint                  : Read / Write / Construct
      "default-monospace-font-size" gint                  : Read / Write / Construct
      "editing-behavior"         WebKitEditingBehavior  : Read / Write / Construct
      "enable-accelerated-compositing" gboolean              : Read / Write / Construct
      "enable-caret-browsing"    gboolean              : Read / Write / Construct
      "enable-css-shaders"       gboolean              : Read / Write / Construct
      "enable-default-context-menu" gboolean              : Read / Write / Construct
      "enable-developer-extras"  gboolean              : Read / Write / Construct
      "enable-display-of-insecure-content" gboolean              : Read / Write / Construct
      "enable-dns-prefetching"   gboolean              : Read / Write / Construct
      "enable-dom-paste"         gboolean              : Read / Write / Construct
      "enable-file-access-from-file-uris" gboolean              : Read / Write / Construct
      "enable-frame-flattening"  gboolean              : Read / Write / Construct
      "enable-fullscreen"        gboolean              : Read / Write / Construct
      "enable-html5-database"    gboolean              : Read / Write / Construct
      "enable-html5-local-storage" gboolean              : Read / Write / Construct
      "enable-hyperlink-auditing" gboolean              : Read / Write / Construct
      "enable-java-applet"       gboolean              : Read / Write / Construct
      "enable-media-stream"      gboolean              : Read / Write / Construct
      "enable-offline-web-application-cache" gboolean              : Read / Write / Construct
      "enable-page-cache"        gboolean              : Read / Write / Construct
      "enable-plugins"           gboolean              : Read / Write / Construct
      "enable-private-browsing"  gboolean              : Read / Write / Construct
      "enable-running-of-insecure-content" gboolean              : Read / Write / Construct
      "enable-scripts"           gboolean              : Read / Write / Construct
      "enable-site-specific-quirks" gboolean              : Read / Write / Construct
      "enable-smooth-scrolling"  gboolean              : Read / Write / Construct
      "enable-spatial-navigation" gboolean              : Read / Write / Construct
      "enable-spell-checking"    gboolean              : Read / Write / Construct
      "enable-universal-access-from-file-uris" gboolean              : Read / Write / Construct
      "enable-webaudio"          gboolean              : Read / Write / Construct
      "enable-webgl"             gboolean              : Read / Write / Construct
      "enable-xss-auditor"       gboolean              : Read / Write / Construct
      "enforce-96-dpi"           gboolean              : Read / Write / Construct
      "fantasy-font-family"      gchar*                : Read / Write / Construct
      "html5-local-storage-database-path" gchar*                : Read / Write / Construct
      "javascript-can-access-clipboard" gboolean              : Read / Write / Construct
      "javascript-can-open-windows-automatically" gboolean              : Read / Write / Construct
      "media-playback-allows-inline" gboolean              : Read / Write / Construct
      "media-playback-requires-user-gesture" gboolean              : Read / Write / Construct
      "minimum-font-size"        gint                  : Read / Write / Construct
      "minimum-logical-font-size" gint                  : Read / Write / Construct
      "monospace-font-family"    gchar*                : Read / Write / Construct
      "print-backgrounds"        gboolean              : Read / Write / Construct
      "resizable-text-areas"     gboolean              : Read / Write / Construct
      "respect-image-orientation" gboolean              : Read / Write / Construct
      "sans-serif-font-family"   gchar*                : Read / Write / Construct
      "serif-font-family"        gchar*                : Read / Write / Construct
      "spell-checking-languages" gchar*                : Read / Write / Construct
      "tab-key-cycles-through-elements" gboolean              : Read / Write / Construct
      "user-agent"               gchar*                : Read / Write / Construct
      "user-stylesheet-uri"      gchar*                : Read / Write / Construct
      "zoom-step"                gfloat                : Read / Write / Construct

## Description

WebKitWebSettings can be applied to a WebKitWebView to control text encoding, color, font sizes, printing mode, script support, loading of images and various other things. After creation, a WebKitWebSettings object contains default settings.

    1
    2
    3
    4
    5
    6
    /* Create a new websettings and disable java script */
    WebKitWebSettings *settings = webkit_web_settings_new ();
    g_object_set (G_OBJECT(settings), "enable-scripts", FALSE, NULL);

    /* Apply the result */
    webkit_web_view_set_settings (WEBKIT_WEB_VIEW(my_webview), settings);

## Details

### WebKitWebSettings

    typedef struct _WebKitWebSettings WebKitWebSettings;

### enum WebKitEditingBehavior

    typedef enum {
        WEBKIT_EDITING_BEHAVIOR_MAC,
        WEBKIT_EDITING_BEHAVIOR_WINDOWS,
        WEBKIT_EDITING_BEHAVIOR_UNIX
    } WebKitEditingBehavior;

Enum values used for determining the editing behavior of editable elements.

`WEBKIT_EDITING_BEHAVIOR_MAC` | Editing behavior mimicking OS X user interfaces.
`WEBKIT_EDITING_BEHAVIOR_WINDOWS` | Editing behavior mimicking Windows user interfaces.
`WEBKIT_EDITING_BEHAVIOR_UNIX` | Editing behavior mimicking free desktop user interfaces.

### webkit_web_settings_copy ()

    WebKitWebSettings * webkit_web_settings_copy            (WebKitWebSettings *web_settings);

Copies an existing WebKitWebSettings instance.

`web_settings` : | a WebKitWebSettings to copy.
Returns : | a new WebKitWebSettings instance. [transfer full]

### webkit_web_settings_new ()

    WebKitWebSettings * webkit_web_settings_new             (void);

Creates a new WebKitWebSettings instance with default values. It must be manually attached to a WebView.

Returns : | a new WebKitWebSettings instance

### webkit_web_settings_get_user_agent ()

    const gchar *       webkit_web_settings_get_user_agent  (WebKitWebSettings *web_settings);

`web_settings` : | a WebKitWebSettings
Returns : | the User-Agent string currently used by the web view(s) associated with the `web_settings`.

Since 1.1.11

## Property Details

### The `"auto-load-images"` property

      "auto-load-images"         gboolean              : Read / Write / Construct

Load images automatically.

Default value: TRUE

### The `"auto-resize-window"` property

      "auto-resize-window"       gboolean              : Read / Write / Construct

Web pages can request to modify the size and position of the window containing the WebKitWebView through various DOM methods (resizeTo, moveTo, resizeBy, moveBy). By default WebKit will not honor this requests, but you can set this property to `TRUE` if you'd like it to do so. If you wish to handle this manually, you can connect to the notify signal for the WebKitWebWindowFeatures of your WebKitWebView.

Default value: FALSE

Since 1.1.22

### The `"auto-shrink-images"` property

      "auto-shrink-images"       gboolean              : Read / Write / Construct

Automatically shrink standalone images to fit.

Default value: TRUE

### The `"cursive-font-family"` property

      "cursive-font-family"      gchar*                : Read / Write / Construct

The default Cursive font family used to display text.

Default value: "serif"

### The `"default-encoding"` property

      "default-encoding"         gchar*                : Read / Write / Construct

The default encoding used to display text.

Default value: "iso-8859-1"

### The `"default-font-family"` property

      "default-font-family"      gchar*                : Read / Write / Construct

The default font family used to display text.

Default value: "sans-serif"

### The `"default-font-size"` property

      "default-font-size"        gint                  : Read / Write / Construct

The default font size used to display text.

Allowed values: >= 5

Default value: 12

### The `"default-monospace-font-size"` property

      "default-monospace-font-size" gint                  : Read / Write / Construct

The default font size used to display monospace text.

Allowed values: >= 5

Default value: 10

### The `"editing-behavior"` property

      "editing-behavior"         WebKitEditingBehavior  : Read / Write / Construct

This setting controls various editing behaviors that differ between platforms and that have been combined in two groups, 'Mac' and 'Windows'. Some examples:

1) Clicking below the last line of an editable area puts the caret at the end of the last line on Mac, but in the middle of the last line on Windows.

2) Pushing down the arrow key on the last line puts the caret at the end of the last line on Mac, but does nothing on Windows. A similar case exists on the top line.

Default value: WEBKIT_EDITING_BEHAVIOR_UNIX

Since 1.1.13

### The `"enable-accelerated-compositing"` property

      "enable-accelerated-compositing" gboolean              : Read / Write / Construct

Enable or disable support for accelerated compositing on pages. Accelerated compositing uses the GPU to render animations on pages smoothly and also allows proper rendering of 3D CSS transforms.

Default value: FALSE

Since 1.7.5

### The `"enable-caret-browsing"` property

      "enable-caret-browsing"    gboolean              : Read / Write / Construct

Whether to enable caret browsing mode.

Default value: FALSE

Since 1.1.6

### The `"enable-css-shaders"` property

      "enable-css-shaders"       gboolean              : Read / Write / Construct

Enable or disable support for css shaders (css custom filters). Accelerated compositing needs to be enabled at compile time, but needs not be enabled at runtime.

See also https://dvcs.w3.org/hg/FXTF/raw-file/tip/custom/index.html

Default value: FALSE

Since 2.0

### The `"enable-default-context-menu"` property

      "enable-default-context-menu" gboolean              : Read / Write / Construct

### Warning

`WebKitWebSettings:enable-default-context-menu` has been deprecated since version 1.10 and should not be used in newly-written code. Use "context-menu" signal instead.

Whether right-clicks should be handled automatically to create, and display the context menu. Turning this off will make WebKitGTK+ not emit the populate-popup signal. Notice that the default button press event handler may still handle right clicks for other reasons, such as in-page context menus, or right-clicks that are handled by the page itself.

Default value: TRUE

Since 1.1.18

### The `"enable-developer-extras"` property

      "enable-developer-extras"  gboolean              : Read / Write / Construct

Whether developer extensions should be enabled. This enables, for now, the Web Inspector, which can be controlled using the WebKitWebInspector instance held by the WebKitWebView this setting is enabled for.

Default value: FALSE

Since 1.0.3

### The `"enable-display-of-insecure-content"` property

      "enable-display-of-insecure-content" gboolean              : Read / Write / Construct

Whether pages loaded via HTTPS should load subresources such as images and frames from non-HTTPS URLs.

Default value: TRUE

Since 2.0

### The `"enable-dns-prefetching"` property

      "enable-dns-prefetching"   gboolean              : Read / Write / Construct

Whether webkit prefetches domain names. This is a separate knob from private browsing. Whether private browsing should set this or not is up for debate, for now it doesn't.

Default value: TRUE

Since 1.3.13.

### The `"enable-dom-paste"` property

      "enable-dom-paste"         gboolean              : Read / Write / Construct

Whether to enable DOM paste. If set to `TRUE`, document.execCommand("Paste") will correctly execute and paste content of the clipboard.

Default value: FALSE

Since 1.1.16

### The `"enable-file-access-from-file-uris"` property

      "enable-file-access-from-file-uris" gboolean              : Read / Write / Construct

Boolean property to control file access for file:// URIs. If this option is enabled every file:// will have its own security unique domain.

Default value: FALSE

Since 1.1.22

### The `"enable-frame-flattening"` property

      "enable-frame-flattening"  gboolean              : Read / Write / Construct

Whether to enable the Frame Flattening. With this setting each subframe is expanded to its contents, which will flatten all the frames to become one scrollable page. On touch devices, it is desired to not have any scrollable sub parts of the page as it results in a confusing user experience, with scrolling sometimes scrolling sub parts and at other times scrolling the page itself. For this reason iframes and framesets are barely usable on touch devices.

Default value: FALSE

Since 1.3.5

### The `"enable-fullscreen"` property

      "enable-fullscreen"        gboolean              : Read / Write / Construct

Whether the Mozilla style API should be enabled.

Default value: FALSE

### The `"enable-html5-database"` property

      "enable-html5-database"    gboolean              : Read / Write / Construct

Whether to enable HTML5 client-side SQL database support. Client-side SQL database allows web pages to store structured data and be able to use SQL to manipulate that data asynchronously.

Default value: TRUE

Since 1.1.8

### The `"enable-html5-local-storage"` property

      "enable-html5-local-storage" gboolean              : Read / Write / Construct

Whether to enable HTML5 localStorage support. localStorage provides simple synchronous storage access.

Default value: TRUE

Since 1.1.8

### The `"enable-hyperlink-auditing"` property

      "enable-hyperlink-auditing" gboolean              : Read / Write / Construct

Enable or disable support for <a ping>.

Default value: FALSE

Since 1.2.5

### The `"enable-java-applet"` property

      "enable-java-applet"       gboolean              : Read / Write / Construct

Enable or disable support for the Java <applet> tag. Keep in mind that Java content can be still shown in the page through <object> or <embed>, which are the preferred tags for this task.

Default value: TRUE

Since 1.1.22

### The `"enable-media-stream"` property

      "enable-media-stream"      gboolean              : Read / Write / Construct

Enable or disable support for Media Stream on pages. Media Stream is an experimental proposal for allowing web pages to access local video and audio input devices. The standard is currently a work-in-progress as part of the Web Applications 1.0 specification from WHATWG.

See also http://www.w3.org/TR/mediacapture-streams/

Default value: FALSE

Since 1.10.0

### The `"enable-offline-web-application-cache"` property

      "enable-offline-web-application-cache" gboolean              : Read / Write / Construct

Whether to enable HTML5 offline web application cache support. Offline Web Application Cache ensures web applications are available even when the user is not connected to the network.

Default value: TRUE

Since 1.1.13

### The `"enable-page-cache"` property

      "enable-page-cache"        gboolean              : Read / Write / Construct

Enable or disable the page cache. Disabling the page cache is generally only useful for special circumstances like low-memory scenarios or special purpose applications like static HTML viewers. This setting only controls the Page Cache, this cache is different than the disk-based or memory-based traditional resource caches, its point is to make going back and forth between pages much faster. For details about the different types of caches and their purposes see: http://webkit.org/blog/427/webkit-page-cache-i-the-basics/

Default value: FALSE

Since 1.1.18

### The `"enable-plugins"` property

      "enable-plugins"           gboolean              : Read / Write / Construct

Enable embedded plugin objects.

Default value: TRUE

### The `"enable-private-browsing"` property

      "enable-private-browsing"  gboolean              : Read / Write / Construct

Whether to enable private browsing mode. Private browsing mode prevents WebKit from updating the global history and storing any session information e.g., on-disk cache, as well as suppressing any messages from being printed into the (javascript) console.

This is currently experimental for WebKitGtk.

Default value: FALSE

Since 1.1.2

### The `"enable-running-of-insecure-content"` property

      "enable-running-of-insecure-content" gboolean              : Read / Write / Construct

Whether pages loaded via HTTPS should run subresources such as CSS, scripts, and plugins from non-HTTPS URLs.

Default value: TRUE

Since 2.0

### The `"enable-scripts"` property

      "enable-scripts"           gboolean              : Read / Write / Construct

Enable embedded scripting languages.

Default value: TRUE

### The `"enable-site-specific-quirks"` property

      "enable-site-specific-quirks" gboolean              : Read / Write / Construct

Enables the site-specific compatibility workarounds.

Default value: FALSE

### The `"enable-smooth-scrolling"` property

      "enable-smooth-scrolling"  gboolean              : Read / Write / Construct

Enable or disable support for smooth scrolling. The current implementation relies upon CPU work to produce a smooth scrolling experience.

Default value: FALSE

Since 1.9.0

### The `"enable-spatial-navigation"` property

      "enable-spatial-navigation" gboolean              : Read / Write / Construct

Whether to enable the Spatial Navigation. This feature consists in the ability to navigate between focusable elements in a Web page, such as hyperlinks and form controls, by using Left, Right, Up and Down arrow keys. For example, if an user presses the Right key, heuristics determine whether there is an element he might be trying to reach towards the right, and if there are multiple elements, which element he probably wants.

Default value: FALSE

Since 1.1.23

### The `"enable-spell-checking"` property

      "enable-spell-checking"    gboolean              : Read / Write / Construct

Whether to enable spell checking while typing.

Default value: FALSE

Since 1.1.6

### The `"enable-universal-access-from-file-uris"` property

      "enable-universal-access-from-file-uris" gboolean              : Read / Write / Construct

Whether to allow files loaded through file:// URIs universal access to all pages.

Default value: FALSE

Since 1.1.13

### The `"enable-webaudio"` property

      "enable-webaudio"          gboolean              : Read / Write / Construct

Enable or disable support for WebAudio on pages. WebAudio is an experimental proposal for allowing web pages to generate Audio WAVE data from JavaScript. The standard is currently a work-in-progress by the W3C Audio Working Group.

See also https://dvcs.w3.org/hg/audio/raw-file/tip/webaudio/specification.html

Default value: FALSE

Since TODO

### The `"enable-webgl"` property

      "enable-webgl"             gboolean              : Read / Write / Construct

Enable or disable support for WebGL on pages. WebGL is an experimental proposal for allowing web pages to use OpenGL ES-like calls directly. The standard is currently a work-in-progress by the Khronos Group.

Default value: FALSE

Since 1.3.14

### The `"enable-xss-auditor"` property

      "enable-xss-auditor"       gboolean              : Read / Write / Construct

Whether to enable the XSS Auditor. This feature filters some kinds of reflective XSS attacks on vulnerable web sites.

Default value: TRUE

Since 1.1.11

### The `"enforce-96-dpi"` property

      "enforce-96-dpi"           gboolean              : Read / Write / Construct

Enforce a resolution of 96 DPI. This is meant for compatibility with web pages which cope badly with different screen resolutions and for automated testing. Web browsers and applications that typically display arbitrary content from the web should provide a preference for this.

Default value: FALSE

Since 1.0.3

### The `"fantasy-font-family"` property

      "fantasy-font-family"      gchar*                : Read / Write / Construct

The default Fantasy font family used to display text.

Default value: "serif"

### The `"html5-local-storage-database-path"` property

      "html5-local-storage-database-path" gchar*                : Read / Write / Construct

Path to store persistent HTML5 localStorage databases, which are enabled by "enable-html5-local-storage". The default path is $XDG_DATA_HOME/webkit/databases/.

Default value: "/home/cgarcia/.local/share/webkit/databases"

Since 1.5.2

### The `"javascript-can-access-clipboard"` property

      "javascript-can-access-clipboard" gboolean              : Read / Write / Construct

Whether JavaScript can access Clipboard.

Default value: FALSE

Since 1.3.0

### The `"javascript-can-open-windows-automatically"` property

      "javascript-can-open-windows-automatically" gboolean              : Read / Write / Construct

Whether JavaScript can open popup windows automatically without user intervention.

Default value: FALSE

Since 1.1.11

### The `"media-playback-allows-inline"` property

      "media-playback-allows-inline" gboolean              : Read / Write / Construct

Whether media playback is full-screen only or inline playback is allowed. This is true by default, so media playback can be inline. Setting it to false allows specifying that media playback should be always fullscreen.

Default value: TRUE

Since 1.10.0

### The `"media-playback-requires-user-gesture"` property

      "media-playback-requires-user-gesture" gboolean              : Read / Write / Construct

Whether a user gesture (such as clicking the play button) would be required to start media playback or load media. This is off by default, so media playback could start automatically. Setting it on requires a gesture by the user to start playback, or to load the media.

Default value: FALSE

Since 1.10.0

### The `"minimum-font-size"` property

      "minimum-font-size"        gint                  : Read / Write / Construct

The minimum font size used to display text.

Allowed values: >= 0

Default value: 5

### The `"minimum-logical-font-size"` property

      "minimum-logical-font-size" gint                  : Read / Write / Construct

The minimum logical font size used to display text.

Allowed values: >= 1

Default value: 5

### The `"monospace-font-family"` property

      "monospace-font-family"    gchar*                : Read / Write / Construct

The default font family used to display monospace text.

Default value: "monospace"

### The `"print-backgrounds"` property

      "print-backgrounds"        gboolean              : Read / Write / Construct

Whether background images should be printed.

Default value: TRUE

### The `"resizable-text-areas"` property

      "resizable-text-areas"     gboolean              : Read / Write / Construct

Whether text areas are resizable.

Default value: TRUE

### The `"respect-image-orientation"` property

      "respect-image-orientation" gboolean              : Read / Write / Construct

Whether WebKit should respect image orientation.

Default value: FALSE

### The `"sans-serif-font-family"` property

      "sans-serif-font-family"   gchar*                : Read / Write / Construct

The default Sans Serif font family used to display text.

Default value: "sans-serif"

### The `"serif-font-family"` property

      "serif-font-family"        gchar*                : Read / Write / Construct

The default Serif font family used to display text.

Default value: "serif"

### The `"spell-checking-languages"` property

      "spell-checking-languages" gchar*                : Read / Write / Construct

The languages to be used for spell checking, separated by commas.

The locale string typically is in the form lang_COUNTRY, where lang is an ISO-639 language code, and COUNTRY is an ISO-3166 country code. For instance, sv_FI for Swedish as written in Finland or pt_BR for Portuguese as written in Brazil.

If no value is specified then the value returned by gtk_get_default_language will be used.

Default value: NULL

Since 1.1.6

### The `"tab-key-cycles-through-elements"` property

      "tab-key-cycles-through-elements" gboolean              : Read / Write / Construct

Whether the tab key cycles through elements on the page.

If `flag` is `TRUE`, pressing the tab key will focus the next element in the `web_view`. If `flag` is `FALSE`, the `web_view` will interpret tab key presses as normal key presses. If the selected element is editable, the tab key will cause the insertion of a tab character.

Default value: TRUE

Since 1.1.17

### The `"user-agent"` property

      "user-agent"               gchar*                : Read / Write / Construct

The User-Agent string used by WebKitGtk.

This will return a default User-Agent string if a custom string wasn't provided by the application. Setting this property to a NULL value or an empty string will result in the User-Agent string being reset to the default value.

Default value: ""

Since 1.1.11

### The `"user-stylesheet-uri"` property

      "user-stylesheet-uri"      gchar*                : Read / Write / Construct

The URI of a stylesheet that is applied to every page.

Default value: NULL

### The `"zoom-step"` property

      "zoom-step"                gfloat                : Read / Write / Construct

The value by which the zoom level is changed when zooming in or out.

Allowed values: >= 0

Default value: 0.1

Since 1.0.1