Macros

Additional Inherited Members

Detailed Description

The QWebPage class provides an object to view and edit web documents.

QWebPage holds a main frame responsible for web content, settings, the history of navigated links and actions. This class can be used, together with QWebFrame, to provide functionality like QWebView in a widget-less environment.

The loadStarted() signal is emitted when the page begins to load.The loadProgress() signal, on the other hand, is emitted whenever an element of the web page completes loading, such as an embedded image, a script, etc. Finally, the loadFinished() signal is emitted when the page contents are loaded completely, independent of script execution or page rendering. Its argument, either true or false, indicates whether or not the load operation succeeded.

Using QWebPage in a Widget-less Environment

Before you begin painting a QWebPage object, you need to set the size of the viewport by calling setViewportSize(). Then, you invoke the main frame's render function (QWebFrame::render()). An example of this is shown in the code snippet below.

We begin by setting the viewportSize and then we instantiate a QImage object, image, with the same size as our viewportSize. This image is then sent as a parameter to painter. Next, we render the contents of the main frame and its subframes into painter. Finally, we save the scaled image.

enum QWebPage::Extension

This enum describes the types of extensions that the page can support. Before using these extensions, you should verify that the extension is supported by calling supportsExtension().

Constant

Value

Description

QWebPage::ChooseMultipleFilesExtension

0

Whether the web page supports multiple file selection. This extension is invoked when the web content requests one or more file names, for example as a result of the user clicking on a "file upload" button in a HTML form where multiple file selection is allowed.

QWebPage::ErrorPageExtension

1

Whether the web page can provide an error page when loading fails. (introduced in Qt 4.6)

enum QWebPage::PermissionPolicy

enum QWebPage::WebAction

This enum describes the types of action which can be performed on the web page.

Actions only have an effect when they are applicable. The availability of actions can be be determined by checking isEnabled() on the action returned by action().

One method of enabling the text editing, cursor movement, and text selection actions is by setting contentEditable to true.

Constant

Value

Description

QWebPage::NoWebAction

-1

No action is triggered.

QWebPage::OpenLink

0

Open the current link.

QWebPage::OpenLinkInNewWindow

1

Open the current link in a new window.

QWebPage::OpenFrameInNewWindow

2

Replicate the current frame in a new window.

QWebPage::DownloadLinkToDisk

3

Download the current link to the disk.

QWebPage::CopyLinkToClipboard

4

Copy the current link to the clipboard.

QWebPage::OpenImageInNewWindow

5

Open the highlighted image in a new window.

QWebPage::DownloadImageToDisk

6

Download the highlighted image to the disk.

QWebPage::CopyImageToClipboard

7

Copy the highlighted image to the clipboard.

QWebPage::CopyImageUrlToClipboard

68

Copy the highlighted image's URL to the clipboard.

QWebPage::Back

8

Navigate back in the history of navigated links.

QWebPage::Forward

9

Navigate forward in the history of navigated links.

QWebPage::Stop

10

Stop loading the current page.

QWebPage::StopScheduledPageRefresh

67

Stop all pending page refresh/redirect requests.

QWebPage::Reload

11

Reload the current page.

QWebPage::ReloadAndBypassCache

53

Reload the current page, but do not use any local cache. (Added in Qt 4.6)

QWebPage::Cut

12

Cut the content currently selected into the clipboard.

QWebPage::Copy

13

Copy the content currently selected into the clipboard.

QWebPage::Paste

14

Paste content from the clipboard.

QWebPage::Undo

15

Undo the last editing action.

QWebPage::Redo

16

Redo the last editing action.

QWebPage::MoveToNextChar

17

Move the cursor to the next character.

QWebPage::MoveToPreviousChar

18

Move the cursor to the previous character.

QWebPage::MoveToNextWord

19

Move the cursor to the next word.

QWebPage::MoveToPreviousWord

20

Move the cursor to the previous word.

QWebPage::MoveToNextLine

21

Move the cursor to the next line.

QWebPage::MoveToPreviousLine

22

Move the cursor to the previous line.

QWebPage::MoveToStartOfLine

23

Move the cursor to the start of the line.

QWebPage::MoveToEndOfLine

24

Move the cursor to the end of the line.

QWebPage::MoveToStartOfBlock

25

Move the cursor to the start of the block.

QWebPage::MoveToEndOfBlock

26

Move the cursor to the end of the block.

QWebPage::MoveToStartOfDocument

27

Move the cursor to the start of the document.

QWebPage::MoveToEndOfDocument

28

Move the cursor to the end of the document.

