#include <Ultralight/View.h>

Details

Web-page container rendered to an offscreen surface that you display yourself.

The View class is responsible for loading and rendering web-pages to an offscreen surface. It is completely isolated from the OS windowing system, you must forward all input events to it from your application.

Note: The API is not thread-safe, all calls must be made on the same thread that the Renderer/App was created on.

Inheritance diagram for ultralight::View:

Public Member Functions
virtual String	url ()=0
	Get the URL of the current page loaded into this View, if any.

virtual String	title ()=0
	Get the title of the current page loaded into this View, if any.

virtual uint32_t	width () const =0
	Get the width of the View, in pixels.

virtual uint32_t	height () const =0
	Get the height of the View, in pixels.

virtual double	device_scale () const =0
	Get the device scale, ie.

virtual void	set_device_scale (double scale)=0
	Set the device scale.

virtual bool	is_accelerated () const =0
	Whether or not the View is GPU-accelerated.

virtual bool	is_transparent () const =0
	Whether or not the View supports transparent backgrounds.

virtual bool	is_loading ()=0
	Check if the main frame of the page is currently loading.

virtual RenderTarget	render_target ()=0
	Get the RenderTarget for the View.

virtual Surface *	surface ()=0
	Get the Surface for the View (native pixel buffer that the CPU renderer draws into).

virtual void	LoadHTML (const String &html, const String &url="", bool add_to_history=false)=0
	Load a raw string of HTML, the View will navigate to it as a new page.

virtual void	LoadURL (const String &url)=0
	Load a URL, the View will navigate to it as a new page.

virtual void	Resize (uint32_t width, uint32_t height)=0
	Resize View to a certain size.

virtual RefPtr< JSContext >	LockJSContext ()=0
	Acquire the page's JSContext for use with the JavaScriptCore API.

virtual void *	JavaScriptVM ()=0
	Get a handle to the internal JavaScriptCore VM.

virtual String	EvaluateScript (const String &script, String *exception=nullptr)=0
	Helper function to evaluate a raw string of JavaScript and return the result as a String.

virtual bool	CanGoBack ()=0
	Whether or not we can navigate backwards in history.

virtual bool	CanGoForward ()=0
	Whether or not we can navigate forwards in history.

virtual void	GoBack ()=0
	Navigate backwards in history.

virtual void	GoForward ()=0
	Navigate forwards in history.

virtual void	GoToHistoryOffset (int offset)=0
	Navigate to an arbitrary offset in history.

virtual void	Reload ()=0
	Reload current page.

virtual void	Stop ()=0
	Stop all page loads.

virtual void	Focus ()=0
	Give focus to the View.

virtual void	Unfocus ()=0
	Remove focus from the View and unfocus any focused input elements.

virtual bool	HasFocus ()=0
	Whether or not the View has focus.

virtual bool	HasInputFocus ()=0
	Whether or not the View has an input element with visible keyboard focus (indicated by a blinking caret).

virtual void	FireKeyEvent (const KeyEvent &evt)=0
	Fire a keyboard event.

virtual void	FireMouseEvent (const MouseEvent &evt)=0
	Fire a mouse event.

virtual void	FireScrollEvent (const ScrollEvent &evt)=0
	Fire a scroll event.

virtual void	set_view_listener (ViewListener *listener)=0
	Set a ViewListener to receive callbacks for View-related events.

virtual ViewListener *	view_listener () const =0
	Get the active ViewListener, if any.

virtual void	set_load_listener (LoadListener *listener)=0
	Set a LoadListener to receive callbacks for Load-related events.

virtual LoadListener *	load_listener () const =0
	Get the active LoadListener, if any.

virtual void	set_needs_paint (bool needs_paint)=0
	Set whether or not this View should be repainted during the next call to Renderer::Render.

virtual bool	needs_paint () const =0
	Whether or not this View should be repainted during the next call to Renderer::Render.

virtual void	CreateLocalInspectorView ()=0
	Create an Inspector View to inspect / debug this View locally.

Public Member Functions inherited from ultralight::RefCounted
virtual void	AddRef () const =0

virtual void	Release () const =0

virtual int	ref_count () const =0

Protected Member Functions
virtual	~View ()

Protected Member Functions inherited from ultralight::RefCounted
virtual	~RefCounted ()

Constructor & Destructor Documentation

◆ ~View()

virtual ultralight::View::~View ( )

protectedvirtual

Member Function Documentation

◆ CanGoBack()

virtual bool ultralight::View::CanGoBack ( )

pure virtual

Whether or not we can navigate backwards in history.

◆ CanGoForward()

virtual bool ultralight::View::CanGoForward ( )

pure virtual

