WebKitGTK+ Reference Manual: WebKitWebFrame

## WebKitWebFrame WebKitWebFrame — The content of a WebKitWebView |

## Synopsis

    enum                WebKitLoadStatus;
                        WebKitWebFrame;
    WebKitWebFrame *    webkit_web_frame_find_frame         (WebKitWebFrame *frame,
                                                             const gchar *name);
    WebKitWebDataSource * webkit_web_frame_get_data_source  (WebKitWebFrame *frame);
    WebKitDOMDocument * webkit_web_frame_get_dom_document   (WebKitWebFrame *frame);
    JSGlobalContextRef  webkit_web_frame_get_global_context (WebKitWebFrame *frame);
    GtkPolicyType       webkit_web_frame_get_horizontal_scrollbar_policy
                                                            (WebKitWebFrame *frame);
    WebKitLoadStatus    webkit_web_frame_get_load_status    (WebKitWebFrame *frame);
    const gchar *       webkit_web_frame_get_name           (WebKitWebFrame *frame);
    WebKitNetworkResponse * webkit_web_frame_get_network_response
                                                            (WebKitWebFrame *frame);
    WebKitWebFrame *    webkit_web_frame_get_parent         (WebKitWebFrame *frame);
    WebKitWebDataSource * webkit_web_frame_get_provisional_data_source
                                                            (WebKitWebFrame *frame);
    WebKitSecurityOrigin * webkit_web_frame_get_security_origin
                                                            (WebKitWebFrame *frame);
    const gchar *       webkit_web_frame_get_title          (WebKitWebFrame *frame);
    const gchar *       webkit_web_frame_get_uri            (WebKitWebFrame *frame);
    GtkPolicyType       webkit_web_frame_get_vertical_scrollbar_policy
                                                            (WebKitWebFrame *frame);
    WebKitWebView *     webkit_web_frame_get_web_view       (WebKitWebFrame *frame);
    void                webkit_web_frame_load_alternate_string
                                                            (WebKitWebFrame *frame,
                                                             const gchar *content,
                                                             const gchar *base_url,
                                                             const gchar *unreachable_url);
    void                webkit_web_frame_load_request       (WebKitWebFrame *frame,
                                                             WebKitNetworkRequest *request);
    void                webkit_web_frame_load_string        (WebKitWebFrame *frame,
                                                             const gchar *content,
                                                             const gchar *mime_type,
                                                             const gchar *encoding,
                                                             const gchar *base_uri);
    void                webkit_web_frame_load_uri           (WebKitWebFrame *frame,
                                                             const gchar *uri);
    WebKitWebFrame *    webkit_web_frame_new                (WebKitWebView *web_view);
    void                webkit_web_frame_print              (WebKitWebFrame *frame);
    GtkPrintOperationResult webkit_web_frame_print_full     (WebKitWebFrame *frame,
                                                             GtkPrintOperation *operation,
                                                             GtkPrintOperationAction action,
                                                             GError **error);
    void                webkit_web_frame_reload             (WebKitWebFrame *frame);
    void                webkit_web_frame_stop_loading       (WebKitWebFrame *frame);

## Object Hierarchy

      GObject
       +----WebKitWebFrame

## Properties

      "horizontal-scrollbar-policy" GtkPolicyType         : Read
      "load-status"              WebKitLoadStatus      : Read
      "name"                     gchar*                : Read
      "title"                    gchar*                : Read
      "uri"                      gchar*                : Read
      "vertical-scrollbar-policy" GtkPolicyType         : Read

## Signals

      "cleared"                                        : Run Last
      "hovering-over-link"                             : Run Last
      "insecure-content-run"                           : Run Last
      "load-committed"                                 : Run Last
      "resource-content-length-received"               : Run Last
      "resource-load-failed"                           : Run Last
      "resource-load-finished"                         : Run Last
      "resource-request-starting"                      : Run Last
      "resource-response-received"                     : Run Last
      "scrollbars-policy-changed"                      : Action
      "title-changed"                                  : Run Last

