#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 creates a View for you when you add a panel to a window (see <AppCore/Layout.h>).

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 (AttachDOMDataContext() and DetachDOMDataContext() are the exceptions).

Inheritance diagram for View:

Public Types
using	DOMTriggersInjectionFilter
	Callback that decides whether an attached set of DOM listeners is applied to a loading page.
using	JSAPIInjectionFilter = bool ()(void user_data, const ULJSAPIInjectionRequest* request)
	Callback that decides whether an attached API's bindings are added to a loading page.

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 bool	is_settled ()=0
	Check if the page has settled after 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 void	Resize (uint32_t width, uint32_t height, double device_scale)=0
	Resize View to a certain size and apply a new device scale in the same pass.
virtual RefPtr< JSContext >	LockJSContext (const String &frame="")=0
	Acquire the page's JSContext for use with the JavaScriptCore API.
virtual void *	JavaScriptVM (const String &frame="")=0
	Get a handle to the internal JavaScriptCore VM.
virtual String	EvaluateScript (const String &script, String *exception=nullptr, const String &frame="")=0
	Evaluate a string of JavaScript and return the result as a String.
virtual ULJSContext	GetJSContext ()=0
	Get a ULJS handle to the main frame's JavaScript context.
virtual ULDOMDocument	GetDOMDocument ()=0
	Get a ULDOM handle to the current page's document (main frame).
virtual bool	AttachDOMTriggers (ULDOMTriggers triggers, unsigned flags=0, const char const origin_rules=nullptr, size_t num_origin_rules=0)=0
	Attach a set of DOM listeners to this View.
virtual void	DetachDOMTriggers (ULDOMTriggers triggers)=0
	Detach a set of DOM listeners from this View.
virtual void	SetDOMTriggersInjectionFilter (DOMTriggersInjectionFilter filter, void user_data, void(destroy_user_data)(void *))=0
	Set a filter that decides whether an attached set of DOM listeners is applied to a page.
virtual bool	AttachDOMDataContext (ULDOMDataContext context, unsigned flags=0, const char const origin_rules=nullptr, size_t num_origin_rules=0)=0
	Attach a data-binding context to this View.
virtual void	DetachDOMDataContext (ULDOMDataContext context)=0
	Detach a data-binding context from this View.
virtual bool	AttachJSAPI (ULJSAPI api, unsigned flags=0, const char const origin_rules=nullptr, size_t num_origin_rules=0)=0
	Attach a JavaScript API to this View.
virtual void	DetachJSAPI (ULJSAPI api)=0
	Detach a JavaScript API from this View.
virtual void	SetJSAPIInjectionFilter (JSAPIInjectionFilter filter, void user_data, void(destroy_user_data)(void *))=0
	Set a filter that decides whether an attached API's bindings are added to a page.
virtual bool	CanGoBack ()=0
	Whether or not the View can navigate back in history.
virtual bool	CanGoForward ()=0
	Whether or not the View can navigate forward 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.
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 Editor *	editor ()=0
	Get the Editor for the View (executes editing commands against the focused frame).
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 (can be nullptr).
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 (can be nullptr).
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 (can be nullptr).
virtual void	CancelDownload (DownloadId id)=0
	Cancel an active download.
virtual void	set_editor_listener (EditorListener *listener)=0
	Set an EditorListener to receive callbacks for editing-related events.
virtual EditorListener *	editor_listener () const =0
	Get the active EditorListener (can be nullptr).
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 (can be nullptr).
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.
virtual void	set_compositor_debug_info_enabled (bool enable)=0
	Set whether or not to display compositor debug information, specifically:
virtual bool	compositor_debug_info_enabled () const =0
	Whether or not compositor debug information is enabled.
virtual void	set_visible (bool visible)=0
	Set whether or not this View is visible.
virtual bool	is_visible () const =0
	Whether or not this View is visible.
