molybden::Frame Class Reference

A web frame that provides access to DOM and JavaScript. More...

#include <frame.hpp>

Public Member Functions
virtual std::shared_ptr< Browser >	browser ()=0
	The browser instance of the frame.
virtual std::shared_ptr< RenderProcess >	renderProcess ()=0
	Returns the render process associated with this frame.
virtual bool	isMain ()=0
	Checks if it is a main frame.
virtual std::string	name ()=0
	Returns the name of the frame or an empty string if the frame does not have a name.
virtual std::string	html ()=0
	Returns content of the frame in the HTML format or an empty string if the frame does not have a content or its content is empty.
virtual std::string	text ()=0
	Returns content of the frame and its sub-frames as plain text or an empty string if the frame does not have content or its content is empty.
virtual void	loadUrl (const std::string &url)=0
	Navigates the frame to a resource identified by the given URL.
virtual bool	executeCommand (const EditorCommand &command)=0
	Executes the given command in the frame.
virtual bool	isCommandEnabled (const std::string &command_name)=0
	Returns true if the command with the given command_name can be executed in the frame.
virtual void	print ()=0
	Requests printing of the currently loaded web page in this frame.
virtual std::shared_ptr< Frame >	parent ()=0
	Returns the parent frame instance or nullptr if the frame is a main (top-level) frame that doesn't have a parent.
virtual JsValue	executeJavaScript (const std::string &script)=0
	Executes the given script in the frame 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 frame and returns the result of the execution.
virtual std::vector< std::shared_ptr< Frame > >	children ()=0
	Returns a list of child frames or an empty list if this frame does not have any children.

Detailed Description

A web frame that provides access to DOM and JavaScript.

Each web page loaded in browser has a main (top-level) frame. The frame itself may have child frames. When a web page is unloaded, its frame and all child frames are closed automatically and become invalid.

Member Function Documentation

executeCommand()

virtual bool molybden::Frame::executeCommand ( const EditorCommand &  command )

pure virtual

Executes the given command in the frame.

Before executing the command it is recommended to check whether it can be executed or not using isCommandEnabled(command.name).

Parameters

command

the command to execute.

Returns

true if the command has been executed successfully.

See also

isCommandEnabled(const std::string&)

executeJavaScript() [1/2]

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

pure virtual

Executes the given script in the frame 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.

Parameters

script

a string that represents JavaScript code to execute.

Returns

the result of the execution.

executeJavaScript() [2/2]

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

pure virtual

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

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

Parameters

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

html()

virtual std::string molybden::Frame::html ( )

pure virtual

Returns content of the frame in the HTML format or an empty string if the frame does not have a content or its content is empty.

Returns

HTML content of the frame

isCommandEnabled()

virtual bool molybden::Frame::isCommandEnabled ( const std::string &  command_name )

pure virtual

Returns true if the command with the given command_name can be executed in the frame.

Some commands can be executed only under certain conditions. For example, EditorCommand::insertText(const std::string&) command can be executed only if there is a focused text field in the frame.

Parameters

command_name

the name of the command to check.

loadUrl()

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

pure virtual

Navigates the frame to a resource identified by the given URL.

This method tells the frame to start asynchronous loading and returns immediately.

Parameters

url	URL of the resource to load

parent()

virtual std::shared_ptr< Frame > molybden::Frame::parent ( )

pure virtual

Returns the parent frame instance or nullptr if the frame is a main (top-level) frame that doesn't have a parent.

Returns

the parent frame or nullptr

renderProcess()

virtual std::shared_ptr< RenderProcess > molybden::Frame::renderProcess ( )

pure virtual

Returns the render process associated with this frame.

When Chromium loads a new web page, it creates a new render process where DOM and JavaScript are running. This render process can be terminated by Chromium when a new web page with different domain is loaded.

text()

virtual std::string molybden::Frame::text ( )

pure virtual

Returns content of the frame and its sub-frames as plain text or an empty string if the frame does not have content or its content is empty.

Limitations:

• If the frame has sub-frames from another domain, their text will not be included into the return value.
• No specification is given for how text from one frame will be delimited from the next.
• The return value may contain text that is not visible to the user, whether due to scrolling, display:none, unexpanded divs, etc.
• The ordering of the text does not reflect the ordering of the text on the page as seen by the user. Each element's text may appear in a totally different position in the result from its position on the page.

This functionality is resource-intensive, consuming significant memory and CPU during a text capture.

Returns

content of the frame as and its sub-frames plain text

---

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

• include/molybden/frame/frame.hpp