## Description

A WebKitWebView contains a main WebKitWebFrame. A WebKitWebFrame contains the content of one URI. The URI and name of the frame can be retrieved, the load status and progress can be observed using the signals and can be controlled using the methods of the WebKitWebFrame. A WebKitWebFrame can have any number of children and one child can be found by using webkit_web_frame_find_frame.

    1
    2
    3
    /* Get the frame from the <a class="link" href="webkitgtk-webkitwebview.html#WebKitWebView">WebKitWebView</a> */
    WebKitWebFrame *frame = webkit_web_view_get_main_frame (WEBKIT_WEB_VIEW(my_view));
    g_print ("The URI of this frame is '%s'", webkit_web_frame_get_uri (frame));

## Details

### enum WebKitLoadStatus

    typedef enum {
        WEBKIT_LOAD_PROVISIONAL,
        WEBKIT_LOAD_COMMITTED,
        WEBKIT_LOAD_FINISHED,
        WEBKIT_LOAD_FIRST_VISUALLY_NON_EMPTY_LAYOUT,
        WEBKIT_LOAD_FAILED
    } WebKitLoadStatus;

`WEBKIT_LOAD_PROVISIONAL` | No data has been received yet, empty structures have been allocated to perform the load; the load may still fail for transport issues such as not being able to resolve a name, or connect to a port.
`WEBKIT_LOAD_COMMITTED` | The first data chunk has arrived, meaning that the necessary transport requirements are stabilished, and the load is being performed.
`WEBKIT_LOAD_FINISHED` | This state means that everything that was required to display the page has been loaded.
`WEBKIT_LOAD_FIRST_VISUALLY_NON_EMPTY_LAYOUT` | The first layout with actual visible content happened; one or more layouts may have happened before that caused nothing to be visible on the screen, because the data available at the time was not significant enough.
`WEBKIT_LOAD_FAILED` | This state means that some error occurred during the page load that prevented it from being completed. You can connect to the "load-error" signal if you want to know precisely what kind of error occurred.

### WebKitWebFrame

    typedef struct _WebKitWebFrame WebKitWebFrame;

### webkit_web_frame_find_frame ()

    WebKitWebFrame *    webkit_web_frame_find_frame         (WebKitWebFrame *frame,
                                                             const gchar *name);

For pre-defined names, returns `frame` if `name` is "_self" or "_current", returns `frame`'s parent frame if `name` is "_parent", and returns the main frame if `name` is "_top". Also returns `frame` if it is the main frame and `name` is either "_parent" or "_top". For other names, this function returns the first frame that matches `name`. This function searches `frame` and its descendents first, then `frame`'s parent and its children moving up the hierarchy until a match is found. If no match is found in `frame`'s hierarchy, this function will search for a matching frame in other main frame hierarchies. Returns `NULL` if no match is found.

`frame` : | a WebKitWebFrame
`name` : | the name of the frame to be found
Returns : | the found WebKitWebFrame or `NULL` in case none is found. [transfer none]

### webkit_web_frame_get_data_source ()

    WebKitWebDataSource * webkit_web_frame_get_data_source  (WebKitWebFrame *frame);

Returns the committed data source.

`frame` : | a WebKitWebFrame
Returns : | the committed WebKitWebDataSource. [transfer none]

Since 1.1.14

### webkit_web_frame_get_dom_document ()

    WebKitDOMDocument * webkit_web_frame_get_dom_document   (WebKitWebFrame *frame);

`frame` : | a WebKitWebFrame
Returns : | the WebKitDOMDocument currently loaded in the `frame` or `NULL` if no document is loaded. [transfer none]

Since 1.10

### webkit_web_frame_get_global_context ()

    JSGlobalContextRef  webkit_web_frame_get_global_context (WebKitWebFrame *frame);

