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 by calling ulCreateView():

// Create a ULViewConfig with default values
ULViewConfig view_config = ulCreateViewConfig();
 
// Create a View, 500 by 500 pixels in size, using the default Session
ULView view = ulCreateView(renderer, 500, 500, view_config, NULL);
 
// Clean up the ULViewConfig
ulDestroyViewConfig(view_config);

Note: When using ulCreateApp(), the library will automatically create a View for you when you call ulWindowAddPanel() (see <AppCore/CAPI/CAPI_Layout.h>).

Callbacks

Each ulViewSet*Callback() function holds one callback. Setting a callback replaces the previous one, and a NULL callback removes it.

Ownership of user_data transfers to the View. destroy_user_data (may be NULL) is invoked exactly once when the callback is replaced or the ULView handle is destroyed (never while the callback itself is running). If view is NULL, nothing is set and destroy_user_data runs right away.

Each setter owns its user_data separately, so a pointer registered with a destroy hook on two setters is released twice. Share one context by passing it with a NULL destroy_user_data to all but one setter, or give each setter its own allocation.

Callbacks belong to the ULView handle you set them on, and each callback receives that handle. A View delivers each group of callbacks to one handle: the load events (below), the download callbacks, the network-request callback, the editing callbacks (editable state and composition), and all the others. Setting a callback on a second handle for the same View (eg, another ulPanelGetView() result) moves its group to that handle, which turns off the first handle's callbacks in the group. Set all of a View's callbacks through one handle. Destroying a handle turns off only its own callbacks.

Callbacks run on the Renderer's thread.

Load Events

A page load calls these callbacks in order:

Callback setter	When
ulViewSetBeginLoadingCallback()	The load starts
ulViewSetWindowObjectReadyCallback()	Before the page's scripts run
ulViewSetDOMReadyCallback()	The document is parsed
ulViewSetFinishLoadingCallback()	The load ends
ulViewSetPageSettledCallback()	Loading and layout have gone quiet

If the load fails, the fail-loading callback comes just before the finish-loading callback.

The window-object-ready and DOM-ready callbacks are called for every frame on the page (check is_main_frame). The begin, finish, and fail loading callbacks are called once per load for the frame that started it (usually the main frame).

Note: The window-object-ready and DOM-ready callbacks aren't called when a page is restored from the back-forward cache.

Functions
ULViewConfig	ulCreateViewConfig (void)
	Create view configuration with default values (see <Ultralight/View.h>).
void	ulDestroyViewConfig (ULViewConfig config)
	Destroy a view configuration created by ulCreateViewConfig().
void	ulViewConfigSetDisplayId (ULViewConfig config, unsigned int display_id)
	Set a user-generated id of the display (monitor, TV, or screen) that the View will be shown on.
void	ulViewConfigSetIsAccelerated (ULViewConfig config, bool is_accelerated)
	Set whether to render using the GPU renderer (accelerated) or the CPU renderer (unaccelerated).
void	ulViewConfigSetIsTransparent (ULViewConfig config, bool is_transparent)
	Set whether or not the View should support transparent backgrounds.
void	ulViewConfigSetBackgroundColor (ULViewConfig config, ULColor color)
	Set the base background color the page renders on before any page styling applies, the color visible while a page loads and wherever the page itself paints nothing.
void	ulViewConfigSetPreferredColorScheme (ULViewConfig config, ULColorScheme scheme)
	Set the color scheme the View reports to pages via the prefers-color-scheme CSS media feature.
void	ulViewConfigSetClipboardReadPolicy (ULViewConfig config, ULClipboardReadPolicy policy)
	Set which pages may read the clipboard from script, eg, a page's own Paste button calling document.execCommand('paste').
void	ulViewConfigSetInitialDeviceScale (ULViewConfig config, double initial_device_scale)
	Set the initial device scale, ie.
void	ulViewConfigSetInitialFocus (ULViewConfig config, bool is_focused)
	Set whether or not the View should initially have input focus.
void	ulViewConfigSetEnableImages (ULViewConfig config, bool enabled)
	Set whether images should be enabled (Default = True).
void	ulViewConfigSetEnableJavaScript (ULViewConfig config, bool enabled)
	Set whether JavaScript should be enabled (Default = True).
void	ulViewConfigSetMatchNativeEditingBehavior (ULViewConfig config, bool enabled)
	Set whether text editing should follow the host OS's native conventions instead of the library's cross-platform behavior (Default = False).
void	ulViewConfigSetFontFamilyStandard (ULViewConfig config, ULString font_name)
	Set the default font family, used for text that doesn't set one (Default = Times New Roman).
void	ulViewConfigSetFontFamilyFixed (ULViewConfig config, ULString font_name)
	Set the default monospace font family, eg, for pre and code (Default = Courier New).
void	ulViewConfigSetFontFamilySerif (ULViewConfig config, ULString font_name)
	Set the default font family for the CSS serif generic (Default = Times New Roman).
void	ulViewConfigSetFontFamilySansSerif (ULViewConfig config, ULString font_name)
	Set the default font family for the CSS sans-serif generic (Default = Arial).
void	ulViewConfigSetFontFamilyCursive (ULViewConfig config, ULString font_name)
	Set the default font family for the CSS cursive generic (Default = Comic Sans MS).
void	ulViewConfigSetFontFamilyFantasy (ULViewConfig config, ULString font_name)
	Set the default font family for the CSS fantasy generic (Default = Impact).
void	ulViewConfigSetFontFamilyPictograph (ULViewConfig config, ULString font_name)
	Set the default font family for the CSS -webkit-pictograph generic.
void	ulViewConfigSetFontSizeDefault (ULViewConfig config, unsigned int size)
	Set the default font size, in pixels (Default = 16).
void	ulViewConfigSetFontSizeFixed (ULViewConfig config, unsigned int size)
	Set the default font size for monospace text, eg, pre and code, in pixels (Default = 13).
void	ulViewConfigSetUserAgent (ULViewConfig config, ULString agent_string)
	Set user agent string (See <Ultralight/platform/Config.h> for the default).
void	ulViewConfigSetEnableCompositor (ULViewConfig config, bool enabled)
	Set whether or not compositing should be enabled.
void	ulViewConfigSetEnableCompositorDebugInfo (ULViewConfig config, bool enabled)
	Set whether or not to display compositor debug information.
void	ulViewConfigSetEnableCanvasFilters (ULViewConfig config, bool enabled)
	Set whether or not the HTML5 Canvas Filters API (CanvasRenderingContext2D.filter) is enabled.
void	ulViewConfigSetEnableHiddenTimerThrottling (ULViewConfig config, bool enabled)
	Set whether to throttle JavaScript timers (setTimeout / setInterval) while the View is hidden (Default = False).
void	ulViewConfigSetMaxRenderFps (ULViewConfig config, unsigned int fps)
	Set the maximum rate, in frames per second, at which the View advances its animations and repaints.
void	ulViewConfigSetJavaScriptCanOpenWindowsAutomatically (ULViewConfig config, bool enabled)
	Set whether or not a script can open a window with window.open() without a user gesture (Default = False).
void	ulViewConfigSetAllowUniversalAccessFromFileURLs (ULViewConfig config, bool enabled)
	Set whether or not pages loaded from file:/// URLs can access content from any origin (Default = True).
ULView	ulCreateView (ULRenderer renderer, unsigned int width, unsigned int height, ULViewConfig view_config, ULSession session)
	Create a View with certain size (in pixels).
void	ulDestroyView (ULView view)
	Destroy a View previously created with ulCreateView().
ULString	ulViewGetURL (ULView view)
	Get current URL.
ULString	ulViewGetTitle (ULView view)
	Get current title.
unsigned int	ulViewGetWidth (ULView view)
	Get the width, in pixels.
unsigned int	ulViewGetHeight (ULView view)
	Get the height, in pixels.
unsigned int	ulViewGetDisplayId (ULView view)
	Get the display id of the View.
void	ulViewSetDisplayId (ULView view, unsigned int display_id)
	Set the display id of the View.
double	ulViewGetDeviceScale (ULView view)
	Get the device scale, ie.
void	ulViewSetDeviceScale (ULView view, double scale)
	Set the device scale.
bool	ulViewIsAccelerated (ULView view)
	Whether or not the View is GPU-accelerated.
bool	ulViewIsTransparent (ULView view)
	Whether or not the View supports transparent backgrounds.
bool	ulViewIsLoading (ULView view)
	Check if the main frame of the page is currently loading.
bool	ulViewIsSettled (ULView view)
	Check whether the page has settled after loading.
ULRenderTarget	ulViewGetRenderTarget (ULView view)
	Get the RenderTarget for the View.
ULSurface	ulViewGetSurface (ULView view)
	Get the Surface for the View (native pixel buffer that the CPU renderer draws into).
void	ulViewLoadHTML (ULView view, ULString html_string)
	Load a raw string of HTML, the View will navigate to it as a new page.
