WebKitGTK+ Reference Manual: WebKitWebSettings

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

## Functions

WebKitWebSettings * | webkit_web_settings_copy ()
WebKitWebSettings * | webkit_web_settings_new ()
const gchar * | webkit_web_settings_get_user_agent ()

## Properties

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

## Types and Values

| WebKitWebSettings
enum | WebKitEditingBehavior

## Object Hierarchy

        GObject
        ╰── WebKitWebSettings

## 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);

## Functions

### webkit_web_settings_copy ()

    WebKitWebSettings *
    webkit_web_settings_copy (WebKitWebSettings *web_settings);

Copies an existing WebKitWebSettings instance.

#### Parameters

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);

#### Parameters

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

## Types and Values

### WebKitWebSettings

    typedef struct _WebKitWebSettings WebKitWebSettings;

### enum WebKitEditingBehavior

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

#### Members

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. |

## Property Details

### The `“auto-load-images”` property

      “auto-load-images”         gboolean

Load images automatically.

Flags: Read / Write / Construct

Default value: TRUE

### The `“auto-resize-window”` property

      “auto-resize-window”       gboolean

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.

Flags: Read / Write / Construct

Default value: FALSE

Since 1.1.22

### The `“auto-shrink-images”` property

      “auto-shrink-images”       gboolean

Automatically shrink standalone images to fit.

Flags: Read / Write / Construct

Default value: TRUE

### The `“cursive-font-family”` property

      “cursive-font-family”      gchar *

The default Cursive font family used to display text.

Flags: Read / Write / Construct

Default value: "serif"

### The `“default-encoding”` property

      “default-encoding”         gchar *

The default encoding used to display text.

Flags: Read / Write / Construct

Default value: "iso-8859-1"

### The `“default-font-family”` property

      “default-font-family”      gchar *

The default font family used to display text.

Flags: Read / Write / Construct

Default value: "sans-serif"

### The `“default-font-size”` property

      “default-font-size”        gint

The default font size used to display text.

Flags: Read / Write / Construct

Allowed values: >= 5

Default value: 12

### The `“default-monospace-font-size”` property

      “default-monospace-font-size” gint

The default font size used to display monospace text.

Flags: Read / Write / Construct

Allowed values: >= 5

Default value: 10

### The `“editing-behavior”` property

      “editing-behavior”         WebKitEditingBehavior

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.

Flags: Read / Write / Construct

Default value: WEBKIT_EDITING_BEHAVIOR_UNIX

Since 1.1.13

### The `“enable-accelerated-compositing”` property

      “enable-accelerated-compositing” gboolean

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.

Flags: Read / Write / Construct

Default value: FALSE

Since 1.7.5

### The `“enable-caret-browsing”` property

      “enable-caret-browsing”    gboolean

Whether to enable caret browsing mode.

Flags: Read / Write / Construct

Default value: FALSE

Since 1.1.6

### The `“enable-default-context-menu”` property

      “enable-default-context-menu” gboolean

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.