Gets the global JavaScript execution context. Use this function to bridge between the WebKit and JavaScriptCore APIs.

`frame` : | a WebKitWebFrame
Returns : | the global JavaScript context JSGlobalContextRef. [transfer none]

### webkit_web_frame_get_horizontal_scrollbar_policy ()

    GtkPolicyType       webkit_web_frame_get_horizontal_scrollbar_policy
                                                            (WebKitWebFrame *frame);

### webkit_web_frame_get_load_status ()

    WebKitLoadStatus    webkit_web_frame_get_load_status    (WebKitWebFrame *frame);

Determines the current status of the load.

`frame` : | a WebKitWebView
Returns : | The WebKitLoadStatus specifying the status of the current load.

Since 1.1.7

### webkit_web_frame_get_name ()

    const gchar *       webkit_web_frame_get_name           (WebKitWebFrame *frame);

Returns the `frame`'s name

`frame` : | a WebKitWebFrame
Returns : | the name of `frame`. This method will return NULL if the WebKitWebFrame is invalid or an empty string if it is not backed by a live WebCore frame.

### webkit_web_frame_get_network_response ()

    WebKitNetworkResponse * webkit_web_frame_get_network_response
                                                            (WebKitWebFrame *frame);

Returns a WebKitNetworkResponse object representing the response that was given to the request for the given frame, or NULL if the frame was not created by a load. You must unref the object when you are done with it.

`frame` : | a WebKitWebFrame
Returns : | a WebKitNetworkResponse object. [transfer full]

Since 1.1.18

### webkit_web_frame_get_parent ()

    WebKitWebFrame *    webkit_web_frame_get_parent         (WebKitWebFrame *frame);

Returns the `frame`'s parent frame, or `NULL` if it has none.

`frame` : | a WebKitWebFrame
Returns : | the parent WebKitWebFrame or `NULL` in case there is none. [transfer none]

### webkit_web_frame_get_provisional_data_source ()

    WebKitWebDataSource * webkit_web_frame_get_provisional_data_source
                                                            (WebKitWebFrame *frame);

You use the webkit_web_frame_load_request method to initiate a request that creates a provisional data source. The provisional data source will transition to a committed data source once any data has been received. Use webkit_web_frame_get_data_source to get the committed data source.

`frame` : | a WebKitWebFrame
Returns : | the provisional WebKitWebDataSource or `NULL` if a load request is not in progress. [transfer none]

Since 1.1.14

### webkit_web_frame_get_security_origin ()

    WebKitSecurityOrigin * webkit_web_frame_get_security_origin
                                                            (WebKitWebFrame *frame);

Returns the `frame`'s security origin.

`frame` : | a WebKitWebFrame
Returns : | the security origin of `frame`. [transfer none]

Since 1.1.14

### webkit_web_frame_get_title ()

    const gchar *       webkit_web_frame_get_title          (WebKitWebFrame *frame);

Returns the `frame`'s document title

`frame` : | a WebKitWebFrame
Returns : | the title of `frame`

### webkit_web_frame_get_uri ()

    const gchar *       webkit_web_frame_get_uri            (WebKitWebFrame *frame);

Returns the current URI of the contents displayed by the `frame`

`frame` : | a WebKitWebFrame
Returns : | the URI of `frame`

### webkit_web_frame_get_vertical_scrollbar_policy ()

    GtkPolicyType       webkit_web_frame_get_vertical_scrollbar_policy
                                                            (WebKitWebFrame *frame);

### webkit_web_frame_get_web_view ()

    WebKitWebView *     webkit_web_frame_get_web_view       (WebKitWebFrame *frame);

Returns the WebKitWebView that manages this WebKitWebFrame.

The WebKitWebView returned manages the entire hierarchy of WebKitWebFrame objects that contains `frame`.

`frame` : | a WebKitWebFrame
Returns : | the WebKitWebView that manages `frame`. [transfer none]