void	ulViewLoadHTMLWithParams (ULView view, ULString html_string, ULString url, bool add_to_history)
	Load a raw string of HTML with additional options.
void	ulViewLoadURL (ULView view, ULString url_string)
	Load a URL, the View will navigate to it as a new page.
void	ulViewResize (ULView view, unsigned int width, unsigned int height)
	Resize view to a certain width and height (in pixels).
void	ulViewResizeWithScale (ULView view, unsigned int width, unsigned int height, double device_scale)
	Resize view and apply a new device scale in the same pass.
JSContextRef	ulViewLockJSContext (ULView view)
	Acquire the page's JSContext for use with JavaScriptCore API.
void	ulViewUnlockJSContext (ULView view)
	Unlock the page's JSContext after a previous call to ulViewLockJSContext().
ULString	ulViewEvaluateScript (ULView view, ULString js_string, ULString *exception)
	Evaluate a string of JavaScript and return result.
JSContextRef	ulViewLockJSContextWithFrame (ULView view, ULString frame)
	Acquire the JSContext of a specific frame for use with JavaScriptCore API.
void	ulViewUnlockJSContextWithFrame (ULView view, ULString frame)
	Unlock the JSContext of a specific frame after a previous call to ulViewLockJSContextWithFrame().
ULJSContext	ulViewGetJSContext (ULView view)
	Get a ULJS handle to the main frame's JavaScript context.
void *	ulViewJavaScriptVMWithFrame (ULView view, ULString frame)
	Get a handle to the internal JavaScriptCore VM for a specific frame.
ULString	ulViewEvaluateScriptWithFrame (ULView view, ULString js_string, ULString *exception, ULString frame)
	Evaluate a string of JavaScript in a specific frame and return the result.
bool	ulViewCanGoBack (ULView view)
	Whether or not the View can navigate back in history.
bool	ulViewCanGoForward (ULView view)
	Whether or not the View can navigate forward in history.
void	ulViewGoBack (ULView view)
	Navigate backwards in history.
void	ulViewGoForward (ULView view)
	Navigate forwards in history.
void	ulViewGoToHistoryOffset (ULView view, int offset)
	Navigate to an arbitrary offset in history.
void	ulViewReload (ULView view)
	Reload current page.
void	ulViewStop (ULView view)
	Stop all page loads.
void	ulViewFocus (ULView view)
	Give focus to the View.
void	ulViewUnfocus (ULView view)
	Remove focus from the View.
bool	ulViewHasFocus (ULView view)
	Whether or not the View has focus.
bool	ulViewHasInputFocus (ULView view)
	Whether or not the View has an input element with visible keyboard focus (indicated by a blinking caret).
void	ulViewFireKeyEvent (ULView view, ULKeyEvent key_event)
	Fire a keyboard event.
void	ulViewFireMouseEvent (ULView view, ULMouseEvent mouse_event)
	Fire a mouse event.
void	ulViewFireScrollEvent (ULView view, ULScrollEvent scroll_event)
	Fire a scroll event.
void	ulViewSetChangeTitleCallback (ULView view, ULChangeTitleCallback callback, void *user_data, ULUserDataDestroyCallback destroy_user_data)
	Set callback for when the page title changes.
void	ulViewSetChangeURLCallback (ULView view, ULChangeURLCallback callback, void *user_data, ULUserDataDestroyCallback destroy_user_data)
	Set callback for when the main frame loads a new page.