Whether or not we can navigate forwards in history.

◆ CreateLocalInspectorView()

virtual void ultralight::View::CreateLocalInspectorView ( )

pure virtual

Create an Inspector View to inspect / debug this View locally.

This will only succeed if you have the inspector assets in your filesystem– the inspector will look for file:///inspector/Main.html when it first loads.

You must handle ViewListener::OnCreateInspectorView so that the library has a View to display the inspector in. This function will call this event only if an inspector view is not currently active.

◆ device_scale()

virtual double ultralight::View::device_scale ( ) const

pure virtual

Get the device scale, ie.

the amount to scale page units to screen pixels.

For example, a value of 1.0 is equivalent to 100% zoom. A value of 2.0 is 200% zoom.

◆ EvaluateScript()

virtual String ultralight::View::EvaluateScript	(	const String &	script,
		String *	exception = `nullptr`
	)

pure virtual

Helper function to evaluate a raw string of JavaScript and return the result as a String.

Parameters

script	A string of JavaScript to evaluate in the main frame.
exception	A string to store the exception in, if any. Pass a nullptr if you don't care about exceptions.

Returns: Returns the JavaScript result typecast to a String.

Note: You do not need to lock the JS context, it is done automatically.; If you need lower-level access to native JavaScript values, you should instead lock the JS context and call JSEvaluateScript() in the JavaScriptCore C API.

See also: <JavaScriptCore/JSBase.h>

◆ FireKeyEvent()

virtual void ultralight::View::FireKeyEvent ( const KeyEvent & evt )

pure virtual

Fire a keyboard event.

Note: Only 'Char' events actually generate text in input fields.

◆ FireMouseEvent()

virtual void ultralight::View::FireMouseEvent ( const MouseEvent & evt )

pure virtual

Fire a mouse event.

◆ FireScrollEvent()

virtual void ultralight::View::FireScrollEvent ( const ScrollEvent & evt )

pure virtual

Fire a scroll event.

◆ Focus()

virtual void ultralight::View::Focus ( )

pure virtual

Give focus to the View.

You should call this to give visual indication that the View has input focus (changes active text selection colors, for example).

◆ GoBack()

virtual void ultralight::View::GoBack ( )

pure virtual

Navigate backwards in history.

◆ GoForward()

virtual void ultralight::View::GoForward ( )

pure virtual

Navigate forwards in history.

◆ GoToHistoryOffset()

virtual void ultralight::View::GoToHistoryOffset ( int offset )

pure virtual

Navigate to an arbitrary offset in history.

◆ HasFocus()

virtual bool ultralight::View::HasFocus ( )

pure virtual

Whether or not the View has focus.

◆ HasInputFocus()

virtual bool ultralight::View::HasInputFocus ( )

pure virtual

Whether or not the View has an input element with visible keyboard focus (indicated by a blinking caret).

You can use this to decide whether or not the View should consume keyboard input events (useful in games with mixed UI and key handling).

◆ height()

virtual uint32_t ultralight::View::height ( ) const

pure virtual

Get the height of the View, in pixels.

◆ is_accelerated()

virtual bool ultralight::View::is_accelerated ( ) const

pure virtual

Whether or not the View is GPU-accelerated.

If this is false, the page will be rendered via the CPU renderer.

◆ is_loading()

virtual bool ultralight::View::is_loading ( )

pure virtual

Check if the main frame of the page is currently loading.

◆ is_transparent()

virtual bool ultralight::View::is_transparent ( ) const

pure virtual

Whether or not the View supports transparent backgrounds.

◆ JavaScriptVM()

virtual void * ultralight::View::JavaScriptVM ( )

pure virtual

Get a handle to the internal JavaScriptCore VM.

◆ load_listener()

virtual LoadListener * ultralight::View::load_listener ( ) const

pure virtual

Get the active LoadListener, if any.

◆ LoadHTML()

virtual void ultralight::View::LoadHTML	(	const String &	html,
		const String &	url = `""`,
		bool	add_to_history = `false`
	)

pure virtual

Load a raw string of HTML, the View will navigate to it as a new page.

Parameters

html	The raw HTML string to load.
url	An optional URL for this load (to make it appear as if we we loaded this HTML from a certain URL). Can be used for resolving relative URLs and cross-origin rules.
add_to_history	Whether or not this load should be added to the session's history (eg, the back/forward list).

◆ LoadURL()

virtual void ultralight::View::LoadURL ( const String & url )

pure virtual

Load a URL, the View will navigate to it as a new page.

