View

#include <Ultralight/View.h>

Overview

Web-page container rendered to an offscreen surface.

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.

Creating a View

You can create a View using Renderer::CreateView.

// Create a ViewConfig with the desired settings
ViewConfig view_config;
 
// Create a View, 500 by 500 pixels in size, using the default Session
RefPtr<View> view = renderer->CreateView(500, 500, view_config, nullptr);

Note

When using App::Create, the library will automatically create a View for you when you call Overlay::Create.

Loading Content into a View

You can load content asynchronously into a View using View::LoadURL().

// Load a URL into the View
view->LoadURL("https://en.wikipedia.org/wiki/Main_Page");

Local File URLs

Local file URLs (eg, file:///page.html) will be loaded via FileSystem. You can provide your own FileSystem implementation so these files can be loaded from your application's resources.

Displaying Views in Your Application

Views are rendered either to a pixel-buffer (View::surface) or a GPU texture (View::render_target) depending on whether CPU or GPU rendering is used (see ViewConfig::is_accelerated).

You can use the Surface or RenderTarget to display the View in your application.

// Get the Surface for the View (assuming CPU rendering)
Surface* surface = view->surface();
 
// Check if the Surface is dirty (pixels have changed)
if (!surface->dirty_bounds().IsEmpty()) {
  // Cast to the default Surface implementation (BitmapSurface) and get
  // the underlying Bitmap.
  RefPtr<Bitmap> bitmap = static_cast<BitmapSurface*>(surface)->bitmap();
 
  // Use the bitmap pixels here...
 
  // Clear the dirty bounds after you're done displaying the pixels
  surface->ClearDirtyBounds();
}

Input Events

You must forward all input events to the View from your application. This includes keyboard, mouse, and scroll events.

// Forward a mouse-move event to the View
MouseEvent evt;
evt.type = MouseEvent::kType_MouseMoved;
evt.x = 100;
evt.y = 100;
evt.button = MouseEvent::kButton_None;
view->FireMouseEvent(evt);

Note

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

Inheritance diagram for 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 uint32_t	display_id () const =0
	Get the display id of the View.
virtual void	set_display_id (uint32_t id)=0
	Set the display id of the View.
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_download_listener (DownloadListener *listener)=0
	Set a DownloadListener to receive callbacks for download-related events.
virtual DownloadListener *	download_listener () const =0
	Get the active DownloadListener, if any.
virtual void	CancelDownload (DownloadId id)=0
	Cancel an active download.
virtual void	set_network_listener (NetworkListener *listener)=0
	Set a NetworkListener to receive callbacks for network-related events.
virtual NetworkListener *	network_listener () const =0
	Get the active NetworkListener, 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 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 RefCounted
virtual	~RefCounted ()

Constructor & Destructor Documentation

~View()

virtual ~View ( )

protectedvirtual

Member Function Documentation

CancelDownload()

virtual void CancelDownload ( DownloadId id )

pure virtual

Cancel an active download.

CanGoBack()

virtual bool CanGoBack ( )

pure virtual

Whether or not we can navigate backwards in history.

CanGoForward()

virtual bool CanGoForward ( )

pure virtual

Whether or not we can navigate forwards in history.

CreateLocalInspectorView()

virtual void 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 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.

display_id()

virtual uint32_t display_id ( ) const

pure virtual

Get the display id of the View.

See also

ViewConfig::display_id

download_listener()

virtual DownloadListener * download_listener ( ) const

pure virtual

Get the active DownloadListener, if any.

EvaluateScript()

virtual String 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 FireKeyEvent ( const KeyEvent & evt )

pure virtual

Fire a keyboard event.

Note

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

FireMouseEvent()

virtual void FireMouseEvent ( const MouseEvent & evt )

pure virtual

Fire a mouse event.

FireScrollEvent()

virtual void FireScrollEvent ( const ScrollEvent & evt )

pure virtual

Fire a scroll event.

Focus()

virtual void 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 GoBack ( )

pure virtual

Navigate backwards in history.

GoForward()

virtual void GoForward ( )

pure virtual

Navigate forwards in history.

GoToHistoryOffset()

virtual void GoToHistoryOffset ( int offset )

pure virtual

Navigate to an arbitrary offset in history.

HasFocus()

virtual bool HasFocus ( )

pure virtual

Whether or not the View has focus.

HasInputFocus()

virtual bool 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 height ( ) const

pure virtual

Get the height of the View, in pixels.

is_accelerated()

virtual bool 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 is_loading ( )

pure virtual

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

is_transparent()

virtual bool is_transparent ( ) const

pure virtual

Whether or not the View supports transparent backgrounds.

JavaScriptVM()

virtual void * JavaScriptVM ( )

pure virtual

Get a handle to the internal JavaScriptCore VM.

load_listener()

virtual LoadListener * load_listener ( ) const

pure virtual

Get the active LoadListener, if any.

LoadHTML()

virtual void 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 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 > 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 needs_paint ( ) const

pure virtual

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

network_listener()

virtual NetworkListener * network_listener ( ) const

pure virtual

Get the active NetworkListener, if any.

Reload()

virtual void Reload ( )

pure virtual

Reload current page.

render_target()

virtual RenderTarget 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 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 set_device_scale ( double scale )

pure virtual

Set the device scale.

set_display_id()

virtual void set_display_id ( uint32_t id )

pure virtual

Set the display id of the View.

This should be called when the View is moved to another display.

set_download_listener()

virtual void set_download_listener ( DownloadListener * listener )

pure virtual

Set a DownloadListener to receive callbacks for download-related events.

Note

Ownership remains with the caller.

set_load_listener()

virtual void 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 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_network_listener()

virtual void set_network_listener ( NetworkListener * listener )

pure virtual

Set a NetworkListener to receive callbacks for network-related events.

Note

Ownership remains with the caller.

set_view_listener()

virtual void 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 Stop ( )

pure virtual

Stop all page loads.

surface()

virtual Surface * 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 title ( )

pure virtual

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

Unfocus()

virtual void 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 url ( )

pure virtual

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

view_listener()

virtual ViewListener * view_listener ( ) const

pure virtual

Get the active ViewListener, if any.

width()

virtual uint32_t 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