void	ulViewSetChangeTooltipCallback (ULView view, ULChangeTooltipCallback callback, void *user_data, ULUserDataDestroyCallback destroy_user_data)
	Set callback for when the tooltip under the mouse changes (the text is empty when there's no tooltip).
void	ulViewSetChangeCursorCallback (ULView view, ULChangeCursorCallback callback, void *user_data, ULUserDataDestroyCallback destroy_user_data)
	Set callback for when the mouse cursor changes.
void	ulViewSetChangeEditableStateCallback (ULView view, ULChangeEditableStateCallback callback, void *user_data, ULUserDataDestroyCallback destroy_user_data)
	Set callback for when the editable state changes.
void	ulViewSetUpdateCompositionCallback (ULView view, ULUpdateCompositionCallback callback, void *user_data, ULUserDataDestroyCallback destroy_user_data)
	Set callback for after every change to the active composition.
void	ulViewSetDiscardCompositionCallback (ULView view, ULDiscardCompositionCallback callback, void *user_data, ULUserDataDestroyCallback destroy_user_data)
	Set callback for when the page ends the active composition on its own (eg, on navigation or when the selection moves away from it).
void	ulViewSetAddConsoleMessageCallback (ULView view, ULAddConsoleMessageCallback callback, void *user_data, ULUserDataDestroyCallback destroy_user_data)
	Set callback for when the page adds a message to the console (useful for errors and debugging).
void	ulViewSetCreateChildViewCallback (ULView view, ULCreateChildViewCallback callback, void *user_data, ULUserDataDestroyCallback destroy_user_data)
	Set callback for when the page wants to open a new window (a link with target="_blank" or a call to window.open()).
void	ulViewSetCreateInspectorViewCallback (ULView view, ULCreateInspectorViewCallback callback, void *user_data, ULUserDataDestroyCallback destroy_user_data)
	Set callback for when the inspector needs a View to display in (after ulViewCreateLocalInspectorView() or when a remote inspector connects).
void	ulViewSetBeginLoadingCallback (ULView view, ULBeginLoadingCallback callback, void *user_data, ULUserDataDestroyCallback destroy_user_data)
	Set callback for when a load starts (see "Load Events" in the file description).
void	ulViewSetFinishLoadingCallback (ULView view, ULFinishLoadingCallback callback, void *user_data, ULUserDataDestroyCallback destroy_user_data)
	Set callback for when a load ends (whether or not it succeeded).
void	ulViewSetFailLoadingCallback (ULView view, ULFailLoadingCallback callback, void *user_data, ULUserDataDestroyCallback destroy_user_data)
	Set callback for when a load fails (just before the finish-loading callback).
void	ulViewSetWindowObjectReadyCallback (ULView view, ULWindowObjectReadyCallback callback, void *user_data, ULUserDataDestroyCallback destroy_user_data)
	Set callback for before a frame's scripts run.
void	ulViewSetDOMReadyCallback (ULView view, ULDOMReadyCallback callback, void *user_data, ULUserDataDestroyCallback destroy_user_data)
	Set callback for when a frame's document has been parsed and the DOM is ready.
void	ulViewSetUpdateHistoryCallback (ULView view, ULUpdateHistoryCallback callback, void *user_data, ULUserDataDestroyCallback destroy_user_data)
	Set callback for when the main frame's back-forward history changes.
void	ulViewSetPageSettledCallback (ULView view, ULPageSettledCallback callback, void *user_data, ULUserDataDestroyCallback destroy_user_data)
	Set callback for when the page has settled and is ready to capture or display (resources have loaded, initial scripts have run, and layout is stable).
void	ulViewSetNeedsPaint (ULView view, bool needs_paint)
	Set whether or not a view should be repainted during the next call to ulRender().
bool	ulViewGetNeedsPaint (ULView view)
	Whether or not a view should be painted during the next call to ulRender().
void	ulViewSetVisible (ULView view, bool visible)
	Set whether or not this View is visible.
bool	ulViewIsVisible (ULView view)
	Whether or not this View is visible.
unsigned int	ulViewGetMaxRenderFps (ULView view)
	Get the frame-rate cap (in FPS) set for the View, or 0 if none is set.
void	ulViewSetMaxRenderFps (ULView view, unsigned int fps)
	Set the maximum rate, in frames per second, at which the View advances its animations and repaints.
void	ulViewSetPreferredColorScheme (ULView view, ULColorScheme scheme)
	Set the color scheme this View reports to pages via the prefers-color-scheme CSS media feature.
ULColorScheme	ulViewGetPreferredColorScheme (ULView view)
	Get the color scheme this View reports to pages.
void	ulViewCreateLocalInspectorView (ULView view)
	Create an Inspector View to inspect / debug this View locally.
void	ulViewSetCompositorDebugInfoEnabled (ULView view, bool enabled)
	Set whether or not to display compositor debug information.
bool	ulViewGetCompositorDebugInfoEnabled (ULView view)
	Whether or not compositor debug information is enabled.
void	ulViewSetRequestCloseCallback (ULView view, ULRequestCloseCallback callback, void *user_data, ULUserDataDestroyCallback destroy_user_data)
	Set callback for when the page asks to close (window.close() in a window that script opened, or in one with a single page in its history).
void	ulViewSetDownloadNextIdCallback (ULView view, ULDownloadNextIdCallback callback, void *user_data, ULUserDataDestroyCallback destroy_user_data)
	Set callback for generating unique download ids.
void	ulViewSetDownloadRequestCallback (ULView view, ULDownloadRequestCallback callback, void *user_data, ULUserDataDestroyCallback destroy_user_data)
	Set callback for when the View requests a download.
void	ulViewSetDownloadBeginCallback (ULView view, ULDownloadBeginCallback callback, void *user_data, ULUserDataDestroyCallback destroy_user_data)
	Set callback for when a download begins.
void	ulViewSetDownloadReceiveDataCallback (ULView view, ULDownloadReceiveDataCallback callback, void *user_data, ULUserDataDestroyCallback destroy_user_data)
	Set callback for when download data is received.
void	ulViewSetDownloadFinishCallback (ULView view, ULDownloadFinishCallback callback, void *user_data, ULUserDataDestroyCallback destroy_user_data)
	Set callback for when a download finishes.
void	ulViewSetDownloadFailCallback (ULView view, ULDownloadFailCallback callback, void *user_data, ULUserDataDestroyCallback destroy_user_data)
	Set callback for when a download fails.
void	ulViewCancelDownload (ULView view, unsigned int id)
	Cancel an active download.
void	ulViewSetNetworkRequestCallback (ULView view, ULNetworkRequestCallback callback, void *user_data, ULUserDataDestroyCallback destroy_user_data)
	Set callback for when the View is about to begin a network request.

Typedefs
typedef void(*)	ULChangeTitleCallback(void *user_data, ULView caller, ULString title)
typedef void(*)	ULChangeURLCallback(void *user_data, ULView caller, ULString url)
typedef void(*)	ULChangeTooltipCallback(void *user_data, ULView caller, ULString tooltip)
typedef void(*)	ULChangeCursorCallback(void *user_data, ULView caller, ULCursor cursor)
typedef void(*)	ULChangeEditableStateCallback(void *user_data, ULView caller, ULEditableState state)
typedef void(*)	ULUpdateCompositionCallback(void *user_data, ULView caller)
typedef void(*)	ULDiscardCompositionCallback(void *user_data, ULView caller)
typedef void(*)	ULAddConsoleMessageCallback(void *user_data, ULView caller, ULMessageSource source, ULMessageLevel level, ULString message, unsigned int line_number, unsigned int column_number, ULString source_id)
typedef ULView(*)	ULCreateChildViewCallback(void *user_data, ULView caller, ULString opener_url, ULString target_url, bool is_popup, ULIntRect popup_rect)
typedef ULView(*)	ULCreateInspectorViewCallback(void *user_data, ULView caller, bool is_local, ULString inspected_url)
typedef void(*)	ULBeginLoadingCallback(void *user_data, ULView caller, unsigned long long frame_id, bool is_main_frame, ULString url)
typedef void(*)	ULFinishLoadingCallback(void *user_data, ULView caller, unsigned long long frame_id, bool is_main_frame, ULString url)
typedef void(*)	ULFailLoadingCallback(void *user_data, ULView caller, unsigned long long frame_id, bool is_main_frame, ULString url, ULString description, ULString error_domain, int error_code)
typedef void(*)	ULWindowObjectReadyCallback(void *user_data, ULView caller, unsigned long long frame_id, bool is_main_frame, ULString url)
typedef void(*)	ULDOMReadyCallback(void *user_data, ULView caller, unsigned long long frame_id, bool is_main_frame, ULString url)
typedef void(*)	ULUpdateHistoryCallback(void *user_data, ULView caller)
typedef void(*)	ULPageSettledCallback(void *user_data, ULView caller, ULString url)
typedef void(*)	ULRequestCloseCallback(void *user_data, ULView caller)
typedef unsigned int(*)	ULDownloadNextIdCallback(void *user_data, ULView caller)
	Callback for when the View needs an ID for a new download.
typedef bool(*)	ULDownloadRequestCallback(void *user_data, ULView caller, unsigned int id, ULString url)
	Callback for when the page wants to download a file.
typedef void(*)	ULDownloadBeginCallback(void *user_data, ULView caller, unsigned int id, ULString url, ULString filename, long long expected_content_length)
	Callback for when a download starts.
typedef void(*)	ULDownloadReceiveDataCallback(void *user_data, ULView caller, unsigned int id, ULBuffer data)
	Callback for when a download receives data (usually several times per download).
typedef void(*)	ULDownloadFinishCallback(void *user_data, ULView caller, unsigned int id)
	Callback for when a download finishes.
typedef void(*)	ULDownloadFailCallback(void *user_data, ULView caller, unsigned int id)
	Callback for when a download fails.
typedef bool(*)	ULNetworkRequestCallback(void *user_data, ULView caller, ULString url)
	Callback for before the View sends a network request.

Enumerations
enum	ULMessageSource { kMessageSource_XML = 0 , kMessageSource_JS , kMessageSource_Network , kMessageSource_ConsoleAPI , kMessageSource_Storage , kMessageSource_AppCache , kMessageSource_Rendering , kMessageSource_CSS , kMessageSource_Security , kMessageSource_ContentBlocker , kMessageSource_Media , kMessageSource_MediaSource , kMessageSource_WebRTC , kMessageSource_ITPDebug , kMessageSource_PrivateClickMeasurement , kMessageSource_PaymentRequest , kMessageSource_Other , kMessageSource_NativeAPI }
	The source of a console message. More...
enum	ULMessageLevel { kMessageLevel_Log = 0 , kMessageLevel_Warning , kMessageLevel_Error , kMessageLevel_Debug , kMessageLevel_Info }
	The severity level of a console message. More...
enum	ULCursor { kCursor_Pointer = 0 , kCursor_Cross , kCursor_Hand , kCursor_IBeam , kCursor_Wait , kCursor_Help , kCursor_EastResize , kCursor_NorthResize , kCursor_NorthEastResize , kCursor_NorthWestResize , kCursor_SouthResize , kCursor_SouthEastResize , kCursor_SouthWestResize , kCursor_WestResize , kCursor_NorthSouthResize , kCursor_EastWestResize , kCursor_NorthEastSouthWestResize , kCursor_NorthWestSouthEastResize , kCursor_ColumnResize , kCursor_RowResize , kCursor_MiddlePanning , kCursor_EastPanning , kCursor_NorthPanning , kCursor_NorthEastPanning , kCursor_NorthWestPanning , kCursor_SouthPanning , kCursor_SouthEastPanning , kCursor_SouthWestPanning , kCursor_WestPanning , kCursor_Move , kCursor_VerticalText , kCursor_Cell , kCursor_ContextMenu , kCursor_Alias , kCursor_Progress , kCursor_NoDrop , kCursor_Copy , kCursor_None , kCursor_NotAllowed , kCursor_ZoomIn , kCursor_ZoomOut , kCursor_Grab , kCursor_Grabbing , kCursor_Custom }
	Cursor types. More...

Function Documentation

◆ ulCreateView()

ULView ulCreateView	(	ULRenderer	renderer,
		unsigned int	width,
		unsigned int	height,
		ULViewConfig	view_config,
		ULSession	session )

Create a View with certain size (in pixels).

Parameters

renderer	The active renderer instance.
width	The initial width, in pixels.
height	The initial height, in pixels.
view_config	Configuration details for the View. Pass NULL to use the default configuration.
session	The session to store local data in. Pass NULL to use the default session.

Returns: Returns a new ULView instance. You must call ulDestroyView() when finished.

◆ ulCreateViewConfig()

ULViewConfig ulCreateViewConfig ( void )

Create view configuration with default values (see <Ultralight/View.h>).

Returns: Returns a new ULViewConfig instance. You must call ulDestroyViewConfig() when finished.

◆ ulDestroyView()

void ulDestroyView ( ULView view )

Destroy a View previously created with ulCreateView().

Parameters

view	The View to destroy (can be NULL).

◆ ulDestroyViewConfig()

void ulDestroyViewConfig ( ULViewConfig config )

Destroy a view configuration created by ulCreateViewConfig().

Parameters

config The view configuration to destroy (can be NULL).

◆ ulViewCancelDownload()

void ulViewCancelDownload	(	ULView	view,
		unsigned int	id )

Cancel an active download.

No more data arrives for the download, and the callback set with ulViewSetDownloadFailCallback() is called for it during a later ulUpdate().

Parameters

view	The View.
id	The download id to cancel.

◆ ulViewCanGoBack()

bool ulViewCanGoBack ( ULView view )

Whether or not the View can navigate back in history.

◆ ulViewCanGoForward()

bool ulViewCanGoForward ( ULView view )

Whether or not the View can navigate forward in history.

◆ ulViewConfigSetAllowUniversalAccessFromFileURLs()

void ulViewConfigSetAllowUniversalAccessFromFileURLs	(	ULViewConfig	config,
		bool	enabled )

Set whether or not pages loaded from file:/// URLs can access content from any origin (Default = True).

When true, a file:/// page can read other frames' documents and make requests to any origin without cross-origin checks. Set this to false to give file:/// pages the same cross-origin rules as web pages (they stay same-origin with other file:/// pages).

◆ ulViewConfigSetBackgroundColor()

void ulViewConfigSetBackgroundColor	(	ULViewConfig	config,
		ULColor	color )

Set the base background color the page renders on before any page styling applies, the color visible while a page loads and wherever the page itself paints nothing.

(Default = unset, meaning opaque white)

Dark applications set a dark base so pages never flash white during load.

Transparent Views keep a fully transparent base regardless of this value. On opaque Views a translucent color is composited over white, so the View itself stays opaque.

◆ ulViewConfigSetClipboardReadPolicy()

void ulViewConfigSetClipboardReadPolicy	(	ULViewConfig	config,
		ULClipboardReadPolicy	policy )

Set which pages may read the clipboard from script, eg, a page's own Paste button calling document.execCommand('paste').

(Default = kClipboardReadPolicy_AllowForAppContent)

The library only considers requests made during a user gesture (a click or key press); script running outside a gesture is always refused. Pastes the user performs directly (Ctrl+V, or ulEditorExecute with kEditorCommand_Paste) are never affected by this policy.

kClipboardReadPolicy_AllowForAppContent (the default) grants requests from your application's own content (local file:/// pages and pages loaded from application-supplied data, eg, ulViewLoadHTML()) and refuses them from other pages. kClipboardReadPolicy_Allow grants requests from any page; kClipboardReadPolicy_Deny refuses them all.

An out-of-range value logs a warning and leaves the config unchanged.

◆ ulViewConfigSetDisplayId()

void ulViewConfigSetDisplayId	(	ULViewConfig	config,
		unsigned int	display_id )

Set a user-generated id of the display (monitor, TV, or screen) that the View will be shown on.

Animations are driven based on the physical refresh rate of the display. Multiple Views can share the same display.

Note: This is automatically managed for you when ulCreateApp() is used.

See also: ulRefreshDisplay()

◆ ulViewConfigSetEnableCanvasFilters()

void ulViewConfigSetEnableCanvasFilters	(	ULViewConfig	config,
		bool	enabled )

Set whether or not the HTML5 Canvas Filters API (CanvasRenderingContext2D.filter) is enabled.

(Default = True)

◆ ulViewConfigSetEnableCompositor()

void ulViewConfigSetEnableCompositor	(	ULViewConfig	config,
		bool	enabled )

Set whether or not compositing should be enabled.

(Default = True)

When enabled, certain content (eg, 3D transforms, will-change, animated transforms or opacity, and video) paints into separate composited layers, making transform and opacity changes cheap to animate.

◆ ulViewConfigSetEnableCompositorDebugInfo()

void ulViewConfigSetEnableCompositorDebugInfo	(	ULViewConfig	config,
		bool	enabled )

Set whether or not to display compositor debug information.

(Default = False)

Note: Only valid when the compositor is enabled.

◆ ulViewConfigSetEnableHiddenTimerThrottling()

void ulViewConfigSetEnableHiddenTimerThrottling	(	ULViewConfig	config,
		bool	enabled )

Set whether to throttle JavaScript timers (setTimeout / setInterval) while the View is hidden (Default = False).

When enabled, repeating timers in a hidden View are aligned to roughly one-second boundaries (about 1 Hz) to reduce CPU usage for off-screen Views. They return to their normal rate once the View is shown again.

Note: This does not affect requestAnimationFrame, which is always suspended while the View is hidden.

See also: ulViewSetVisible()

◆ ulViewConfigSetEnableImages()

void ulViewConfigSetEnableImages	(	ULViewConfig	config,
		bool	enabled )

Set whether images should be enabled (Default = True).

◆ ulViewConfigSetEnableJavaScript()

void ulViewConfigSetEnableJavaScript	(	ULViewConfig	config,
		bool	enabled )

Set whether JavaScript should be enabled (Default = True).

◆ ulViewConfigSetFontFamilyCursive()

void ulViewConfigSetFontFamilyCursive	(	ULViewConfig	config,
		ULString	font_name )

Set the default font family for the CSS cursive generic (Default = Comic Sans MS).

◆ ulViewConfigSetFontFamilyFantasy()

void ulViewConfigSetFontFamilyFantasy	(	ULViewConfig	config,
		ULString	font_name )

Set the default font family for the CSS fantasy generic (Default = Impact).

◆ ulViewConfigSetFontFamilyFixed()

void ulViewConfigSetFontFamilyFixed	(	ULViewConfig	config,
		ULString	font_name )

Set the default monospace font family, eg, for pre and code (Default = Courier New).

◆ ulViewConfigSetFontFamilyPictograph()

void ulViewConfigSetFontFamilyPictograph	(	ULViewConfig	config,
		ULString	font_name )

Set the default font family for the CSS -webkit-pictograph generic.

Pass an empty string to use the standard font family (Default = empty).

◆ ulViewConfigSetFontFamilySansSerif()

void ulViewConfigSetFontFamilySansSerif	(	ULViewConfig	config,
		ULString	font_name )

Set the default font family for the CSS sans-serif generic (Default = Arial).

◆ ulViewConfigSetFontFamilySerif()

void ulViewConfigSetFontFamilySerif	(	ULViewConfig	config,
		ULString	font_name )

Set the default font family for the CSS serif generic (Default = Times New Roman).

◆ ulViewConfigSetFontFamilyStandard()

void ulViewConfigSetFontFamilyStandard	(	ULViewConfig	config,
		ULString	font_name )

Set the default font family, used for text that doesn't set one (Default = Times New Roman).

◆ ulViewConfigSetFontSizeDefault()

void ulViewConfigSetFontSizeDefault	(	ULViewConfig	config,
		unsigned int	size )

Set the default font size, in pixels (Default = 16).

◆ ulViewConfigSetFontSizeFixed()

void ulViewConfigSetFontSizeFixed	(	ULViewConfig	config,
		unsigned int	size )

Set the default font size for monospace text, eg, pre and code, in pixels (Default = 13).

◆ ulViewConfigSetInitialDeviceScale()

void ulViewConfigSetInitialDeviceScale	(	ULViewConfig	config,
		double	initial_device_scale )

Set the initial device scale, ie.

the amount to scale page units to screen pixels. This should be set to the scaling factor of the device that the View is displayed on. (Default = 1.0)

Note: 1.0 is equal to 100% zoom (no scaling), 2.0 is equal to 200% zoom (2x scaling)

◆ ulViewConfigSetInitialFocus()

void ulViewConfigSetInitialFocus	(	ULViewConfig	config,
		bool	is_focused )

Set whether or not the View should initially have input focus.

(Default = True)

◆ ulViewConfigSetIsAccelerated()

void ulViewConfigSetIsAccelerated	(	ULViewConfig	config,
		bool	is_accelerated )

Set whether to render using the GPU renderer (accelerated) or the CPU renderer (unaccelerated).

This option is only valid if you're managing the Renderer yourself (eg, you've previously called ulCreateRenderer() instead of ulCreateApp()).