`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.

Flags: Read / Write / Construct

Default value: TRUE

Since 1.1.18

### The `“enable-developer-extras”` property

      “enable-developer-extras”  gboolean

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.

Flags: Read / Write / Construct

Default value: FALSE

Since 1.0.3

### The `“enable-display-of-insecure-content”` property

      “enable-display-of-insecure-content” gboolean

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

Flags: Read / Write / Construct

Default value: TRUE

Since 2.0

### The `“enable-dns-prefetching”` property

      “enable-dns-prefetching”   gboolean

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.

Flags: Read / Write / Construct

Default value: TRUE

Since 1.3.13.

### The `“enable-dom-paste”` property

      “enable-dom-paste”         gboolean

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

Flags: Read / Write / Construct

Default value: FALSE

Since 1.1.16

### The `“enable-file-access-from-file-uris”` property

      “enable-file-access-from-file-uris” gboolean

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

Flags: Read / Write / Construct

Default value: FALSE

Since 1.1.22

### The `“enable-frame-flattening”` property

      “enable-frame-flattening”  gboolean

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.

Flags: Read / Write / Construct

Default value: FALSE

Since 1.3.5

### The `“enable-fullscreen”` property

      “enable-fullscreen”        gboolean

Whether to enable the Javascript Fullscreen API. The API allows any HTML element to request fullscreen display. See also the current draft of the spec: http://www.w3.org/TR/fullscreen/

Flags: Read / Write / Construct

Default value: TRUE

Since 2.4

### The `“enable-html5-database”` property

      “enable-html5-database”    gboolean

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.

Flags: Read / Write / Construct

Default value: TRUE

Since 1.1.8

### The `“enable-html5-local-storage”` property

      “enable-html5-local-storage” gboolean

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

Flags: Read / Write / Construct

Default value: TRUE

Since 1.1.8

### The `“enable-hyperlink-auditing”` property

      “enable-hyperlink-auditing” gboolean

Enable or disable support for <a ping>.

Flags: Read / Write / Construct

Default value: FALSE

Since 1.2.5

### The `“enable-java-applet”` property

      “enable-java-applet”       gboolean

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.

Flags: Read / Write / Construct

Default value: TRUE

Since 1.1.22

### The `“enable-media-stream”` property

      “enable-media-stream”      gboolean

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/

Flags: Read / Write / Construct

Default value: FALSE

Since 1.10.0

### The `“enable-mediasource”` property

      “enable-mediasource”       gboolean

Enable or disable support for MediaSource on pages. MediaSource is an experimental proposal which extends HTMLMediaElement to allow JavaScript to generate media streams for playback. The standard is currently a work-in-progress by the W3C HTML Media Task Force.

See also http://www.w3.org/TR/media-source/

Flags: Read / Write / Construct

Default value: FALSE

Since 2.4

### The `“enable-offline-web-application-cache”` property

      “enable-offline-web-application-cache” gboolean

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.

Flags: Read / Write / Construct

Default value: TRUE

Since 1.1.13

### The `“enable-page-cache”` property

      “enable-page-cache”        gboolean

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/

Flags: Read / Write / Construct

Default value: FALSE

Since 1.1.18

### The `“enable-plugins”` property

      “enable-plugins”           gboolean

Enable embedded plugin objects.

Flags: Read / Write / Construct

Default value: TRUE

### The `“enable-private-browsing”` property

      “enable-private-browsing”  gboolean

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.

Flags: Read / Write / Construct

Default value: FALSE

Since 1.1.2

### The `“enable-running-of-insecure-content”` property

      “enable-running-of-insecure-content” gboolean

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

Flags: Read / Write / Construct

Default value: TRUE

Since 2.0

### The `“enable-scripts”` property

      “enable-scripts”           gboolean

Enable embedded scripting languages.

Flags: Read / Write / Construct

Default value: TRUE

### The `“enable-site-specific-quirks”` property

      “enable-site-specific-quirks” gboolean

Enables the site-specific compatibility workarounds.

Flags: Read / Write / Construct

Default value: FALSE

### The `“enable-smooth-scrolling”` property

      “enable-smooth-scrolling”  gboolean

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

Flags: Read / Write / Construct

Default value: FALSE

Since 1.9.0

### The `“enable-spatial-navigation”` property

      “enable-spatial-navigation” gboolean

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.

Flags: Read / Write / Construct

Default value: FALSE

Since 1.1.23

### The `“enable-spell-checking”` property

      “enable-spell-checking”    gboolean

Whether to enable spell checking while typing.

Flags: Read / Write / Construct

Default value: FALSE

Since 1.1.6

### The `“enable-universal-access-from-file-uris”` property

      “enable-universal-access-from-file-uris” gboolean

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

Flags: Read / Write / Construct

Default value: FALSE

Since 1.1.13

### The `“enable-webaudio”` property

      “enable-webaudio”          gboolean

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

Flags: Read / Write / Construct

Default value: FALSE

Since TODO

### The `“enable-webgl”` property

      “enable-webgl”             gboolean

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.

Flags: Read / Write / Construct

Default value: FALSE

Since 1.3.14

### The `“enable-xss-auditor”` property

      “enable-xss-auditor”       gboolean

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

Flags: Read / Write / Construct

Default value: TRUE

Since 1.1.11

### The `“enforce-96-dpi”` property

      “enforce-96-dpi”           gboolean

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.

Flags: Read / Write / Construct

Default value: FALSE

Since 1.0.3

### The `“fantasy-font-family”` property

      “fantasy-font-family”      gchar *

The default Fantasy font family used to display text.

Flags: Read / Write / Construct

Default value: "serif"

### The `“html5-local-storage-database-path”` property

      “html5-local-storage-database-path” gchar *

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

Flags: Read / Write / Construct

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

Since 1.5.2

### The `“javascript-can-access-clipboard”` property

      “javascript-can-access-clipboard” gboolean

Whether JavaScript can access Clipboard.

Flags: Read / Write / Construct

Default value: FALSE

Since 1.3.0

### The `“javascript-can-open-windows-automatically”` property

      “javascript-can-open-windows-automatically” gboolean

Whether JavaScript can open popup windows automatically without user intervention.

Flags: Read / Write / Construct

Default value: FALSE

Since 1.1.11

### The `“media-playback-allows-inline”` property

      “media-playback-allows-inline” gboolean

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.

Flags: Read / Write / Construct

Default value: TRUE

Since 1.10.0

### The `“media-playback-requires-user-gesture”` property

      “media-playback-requires-user-gesture” gboolean

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.

Flags: Read / Write / Construct

Default value: FALSE

Since 1.10.0

### The `“minimum-font-size”` property

      “minimum-font-size”        gint

The minimum font size used to display text.

Flags: Read / Write / Construct

Allowed values: >= 0

Default value: 5

### The `“minimum-logical-font-size”` property

      “minimum-logical-font-size” gint

The minimum logical font size used to display text.

Flags: Read / Write / Construct

Allowed values: >= 1

Default value: 5

### The `“monospace-font-family”` property

      “monospace-font-family”    gchar *

The default font family used to display monospace text.

Flags: Read / Write / Construct

Default value: "monospace"

### The `“print-backgrounds”` property

      “print-backgrounds”        gboolean

Whether background images should be printed.

Flags: Read / Write / Construct

Default value: TRUE

### The `“resizable-text-areas”` property

      “resizable-text-areas”     gboolean

Whether text areas are resizable.

Flags: Read / Write / Construct

Default value: TRUE

### The `“respect-image-orientation”` property

      “respect-image-orientation” gboolean

Whether WebKit should respect image orientation.

Flags: Read / Write / Construct

Default value: FALSE

### The `“sans-serif-font-family”` property

      “sans-serif-font-family”   gchar *

The default Sans Serif font family used to display text.

Flags: Read / Write / Construct

Default value: "sans-serif"

### The `“serif-font-family”` property

      “serif-font-family”        gchar *

The default Serif font family used to display text.

Flags: Read / Write / Construct

Default value: "serif"

### The `“spell-checking-languages”` property

      “spell-checking-languages” gchar *

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.

Flags: Read / Write / Construct

Default value: NULL

Since 1.1.6

### The `“tab-key-cycles-through-elements”` property

      “tab-key-cycles-through-elements” gboolean

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.

Flags: Read / Write / Construct

Default value: TRUE

Since 1.1.17

### The `“user-agent”` property

      “user-agent”               gchar *

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.

Flags: Read / Write / Construct

Default value: ""

Since 1.1.11

### The `“user-stylesheet-uri”` property

      “user-stylesheet-uri”      gchar *

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

Flags: Read / Write / Construct

Default value: NULL

### The `“zoom-step”` property

      “zoom-step”                gfloat

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

Flags: Read / Write / Construct

Allowed values: >= 0

Default value: 0.1

Since 1.0.1