virtual void	set_max_render_fps (uint32_t fps)=0
	Set the maximum rate, in frames per second, at which this View advances its animations and repaints.
virtual uint32_t	max_render_fps () const =0
	Get the frame-rate cap set for this View, or 0 if none is set.
virtual void	set_preferred_color_scheme (ColorScheme scheme)=0
	Set the color scheme this View reports to pages via the prefers-color-scheme CSS media feature.
virtual ColorScheme	preferred_color_scheme () const =0
	The color scheme this View reports to pages.
Public Member Functions inherited from RefCounted
virtual void	AddRef () const =0
	Increment the reference count (thread-safe).
virtual void	Release () const =0
	Decrement the reference count (thread-safe).
virtual int	ref_count () const =0
	Get the current reference count.
virtual WeakControlBlock *	weak_control_block () const
	Get the control block used to track weak references to this object.

Protected Member Functions
virtual	~View ()
Protected Member Functions inherited from RefCounted
virtual	~RefCounted ()

Member Typedef Documentation

◆ DOMTriggersInjectionFilter

using DOMTriggersInjectionFilter

Initial value:

bool (*)(void* user_data,

const ULDOMTriggersInjectionRequest* request)

ULDOMTriggersInjectionRequest

struct ULDOMTriggersInjectionRequest ULDOMTriggersInjectionRequest

The details a DOM triggers injection filter decides on.

Definition View.h:67

Callback that decides whether an attached set of DOM listeners is applied to a loading page.

This is called on the Renderer's thread after the origin rules have been evaluated. See SetDOMTriggersInjectionFilter() and <Ultralight/CAPI/CAPI_DOMTriggers.h>. Most C++ code uses dom::SetInjectionFilter() instead.

Parameters