When true, the View will be rendered to an offscreen GPU texture using the GPU driver set in ulPlatformSetGPUDriver(). You can fetch details for the texture via ulViewGetRenderTarget().

When false (the default), the View will be rendered to an offscreen pixel buffer using the multithreaded CPU renderer. This pixel buffer can optionally be provided by the user– for more info see ulViewGetSurface().

Note: You must set a GPU driver before creating an accelerated View (the process exits with an error otherwise).

◆ ulViewConfigSetIsTransparent()

void ulViewConfigSetIsTransparent	(	ULViewConfig	config,
		bool	is_transparent )

Set whether or not the View should support transparent backgrounds.

(Default = False)

The page needs a transparent background too:

html, body { background: transparent; }

◆ ulViewConfigSetJavaScriptCanOpenWindowsAutomatically()

void ulViewConfigSetJavaScriptCanOpenWindowsAutomatically	(	ULViewConfig	config,
		bool	enabled )

Set whether or not a script can open a window with window.open() without a user gesture (Default = False).

When false, Ultralight behaves like a typical browser: a window.open() call succeeds only while the page is handling a user gesture, such as from a click handler. A call made on its own (on page load, or from a timer) is blocked as a popup. Set this to true to let scripts call window.open() at any time. The same gesture rule applies to a form submission that targets a new window.

Note: Even when this is allowed, a window is only created if your create-child-view callback returns one; return NULL there to block it.

See also: ulViewSetCreateChildViewCallback()

◆ ulViewConfigSetMatchNativeEditingBehavior()

void ulViewConfigSetMatchNativeEditingBehavior	(	ULViewConfig	config,
		bool	enabled )

Set whether text editing should follow the host OS's native conventions instead of the library's cross-platform behavior (Default = False).

When false, text selection and editing behave identically on every platform (a directionless selection is promoted to forward, the convention Windows browsers use). Set this to true for desktop applications that should feel native to each platform.

