WebKitWebFrame

WebKitWebFrame — The content of a WebKitWebView

Functions

Properties

Signals

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

Types and Values

Object Hierarchy

    GObject
    ╰── WebKitWebFrame

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

Functions

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.

Parameters

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.

Parameters

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

Parameters

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.

Parameters

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

Returns


webkit_web_frame_get_load_status ()

WebKitLoadStatus
webkit_web_frame_get_load_status (WebKitWebFrame *frame);

Determines the current status of the load.

Parameters

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

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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

Parameters

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

Parameters

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

Returns


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 .

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

frame

a WebKitWebFrame

 

uri

an URI string

 

Since 1.1.1


webkit_web_frame_new ()

WebKitWebFrame *
webkit_web_frame_new (WebKitWebView *web_view);

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.

Parameters

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

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

frame

a WebKitWebFrame

 

Types and Values

enum WebKitLoadStatus

Members

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;

Property Details

The “horizontal-scrollbar-policy” property

  “horizontal-scrollbar-policy” GtkPolicyType

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.

Flags: Read

Default value: GTK_POLICY_AUTOMATIC

Since 1.1.14


The “load-status” property

  “load-status”              WebKitLoadStatus

Determines the current status of the load.

Flags: Read

Default value: WEBKIT_LOAD_FINISHED

Since 1.1.7


The “name” property

  “name”                     gchar *

The name of the frame.

Flags: Read

Default value: NULL


The “title” property

  “title”                    gchar *

The document title of the frame.

Flags: Read

Default value: NULL


The “uri” property

  “uri”                      gchar *

The current URI of the contents displayed by the frame.

Flags: Read

Default value: NULL


The “vertical-scrollbar-policy” property

  “vertical-scrollbar-policy” GtkPolicyType

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.

Flags: Read

Default value: GTK_POLICY_AUTOMATIC

Since 1.1.14

Signal Details

The “cleared” signal

void
user_function (WebKitWebFrame *webkitwebframe,
               gpointer        user_data)

Parameters

webkitwebframe

the object which received the signal.

 

user_data

user data set when the signal handler was connected.

 

Flags: Run Last


The “hovering-over-link” signal

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

Parameters

webkitwebframe

the object which received the signal.

 

user_data

user data set when the signal handler was connected.

 

Flags: Run Last


The “insecure-content-run” signal

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

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.

Parameters

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.

 

Flags: Run Last

Since 1.10.0


The “load-committed” signal

void
user_function (WebKitWebFrame *web_frame,
               gpointer        user_data)

Emitted when frame loading is done.

WebKitWebFrame::load-committed is deprecated and should not be used in newly-written code.

Use the "load-status" property instead.

Parameters

web_frame

the object on which the signal is emitted

 

user_data

user data set when the signal handler was connected.

 

Flags: Run Last


The “resource-content-length-received” signal

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

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.

Parameters

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.

 

Flags: Run Last

Since 1.7.5


The “resource-load-failed” signal

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

Invoked when a resource failed to load.

Parameters

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.

 

Flags: Run Last

Since 1.7.5


The “resource-load-finished” signal

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

Emitted when all the data for the resource was loaded.

Parameters

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.

 

Flags: Run Last

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)

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.

Parameters

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.

 

Flags: Run Last

Since 1.7.5


The “resource-response-received” signal

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

Emitted when the response is received from the server.

Parameters

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.

 

Flags: Run Last

Since 1.7.5


The “scrollbars-policy-changed” signal

gboolean
user_function (WebKitWebFrame *web_view,
               gpointer        user_data)

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.

Parameters

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.

Flags: Action

Since 1.1.14


The “title-changed” signal

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

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

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

Use "notify::title" instead.

Parameters

frame

the object on which the signal is emitted

 

title

the new title

 

user_data

user data set when the signal handler was connected.

 

Flags: Run Last