An object that displays web content inside a native window. More...

#include <browser.hpp>

Inheritance diagram for molybden::Browser:

Public Member Functions
virtual std::shared_ptr< App >	app ()=0
	Returns the application instance for this browser.

virtual std::shared_ptr< Profile >	profile ()=0
	Returns the profile of this browser.

virtual std::shared_ptr< BrowserSettings >	settings ()=0
	Returns the content settings of this browser.

virtual std::shared_ptr< Media >	media ()=0
	Returns the media controller of this browser.

virtual std::shared_ptr< Navigation >	navigation ()=0
	Returns the navigation controller of this browser.

virtual std::shared_ptr< DevTools >	devTools ()=0
	Returns the DevTools of this browser.

virtual std::shared_ptr< TextFinder >	textFinder ()=0
	Returns the text finder of this browser.

virtual std::shared_ptr< Zoom >	zoom ()=0
	Returns a service that allows zooming content of a web page loaded in the current browser.

virtual std::string	pageUrl ()=0
	Gets URL of the currently loaded web page or an empty string if the browser hasn't loaded any web page yet.

virtual std::string	pageTitle ()=0
	Returns a string that represents the title of the currently loaded web page or an empty string if the browser hasn't loaded any web page yet.

virtual std::shared_ptr< Frame >	mainFrame ()=0
	Returns the main frame of the currently loaded web page if it exists, otherwise an empty `std::shared_ptr`.

virtual std::shared_ptr< Frame >	focusedFrame ()=0
	Returns the focused frame of the currently loaded web page if it exists, otherwise an empty `std::shared_ptr`.

virtual std::unordered_set< std::shared_ptr< Frame > >	frames ()=0
	Returns all the frames on the currently loaded web page or an empty set if the current browser did not load any web pages.

virtual std::vector< std::shared_ptr< CaptureSession > >	captureSessions ()=0
	Returns the list of all active capture sessions initiated by this browser.

virtual void	loadUrl (const std::string &url)=0
	Starts a navigation to the resource identified by the given `url`.

virtual JsValue	executeJavaScript (const std::string &script)=0
	Executes the given `script` in the main frame of this browser and returns the result of the execution.

virtual void	executeJavaScript (const std::string &script, std::function< void(JsValue)> callback)=0
	Executes the given `script` in the main frame of this browser and returns the result of the execution.

virtual void	download (const std::string &url)=0
	Initiates a download of the resource identified by the given URL.

virtual void	setSize (const Size &size)=0
	Sets the browser window's size.

virtual void	setSize (uint32_t width, uint32_t height)=0
	Sets the browser window's size.

virtual void	setPosition (const Point &position_on_screen)=0
	Sets the browser window's position on screen.

virtual void	setPosition (int32_t x, int32_t y)=0
	Sets the browser window's position on screen.

virtual void	setBounds (const Rect &bounds)=0
	Sets the browser window's size and location on screen.

virtual Rect	bounds ()=0
	Returns the browser window's size and position on screen.

virtual void	centerWindow ()=0
	Centers the browser window on the primary screen.

virtual void	show ()=0
	Shows the browser window, or activates it if it's already visible.

virtual bool	isVisible ()=0
	Indicates whether the browser window is visible.

virtual void	hide ()=0
	Hides the browser window.

virtual void	close ()=0
	Hides and destroys the browser window and releases all allocated resources including the browser instance.

virtual bool	isClosed ()=0
	Checks if the browser window is closed.

virtual void	activate ()=0
	Activates (brings to front) the browser window.

virtual bool	isActive ()=0
	Indicates if the browser window is currently the active/focused window.

virtual void	deactivate ()=0
	Deactivates the browser window, making the next window in the Z order the active window.

virtual void	maximize ()=0
	Maximizes the browser window.

virtual bool	isMaximized ()=0
	Indicates whether the browser window is maximized.

virtual void	minimize ()=0
	Minimizes the browser window.

virtual bool	isMinimized ()=0
	Indicates whether the browser window is minimized.

virtual void	restore ()=0
	Restores the browser window.

virtual void	enterFullScreen ()=0
	Sets the browser window to full screen.

virtual bool	isFullScreen ()=0
	Indicates whether the browser window is running in full screen mode.

virtual void	exitFullScreen ()=0
	Brings the browser window out of full screen mode.

virtual void	setTitle (const std::string &title)=0
	Updates the browser window title.

virtual std::string	title ()=0
	Returns the current browser window title.

virtual void	setWindowTitleVisible (bool visible)=0
	Configures visibility of the title in the browser window title bar.