Note: ulCreateApp() turns this on for the Views it creates for a panel added without a ViewConfig (see ulSettingsSetMatchNativeEditingBehavior() in <AppCore/CAPI.h>). A config you pass yourself keeps this value.

◆ ulViewConfigSetMaxRenderFps()

void ulViewConfigSetMaxRenderFps	(	ULViewConfig	config,
		unsigned int	fps )

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

(Default = 0, unthrottled)

This caps the View's whole frame loop (requestAnimationFrame, CSS and Web animations, smooth scrolling, and painting). A value of 0 leaves the View unthrottled, advancing at the display's refresh rate.

Note: The View is always capped at your edition's maximum frame rate.

◆ ulViewConfigSetPreferredColorScheme()

void ulViewConfigSetPreferredColorScheme	(	ULViewConfig	config,
		ULColorScheme	scheme )

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

(Default = kColorScheme_Auto)

kColorScheme_Auto follows the system scheme set via ulRendererSetSystemColorScheme() (Light until it is fed a different value). Light or Dark pins the scheme for this View.

An out-of-range value logs a warning and leaves the config unchanged.

Note: The scheme is only a signal to the page. Pages style themselves via media queries, and built-in UI (form controls, scrollbars, the default white canvas) keeps its light appearance under a dark scheme.

See also: ulViewSetPreferredColorScheme()

◆ ulViewConfigSetUserAgent()

void ulViewConfigSetUserAgent	(	ULViewConfig	config,
		ULString	agent_string )

Set user agent string (See <Ultralight/platform/Config.h> for the default).

◆ ulViewCreateLocalInspectorView()

void ulViewCreateLocalInspectorView ( ULView view )

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 ulViewSetCreateInspectorViewCallback() so that the library has a View to display the inspector in. This function will call the callback only if an inspector view is not currently active.

◆ ulViewEvaluateScript()

ULString ulViewEvaluateScript	(	ULView	view,
		ULString	js_string,
		ULString *	exception )

Evaluate a string of JavaScript and return result.

Parameters

view	The View.
js_string	The string of JavaScript to evaluate.
exception	The address of a ULString that receives the exception message if the script throws, or an empty string if it doesn't. Pass NULL to ignore this. Don't destroy the exception string returned, it's owned by the View.

Note: Don't destroy the returned string, it's owned by the View. This value is reset with every call– if you want to retain it you should copy the result to a new string via ulCreateStringFromCopy().

Note: The result is converted to a string (eg, undefined becomes "undefined"), or is empty if the page can't run scripts.

ULString script = ulCreateString("1 + 1");
ULString exception;
ULString result = ulViewEvaluateScript(view, script, &exception);
/* Use the result ("2") and exception description (if any) here. */
ulDestroyString(script);

◆ ulViewEvaluateScriptWithFrame()

ULString ulViewEvaluateScriptWithFrame	(	ULView	view,
		ULString	js_string,
		ULString *	exception,
		ULString	frame )

Evaluate a string of JavaScript in a specific frame and return the result.

Parameters

view	The View.
js_string	The string of JavaScript to evaluate.
exception	The address of a ULString that receives the exception message if the script throws, or an empty string if it doesn't. Pass NULL to ignore this. Don't destroy the exception string returned, it's owned by the View.
frame	The name of the frame to evaluate the script in. Pass an empty string 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. Don't destroy the returned string, it's owned by the View. This value is reset with every call– if you want to retain it you should copy it via ulCreateStringFromCopy().

◆ ulViewFireKeyEvent()

void ulViewFireKeyEvent	(	ULView	view,
		ULKeyEvent	key_event )

Fire a keyboard event.

Parameters

view	The View.
key_event	The key event.

Note: kKeyEventType_Char events insert text into input fields, and so does a legacy kKeyEventType_KeyDown that carries text. kKeyEventType_RawKeyDown never inserts text.

◆ ulViewFireMouseEvent()

void ulViewFireMouseEvent	(	ULView	view,
		ULMouseEvent	mouse_event )

Fire a mouse event.

Parameters

view	The View.
mouse_event	The mouse event.

◆ ulViewFireScrollEvent()

void ulViewFireScrollEvent	(	ULView	view,
		ULScrollEvent	scroll_event )

Fire a scroll event.

Parameters

view	The View.
scroll_event	The scroll event.

◆ ulViewFocus()

void ulViewFocus ( ULView view )

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

◆ ulViewGetCompositorDebugInfoEnabled()

bool ulViewGetCompositorDebugInfoEnabled ( ULView view )

Whether or not compositor debug information is enabled.

◆ ulViewGetDeviceScale()

double ulViewGetDeviceScale ( ULView view )

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.

◆ ulViewGetDisplayId()

unsigned int ulViewGetDisplayId ( ULView view )

Get the display id of the View.

◆ ulViewGetHeight()

unsigned int ulViewGetHeight ( ULView view )

Get the height, in pixels.

◆ ulViewGetJSContext()

ULJSContext ulViewGetJSContext ( ULView view )

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

Unlike ulViewLockJSContext(), 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>.

Returns: Returns a new ULJSContext handle for the current page, or NULL if the main frame can't run scripts (eg, when ulViewConfigSetEnableJavaScript() disabled JavaScript, 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. The callbacks set via ulViewSetWindowObjectReadyCallback() and ulViewSetDOMReadyCallback() are good acquisition points.

◆ ulViewGetMaxRenderFps()

unsigned int ulViewGetMaxRenderFps ( ULView view )

Get the frame-rate cap (in FPS) set for the View, or 0 if none is set.

◆ ulViewGetNeedsPaint()

bool ulViewGetNeedsPaint ( ULView view )

Whether or not a view should be painted during the next call to ulRender().

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 its frame-rate cap holds back its next frame.

When this returns true, the next call to ulRender() repaints the view. The resulting frame may still be visually identical to the previous frame.

Note: Continue calling ulRefreshDisplay() on every display refresh regardless of this flag. A View whose only pending work is animation callbacks or CSS animations repaints only after that call, and reports ulViewGetNeedsPaint() as true again from it.

◆ ulViewGetPreferredColorScheme()

ULColorScheme ulViewGetPreferredColorScheme ( ULView view )

Get the color scheme this View reports to pages.

◆ ulViewGetRenderTarget()

ULRenderTarget ulViewGetRenderTarget ( ULView view )

Get the RenderTarget for the View.

Note

Only valid if this View is GPU accelerated.

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

◆ ulViewGetSurface()

ULSurface ulViewGetSurface ( ULView view )

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

Note: This operation is only valid if you're managing the Renderer yourself (eg, you've previously called ulCreateRenderer() instead of ulCreateApp()).

This returns NULL if the View uses the GPU renderer.

The default Surface is BitmapSurface, but you can provide your own Surface implementation with ulPlatformSetSurfaceDefinition().

When using the default Surface, you can retrieve the underlying bitmap by casting ULSurface to ULBitmapSurface and calling ulBitmapSurfaceGetBitmap().

◆ ulViewGetTitle()

ULString ulViewGetTitle ( ULView view )

Get current title.

Note: Don't destroy the returned string, it is owned by the View. This value is reset with every call– if you want to retain it you should copy it via ulCreateStringFromCopy().

◆ ulViewGetURL()

ULString ulViewGetURL ( ULView view )

Get current URL.

Note: Don't destroy the returned string, it is owned by the View. This value is reset with every call– if you want to retain it you should copy it via ulCreateStringFromCopy().

◆ ulViewGetWidth()

unsigned int ulViewGetWidth ( ULView view )

Get the width, in pixels.

◆ ulViewGoBack()

void ulViewGoBack ( ULView view )

Navigate backwards in history.

◆ ulViewGoForward()

void ulViewGoForward ( ULView view )

Navigate forwards in history.

◆ ulViewGoToHistoryOffset()

void ulViewGoToHistoryOffset	(	ULView	view,
		int	offset )

Navigate to an arbitrary offset in history.

Parameters

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

◆ ulViewHasFocus()

bool ulViewHasFocus ( ULView view )

Whether or not the View has focus.

◆ ulViewHasInputFocus()

bool ulViewHasInputFocus ( ULView view )

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

◆ ulViewIsAccelerated()

bool ulViewIsAccelerated ( ULView view )

Whether or not the View is GPU-accelerated.

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

◆ ulViewIsLoading()

bool ulViewIsLoading ( ULView view )

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

◆ ulViewIsSettled()

bool ulViewIsSettled ( ULView view )

Check whether the page has settled after loading.

This is the queryable form of the page-settled callback. It flips true when that callback fires and resets to false on each new navigation.

Returns: Returns true once the page's network and layout activity have gone idle following the main frame's onload event, and false otherwise.

See also: ulViewSetPageSettledCallback()

◆ ulViewIsTransparent()

bool ulViewIsTransparent ( ULView view )

Whether or not the View supports transparent backgrounds.