### webkit_web_frame_load_alternate_string ()

    void                webkit_web_frame_load_alternate_string
                                                            (WebKitWebFrame *frame,
                                                             const gchar *content,
                                                             const gchar *base_url,
                                                             const gchar *unreachable_url);

Request loading of an alternate content for a URL that is unreachable. Using this method will preserve the back-forward list. The URI passed in `base_url` has to be an absolute URI.

`frame` : | a WebKitWebFrame
`content` : | the alternate content to display as the main page of the `frame`
`base_url` : | the base URI for relative locations
`unreachable_url` : | the URL for the alternate page content

Since 1.1.6

### webkit_web_frame_load_request ()

    void                webkit_web_frame_load_request       (WebKitWebFrame *frame,
                                                             WebKitNetworkRequest *request);

Connects to a given URI by initiating an asynchronous client request.

Creates a provisional data source that will transition to a committed data source once any data has been received. Use `webkit_web_frame_stop_loading()` to stop the load. This function is typically invoked on the main frame.

`frame` : | a WebKitWebFrame
`request` : | a WebKitNetworkRequest

### webkit_web_frame_load_string ()

    void                webkit_web_frame_load_string        (WebKitWebFrame *frame,
                                                             const gchar *content,
                                                             const gchar *mime_type,
                                                             const gchar *encoding,
                                                             const gchar *base_uri);

Requests loading of the given `content` with the specified `mime_type`, `encoding` and `base_uri`.

If `mime_type` is `NULL`, "text/html" is assumed.

If `encoding` is `NULL`, "UTF-8" is assumed.

`frame` : | a WebKitWebFrame
`content` : | an URI string
`mime_type` : | the MIME type, or `NULL`
`encoding` : | the encoding, or `NULL`
`base_uri` : | the base URI for relative locations

Since 1.1.1

### webkit_web_frame_load_uri ()

    void                webkit_web_frame_load_uri           (WebKitWebFrame *frame,
                                                             const gchar *uri);

Requests loading of the specified URI string.

`frame` : | a WebKitWebFrame
`uri` : | an URI string

Since 1.1.1

### webkit_web_frame_new ()

    WebKitWebFrame *    webkit_web_frame_new                (WebKitWebView *web_view);

### Warning

`webkit_web_frame_new` has been deprecated since version 1.0.2 and should not be used in newly-written code. WebKitWebFrame can only be used to inspect existing frames.

Creates a new WebKitWebFrame initialized with a controlling WebKitWebView.

`web_view` : | the controlling WebKitWebView
Returns : | a new WebKitWebFrame

### webkit_web_frame_print ()

    void                webkit_web_frame_print              (WebKitWebFrame *frame);

Prints the given WebKitWebFrame, by presenting a print dialog to the user. If you need more control over the printing process, see `webkit_web_frame_print_full()`.

`frame` : | a WebKitWebFrame

Since 1.1.5

### webkit_web_frame_print_full ()

    GtkPrintOperationResult webkit_web_frame_print_full     (WebKitWebFrame *frame,
                                                             GtkPrintOperation *operation,
                                                             GtkPrintOperationAction action,
                                                             GError **error);

Prints the given WebKitWebFrame, using the given GtkPrintOperation and GtkPrintOperationAction. This function wraps a call to `gtk_print_operation_run()` for printing the contents of the WebKitWebFrame.

`frame` : | a WebKitWebFrame to be printed
`operation` : | the GtkPrintOperation to be carried
`action` : | the GtkPrintOperationAction to be performed
`error` : | GError for error return
Returns : | The GtkPrintOperationResult specifying the result of this operation.

Since 1.1.5

### webkit_web_frame_reload ()

    void                webkit_web_frame_reload             (WebKitWebFrame *frame);

Reloads the initial request.

`frame` : | a WebKitWebFrame

### webkit_web_frame_stop_loading ()

    void                webkit_web_frame_stop_loading       (WebKitWebFrame *frame);

Stops any pending loads on `frame`'s data source, and those of its children.