QWebPage::SelectNextChar

29

Select to the next character.

QWebPage::SelectPreviousChar

30

Select to the previous character.

QWebPage::SelectNextWord

31

Select to the next word.

QWebPage::SelectPreviousWord

32

Select to the previous word.

QWebPage::SelectNextLine

33

Select to the next line.

QWebPage::SelectPreviousLine

34

Select to the previous line.

QWebPage::SelectStartOfLine

35

Select to the start of the line.

QWebPage::SelectEndOfLine

36

Select to the end of the line.

QWebPage::SelectStartOfBlock

37

Select to the start of the block.

QWebPage::SelectEndOfBlock

38

Select to the end of the block.

QWebPage::SelectStartOfDocument

39

Select to the start of the document.

QWebPage::SelectEndOfDocument

40

Select to the end of the document.

QWebPage::DeleteStartOfWord

41

Delete to the start of the word.

QWebPage::DeleteEndOfWord

42

Delete to the end of the word.

QWebPage::SetTextDirectionDefault

43

Set the text direction to the default direction.

QWebPage::SetTextDirectionLeftToRight

44

Set the text direction to left-to-right.

QWebPage::SetTextDirectionRightToLeft

45

Set the text direction to right-to-left.

QWebPage::ToggleBold

46

Toggle the formatting between bold and normal weight.

QWebPage::ToggleItalic

47

Toggle the formatting between italic and normal style.

QWebPage::ToggleUnderline

48

Toggle underlining.

QWebPage::InspectElement

49

Show the Web Inspector with the currently highlighted HTML element.

QWebPage::InsertParagraphSeparator

50

Insert a new paragraph.

QWebPage::InsertLineSeparator

51

Insert a new line.

QWebPage::SelectAll

52

Selects all content.

QWebPage::PasteAndMatchStyle

54

Paste content from the clipboard with current style.

QWebPage::RemoveFormat

55

Removes formatting and style.

QWebPage::ToggleStrikethrough

56

Toggle the formatting between strikethrough and normal style.

QWebPage::ToggleSubscript

57

Toggle the formatting between subscript and baseline.

QWebPage::ToggleSuperscript

58

Toggle the formatting between supercript and baseline.

QWebPage::InsertUnorderedList

59

Toggles the selection between an ordered list and a normal block.

QWebPage::InsertOrderedList

60

Toggles the selection between an ordered list and a normal block.

QWebPage::Indent

61

Increases the indentation of the currently selected format block by one increment.

QWebPage::Outdent

62

Decreases the indentation of the currently selected format block by one increment.

QWebPage::AlignCenter

63

Applies center alignment to content.

QWebPage::AlignJustified

64

Applies full justification to content.

QWebPage::AlignLeft

65

Applies left justification to content.

QWebPage::AlignRight

66

Applies right justification to content.

enum QWebPage::WebWindowType

This enum describes the types of window that can be created by the createWindow() function.

Constant

Value

Description

QWebPage::WebBrowserWindow

0

The window is a regular web browser window.

QWebPage::WebModalDialog

1

The window acts as modal dialog.

Property Documentation

contentEditable : bool

This property holds whether the content in this QWebPage is editable or not.

If this property is enabled the contents of the page can be edited by the user through a visible cursor. If disabled (the default) only HTML elements in the web page with their contenteditable attribute set are editable.

This property holds a custom size used for laying out the page contents.

By default all pages are laid out using the viewport of the page as the base.

As pages mostly are designed for desktop usage, they often do not layout properly on small devices as the contents require a certain view width. For this reason it is common to use a different layout size and then scale the contents to fit within the actual view.

If this property is set to a valid size, this size is used for all layout needs instead of the size of the viewport.

Setting an invalid size, makes the page fall back to using the viewport size for layout.

This function is called whenever WebKit encounters a HTML object element with type "application/x-qt-plugin". It is called regardless of the value of QWebSettings::PluginsEnabled. The classid, url, paramNames and paramValues correspond to the HTML object element attributes and child elements to configure the embeddable object.

This function creates the standard context menu which is shown when the user clicks on the web page with the right mouse button. It is called from the default contextMenuEvent() handler. The popup menu's ownership is transferred to the caller.

Note: In the cases when the window creation is being triggered by JavaScript, apart from reimplementing this method application must also set the JavaScriptCanOpenWindows attribute of QWebSettings to true in order for it to get called.

This virtual function can be reimplemented in a QWebPage subclass to provide support for extensions. The option argument is provided as input to the extension; the output results can be stored in output.

Finds the specified string, subString, in the page, using the given options.