◆ ulViewIsVisible()

bool ulViewIsVisible ( ULView view )

Whether or not this View is visible.

◆ ulViewJavaScriptVMWithFrame()

void * ulViewJavaScriptVMWithFrame	(	ULView	view,
		ULString	frame )

Get a handle to the internal JavaScriptCore VM for a specific frame.

Parameters

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

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

◆ ulViewLoadHTML()

void ulViewLoadHTML	(	ULView	view,
		ULString	html_string )

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

◆ ulViewLoadHTMLWithParams()

void ulViewLoadHTMLWithParams	(	ULView	view,
		ULString	html_string,
		ULString	url,
		bool	add_to_history )

Load a raw string of HTML with additional options.

Parameters

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

◆ ulViewLoadURL()

void ulViewLoadURL	(	ULView	view,
		ULString	url_string )

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

Parameters

view	The View.
url_string	The URL to load.

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

◆ ulViewLockJSContext()

JSContextRef ulViewLockJSContext ( ULView view )

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

Note: This locks the JavaScript VM for the current thread. You should call ulViewUnlockJSContext() when you're done so other threads can use JavaScript.

Note: The lock is recursive, it's okay to call this multiple times as long as you call ulViewUnlockJSContext() the same number of times.

◆ ulViewLockJSContextWithFrame()

JSContextRef ulViewLockJSContextWithFrame	(	ULView	view,
		ULString	frame )

Acquire the JSContext of a specific frame for use with JavaScriptCore API.

Parameters

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

Returns: Returns the JSContextRef for the frame, or NULL if the frame doesn't exist or can't run scripts.

Note: This locks the JavaScript VM for the current thread. You should call ulViewUnlockJSContextWithFrame() with the same frame name when you're done so other threads can use JavaScript.

Note: The lock is recursive, it's okay to call this multiple times as long as you call ulViewUnlockJSContextWithFrame() the same number of times.

◆ ulViewReload()

void ulViewReload ( ULView view )

Reload current page.

◆ ulViewResize()

void ulViewResize	(	ULView	view,
		unsigned int	width,
		unsigned int	height )

Resize view to a certain width and height (in pixels).

◆ ulViewResizeWithScale()

void ulViewResizeWithScale	(	ULView	view,
		unsigned int	width,
		unsigned int	height,
		double	device_scale )

Resize view and apply a new device scale in the same pass.

Prefer this over separate ulViewSetDeviceScale() and ulViewResize() 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

view	The View.
width	The new width, in pixels.
height	The new height, in pixels.
device_scale	The new device scale (see ulViewSetDeviceScale()).

See also: ulViewResize()

◆ ulViewSetAddConsoleMessageCallback()

void ulViewSetAddConsoleMessageCallback	(	ULView	view,
		ULAddConsoleMessageCallback	callback,
		void *	user_data,
		ULUserDataDestroyCallback	destroy_user_data )

Set callback for when the page adds a message to the console (useful for errors and debugging).

◆ ulViewSetBeginLoadingCallback()

void ulViewSetBeginLoadingCallback	(	ULView	view,
		ULBeginLoadingCallback	callback,
		void *	user_data,
		ULUserDataDestroyCallback	destroy_user_data )

Set callback for when a load starts (see "Load Events" in the file description).

◆ ulViewSetChangeCursorCallback()

void ulViewSetChangeCursorCallback	(	ULView	view,
		ULChangeCursorCallback	callback,
		void *	user_data,
		ULUserDataDestroyCallback	destroy_user_data )

Set callback for when the mouse cursor changes.

◆ ulViewSetChangeEditableStateCallback()

void ulViewSetChangeEditableStateCallback	(	ULView	view,
		ULChangeEditableStateCallback	callback,
		void *	user_data,
		ULUserDataDestroyCallback	destroy_user_data )

Set callback for when the editable state changes.

This happens when focus moves to or from an editable element, when the View gains or loses focus, and when the focused element's inputmode changes. Use the state to turn an input method or on-screen keyboard on or off (see ULEditableState).

Warning: The callback can be called from inside your own ulViewFocus() or ulViewUnfocus() call. Don't change focus or content from the callback (wait until it returns).

◆ ulViewSetChangeTitleCallback()

void ulViewSetChangeTitleCallback	(	ULView	view,
		ULChangeTitleCallback	callback,
		void *	user_data,
		ULUserDataDestroyCallback	destroy_user_data )

Set callback for when the page title changes.

◆ ulViewSetChangeTooltipCallback()

void ulViewSetChangeTooltipCallback	(	ULView	view,
		ULChangeTooltipCallback	callback,
		void *	user_data,
		ULUserDataDestroyCallback	destroy_user_data )