`frame` : | a WebKitWebFrame

## Property Details

### The `"horizontal-scrollbar-policy"` property

      "horizontal-scrollbar-policy" GtkPolicyType         : Read

Determines the current policy for the horizontal scrollbar of the frame. For the main frame, make sure to set the same policy on the scrollable widget containing the WebKitWebView, unless you know what you are doing.

Default value: GTK_POLICY_AUTOMATIC

Since 1.1.14

### The `"load-status"` property

      "load-status"              WebKitLoadStatus      : Read

Determines the current status of the load.

Default value: WEBKIT_LOAD_FINISHED

Since 1.1.7

### The `"name"` property

      "name"                     gchar*                : Read

The name of the frame.

Default value: NULL

### The `"title"` property

      "title"                    gchar*                : Read

The document title of the frame.

Default value: NULL

### The `"uri"` property

      "uri"                      gchar*                : Read

The current URI of the contents displayed by the frame.

Default value: NULL

### The `"vertical-scrollbar-policy"` property

      "vertical-scrollbar-policy" GtkPolicyType         : Read

Determines the current policy for the vertical scrollbar of the frame. For the main frame, make sure to set the same policy on the scrollable widget containing the WebKitWebView, unless you know what you are doing.

Default value: GTK_POLICY_AUTOMATIC

Since 1.1.14

## Signal Details

### The `"cleared"` signal

    void                user_function                      (WebKitWebFrame *webkitwebframe,
                                                            gpointer        user_data)           : Run Last

`webkitwebframe` : | the object which received the signal.
`user_data` : | user data set when the signal handler was connected.

### The `"hovering-over-link"` signal

    void                user_function                      (WebKitWebFrame *webkitwebframe,
                                                            gchar          *arg1,
                                                            gchar          *arg2,
                                                            gpointer        user_data)           : Run Last

`webkitwebframe` : | the object which received the signal.
`user_data` : | user data set when the signal handler was connected.

### The `"insecure-content-run"` signal

    void                user_function                      (WebKitWebFrame       *web_frame,
                                                            WebKitSecurityOrigin *security_origin,
                                                            gchar                *url,
                                                            gpointer              user_data)            : Run Last

Invoked when insecure content is run from a secure page. This happens when a page loaded via HTTPS loads a stylesheet, script, image or iframe from an unencrypted HTTP URL.

`web_frame` : | the WebKitWebFrame the response was received for.
`security_origin` : | the WebKitSecurityOrigin.
`url` : | the url of the insecure content.
`user_data` : | user data set when the signal handler was connected.

Since 1.10.0

### The `"load-committed"` signal

    void                user_function                      (WebKitWebFrame *web_frame,
                                                            gpointer        user_data)      : Run Last

### Warning

`WebKitWebFrame::load-committed` is deprecated and should not be used in newly-written code. Use the "load-status" property instead.

Emitted when frame loading is done.

`web_frame` : | the object on which the signal is emitted
`user_data` : | user data set when the signal handler was connected.

### The `"resource-content-length-received"` signal

    void                user_function                      (WebKitWebFrame    *web_frame,
                                                            WebKitWebResource *web_resource,
                                                            gint               length_received,
                                                            gpointer           user_data)            : Run Last

Emitted when new resource data has been received. The `length_received` variable stores the amount of bytes received since the last time this signal was emitted. This is useful to provide progress information about the resource load operation.

`web_frame` : | the WebKitWebFrame the response was received for
`web_resource` : | the WebKitWebResource that was loaded
`length_received` : | the amount of data received since the last signal emission
`user_data` : | user data set when the signal handler was connected.

Since 1.7.5

### The `"resource-load-failed"` signal

    void                user_function                      (WebKitWebFrame    *web_frame,
                                                            WebKitWebResource *web_resource,
                                                            gpointer           error,
                                                            gpointer           user_data)         : Run Last

Invoked when a resource failed to load.