If the HighlightAllOccurrences flag is passed, the function will highlight all occurrences that exist in the page. All subsequent calls will extend the highlight, rather than replace it, with occurrences of the new string.

If the HighlightAllOccurrences flag is not passed, the function will select an occurrence and all subsequent calls will replace the current occurrence with the next one.

To clear the selection, just pass an empty string.

Returns true if subString was found; otherwise returns false.

bool QWebPage::focusNextPrevChild ( boolnext )

Similar to QWidget::focusNextPrevChild() it focuses the next focusable web element if next is true; otherwise the previous element is focused.

Returns true if it can find a new focusable element, or false if it can't.

This function is called whenever a JavaScript program running inside frame tries to prompt the user for input. The program may provide an optional message, msg, as well as a default value for the input in defaultValue.

If the prompt was cancelled by the user the implementation should return false; otherwise the result should be written to result and true should be returned. If the prompt was not cancelled by the user, the implementation should return true and the result string must not be null.

void QWebPage::loadProgress ( intprogress ) [signal]

This signal is emitted when the global progress status changes. The current value is provided by progress and scales from 0 to 100, which is the default range of QProgressBar. It accumulates changes from all the child frames.

This signal is emitted whenever the visibility of the menubar in a web browser window that hosts QWebPage should be changed to visible.

void QWebPage::microFocusChanged () [signal]

This signal is emitted when for example the position of the cursor in an editable form element changes. It is used to inform input methods about the new on-screen position where the user is able to enter text. This signal is usually connected to the QWidget::updateMicroFocus() slot.

Warning: Because of binary compatibility constraints, this function is not virtual. If you want to provide your own implementation in a QWebPage subclass, reimplement the shouldInterruptJavaScript() slot in your subclass instead. QtWebKit will dynamically detect the slot and call it.

This signal is emitted when WebKit cannot handle a link the user navigated to or a web server's response includes a "Content-Disposition" header with the 'attachment' directive. If "Content-Disposition" is present in reply, the web server is indicating that the client should prompt the user to save the content regardless of content-type. See RFC 2616 sections 19.5.1 for details about Content-Disposition.

At signal emission time the meta-data of the QNetworkReplyreply is available.

Note: The receiving slot is responsible for deleting the QNetworkReplyreply.

Computes the optimal viewport configuration given the availableSize, when user interface components are disregarded.

The configuration is also dependent on the device screen size which is obtained automatically. For testing purposes the size can be overridden by setting two environment variables QTWEBKIT_DEVICE_WIDTH and QTWEBKIT_DEVICE_HEIGHT, which both needs to be set.

The ViewportAttributes includes a pixel density ratio, which will also be exposed to the web author though the -webkit-pixel-ratio media feature. This is the ratio between 1 density-independent pixel (DPI) and physical pixels.

A density-independent pixel is equivalent to one physical pixel on a 160 DPI screen, so on our platform assumes that as the baseline density.

The conversion of DIP units to screen pixels is quite simple:

pixels = DIPs * (density / 160).

Thus, on a 240 DPI screen, 1 DIPs would equal 1.5 physical pixels.

An invalid instance will be returned in the case an empty size is passed to the method.

Note: The density is automatically obtained from the DPI of the screen where the page is being shown, but as many X11 servers are reporting wrong DPI, it is possible to override it using QX11Info::setAppDpiY().

Returns the version number of WebKit at run-time as a string (for example, "531.3").

This version is commonly used in WebKit based browsers as part of the user agent string. Web servers and JavaScript might use it to identify the presence of certain WebKit engine features and behaviour.

The evolution of this version is bound to the releases of Apple's Safari browser. For a version specific to the QtWebKit library, see QTWEBKIT_VERSION

Macro Documentation

QTWEBKIT_VERSION

This macro expands a numeric value of the form 0xMMNNPP (MM = major, NN = minor, PP = patch) that specifies QtWebKit's version number. For example, if you compile your application against QtWebKit 2.1.2, the QTWEBKIT_VERSION macro will expand to 0x020102.

You can use QTWEBKIT_VERSION to use the latest QtWebKit API where available.

QTWEBKIT_VERSION_CHECK

Turns the major, minor and patch numbers of a version into an integer, 0xMMNNPP (MM = major, NN = minor, PP = patch). This can be compared with another similarly processed version id, for example in a preprocessor statement:

QTWEBKIT_VERSION_STR

Copyright 2013 Digia Plc and/or it's subsidiaries. Documentation contributions included herein are the copyrights of their respective owners.
Information about Qt licenses are available in the Qt Licensing page.