DOCSEARCHbyAlgolia
Submit Docs

Qt WebEngine

repository·dev·Indexed 19 days ago

https://github.com/qt/qtwebengine

A web browser engine module for the Qt framework that provides a high-level API for integrating web content into Qt applications. It includes functionality for managing SSL certificate errors via QWebEngineCertificateError, client certificate selection and storage with QWebEngineClientCertificateSelection and QWebEngineClientCertificateStore, and control of client hints through QWebEngineClientHints. The module also provides QWebEngineContextMenuRequest for inspecting context menu metadata and various build configuration flags for audio, multimedia, and library linking.

Tokens
4.3K
Snippets
11
Records
14
Agent score
65%

What's inside Qt WebEngine

  1. Configure Qt WebEngine build and runtime options

    dev

    Qt WebEngine provides several configuration flags to control feature support, library linking, and codec capabilities. These options are primarily used during the build process or to configure the environment for specific platform requirements (notably Linux, macOS, and embedded systems).

    Audio and Multimedia (Linux)

    • -webengine-alsa: Enables ALSA support. Default is [auto].
    • -webengine-pulseaudio: Enables PulseAudio support. Default is [auto].
    • -webengine-webrtc: Enables support for WebRTC. Default is [auto].

    Library Linking (Linux)

    The following flags determine whether to use system-provided libraries or the libraries bundled with Qt:

    • -webengine-icu: Use system ICU libraries. Options: [system/qt].
    • -webengine-ffmpeg: Use system FFmpeg libraries. Options: [system/qt].
    • -webengine-opus: Use system Opus libraries. Options: [system/qt].
    • -webengine-webp: Use system WebP libraries. Options: [system/qt].

    Codecs and Plugins

    • -webengine-proprietary-codecs: Enable support for proprietary codecs. Default is [no].
    • -webengine-pepper-plugins: Enable use of Pepper Flash and Widevine plugins. Default is [auto].

    Text and Printing

    • -webengine-spellchecker: Enable support for spellchecker. Default is [yes].
    • -webengine-native-spellchecker: Enable support for native spellchecker (macOS only). Default is [no].
    • -webengine-printing-and-pdf: Enable use of printing and output to PDF. Default is [auto].

    Embedded Systems (Linux)

    • -webengine-embedded-build: Enable Linux embedded build. Default is [auto].
    -webengine-alsa ................ Enable ALSA support [auto] (Linux only)
-webengine-pulseaudio .......... Enable PulseAudio support [auto]
                                (Linux only)
-webengine-embedded-build ...... Enable Linux embedded build [auto]
                                (Linux only)
-webengine-icu ................. Use system ICU libraries [system/qt]
                                (Linux only)
-webengine-ffmpeg .............. Use system FFmpeg libraries [system/qt]
                                (Linux only)
-webengine-opus ................ Use system Opus libraries [system/qt]
                                (Linux only)
-webengine-webp ................ Use system WebP libraries [system/qt]
                                (Linux only)
-webengine-pepper-plugins ...... Enable use of Pepper Flash and Widevine
                                plugins [auto]
-webengine-printing-and-pdf .... Enable use of printing and output to PDF
                                [auto]
-webengine-proprietary-codecs .. Enable support for proprietary codecs [no]
-webengine-spellchecker ........ Enable support for spellchecker [yes]
-webengine-native-spellchecker . Enable support for native spellchecker [no]
                                (macOS only)
-webengine-webrtc .............. Enable support for WebRTC [auto]

  2. Manage client certificates with QWebEngineClientCertificateStore

    dev

    The QWebEngineClientCertificateStore class allows you to programmatically manage the collection of client certificates used by the WebEngine for SSL/TLS authentication. You can add new certificate/private key pairs, retrieve the current list of certificates, remove specific certificates, or clear the entire store. This is useful for handling client-side certificate authentication in secure web environments.

    Note: This class requires the ssl configuration to be enabled in Qt WebEngine.

    // Example usage of QWebEngineClientCertificateStore

// Adding a certificate and its private key
store.add(myCertificate, myPrivateKey);

// Retrieving all currently stored certificates
QList<QSslCertificate> certs = store.certificates();

// Removing a specific certificate
store.remove(myCertificate);

// Clearing all certificates from the store
store.clear();

  3. Handle SSL certificate errors with QWebEngineCertificateError

    dev

    When a web page encounters an SSL certificate error, a QWebEngineCertificateError object is generated. You can use this object to inspect the error details and decide whether to allow the user to proceed (accept) or block the connection (reject).

    Key actions available on a QWebEngineCertificateError instance:

    • acceptCertificate(): Instructs the engine to proceed with the connection despite the error.
    • rejectCertificate(): Instructs the engine to terminate the connection.
    • defer(): Delays the decision, allowing for asynchronous handling (e.g., showing a custom UI dialog to the user before calling accept or reject).

    To inspect the error, use type() to get the specific error category, url() to see the affected URL, and description() for a human-readable explanation.

    // Example logic for handling a certificate error
