juce_WebBrowserComponent.h

Go to the documentation of this file.

/*
  ==============================================================================
 
   This file is part of the JUCE library.
   Copyright (c) 2022 - Raw Material Software Limited
 
   JUCE is an open source library subject to commercial or open-source
   licensing.
 
   By using JUCE, you agree to the terms of both the JUCE 7 End-User License
   Agreement and JUCE Privacy Policy.
 
   End User License Agreement: www.juce.com/juce-7-licence
   Privacy Policy: www.juce.com/juce-privacy-policy
 
   Or: You may also use this code under the terms of the GPL v3 (see
   www.gnu.org/licenses).
 
   JUCE IS PROVIDED "AS IS" WITHOUT ANY WARRANTY, AND ALL WARRANTIES, WHETHER
   EXPRESSED OR IMPLIED, INCLUDING MERCHANTABILITY AND FITNESS FOR PURPOSE, ARE
   DISCLAIMED.
 
  ==============================================================================
*/
 
namespace juce
{
 
#if JUCE_WEB_BROWSER || DOXYGEN
 
//==============================================================================
class JUCE_API  WebBrowserComponent  : public Component
{
public:
    //==============================================================================
    explicit WebBrowserComponent (bool unloadPageWhenBrowserIsHidden = true);

    ~WebBrowserComponent() override;
 
    //==============================================================================
    void goToURL (const String& url,
                  const StringArray* headers = nullptr,
                  const MemoryBlock* postData = nullptr);

    void stop();

    void goBack();

    void goForward();

    void refresh();

    static void clearCookies();
 
    //==============================================================================
    virtual bool pageAboutToLoad (const String& newURL)             { ignoreUnused (newURL); return true; }

    virtual void pageFinishedLoading (const String& url)            { ignoreUnused (url); }

    virtual bool pageLoadHadNetworkError (const String& errorInfo)  { ignoreUnused (errorInfo); return true; }

    virtual void windowCloseRequest()                               {}

    virtual void newWindowAttemptingToLoad (const String& newURL)   { ignoreUnused (newURL); }
 
    //==============================================================================
    void paint (Graphics&) override;
    void resized() override;
    void parentHierarchyChanged() override;
    void visibilityChanged() override;
    void focusGained (FocusChangeType) override;

    class Pimpl;
 
protected:
    friend class WindowsWebView2WebBrowserComponent;

    struct ConstructWithoutPimpl
    {
        explicit ConstructWithoutPimpl (bool unloadOnHide) : unloadWhenHidden (unloadOnHide) {}
        const bool unloadWhenHidden;
    };
    explicit WebBrowserComponent (ConstructWithoutPimpl);
 
private:
    //==============================================================================
    std::unique_ptr<Pimpl> browser;
    bool blankPageShown = false, unloadPageWhenHidden;
    String lastURL;
    StringArray lastHeaders;
    MemoryBlock lastPostData;
 
    void reloadLastURL();
    void checkWindowAssociation();
 
    JUCE_DECLARE_NON_COPYABLE_WITH_LEAK_DETECTOR (WebBrowserComponent)
};
 
//==============================================================================
class JUCE_API  WebView2Preferences
{
public:
    //==============================================================================
    JUCE_NODISCARD WebView2Preferences withDLLLocation (const File& location) const   { return with (&WebView2Preferences::dllLocation, location); }

    WebView2Preferences withUserDataFolder (const File& folder) const  { return with (&WebView2Preferences::userDataFolder, folder); }

    JUCE_NODISCARD WebView2Preferences withStatusBarDisabled() const                  { return with (&WebView2Preferences::disableStatusBar, true); }

    JUCE_NODISCARD WebView2Preferences withBuiltInErrorPageDisabled() const           { return with (&WebView2Preferences::disableBuiltInErrorPage, true); }

    JUCE_NODISCARD WebView2Preferences withBackgroundColour (const Colour& colour) const
    {
        // the background colour must be either fully opaque or transparent!
        jassert (colour.isOpaque() || colour.isTransparent());
 
        return with (&WebView2Preferences::backgroundColour, colour);
    }
 
    //==============================================================================
    File getDLLLocation() const                          { return dllLocation; }
    File getUserDataFolder() const                       { return userDataFolder; }
    bool getIsStatusBarDisabled() const noexcept         { return disableStatusBar; }
    bool getIsBuiltInErrorPageDisabled() const noexcept  { return disableBuiltInErrorPage; }
    Colour getBackgroundColour() const                   { return backgroundColour; }
 
private:
    //==============================================================================
    template <typename Member, typename Item>
    WebView2Preferences with (Member&& member, Item&& item) const
    {
        auto options = *this;
        options.*member = std::forward<Item> (item);
 
        return options;
    }
 
    File dllLocation, userDataFolder;
    bool disableStatusBar = false, disableBuiltInErrorPage = false;
    Colour backgroundColour = Colours::white;
};

class WindowsWebView2WebBrowserComponent  : public WebBrowserComponent
{
public:
    //==============================================================================
    WindowsWebView2WebBrowserComponent (bool unloadPageWhenBrowserIsHidden = true,
                                        const WebView2Preferences& preferences = {});
 
    // This constructor has been deprecated. Use the new constructor that takes a
    // WebView2Preferences instead.
    explicit WindowsWebView2WebBrowserComponent (bool unloadPageWhenBrowserIsHidden = true,
                                                 const File& dllLocation = {},
                                                 const File& userDataFolder = {})
                                  : WindowsWebView2WebBrowserComponent (unloadPageWhenBrowserIsHidden,
                                                                        WebView2Preferences().withDLLLocation (dllLocation)
                                                                                             .withUserDataFolder (userDataFolder))
    {
    }
};
 
#endif
 
} // namespace juce