`web_frame` : | the WebKitWebFrame the response was received for
`web_resource` : | the WebKitWebResource that was loaded
`error` : | the GError that was triggered
`user_data` : | user data set when the signal handler was connected.

Since 1.7.5

### The `"resource-load-finished"` signal

    void                user_function                      (WebKitWebFrame    *web_frame,
                                                            WebKitWebResource *web_resource,
                                                            gpointer           user_data)         : Run Last

Emitted when all the data for the resource was loaded.

`web_frame` : | the WebKitWebFrame the response was received for
`web_resource` : | the WebKitWebResource being loaded
`user_data` : | user data set when the signal handler was connected.

Since 1.7.5

### The `"resource-request-starting"` signal

    void                user_function                      (WebKitWebFrame        *web_frame,
                                                            WebKitWebResource     *web_resource,
                                                            WebKitNetworkRequest  *request,
                                                            WebKitNetworkResponse *response,
                                                            gpointer               user_data)         : Run Last

Emitted when a request is about to be sent. You can modify the request while handling this signal. You can set the URI in the WebKitNetworkRequest object itself, and add/remove/replace headers using the SoupMessage object it carries, if it is present. See `webkit_network_request_get_message()`. Setting the request URI to "about:blank" will effectively cause the request to load nothing, and can be used to disable the loading of specific resources.

Notice that information about an eventual redirect is available in `response`'s SoupMessage, not in the SoupMessage carried by the `request`. If `response` is `NULL`, then this is not a redirected request.

The WebKitWebResource object will be the same throughout all the lifetime of the resource, but the contents may change between signal emissions.

`web_frame` : | the WebKitWebFrame whose load dispatched this request
`web_resource` : | an empty WebKitWebResource object
`request` : | the WebKitNetworkRequest that will be dispatched
`response` : | the WebKitNetworkResponse representing the redirect response, if any
`user_data` : | user data set when the signal handler was connected.

Since 1.7.5

### The `"resource-response-received"` signal

    void                user_function                      (WebKitWebFrame        *web_frame,
                                                            WebKitWebResource     *web_resource,
                                                            WebKitNetworkResponse *response,
                                                            gpointer               user_data)         : Run Last

Emitted when the response is received from the server.

`web_frame` : | the WebKitWebFrame the response was received for
`web_resource` : | the WebKitWebResource being loaded
`response` : | the WebKitNetworkResponse that was received.
`user_data` : | user data set when the signal handler was connected.

Since 1.7.5

### The `"scrollbars-policy-changed"` signal

    gboolean            user_function                      (WebKitWebFrame *web_view,
                                                            gpointer        user_data)      : Action

Signal emitted when policy for one or both of the scrollbars of the view has changed. The default handler will apply the new policy to the container that holds the WebKitWebFrame if it is a GtkScrolledWindow and the frame is the main frame. If you do not want this to be handled automatically, you need to handle this signal.

The exception to this rule is that policies to disable the scrollbars are applied as `GTK_POLICY_AUTOMATIC` instead, since the size request of the widget would force browser windows to not be resizable.

You can obtain the new policies from the WebKitWebFrame:horizontal-scrollbar-policy and WebKitWebFrame:vertical-scrollbar-policy properties.

`web_view` : | the object which received the signal
`user_data` : | user data set when the signal handler was connected.
Returns : | `TRUE` to stop other handlers from being invoked for the event. `FALSE` to propagate the event further.

Since 1.1.14

### The `"title-changed"` signal

    void                user_function                      (WebKitWebFrame *frame,
                                                            gchar          *title,
                                                            gpointer        user_data)      : Run Last

### Warning

`WebKitWebFrame::title-changed` has been deprecated since version 1.1.18 and should not be used in newly-written code. Use "notify::title" instead.

When a WebKitWebFrame changes the document title this signal is emitted.

`frame` : | the object on which the signal is emitted
`title` : | the new title
`user_data` : | user data set when the signal handler was connected.