virtual bool	isWindowTitleVisible ()=0
	Indicates whether the title is visible in the browser window title bar.

virtual void	setWindowTitlebarVisible (bool visible)=0
	Configures visibility of the browser window title bar.

virtual bool	isWindowTitlebarVisible ()=0
	Indicates whether the browser window title bar is visible.

virtual void	setWindowButtonVisible (WindowButtonType button_type, bool visible)=0
	Configures visibility of the given standard browser window button.

virtual bool	isWindowButtonVisible (WindowButtonType button_type)=0
	Indicates whether the standard browser window button with the given type is visible.

virtual void	setAlwaysOnTop (bool always_on_top)=0
	Configures the browser window to always be displayed on top of other windows.

virtual bool	isAlwaysOnTop ()=0
	Indicates whether the browser window is always on top of other windows.

virtual void	setWindowDisplayPolicy (WindowDisplayPolicy policy)=0
	Specifies the policy for displaying the window across multiple desktops.

virtual WindowDisplayPolicy	windowDisplayPolicy ()=0
	Returns the policy for displaying the window across multiple desktops.

virtual void	setWindowAnimationEnabled (bool enabled)=0
	Allows enabling or disabling the default window animation when showing the browser window on macOS.

Static Public Member Functions
static std::shared_ptr< Browser >	create (std::shared_ptr< App > app)
	Creates a new browser instance.

static std::shared_ptr< Browser >	create (std::shared_ptr< Profile > profile)
	Creates a new browser instance.

Additional Inherited Members
Public Attributes inherited from molybden::BrowserEvents
Event< TitleChanged >	onTitleChanged
	Invoked when the web page title has been changed.

Event< StatusChanged >	onStatusChanged
	Invoked when the status text has been changed.

Event< FrameCreated >	onFrameCreated
	Invoked when a new frame has been created.

Event< FrameDeleted >	onFrameDeleted
	Invoked when a frame has been deleted.

Event< ConsoleMessageReceived >	onConsoleMessageReceived
	Invoked when a JavaScript console message has been received.

Event< BrowserBecameResponsive >	onBecameResponsive
	Invoked when the browser has become responsive.

Event< BrowserBecameUnresponsive >	onBecameUnresponsive
	Invoked when browser has become unresponsive.

Event< RenderProcessStarted >	onRenderProcessStarted
	Invoked when a new Chromium render process has been started.

Event< RenderProcessTerminated >	onRenderProcessTerminated
	Invoked when the Chromium render process has been terminated.

Event< CaptureSessionStarted >	onCaptureSessionStarted
	Invoked browser has started a capture session.

Event< SpellCheckCompleted >	onSpellCheckCompleted
	Invoked when spell checking on the frame has been completed.

Event< MediaStreamCaptureStarted >	onMediaStreamCaptureStarted
	Invoked when a web page has started capturing an audio or video stream.

Event< MediaStreamCaptureStopped >	onMediaStreamCaptureStopped
	Invoked when a web page has stopped capturing an audio or video stream.

Event< BrowserClosed >	onBrowserClosed
	Invoked when browser instance has been closed.

Event< FullScreenEntered >	onFullScreenEntered
	Invoked when browser has entered the full screen mode.

Event< FullScreenExited >	onFullScreenExited
	Invoked when browser has exited the full screen mode.

Event< FocusGained >	onFocusGained
	Invoked when the browser has been focused.

Event< FocusLost >	onFocusLost
	Invoked when browser has lost focus.

Public Attributes inherited from molybden::BrowserDelegates
Delegate< InjectJsArgs, InjectJsAction >	onInjectJs
	Invoked when a document element has been created and a custom JavaScript can be executed before any other JavaScript code on the page.

Delegate< InjectCssArgs, InjectCssAction >	onInjectCss
	Invoked when a web page frame's document element has been created and a custom style sheet can be injected into it.

Delegate< CertErrorArgs, CertErrorAction >	onCertError
	Invoked when an SSL certificate error occurs during loading a web page.

Delegate< VerifyCertArgs, VerifyCertAction >	onVerifyCert
	Invoked when certificate verification is required.

Delegate< OpenPopupArgs, OpenPopupAction >	onOpenPopup
	Invoked when a new popup window has been created and can be displayed.

Delegate< ShowContextMenuArgs, ShowContextMenuAction >	onShowContextMenu
	Invoked when context menu on the loaded web page should be shown.

Delegate< AlertArgs, AlertAction >	onAlert
	Invoked when the JavaScript alert dialog should be displayed.