Set callback for when the tooltip under the mouse changes (the text is empty when there's no tooltip).

This is called as the mouse moves over the page, with the tooltip text of the element under the cursor (eg, its title attribute). It may repeat the same text on every move.

The library doesn't display tooltips (and neither does AppCore)– you should draw the text yourself near the cursor and hide it when the text is empty.

◆ ulViewSetChangeURLCallback()

void ulViewSetChangeURLCallback	(	ULView	view,
		ULChangeURLCallback	callback,
		void *	user_data,
		ULUserDataDestroyCallback	destroy_user_data )

Set callback for when the main frame loads a new page.

◆ ulViewSetCompositorDebugInfoEnabled()

void ulViewSetCompositorDebugInfoEnabled	(	ULView	view,
		bool	enabled )

Set whether or not to display compositor debug information.

Parameters

view	The View.
enabled	Whether or not to show the debug information.

Note: Only valid when the compositor is enabled.

◆ ulViewSetCreateChildViewCallback()

void ulViewSetCreateChildViewCallback	(	ULView	view,
		ULCreateChildViewCallback	callback,
		void *	user_data,
		ULUserDataDestroyCallback	destroy_user_data )

Set callback for when the page wants to open a new window (a link with target="_blank" or a call to window.open()).

Return a new View from the callback to allow the window or NULL to block it. The library loads target_url into the View, and you display it. popup_rect is the position and size the page asked for in window.open().

Warning: Don't destroy the View you return while its window is open.

◆ ulViewSetCreateInspectorViewCallback()

void ulViewSetCreateInspectorViewCallback	(	ULView	view,
		ULCreateInspectorViewCallback	callback,
		void *	user_data,
		ULUserDataDestroyCallback	destroy_user_data )

Set callback for when the inspector needs a View to display in (after ulViewCreateLocalInspectorView() or when a remote inspector connects).

Return a new View from the callback or NULL to cancel. The library loads the inspector into the View, and you display it.

◆ ulViewSetDeviceScale()

void ulViewSetDeviceScale	(	ULView	view,
		double	scale )

Set the device scale.

Parameters

view	The View.
scale	The new device scale (see ulViewGetDeviceScale()).

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

◆ ulViewSetDiscardCompositionCallback()

void ulViewSetDiscardCompositionCallback	(	ULView	view,
		ULDiscardCompositionCallback	callback,
		void *	user_data,
		ULUserDataDestroyCallback	destroy_user_data )

Set callback for when the page ends the active composition on its own (eg, on navigation or when the selection moves away from it).

Cancel the input method's composition from the callback (on Windows, call ImmNotifyIME() with CPS_CANCEL). The composition's text stays in the page as final text, so don't insert it again.

◆ ulViewSetDisplayId()

void ulViewSetDisplayId	(	ULView	view,
		unsigned int	display_id )

Set the display id of the View.

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

Parameters

view	The View.
display_id	The id of the new display (see ulViewConfigSetDisplayId()).

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

◆ ulViewSetDOMReadyCallback()

void ulViewSetDOMReadyCallback	(	ULView	view,
		ULDOMReadyCallback	callback,
		void *	user_data,
		ULUserDataDestroyCallback	destroy_user_data )

Set callback for when a frame's document has been parsed and the DOM is ready.

This is the best time to read or change the DOM. The page's own DOMContentLoaded event has already fired. This is also called when JavaScript is disabled.

◆ ulViewSetDownloadBeginCallback()

void ulViewSetDownloadBeginCallback	(	ULView	view,
		ULDownloadBeginCallback	callback,
		void *	user_data,
		ULUserDataDestroyCallback	destroy_user_data )

Set callback for when a download begins.

◆ ulViewSetDownloadFailCallback()

void ulViewSetDownloadFailCallback	(	ULView	view,
		ULDownloadFailCallback	callback,
		void *	user_data,
		ULUserDataDestroyCallback	destroy_user_data )

Set callback for when a download fails.

◆ ulViewSetDownloadFinishCallback()

void ulViewSetDownloadFinishCallback	(	ULView	view,
		ULDownloadFinishCallback	callback,
		void *	user_data,
		ULUserDataDestroyCallback	destroy_user_data )

Set callback for when a download finishes.

◆ ulViewSetDownloadNextIdCallback()

void ulViewSetDownloadNextIdCallback	(	ULView	view,
		ULDownloadNextIdCallback	callback,
		void *	user_data,
		ULUserDataDestroyCallback	destroy_user_data )

Set callback for generating unique download ids.

◆ ulViewSetDownloadReceiveDataCallback()

void ulViewSetDownloadReceiveDataCallback	(	ULView	view,
		ULDownloadReceiveDataCallback	callback,
		void *	user_data,
		ULUserDataDestroyCallback	destroy_user_data )

Set callback for when download data is received.

◆ ulViewSetDownloadRequestCallback()

void ulViewSetDownloadRequestCallback	(	ULView	view,
		ULDownloadRequestCallback	callback,
		void *	user_data,
		ULUserDataDestroyCallback	destroy_user_data )

Set callback for when the View requests a download.

◆ ulViewSetFailLoadingCallback()

void ulViewSetFailLoadingCallback	(	ULView	view,
		ULFailLoadingCallback	callback,
		void *	user_data,
		ULUserDataDestroyCallback	destroy_user_data )

Set callback for when a load fails (just before the finish-loading callback).

HTTP error responses count as failures (error_domain is "HTTPErrorDomain" and error_code is the HTTP status code). Canceled loads aren't reported.

◆ ulViewSetFinishLoadingCallback()

void ulViewSetFinishLoadingCallback	(	ULView	view,
		ULFinishLoadingCallback	callback,
		void *	user_data,
		ULUserDataDestroyCallback	destroy_user_data )

Set callback for when a load ends (whether or not it succeeded).

◆ ulViewSetMaxRenderFps()

void ulViewSetMaxRenderFps	(	ULView	view,
		unsigned int	fps )

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

(Default = 0, unthrottled)

This caps the View's whole frame loop (requestAnimationFrame, CSS and Web animations, smooth scrolling, and painting).

Parameters

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

◆ ulViewSetNeedsPaint()

void ulViewSetNeedsPaint	(	ULView	view,
		bool	needs_paint )

Set whether or not a view should be repainted during the next call to ulRender().

Parameters

view	The View.
needs_paint	Whether or not the View needs a repaint.

Note: The library sets this flag automatically when a repaint is due: after a ulRefreshDisplay() 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 the View's frame-rate cap).

◆ ulViewSetNetworkRequestCallback()

void ulViewSetNetworkRequestCallback	(	ULView	view,
		ULNetworkRequestCallback	callback,
		void *	user_data,
		ULUserDataDestroyCallback	destroy_user_data )

Set callback for when the View is about to begin a network request.

◆ ulViewSetPageSettledCallback()

void ulViewSetPageSettledCallback	(	ULView	view,
		ULPageSettledCallback	callback,
		void *	user_data,
		ULUserDataDestroyCallback	destroy_user_data )

Set callback for when the page has settled and is ready to capture or display (resources have loaded, initial scripts have run, and layout is stable).

This fires after the finish-loading callback once network and layout activity have stayed idle for a short time (see ulConfigSetPageSettleDelay()).

Warning: Pages with constant network or layout activity (ads, animated layouts, streaming video) may never settle. Use a timeout.

Note: Animations that don't change layout (eg, a CSS transform or opacity transition) can still be running when the page settles.

Note: You must call ulUpdate(), ulRefreshDisplay(), and ulRender() from your run loop for this to fire (ulCreateApp() does this for you).

◆ ulViewSetPreferredColorScheme()

void ulViewSetPreferredColorScheme	(	ULView	view,
		ULColorScheme	scheme )

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

(Default = kColorScheme_Auto)

Overrides the value set via ulViewConfigSetPreferredColorScheme(). A change re-evaluates prefers-color-scheme media queries on the page. matchMedia change listeners fire and styles recalculate, the same as an OS theme change.

An out-of-range value logs a warning and leaves the View unchanged.

See also: ulRendererSetSystemColorScheme()

◆ ulViewSetRequestCloseCallback()

void ulViewSetRequestCloseCallback	(	ULView	view,
		ULRequestCloseCallback	callback,
		void *	user_data,
		ULUserDataDestroyCallback	destroy_user_data )

Set callback for when the page asks to close (window.close() in a window that script opened, or in one with a single page in its history).

◆ ulViewSetUpdateCompositionCallback()

void ulViewSetUpdateCompositionCallback	(	ULView	view,
		ULUpdateCompositionCallback	callback,
		void *	user_data,
		ULUserDataDestroyCallback	destroy_user_data )

Set callback for after every change to the active composition.

Move the input method's candidate window from the callback (see ulEditorGetCompositionCharacterBounds()).

◆ ulViewSetUpdateHistoryCallback()

void ulViewSetUpdateHistoryCallback	(	ULView	view,
		ULUpdateHistoryCallback	callback,
		void *	user_data,
		ULUserDataDestroyCallback	destroy_user_data )

Set callback for when the main frame's back-forward history changes.

◆ ulViewSetVisible()

void ulViewSetVisible	(	ULView	view,
		bool	visible )

Set whether or not this View is visible.

(Default = True)

Hiding a View (passing false) stops it from being painted during ulRender and pauses its requestAnimationFrame callbacks and CSS animations (they stop advancing while hidden). 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 ulRender.

Parameters

view	The View.
visible	Whether or not the View is visible.

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

◆ ulViewSetWindowObjectReadyCallback()

void ulViewSetWindowObjectReadyCallback	(	ULView	view,
		ULWindowObjectReadyCallback	callback,
		void *	user_data,
		ULUserDataDestroyCallback	destroy_user_data )

Set callback for before a frame's scripts run.

Set up JavaScript state for the page from the callback (APIs you added with ulViewAttachJSAPI() are already there). Use the DOM-ready callback for anything that needs the DOM.

Note: Only called when JavaScript is enabled. A page with no scripts may never trigger it.

◆ ulViewStop()

void ulViewStop ( ULView view )

Stop all page loads.

◆ ulViewUnfocus()

void ulViewUnfocus ( ULView view )

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

◆ ulViewUnlockJSContext()

void ulViewUnlockJSContext ( ULView view )

Unlock the page's JSContext after a previous call to ulViewLockJSContext().

◆ ulViewUnlockJSContextWithFrame()

void ulViewUnlockJSContextWithFrame	(	ULView	view,
		ULString	frame )

Unlock the JSContext of a specific frame after a previous call to ulViewLockJSContextWithFrame().

Parameters

view	The View.
frame	The frame name you passed to ulViewLockJSContextWithFrame().

Note: Must be called the same number of times as ulViewLockJSContextWithFrame() for the same frame name (the lock is recursive).

Typedef Documentation

◆ ULAddConsoleMessageCallback

typedef void(*) ULAddConsoleMessageCallback(void *user_data, ULView caller, ULMessageSource source, ULMessageLevel level, ULString message, unsigned int line_number, unsigned int column_number, ULString source_id)

◆ ULBeginLoadingCallback

typedef void(*) ULBeginLoadingCallback(void *user_data, ULView caller, unsigned long long frame_id, bool is_main_frame, ULString url)

◆ ULChangeCursorCallback

typedef void(*) ULChangeCursorCallback(void *user_data, ULView caller, ULCursor cursor)

◆ ULChangeEditableStateCallback

typedef void(*) ULChangeEditableStateCallback(void *user_data, ULView caller, ULEditableState state)

◆ ULChangeTitleCallback

typedef void(*) ULChangeTitleCallback(void *user_data, ULView caller, ULString title)

◆ ULChangeTooltipCallback

typedef void(*) ULChangeTooltipCallback(void *user_data, ULView caller, ULString tooltip)

◆ ULChangeURLCallback

typedef void(*) ULChangeURLCallback(void *user_data, ULView caller, ULString url)

◆ ULCreateChildViewCallback

typedef ULView(*) ULCreateChildViewCallback(void *user_data, ULView caller, ULString opener_url, ULString target_url, bool is_popup, ULIntRect popup_rect)

◆ ULCreateInspectorViewCallback

typedef ULView(*) ULCreateInspectorViewCallback(void *user_data, ULView caller, bool is_local, ULString inspected_url)

◆ ULDiscardCompositionCallback

typedef void(*) ULDiscardCompositionCallback(void *user_data, ULView caller)

◆ ULDOMReadyCallback

typedef void(*) ULDOMReadyCallback(void *user_data, ULView caller, unsigned long long frame_id, bool is_main_frame, ULString url)

◆ ULDownloadBeginCallback

typedef void(*) ULDownloadBeginCallback(void *user_data, ULView caller, unsigned int id, ULString url, ULString filename, long long expected_content_length)

Callback for when a download starts.

Open a file to write the data to here. filename is the suggested file name (from the server, or the end of the URL).

◆ ULDownloadFailCallback

typedef void(*) ULDownloadFailCallback(void *user_data, ULView caller, unsigned int id)

Callback for when a download fails.

Close the file and delete it here.

◆ ULDownloadFinishCallback

typedef void(*) ULDownloadFinishCallback(void *user_data, ULView caller, unsigned int id)

Callback for when a download finishes.

Close the file here.

◆ ULDownloadNextIdCallback

typedef unsigned int(*) ULDownloadNextIdCallback(void *user_data, ULView caller)

Callback for when the View needs an ID for a new download.

A download starts when the page navigates to a file it can't display (eg, a response with Content-Disposition: attachment). Downloads are ignored until you set the download callbacks.

The library doesn't write anything to disk. You save the data yourself in these callbacks (called in this order):

Callback	What to do
ULDownloadNextIdCallback	Return a new ID
ULDownloadRequestCallback	Return true to accept the download
ULDownloadBeginCallback	Open a file
ULDownloadReceiveDataCallback	Write the data to the file
ULDownloadFinishCallback	Close the file
ULDownloadFailCallback	Close the file and delete it

Returns: Return a new ID (a different one on every call, eg a counter starting at 0).

◆ ULDownloadReceiveDataCallback

typedef void(*) ULDownloadReceiveDataCallback(void *user_data, ULView caller, unsigned int id, ULBuffer data)

Callback for when a download receives data (usually several times per download).

Write the data to the file here.

Parameters

data	The data (only valid during this call, so copy it to keep it).

◆ ULDownloadRequestCallback

typedef bool(*) ULDownloadRequestCallback(void *user_data, ULView caller, unsigned int id, ULString url)

Callback for when the page wants to download a file.

Returns: Return true to allow the download, or false to block it.

◆ ULFailLoadingCallback

typedef void(*) ULFailLoadingCallback(void *user_data, ULView caller, unsigned long long frame_id, bool is_main_frame, ULString url, ULString description, ULString error_domain, int error_code)

◆ ULFinishLoadingCallback

typedef void(*) ULFinishLoadingCallback(void *user_data, ULView caller, unsigned long long frame_id, bool is_main_frame, ULString url)

◆ ULNetworkRequestCallback

typedef bool(*) ULNetworkRequestCallback(void *user_data, ULView caller, ULString url)

Callback for before the View sends a network request.

Returns: Return true to allow the request, or false to block it.

Note: file: and data: URLs and synchronous XMLHttpRequests don't go through here.

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

◆ ULPageSettledCallback

typedef void(*) ULPageSettledCallback(void *user_data, ULView caller, ULString url)

◆ ULRequestCloseCallback

typedef void(*) ULRequestCloseCallback(void *user_data, ULView caller)

◆ ULUpdateCompositionCallback

typedef void(*) ULUpdateCompositionCallback(void *user_data, ULView caller)

◆ ULUpdateHistoryCallback

typedef void(*) ULUpdateHistoryCallback(void *user_data, ULView caller)

◆ ULWindowObjectReadyCallback

typedef void(*) ULWindowObjectReadyCallback(void *user_data, ULView caller, unsigned long long frame_id, bool is_main_frame, ULString url)

Enumeration Type Documentation

◆ ULCursor

enum ULCursor

Cursor types.

See also: ULChangeCursorCallback

Enumerator
kCursor_Pointer
kCursor_Cross
kCursor_Hand
kCursor_IBeam
kCursor_Wait
kCursor_Help
kCursor_EastResize
kCursor_NorthResize
kCursor_NorthEastResize
kCursor_NorthWestResize
kCursor_SouthResize
kCursor_SouthEastResize
kCursor_SouthWestResize
kCursor_WestResize
kCursor_NorthSouthResize
kCursor_EastWestResize
kCursor_NorthEastSouthWestResize
kCursor_NorthWestSouthEastResize
kCursor_ColumnResize
kCursor_RowResize
kCursor_MiddlePanning
kCursor_EastPanning
kCursor_NorthPanning
kCursor_NorthEastPanning
kCursor_NorthWestPanning
kCursor_SouthPanning
kCursor_SouthEastPanning
kCursor_SouthWestPanning
kCursor_WestPanning
kCursor_Move
kCursor_VerticalText
kCursor_Cell
kCursor_ContextMenu
kCursor_Alias
kCursor_Progress
kCursor_NoDrop
kCursor_Copy
kCursor_None
kCursor_NotAllowed
kCursor_ZoomIn
kCursor_ZoomOut
kCursor_Grab
kCursor_Grabbing
kCursor_Custom

◆ ULMessageLevel

enum ULMessageLevel

The severity level of a console message.

See also: ULAddConsoleMessageCallback

Enumerator
kMessageLevel_Log
kMessageLevel_Warning
kMessageLevel_Error
kMessageLevel_Debug
kMessageLevel_Info

◆ ULMessageSource

enum ULMessageSource

The source of a console message.

See also: ULAddConsoleMessageCallback

Enumerator
kMessageSource_XML
kMessageSource_JS
kMessageSource_Network
kMessageSource_ConsoleAPI
kMessageSource_Storage
kMessageSource_AppCache
kMessageSource_Rendering
kMessageSource_CSS
kMessageSource_Security
kMessageSource_ContentBlocker
kMessageSource_Media
kMessageSource_MediaSource
kMessageSource_WebRTC
kMessageSource_ITPDebug
kMessageSource_PrivateClickMeasurement
kMessageSource_PaymentRequest
kMessageSource_Other
kMessageSource_NativeAPI	Diagnostics from application-bound JavaScript APIs.

Go to the source code of this file.

Overview

Creating a View

Callbacks

Load Events

Functions

Typedefs

Enumerations

Function Documentation

◆ ulCreateView()

◆ ulCreateViewConfig()

◆ ulDestroyView()

◆ ulDestroyViewConfig()

◆ ulViewCancelDownload()

◆ ulViewCanGoBack()

◆ ulViewCanGoForward()

◆ ulViewConfigSetAllowUniversalAccessFromFileURLs()

◆ ulViewConfigSetBackgroundColor()

◆ ulViewConfigSetClipboardReadPolicy()

◆ ulViewConfigSetDisplayId()

◆ ulViewConfigSetEnableCanvasFilters()

◆ ulViewConfigSetEnableCompositor()

◆ ulViewConfigSetEnableCompositorDebugInfo()

◆ ulViewConfigSetEnableHiddenTimerThrottling()

◆ ulViewConfigSetEnableImages()

◆ ulViewConfigSetEnableJavaScript()

◆ ulViewConfigSetFontFamilyCursive()

◆ ulViewConfigSetFontFamilyFantasy()

◆ ulViewConfigSetFontFamilyFixed()

◆ ulViewConfigSetFontFamilyPictograph()

◆ ulViewConfigSetFontFamilySansSerif()

◆ ulViewConfigSetFontFamilySerif()

◆ ulViewConfigSetFontFamilyStandard()

◆ ulViewConfigSetFontSizeDefault()

◆ ulViewConfigSetFontSizeFixed()

◆ ulViewConfigSetInitialDeviceScale()

◆ ulViewConfigSetInitialFocus()

◆ ulViewConfigSetIsAccelerated()

◆ ulViewConfigSetIsTransparent()

◆ ulViewConfigSetJavaScriptCanOpenWindowsAutomatically()

◆ ulViewConfigSetMatchNativeEditingBehavior()

◆ ulViewConfigSetMaxRenderFps()

◆ ulViewConfigSetPreferredColorScheme()

◆ ulViewConfigSetUserAgent()

◆ ulViewCreateLocalInspectorView()

◆ ulViewEvaluateScript()

◆ ulViewEvaluateScriptWithFrame()

◆ ulViewFireKeyEvent()

◆ ulViewFireMouseEvent()

◆ ulViewFireScrollEvent()

◆ ulViewFocus()

◆ ulViewGetCompositorDebugInfoEnabled()

◆ ulViewGetDeviceScale()

◆ ulViewGetDisplayId()

◆ ulViewGetHeight()

◆ ulViewGetJSContext()

◆ ulViewGetMaxRenderFps()

◆ ulViewGetNeedsPaint()

◆ ulViewGetPreferredColorScheme()

◆ ulViewGetRenderTarget()

◆ ulViewGetSurface()

◆ ulViewGetTitle()

◆ ulViewGetURL()

◆ ulViewGetWidth()

◆ ulViewGoBack()

◆ ulViewGoForward()

◆ ulViewGoToHistoryOffset()

◆ ulViewHasFocus()

◆ ulViewHasInputFocus()

◆ ulViewIsAccelerated()

◆ ulViewIsLoading()

◆ ulViewIsSettled()

◆ ulViewIsTransparent()

◆ ulViewIsVisible()

◆ ulViewJavaScriptVMWithFrame()

◆ ulViewLoadHTML()

◆ ulViewLoadHTMLWithParams()

◆ ulViewLoadURL()

◆ ulViewLockJSContext()

◆ ulViewLockJSContextWithFrame()

◆ ulViewReload()