void handleCertificateError(const QWebEngineCertificateError &error) {
    if (error.isOverridable()) {
        // Show a dialog to the user
        if (userClickedProceed()) {
            error.acceptCertificate();
        } else {
            error.rejectCertificate();
        }
    } else {
        error.rejectCertificate();
    }
}

  4. Manage Client Hints with QWebEngineClientHints

    dev

    The QWebEngineClientHints class allows you to control the client hints sent to websites. Client hints are used by web servers to understand the capabilities and characteristics of the user's device and browser, enabling them to serve optimized content. You can manually override properties such as architecture, platform, model, and mobile status.

    Available properties and methods:

    • arch() / setArch(QString): The CPU architecture.
    • platform() / setPlatform(QString): The operating system platform.
    • model() / setModel(QString): The device model.
    • isMobile() / setIsMobile(bool): Whether the device is a mobile device.
    • fullVersion() / setFullVersion(QString): The full version of the browser/client.
    • platformVersion() / setPlatformVersion(QString): The version of the operating system platform.
    • bitness() / setBitness(QString): The bitness of the architecture (e.g., 64-bit).
    • fullVersionList() / setFullVersionList(QVariantMap): A map containing a list of full versions.
    • isWow64() / setIsWow64(bool): Indicates if the process is running under WOW64.
    • formFactors() / setFormFactors(QStringList): A list of form factors (available from revision 6.10).
    • isAllClientHintsEnabled() / setAllClientHintsEnabled(bool): Enables or disables all client hints.
    • resetAll(): A Q_INVOKABLE method to reset all client hints to their default values.

  5. Get domain and registry information for a URL

    dev

    The qWebEngineGetDomainAndRegistry function takes a QUrl and returns a QString representing the domain and registry information associated with that URL. This is typically used to identify the origin or security context of a web resource.

    QUrl url("https://example.com/path");
QString domainInfo = qWebEngineGetDomainAndRegistry(url);

  6. Inspect QWebEngineCertificateError properties

    dev

    The QWebEngineCertificateError class provides several properties to diagnose the certificate issue:

    • url(): Returns the QUrl of the resource that triggered the error.
    • type(): Returns the Type enum value representing the error category.
    • description(): Returns a QString containing a description of the error.
    • isOverridable(): Returns true if the error allows the user to manually bypass the security warning.
    • isMainFrame(): Returns true if the error occurred in the main frame of the page (available in newer versions).

  7. Retrieve Qt WebEngine and Chromium version information

    dev

    You can programmatically retrieve the version strings for the Qt WebEngine module, the underlying Chromium engine, and the Chromium security patch level using global functions. These are useful for logging, debugging, or enforcing minimum version requirements in your application.

    const char *webEngineVer = qWebEngineVersion();
const char *chromiumVer = qWebEngineChromiumVersion();
const char *securityPatch = qWebEngineChromiumSecurityPatchVersion();
const char *processName = qWebEngineProcessName();

  8. Handle client certificate selection with QWebEngineClientCertificateSelection

    dev

    When a web page requests client authentication, you can use the QWebEngineClientCertificateSelection object to provide a certificate or decline the request.

    To handle this, you typically intercept the selection request (often via a signal in QWebEnginePage) and use the following methods:

    • certificates(): Returns a QList<QSslCertificate> containing the available client certificates that the engine has identified.
    • select(const QSslCertificate &certificate): Selects the specified certificate to be used for the authentication request.
    • selectNone(): Declines the authentication request by selecting no certificate.
    • host(): Returns the QUrl of the host requesting the certificate.
    // Example logic for selecting a certificate
void handleCertificateSelection(QWebEngineClientCertificateSelection selection) {
    QList<QSslCertificate> certs = selection.certificates();
    if (!certs.isEmpty()) {
        // Select the first available certificate
        selection.select(certs.first());
    } else {
        // Or decline if no suitable certificate is found
        selection.selectNone();
    }
}

  9. Inspect context menu request details with QWebEngineContextMenuRequest

    dev

    When a user triggers a context menu in a web view, QWebEngineContextMenuRequest provides metadata about the specific element or area that was interacted with. You can use this object to determine what kind of content was clicked (e.g., a link, an image, or text) and what actions are valid (e.g., copy/paste capabilities or media controls).

    Key information available includes:

    • Selection/Link Data: The text selected, the text of a link, the URL of a link, or the URL of a media element.
    • Media Information: The type of media (Image, Video, Audio, etc.) and specific flags like MediaPaused, MediaMuted, or MediaCanSave.
    • Edit Capabilities: Flags indicating if actions like CanUndo, CanCopy, or CanPaste are available.
    • Spellcheck: Information about misspelled words and suggested corrections.
    • Context: Whether the content is editable (isContentEditable).

  10. Reference: QWebEngineContextMenuRequest::EditFlags

    dev

    The EditFlags bitmask indicates which text editing operations are currently valid in the context of the user's selection.

    enum EditFlag {
    CanUndo = 0x1,
    CanRedo = 0x2,
    CanCut = 0x4,
    CanCopy = 0x8,
    CanPaste = 0x10,
    CanDelete = 0x20,
    CanSelectAll = 0x40,
    CanTranslate = 0x80,
    CanEditRichly = 0x100,
};

  12. QWebEngineClientCertificateStore API Reference

    dev

    The QWebEngineClientCertificateStore provides the following public methods for managing client certificates:

    • void add(const QSslCertificate &certificate, const QSslKey &privateKey): Adds a certificate and its corresponding private key to the store.
    • QList<QSslCertificate> certificates() const: Returns a list of all QSslCertificate objects currently in the store.
    • void remove(const QSslCertificate &certificate): Removes the specified certificate from the store.
    • void clear(): Removes all certificates from the store.
    void add(const QSslCertificate &certificate, const QSslKey &privateKey);
QList<QSslCertificate> certificates() const;
void remove(const QSslCertificate &certificate);
void clear();