Delegate< ConfirmArgs, ConfirmAction >	onConfirm
	Invoked when the JavaScript confirmation dialog should be displayed.

Delegate< PromptArgs, PromptAction >	onPrompt
	Invoked when the JavaScript dialog prompting the user to input some text should be displayed.

Delegate< BeforeUnloadArgs, BeforeUnloadAction >	onBeforeUnload
	Invoked when the webpage is about to be unloaded and the JavaScript before unload confirmation dialog should be displayed.

Delegate< BeforeFormRepostArgs, BeforeFormRepostAction >	onBeforeFormRepost
	Invoked when the web page with POST data is going to be reloaded and the user must confirm that the POST data can be resubmitted.

Delegate< SaveAsPdfArgs, SaveAsPdfAction >	onSaveAsPdf
	Invoked when the currently loaded web page is about to save as PDF document and the browser wants to display a file chooser dialog to ask the end user where to save the PDF file.

Delegate< CanExecuteCommandArgs, CanExecuteCommandAction >	onCanExecuteCommand
	Invoked to check if a browser command can be executed or not.

Delegate< StartDownloadArgs, StartDownloadAction >	onStartDownload
	Invoked when the browser is about to start downloading a file.

Delegate< SavePasswordArgs, SavePasswordAction >	onSavePassword
	Invoked when the the user is prompted to save the password credentials in the password store after web form submission.

Delegate< UpdatePasswordArgs, UpdatePasswordAction >	onUpdatePassword
	Invoked when the the user is prompted to update the password credentials in the password store after web form submission.

Delegate< AuthenticateArgs, AuthenticateAction >	onAuthenticate
	Invoked when an HTTP request receives an authentication challenge and it is unable to respond using the cached credentials.

Delegate< RequestPdfPasswordArgs, RequestPdfPasswordAction >	onRequestPdfPassword
	Invoked when a web page needs a password to open an encrypted PDF document.

Delegate< StartCaptureSessionArgs, StartCaptureSessionAction >	onStartCaptureSession
	Invoked when a web page requests permission to start a capture session.

Delegate< SaveCreditCardArgs, SaveCreditCardAction >	onSaveCreditCard
	Invoked when user is prompted to save the credit card credentials in the credit card store after web form submission.

Delegate< SaveUserProfileArgs, SaveUserProfileAction >	onSaveUserProfile
	Invoked when user is prompted to save the user profile in the user profile store after web form submission.

Delegate< UpdateUserProfileArgs, UpdateUserProfileAction >	onUpdateUserProfile
	Invoked when user is prompted to update the user profile in the user profile store after web form submission.

Detailed Description

An object that displays web content inside a native window.

Allows loading and displaying content of a web page or a local HTML file, accessing DOM and executing JavaScript, getting notifications about loading progress etc.

When browser is no longer needed, it must be closed through the close() method to release all the allocated memory and system resources.

The Browser instance is closed automatically when its Profile is deleted or App is terminated. If the instance represents a popup window created by JavaScript via window.open(), then JavaScript can close the instance using window.close().

Member Function Documentation

◆ activate()

virtual void molybden::Browser::activate ( )

pure virtual

Activates (brings to front) the browser window.

Restores the window from minimized state if necessary.

◆ close()

virtual void molybden::Browser::close ( )

pure virtual

Hides and destroys the browser window and releases all allocated resources including the browser instance.

The unload and beforeunload JavaScript events will be fired. The beforeunload JavaScript event will trigger a confirmation dialog asking the user if they really want to leave the page and close the browser window. If the user confirms, the browser window will be closed, otherwise the attempt to close the browser window will be canceled.

If the browser window is already closed, then this method does nothing.

◆ create() [1/2]

static std::shared_ptr< Browser > molybden::Browser::create ( std::shared_ptr< App > app )

static

Creates a new browser instance.

Parameters

app	the application of the new browser.

◆ create() [2/2]

static std::shared_ptr< Browser > molybden::Browser::create ( std::shared_ptr< Profile > profile )

static

Creates a new browser instance.

Parameters

profile the profile of the new browser.

◆ download()

virtual void molybden::Browser::download ( const std::string & url )

pure virtual

Initiates a download of the resource identified by the given URL.

If the given URL is valid and points to a downloadable resource, then the download process will be started. To control the download process, use the onStartDownload delegate.

The method does nothing if the given URL is invalid or points to a resource that cannot be downloaded.

Parameters

url	the URL of the resource to download.

◆ enterFullScreen()

virtual void molybden::Browser::enterFullScreen ( )

pure virtual

Sets the browser window to full screen.