user_data	The user data passed to SetDOMTriggersInjectionFilter().
request	The set of DOM listeners, the page's origin, and the verdict of the origin rules (see ULDOMTriggersInjectionRequest). It's owned by the library and valid only during the callback. Its view member is NULL here (it's set only for a filter set with ulViewSetDOMTriggersInjectionFilter()).

Returns: Return true to apply the listeners to this page, or false to skip it. The return value is final: it can override the origin rules either way.

◆ JSAPIInjectionFilter

using JSAPIInjectionFilter = bool (*)(void* user_data, const ULJSAPIInjectionRequest* request)

Callback that decides whether an attached API's bindings are added to a loading page.

This is called on the Renderer's thread after the origin rules have been evaluated. See SetJSAPIInjectionFilter() and <Ultralight/CAPI/CAPI_JSAPI.h>. Most C++ code uses js::SetInjectionFilter() instead.

Parameters

user_data	The user data passed to SetJSAPIInjectionFilter().
request	The API, the page's origin, and the verdict of the origin rules (see ULJSAPIInjectionRequest). It's owned by the library and valid only during the callback. Its view member is NULL here (it's set only for a filter set with ulViewSetJSAPIInjectionFilter()).

Returns: Return true to add the bindings to this page, or false to withhold them. The return value is final: it can override the origin rules either way.

Constructor & Destructor Documentation

◆ ~View()

virtual ~View ( )

protectedvirtual

Member Function Documentation

◆ AttachDOMDataContext()

virtual bool AttachDOMDataContext	(	ULDOMDataContext	context,
		unsigned	flags = 0,
		const char const	origin_rules = nullptr,
		size_t	num_origin_rules = 0 )

pure virtual

Attach a data-binding context to this View.

Once attached, pages loaded into this View compile their binding markup against the context's published models and stay updated as the context publishes new data (see <Ultralight/dom/data/Context.h>).

One context may attach to any number of Views (one publish serves them all). The View keeps the context attached while an owning handle to it exists (see ulDestroyDOMDataContext()). Attaching an already-attached context updates its flags and origin rules.

Parameters

context	The context to attach.
flags	A logically ORed set of ULDOMDataContextAttachFlags (none are defined yet, so pass kULDOMDataContextAttachFlags_None). Unknown bits fail the attach.
origin_rules	An array of scheme://host[:port] origin patterns for the pages that compile the context's bindings, or nullptr for the default policy (local pages plus your application's own content). See ultralight::OriginRules for the rule syntax.
num_origin_rules	The number of entries in origin_rules.

Returns: Returns true on success, or false if context is NULL, a flag is unknown, or a rule failed to parse (nothing changes then, and a logged warning says why).

Note: The origin policy is shared with AttachJSAPI(): same rule syntax, same default, evaluated against each page's security origin. A page that isn't allowed compiles no binding markup: it shows its authored content, and none of its controls stage changes or fire actions. A data context has no injection filter, so the origin rules alone decide which pages get it.

Note: Safe to call from any thread, including the context's home thread (origin rules parse on the calling thread). Unlike most View methods this only records intent, the attachment takes effect on the Renderer's thread during the next update.

◆ AttachDOMTriggers()

virtual bool AttachDOMTriggers	(	ULDOMTriggers	triggers,
		unsigned	flags = 0,
		const char const	origin_rules = nullptr,
		size_t	num_origin_rules = 0 )

pure virtual

Attach a set of DOM listeners to this View.

A set of DOM listeners (see <Ultralight/CAPI/CAPI_DOMTriggers.h>) holds event listeners matched by CSS selector and DOM-ready hooks. Once attached, the set is added to the current page (if its document has finished parsing) and to every page the View loads afterward, so you don't need to register again after a navigation. This works with or without JavaScript enabled. Most C++ code uses dom::Triggers::AttachTo() instead.

ULDOMTriggers triggers = ulCreateDOMTriggers();
ulDOMTriggersOn(triggers, "#save", "click", kULDOMEventFlags_None, OnSave, ctx, nullptr);
view->AttachDOMTriggers(triggers);
// #save is clickable on this page and on every page the View navigates to.

The View keeps the set attached while an owning handle to it exists (see ulDestroyDOMTriggers()). Attaching it again changes the flags and origin rules for later pages (a page that already has the listeners keeps them).

Parameters

triggers	The listeners to attach.
flags	A logically ORed set of ULDOMTriggersAttachFlags. Unknown bits fail the attach.
origin_rules	An array of scheme://host[:port] origin patterns for the pages that get the set, or nullptr for the default policy (local pages plus your application's own content). Rules replace the default. See ultralight::OriginRules for the rule syntax.
num_origin_rules	The number of entries in origin_rules.

Returns: Returns true on success, or false if triggers is NULL, a flag is unknown, or a rule failed to parse (nothing changes then, and a logged warning says why).

Note: The origin policy is shared with AttachJSAPI(): same rule syntax, same default, evaluated against the page's security origin.

Note: Without kULDOMTriggersAttachFlags_AllFrames, only the main frame gets the set.

Note: A page restored from the back-forward cache (Config::page_cache_size > 0) gets the listeners again before its pageshow event. Its DOM-ready hooks don't run again, so register a restore hook with ulDOMTriggersOnRestore() for work you need on every restore.

◆ AttachJSAPI()

virtual bool AttachJSAPI	(	ULJSAPI	api,
		unsigned	flags = 0,
		const char const	origin_rules = nullptr,
		size_t	num_origin_rules = 0 )

pure virtual

Attach a JavaScript API to this View.

A ULJSAPI (see <Ultralight/CAPI/CAPI_JSAPI.h>) is a set of native bindings under a global namespace such as myApp.

Once attached, the bindings are added to the current page (if any) and to every page the View navigates to afterwards, so you don't need to register them again after a navigation:

ULJSAPI api = ulCreateJSAPI("myApp");
ulJSAPIBindFunction(api, "greet", OnGreet, nullptr, nullptr);
view->AttachJSAPI(api);
// Page script on every admitted page:  myApp.greet()

The View keeps the API attached while an owning handle to it exists (see ulDestroyJSAPI()). Attaching it again updates its flags and origin rules.

Parameters

api	The API to attach.
flags	A logically ORed set of ULJSAPIAttachFlags. Unknown bits fail the attach.
origin_rules	An array of scheme://host[:port] origin patterns for the pages that get the bindings (eg, https://*.mygame.com), or nullptr for the default policy (local pages plus your application's own content, ie. pages loaded with LoadHTML()). See ultralight::OriginRules for the rule syntax.
num_origin_rules	The number of entries in origin_rules.

Returns: Returns true on success, or false if api is NULL, a flag is unknown, or a rule failed to parse (nothing changes then, and a logged warning says why).

Note: APIs that share a namespace prefix (eg, myApp.fs and myApp.net) should all be attached before the page loads. An API attached later can't add to a namespace the page already has, so its bindings appear after the page's next navigation instead (see ulViewAttachJSAPI()).

Note: Without kULJSAPIAttachFlags_AllFrames, the bindings are added to the main frame only.

Note: A page restored from the back-forward cache (Config::page_cache_size > 0) resumes with working bindings: the API objects it kept (and any function references its scripts held) become callable again, and native events reach the page. Page-side event subscriptions made with the on mixin do not survive the round trip, so page scripts should re-subscribe in a pageshow handler.

◆ CancelDownload()

virtual void CancelDownload ( DownloadId id )

pure virtual

Cancel an active download.

No more data arrives for the download, and DownloadListener::OnFailDownload() is called for it during a later Renderer::Update().

Parameters

id	The id of the download to cancel (see DownloadListener).

◆ CanGoBack()

virtual bool CanGoBack ( )

pure virtual

Whether or not the View can navigate back in history.

◆ CanGoForward()

virtual bool CanGoForward ( )

pure virtual

Whether or not the View can navigate forward in history.

◆ compositor_debug_info_enabled()

virtual bool compositor_debug_info_enabled ( ) const

pure virtual

Whether or not compositor debug information is enabled.

◆ 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.

◆ DetachDOMDataContext()

virtual void DetachDOMDataContext ( ULDOMDataContext context )

pure virtual

Detach a data-binding context from this View.

Its pages stop receiving updates, and the page's binding markup recompiles against the remaining attached contexts.

Parameters

context The context to detach.

Note: Safe to call from any thread. The attachment is removed immediately, and the page recompiles on the Renderer's thread during its next update.

◆ DetachDOMTriggers()

virtual void DetachDOMTriggers ( ULDOMTriggers triggers )

pure virtual

Detach a set of DOM listeners from this View.

The listeners stop right away (they're removed from the current page), and no later page gets them.

Parameters

triggers The listeners to detach.

◆ DetachJSAPI()

virtual void DetachJSAPI ( ULJSAPI api )

pure virtual

Detach a JavaScript API from this View.

Functions and objects already added to the current page remain until the next navigation, but event delivery to this View stops immediately.

Parameters

api	The API to detach.

◆ 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, Renderer::RefreshDisplay()

◆ download_listener()

virtual DownloadListener * download_listener ( ) const

pure virtual

Get the active DownloadListener (can be nullptr).

◆ editor()

virtual Editor * editor ( )

pure virtual

Get the Editor for the View (executes editing commands against the focused frame).

You can use this to drive text editing natively: caret motion, selection, deletion, clipboard operations, undo/redo, and typed text insertion (the commands a native Edit menu or keybinding table needs).

Returns: Returns the View's Editor instance (owned by the View, this is never NULL).

See also: Editor

◆ editor_listener()

virtual EditorListener * editor_listener ( ) const

pure virtual

Get the active EditorListener (can be nullptr).

◆ EvaluateScript()

virtual String EvaluateScript	(	const String &	script,
		String *	exception = nullptr,
		const String &	frame = "" )

pure virtual

Evaluate a string of JavaScript and return the result as a String.

Parameters

script	The JavaScript to evaluate.
exception	Receives the exception message if the script throws, or an empty string if it doesn't. Pass a nullptr if you don't care about exceptions.
frame	The name of the frame to evaluate the script in. Pass an empty string (default) for the main frame, or the name attribute of one of the main frame's iframes.

Returns: Returns the result converted to a String (eg, undefined becomes "undefined"), or an empty string if the frame doesn't exist or can't run scripts.

Note: You don't need to lock the JS context, this does it for you.

Note: For typed access to the result, use the ultralight::js layer instead: acquire the page's context with js::Context (see <Ultralight/JS.h>) and call Context::Evaluate(), which returns a js::Result holding the completion value or the script's exception rather than a flattened string.

Note: For raw JavaScriptCore access, 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.

Parameters

evt	The key event.

Note: KeyEvent::kType_Char events insert text into input fields, and so does a legacy KeyEvent::kType_KeyDown that carries text. KeyEvent::kType_RawKeyDown never inserts text.

◆ FireMouseEvent()

virtual void FireMouseEvent ( const MouseEvent & evt )

pure virtual

Fire a mouse event.

Parameters

evt	The mouse event.

◆ FireScrollEvent()

virtual void FireScrollEvent ( const ScrollEvent & evt )

pure virtual

Fire a scroll event.

Parameters

evt	The 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). The page gets a window focus event, and so does the element that had focus before Unfocus().

◆ GetDOMDocument()

virtual ULDOMDocument GetDOMDocument ( )

pure virtual

Get a ULDOM handle to the current page's document (main frame).

The document is available even when JavaScript is disabled (ViewConfig::enable_javascript is false). Most C++ code uses dom::Document instead (see <Ultralight/DOM.h>).

Returns: Returns the document (NULL if the main frame has none). You must call ulDestroyDOMDocument() when finished.

Note: The handle stops working when the page goes away, so get it again for each page (eg, in LoadListener::OnDOMReady()). Before your page loads, and while a new page is loading, this returns the previous document.

◆ GetJSContext()

virtual ULJSContext GetJSContext ( )

pure virtual

Get a ULJS handle to the main frame's JavaScript context.

Unlike LockJSContext(), the returned handle never keeps the page alive. When the page navigates away or the View is destroyed, the handle stops working and operations on it fail safely. Use it with the functions in <Ultralight/CAPI/CAPI_JSValue.h>. Most C++ code uses js::Context instead (see <Ultralight/JS.h>), which wraps this handle.

Returns: Returns a new ULJSContext handle for the current page, or NULL if the main frame can't run scripts (eg, when ViewConfig::enable_javascript is false, or the document is sandboxed against scripts). You must call ulDestroyJSContext() when finished.

Note: Each page gets a fresh context. After a navigation, call this again to obtain a handle to the new page's context. LoadListener::OnWindowObjectReady() and LoadListener::OnDOMReady() are good acquisition points.

◆ 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.

Parameters

offset The number of entries to move (negative goes back, positive goes forward).

◆ 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).

Note: This reports text-editing focus specifically: a focused text field, text area, or editable (contenteditable) region that can accept typed input. Focused elements that consume keys without editing text (eg, a select or checkbox) report false, as do read-only text fields, and so does everything while the View itself is unfocused (see Unfocus()).

◆ 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_settled()

virtual bool is_settled ( )

pure virtual

Check if the page has settled after loading.

This is true once the page's network and layout activity have gone idle following the main frame's onload event. It is the latched, queryable form of the LoadListener::OnPageSettled() event, flipping true when that event fires and resetting to false on each new navigation.

Note: Settling covers network and layout activity only. See LoadListener::OnPageSettled() for what settling does not promise and for the run-loop calls the library needs in order to observe it.

◆ is_transparent()

virtual bool is_transparent ( ) const

pure virtual

Whether or not the View supports transparent backgrounds.

◆ is_visible()

virtual bool is_visible ( ) const

pure virtual

Whether or not this View is visible.

See also: set_visible()

◆ JavaScriptVM()

virtual void * JavaScriptVM ( const String & frame = "" )

pure virtual

Get a handle to the internal JavaScriptCore VM.

Parameters

frame The name of the frame to access. Pass an empty string (default) for the main frame, or the name attribute of one of the main frame's iframes.

Returns: Returns a pointer to the VM, or nullptr if the frame doesn't exist or can't run scripts. Every frame and View shares one VM.

◆ load_listener()

virtual LoadListener * load_listener ( ) const

pure virtual

Get the active LoadListener (can be nullptr).

◆ 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 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.

Parameters

url	The URL to load.

Note: You can use file URLs (eg, file:///page.html), but you must provide your own FileSystem if you aren't using AppCore.

See also: Platform::set_file_system()

◆ LockJSContext()

virtual RefPtr< JSContext > LockJSContext ( const String & frame = "" )

pure virtual

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

Parameters

frame The name of the frame to access. Pass an empty string (default) for the main frame, or the name attribute of one of the main frame's iframes.

Returns: Returns a RefPtr to the JSContext for the frame, or nullptr if the frame doesn't exist or can't run scripts (eg, when ViewConfig::enable_javascript is false).

Note: You can use the underlying JSContextRef with the JavaScriptCore C API to marshal C/C++ objects to and from JavaScript, bind callbacks, and call JS functions directly.

Note: The JSContextRef is reset on each page navigation. You should set up your JavaScript state in LoadListener::OnWindowObjectReady() or LoadListener::OnDOMReady().

Note: This locks the JavaScript VM for the current thread until the returned JSContext's ref-count drops to zero. The lock is recursive, so you can call this more than once.

◆ max_render_fps()

virtual uint32_t max_render_fps ( ) const

pure virtual

Get the frame-rate cap set for this View, or 0 if none is set.

See also: set_max_render_fps()

◆ needs_paint()

virtual bool needs_paint ( ) const

pure virtual

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

When this returns false, rendering would reproduce the previous frame, so you can skip rendering or presenting the View. This is always false while the View is hidden, and while max_render_fps() holds back its next frame.

When this returns true, the next call to Renderer::Render() repaints the View. The resulting frame may still be visually identical to the previous frame.

Note: Continue calling Renderer::RefreshDisplay() on every display refresh regardless of this flag. A View whose only pending work is animation callbacks or CSS animations only requests a repaint after that call.

◆ network_listener()

virtual NetworkListener * network_listener ( ) const

pure virtual

Get the active NetworkListener (can be nullptr).

◆ preferred_color_scheme()

virtual ColorScheme preferred_color_scheme ( ) const

pure virtual

The color scheme this View reports to pages.

See also: set_preferred_color_scheme()

◆ 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() [1/2]

virtual void Resize	(	uint32_t	width,
		uint32_t	height )

pure virtual

Resize View to a certain size.

Parameters

width	The new width, in pixels.
height	The new height, in pixels.

◆ Resize() [2/2]

virtual void Resize	(	uint32_t	width,
		uint32_t	height,
		double	device_scale )

pure virtual

Resize View to a certain size and apply a new device scale in the same pass.

Prefer this over separate set_device_scale() and Resize() calls when both change at once (for example, when a window moves to a display with a different DPI): applying them together resizes the page once instead of twice.

Parameters

width	The new width, in pixels.
height	The new height, in pixels.
device_scale	The new device scale (see set_device_scale()).

◆ set_compositor_debug_info_enabled()

virtual void set_compositor_debug_info_enabled ( bool enable )

pure virtual

Set whether or not to display compositor debug information, specifically:

Visualize compositor layers and tile boundaries
Display repaint counters for each layer

Parameters

enable Whether or not to show the debug information.

Note: This is only valid when the compositor is enabled.

See also: ViewConfig::enable_compositor

◆ set_device_scale()

virtual void set_device_scale ( double scale )

pure virtual

Set the device scale.

Parameters

scale The new device scale (see device_scale()).

Note: To change the View's size at the same time, use Resize(width, height, device_scale) instead, which applies both in one pass.

◆ set_display_id()

virtual void set_display_id ( uint32_t id )

pure virtual

Set the display id of the View.

You should call this when the View moves to another display.

Parameters

id	The id of the new display (see ViewConfig::display_id).

Note: This is automatically managed for you for Views hosted in an AppCore Window.

◆ set_download_listener()

virtual void set_download_listener ( DownloadListener * listener )

pure virtual

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

Parameters

listener A user-defined DownloadListener implementation, ownership remains with the caller. Pass a nullptr to remove the current listener.

◆ set_editor_listener()

virtual void set_editor_listener ( EditorListener * listener )

pure virtual

Set an EditorListener to receive callbacks for editing-related events.

Parameters

listener A user-defined EditorListener implementation, ownership remains with the caller. Pass a nullptr to remove the current listener.

Note: An AppCore panel uses its View's editor listener for input method support and Window::OnEditableStateChange(). Replacing it on a hosted View turns both off for that View.

◆ set_load_listener()

virtual void set_load_listener ( LoadListener * listener )

pure virtual

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

Parameters

listener A user-defined LoadListener implementation, ownership remains with the caller. Pass a nullptr to remove the current listener.

◆ set_max_render_fps()

virtual void set_max_render_fps ( uint32_t fps )

pure virtual

Set the maximum rate, in frames per second, at which this View advances its animations and repaints.

Parameters

fps	The frame-rate cap, or 0 to remove it (the View then advances at the display's refresh rate).

See also: ViewConfig::max_render_fps

◆ 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().

Parameters

needs_paint Whether or not the View needs a repaint.

Note: The library sets this flag automatically when a repaint is due: after a Renderer::RefreshDisplay() call that produces animating or changed content, on resize, when the View is shown, and when the page reacts to user input. You can also set it directly to force a repaint (it still waits for max_render_fps()).

◆ set_network_listener()

virtual void set_network_listener ( NetworkListener * listener )

pure virtual

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

Parameters

listener A user-defined NetworkListener implementation, ownership remains with the caller. Pass a nullptr to remove the current listener.

Precondition: Not available in the Free edition (the listener is never called there).

◆ set_preferred_color_scheme()

virtual void set_preferred_color_scheme ( ColorScheme scheme )

pure virtual

Set the color scheme this View reports to pages via the prefers-color-scheme CSS media feature.

Overrides ViewConfig::preferred_color_scheme for this View. A change re-evaluates prefers-color-scheme media queries on the page, firing matchMedia change listeners and recalculating styles, the same as an OS theme change.

Parameters

scheme The new scheme. Auto follows the system value set via Renderer::set_system_color_scheme().

◆ set_view_listener()

virtual void set_view_listener ( ViewListener * listener )

pure virtual

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

Parameters

listener A user-defined ViewListener implementation, ownership remains with the caller. Pass a nullptr to remove the current listener.

◆ set_visible()

virtual void set_visible ( bool visible )

pure virtual

Set whether or not this View is visible.

Hiding a View (passing false) stops it from being painted during Renderer::Render and pauses its rendering-driven work: requestAnimationFrame callbacks and CSS animations stop advancing while hidden, and the page's visibilitychange event fires with document.visibilityState set to "hidden".

Showing a View again (passing true) resumes its animations and forces a repaint on the next call to Renderer::Render.

Parameters

visible Whether or not the View is visible.

Note: Views are visible by default.

Note: JavaScript timers (setTimeout / setInterval) keep running while hidden unless ViewConfig::enable_hidden_timer_throttling was set when the View was created.

◆ SetDOMTriggersInjectionFilter()

virtual void SetDOMTriggersInjectionFilter	(	DOMTriggersInjectionFilter	filter,
		void *	user_data,
		void(*	destroy_user_data )(void *) )

pure virtual

Set a filter that decides whether an attached set of DOM listeners is applied to a page.

The filter is consulted after the origin rules, for every attached set and page.

Parameters

filter	The filter callback. Pass nullptr to remove the current filter.
user_data	User data passed through to the filter on every call.
destroy_user_data	Callback invoked exactly once to destroy user_data after the filter is replaced or the View is destroyed (may be nullptr).

See also: dom::SetInjectionFilter()

◆ SetJSAPIInjectionFilter()

virtual void SetJSAPIInjectionFilter	(	JSAPIInjectionFilter	filter,
		void *	user_data,
		void(*	destroy_user_data )(void *) )

pure virtual

Set a filter that decides whether an attached API's bindings are added to a page.

The filter is consulted after the origin rules, for every attached API and page.

Parameters

filter	The filter callback. Pass nullptr to remove the current filter.
user_data	User data passed through to the filter on every call.
destroy_user_data	Callback invoked exactly once to destroy user_data after the filter is replaced or the View is destroyed (may be nullptr).

See also: js::SetInjectionFilter()

◆ 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: Only valid if the View uses the CPU renderer (see ViewConfig::is_accelerated). This returns nullptr if the View uses the GPU renderer.

Note: The default Surface is BitmapSurface, but you can provide your own Surface implementation with 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.

You should call this to give visual indication that the View has lost input focus. The page gets a window blur event.

Note: The page's focused element gets a blur event but stays focused in the document, and shows focus again the next time you call 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 (can be nullptr).

◆ 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

Overview

Creating a View

Loading Content into a View

Local File URLs

Displaying Views in Your Application

Input Events

Public Types

Public Member Functions

Protected Member Functions

Member Typedef Documentation

◆ DOMTriggersInjectionFilter

◆ JSAPIInjectionFilter

Constructor & Destructor Documentation

◆ ~View()

Member Function Documentation

◆ AttachDOMDataContext()

◆ AttachDOMTriggers()

◆ AttachJSAPI()

◆ CancelDownload()

◆ CanGoBack()

◆ CanGoForward()

◆ compositor_debug_info_enabled()

◆ CreateLocalInspectorView()

◆ DetachDOMDataContext()

◆ DetachDOMTriggers()

◆ DetachJSAPI()

◆ device_scale()

◆ display_id()

◆ download_listener()

◆ editor()

◆ editor_listener()

◆ EvaluateScript()

◆ FireKeyEvent()

◆ FireMouseEvent()

◆ FireScrollEvent()

◆ Focus()

◆ GetDOMDocument()

◆ GetJSContext()

◆ GoBack()

◆ GoForward()

◆ GoToHistoryOffset()

◆ HasFocus()

◆ HasInputFocus()

◆ height()

◆ is_accelerated()

◆ is_loading()

◆ is_settled()

◆ is_transparent()

◆ is_visible()

◆ JavaScriptVM()

◆ load_listener()

◆ LoadHTML()

◆ LoadURL()

◆ LockJSContext()

◆ max_render_fps()

◆ needs_paint()

◆ network_listener()

◆ preferred_color_scheme()

◆ Reload()

◆ render_target()

◆ Resize() [1/2]

◆ Resize() [2/2]

◆ set_compositor_debug_info_enabled()

◆ set_device_scale()

◆ set_display_id()

◆ set_download_listener()

◆ set_editor_listener()

◆ set_load_listener()

◆ set_max_render_fps()

◆ set_needs_paint()

◆ set_network_listener()

◆ set_preferred_color_scheme()

◆ set_view_listener()

◆ set_visible()

◆ SetDOMTriggersInjectionFilter()

◆ SetJSAPIInjectionFilter()

◆ Stop()

◆ surface()

◆ title()

◆ Unfocus()