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:
    //==============================================================================
    class JUCE_API Options
    {
    public:
        //==============================================================================
        enum class Backend
        {
            defaultBackend,
 
            ie,
 
            webview2
        };
 
        [[nodiscard]] Options withBackend (Backend backend) const              { return withMember (*this, &Options::browserBackend, backend); }
 
        //==============================================================================
        [[nodiscard]] Options withKeepPageLoadedWhenBrowserIsHidden() const   { return withMember (*this, &Options::keepPageLoadedWhenBrowserIsHidden, true); }
 
        [[nodiscard]] Options withUserAgent (String ua) const                  { return withMember (*this, &Options::userAgent, std::move (ua)); }
 
        //==============================================================================
        class WinWebView2
        {
        public:
            //==============================================================================
            [[nodiscard]] WinWebView2 withDLLLocation (const File& location) const   { return withMember (*this, &WinWebView2::dllLocation, location); }
 
            [[nodiscard]] WinWebView2 withUserDataFolder (const File& folder) const  { return withMember (*this, &WinWebView2::userDataFolder, folder); }
 
            [[nodiscard]] WinWebView2 withStatusBarDisabled() const                  { return withMember (*this, &WinWebView2::disableStatusBar, true); }
 
            [[nodiscard]] WinWebView2 withBuiltInErrorPageDisabled() const           { return withMember (*this, &WinWebView2::disableBuiltInErrorPage, true); }
 
            [[nodiscard]] WinWebView2 withBackgroundColour (const Colour& colour) const
            {
                // the background colour must be either fully opaque or transparent!
                jassert (colour.isOpaque() || colour.isTransparent());
 
                return withMember (*this, &WinWebView2::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:
            //==============================================================================
            File dllLocation, userDataFolder;
            bool disableStatusBar = false, disableBuiltInErrorPage = false;
            Colour backgroundColour;
        };
 
        [[nodiscard]] Options withWinWebView2Options (const WinWebView2& winWebView2Options) const
        {
            return withMember (*this, &Options::winWebView2, winWebView2Options);
        }
 
        //==============================================================================
        Backend getBackend() const noexcept                       { return browserBackend; }
        bool keepsPageLoadedWhenBrowserIsHidden() const noexcept  { return keepPageLoadedWhenBrowserIsHidden; }
        String getUserAgent() const                               { return userAgent; }
        WinWebView2 getWinWebView2BackendOptions() const          { return winWebView2; }
 
    private:
        //==============================================================================
        Backend browserBackend = Backend::defaultBackend;
        bool keepPageLoadedWhenBrowserIsHidden = false;
        String userAgent;
        WinWebView2 winWebView2;
    };
 
    //==============================================================================
    WebBrowserComponent() : WebBrowserComponent (Options {}) {}
 
    explicit WebBrowserComponent (const Options& options);
 
    ~WebBrowserComponent() override;
 
    //==============================================================================
    static bool areOptionsSupported (const Options& options);
 
    //==============================================================================
    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);
 
    virtual void pageFinishedLoading (const String& url);
 
    virtual bool pageLoadHadNetworkError (const String& errorInfo);
 
    virtual void windowCloseRequest();
 
    virtual void newWindowAttemptingToLoad (const String& newURL);
 
    //==============================================================================
    void paint (Graphics&) override;
    void resized() override;
    void parentHierarchyChanged() override;
    void visibilityChanged() override;
    void focusGainedWithDirection (FocusChangeType, FocusChangeDirection) override;
 
    class Pimpl;
 
private:
    std::unique_ptr<AccessibilityHandler> createAccessibilityHandler() override
    {
        return std::make_unique<AccessibilityHandler> (*this, AccessibilityRole::group);
    }
 
    //==============================================================================
    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)
};
 
#endif
 
} // namespace juce