Does nothing if the browser window is not shown or it's already running in full screen mode.

◆ executeJavaScript() [1/2]

virtual JsValue molybden::Browser::executeJavaScript ( const std::string & script )

pure virtual

Executes the given script in the main frame of this browser and returns the result of the execution.

This method blocks the current thread execution and waits until the passed JavaScript code has been executed completely. The time required to complete the execution can be different depending on the passed JavaScript code. So, it is strongly recommended that the method is not invoked in the application UI thread.

Equivalent to mainFrame()->executeJavaScript(script).

Parameters

script a string that represents JavaScript code to execute.

Returns: the result of the execution.

◆ executeJavaScript() [2/2]

virtual void molybden::Browser::executeJavaScript	(	const std::string &	script,
		std::function< void(JsValue)>	callback
	)

pure virtual

Executes the given script in the main frame of this browser and returns the result of the execution.

This method does not block the current thread execution and executes the given JavaScript code asynchronously.

Equivalent to mainFrame()->executeJavaScript(script, callback).

Parameters

script	a string that represents JavaScript code to execute.
callback	a callback you can use to get the result of the execution.

◆ exitFullScreen()

virtual void molybden::Browser::exitFullScreen ( )

pure virtual

Brings the browser window out of full screen mode.

Does nothing if the browser window is not shown or it's not running in full screen mode.

◆ loadUrl()

virtual void molybden::Browser::loadUrl ( const std::string & url )

pure virtual

Starts a navigation to the resource identified by the given url.

Tells browser to start asynchronous loading and returns immediately. There is no guarantee that the resource will be loaded completely, by the time this method returns. If there is a pending navigation, it will be stopped/canceled.

Parameters

url	the URL of the resource to load. It can be the URL of a web page (e.g. https://teamdev.com/molybden) or absolute path to a local file (e.g. file:///Users/me/index.html)

◆ setBounds()

virtual void molybden::Browser::setBounds ( const Rect & bounds )

pure virtual

Sets the browser window's size and location on screen.

Parameters

bounds the bounds on screen.

◆ setTitle()

virtual void molybden::Browser::setTitle ( const std::string & title )

pure virtual

Updates the browser window title.

By default, the window title corresponds to the title of the currently loaded web page.

To reset the window title to the default one, simply set an empty title.

Parameters

title the new window title.

◆ setWindowAnimationEnabled()

virtual void molybden::Browser::setWindowAnimationEnabled ( bool enabled )

pure virtual

Allows enabling or disabling the default window animation when showing the browser window on macOS.

On Windows and Linux this method does nothing.

◆ setWindowDisplayPolicy()

virtual void molybden::Browser::setWindowDisplayPolicy ( WindowDisplayPolicy policy )

pure virtual

Specifies the policy for displaying the window across multiple desktops.

This functionality is available on macOS only. On Windows and Linux the method does nothing.

◆ setWindowTitlebarVisible()

virtual void molybden::Browser::setWindowTitlebarVisible ( bool visible )

pure virtual

Configures visibility of the browser window title bar.

When the window title bar is hidden the window becomes a full size content window. The hidden title bar does not draw its background, allowing all buttons to show through, and "click through" to happen.

On macOS the window will still have the standard window buttons ("traffic lights") in the top left and the window title in the top center. To hide the standard window buttons use setWindowButtonVisible(bool). To hide the window title use setWindowTitleVisible().

◆ title()

virtual std::string molybden::Browser::title ( )

pure virtual

Returns the current browser window title.

By default, the window title corresponds to the title of the currently loaded web page.

◆ windowDisplayPolicy()

virtual WindowDisplayPolicy molybden::Browser::windowDisplayPolicy ( )

pure virtual

Returns the policy for displaying the window across multiple desktops.

This functionality is available on macOS only. On Windows and Linux the method returns WindowDisplayPolicy::kDefault.

The documentation for this class was generated from the following file:

include/molybden/browser/browser.hpp

Public Member Functions

Static Public Member Functions

Additional Inherited Members

Detailed Description

Member Function Documentation

◆ activate()

◆ close()

◆ create() [1/2]

◆ create() [2/2]

◆ download()

◆ enterFullScreen()

◆ executeJavaScript() [1/2]

◆ executeJavaScript() [2/2]

◆ exitFullScreen()

◆ loadUrl()

◆ setBounds()

◆ setTitle()

◆ setWindowAnimationEnabled()

◆ setWindowDisplayPolicy()

◆ setWindowTitlebarVisible()

◆ title()

◆ windowDisplayPolicy()