Note: You can use File URLs (eg, file:///page.html) but you must define your own FileSystem implementation if you are not using AppCore.

See also: Platform::set_file_system

◆ LockJSContext()

virtual RefPtr< JSContext > ultralight::View::LockJSContext ( )

pure virtual

Acquire the page's JSContext for use with the JavaScriptCore API.

Note: You can use the underlying JSContextRef with the JavaScriptCore C API. This allows you to marshall C/C++ objects to/from JavaScript, bind callbacks, and call JS functions directly.; The JSContextRef gets reset after each page navigation. You should initialize your JavaScript state within the OnWindowObjectReady and OnDOMReady events,

See also: ViewListener.

Note: This call locks the internal context for the current thread. It will be unlocked when the returned JSContext's ref-count goes to zero. The lock is recursive, you can call this multiple times.

◆ needs_paint()

virtual bool ultralight::View::needs_paint ( ) const

pure virtual

Whether or not this View should be repainted during the next call to Renderer::Render.

◆ Reload()

virtual void ultralight::View::Reload ( )

pure virtual

Reload current page.

◆ render_target()

virtual RenderTarget ultralight::View::render_target ( )

pure virtual

Get the RenderTarget for the View.

Precondition: Only valid if this View is using the GPU renderer (see ViewConfig::is_accelerated).

Note: You can use this with your GPUDriver implementation to bind and display the corresponding texture in your application.

◆ Resize()

virtual void ultralight::View::Resize	(	uint32_t	width,
		uint32_t	height
	)

pure virtual

Resize View to a certain size.

Parameters

width	The initial width, in pixels.
height	The initial height, in pixels.

◆ set_device_scale()

virtual void ultralight::View::set_device_scale ( double scale )

pure virtual

Set the device scale.

◆ set_load_listener()

virtual void ultralight::View::set_load_listener ( LoadListener * listener )

pure virtual

Set a LoadListener to receive callbacks for Load-related events.

Note: Ownership remains with the caller.

◆ set_needs_paint()

virtual void ultralight::View::set_needs_paint ( bool needs_paint )

pure virtual

Set whether or not this View should be repainted during the next call to Renderer::Render.

Note: This flag is automatically set whenever the page content changes but you can set it directly in case you need to force a repaint.

◆ set_view_listener()

virtual void ultralight::View::set_view_listener ( ViewListener * listener )

pure virtual

Set a ViewListener to receive callbacks for View-related events.

Note: Ownership remains with the caller.

◆ Stop()

virtual void ultralight::View::Stop ( )

pure virtual

Stop all page loads.

◆ surface()

virtual Surface * ultralight::View::surface ( )

pure virtual

Get the Surface for the View (native pixel buffer that the CPU renderer draws into).

Precondition: This operation is only valid if the View is using the CPU renderer, (eg, it is not GPU accelerated, see ViewConfig::is_accelerated). This function will return return nullptr if the View is using the GPU renderer.

Note: The default Surface is BitmapSurface but you can provide your own Surface implementation via Platform::set_surface_factory().

◆ title()

virtual String ultralight::View::title ( )

pure virtual

Get the title of the current page loaded into this View, if any.

◆ Unfocus()

virtual void ultralight::View::Unfocus ( )

pure virtual

Remove focus from the View and unfocus any focused input elements.

You should call this to give visual indication that the View has lost input focus.

◆ url()

virtual String ultralight::View::url ( )

pure virtual

Get the URL of the current page loaded into this View, if any.

◆ view_listener()

virtual ViewListener * ultralight::View::view_listener ( ) const

pure virtual

Get the active ViewListener, if any.

◆ width()

virtual uint32_t ultralight::View::width ( ) const

pure virtual

Get the width of the View, in pixels.

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

Ultralight/View.h

Details

Public Member Functions

Protected Member Functions

Constructor & Destructor Documentation

◆ ~View()

Member Function Documentation

◆ CanGoBack()

◆ CanGoForward()

◆ CreateLocalInspectorView()

◆ device_scale()

◆ EvaluateScript()

◆ FireKeyEvent()

◆ FireMouseEvent()

◆ FireScrollEvent()

◆ Focus()

◆ GoBack()

◆ GoForward()

◆ GoToHistoryOffset()

◆ HasFocus()

◆ HasInputFocus()

◆ height()

◆ is_accelerated()

◆ is_loading()

◆ is_transparent()

◆ JavaScriptVM()

◆ load_listener()

◆ LoadHTML()

◆ LoadURL()

◆ LockJSContext()

◆ needs_paint()

◆ Reload()

◆ render_target()

◆ Resize()

◆ set_device_scale()

◆ set_load_listener()

◆ set_needs_paint()

◆ set_view_listener()

◆ Stop()

◆ surface()

◆ title()

◆ Unfocus()

◆ url()

◆ view_listener()

◆ width()