#include <Ultralight/View.h>

Overview

View-specific configuration settings.

See also: Renderer::CreateView()

Public Attributes
uint32_t	display_id = 0
	A user-generated id for the display (monitor, TV, or screen) that this View will be shown on.
bool	is_accelerated = false
	Whether to render using the GPU renderer (accelerated) or the CPU renderer (unaccelerated).
double	initial_device_scale = 1.0
	The initial device scale, ie.
bool	is_transparent = false
	Whether or not this View should support transparency.
Color	background_color
	The base color the page renders on before any page styling applies.
ColorScheme	preferred_color_scheme = ColorScheme::Auto
	The color scheme this View reports to pages via the prefers-color-scheme CSS media feature.
bool	initial_focus = true
	Whether or not the View should initially have input focus.
bool	enable_images = true
	Whether or not images should be enabled.
bool	enable_javascript = true
	Whether or not JavaScript should be enabled.
bool	enable_compositor = true
	Whether or not compositing should be enabled.
bool	enable_compositor_debug_info = false
	Whether or not to enable extra compositor debug information, specifically:
bool	enable_canvas_filters = true
	Whether or not the HTML5 Canvas Filters API (CanvasRenderingContext2D.filter) is enabled.
bool	match_native_editing_behavior = false
	Whether or not text editing should follow the host OS's native conventions instead of the library's cross-platform behavior.
ClipboardReadPolicy	clipboard_read_policy = ClipboardReadPolicy::AllowForAppContent
	Policy governing script-initiated clipboard reads (eg, a page's own Paste button calling document.execCommand('paste')).
bool	enable_hidden_timer_throttling = false
	Whether to throttle JavaScript timers (setTimeout / setInterval) while this View is hidden.
uint32_t	max_render_fps = 0
	The maximum rate, in frames per second, at which this View advances its animations and repaints.
bool	javascript_can_open_windows_automatically = false
	Whether or not a script can open a window with window.open() without a user gesture.
bool	allow_universal_access_from_file_urls = true
	Whether or not pages loaded from file:/// URLs can access content from any origin.
String	font_family_standard = "Times New Roman"
	The default font family (used for text that doesn't set one).
String	font_family_fixed = "Courier New"
	The default monospace font family (eg, for pre and code).
String	font_family_serif = "Times New Roman"
	The default font family for the CSS serif generic.
String	font_family_sans_serif = "Arial"
	The default font family for the CSS sans-serif generic.
String	font_family_cursive = "Comic Sans MS"
	The default font family for the CSS cursive generic.
String	font_family_fantasy = "Impact"
	The default font family for the CSS fantasy generic.
String	font_family_pictograph = ""
	The default font family for the CSS -webkit-pictograph generic.
uint32_t	font_size_default = 16
	The default font size, in pixels.
uint32_t	font_size_fixed = 13
	The default font size for monospace text (eg, pre and code), in pixels.
String	user_agent = ULTRALIGHT_USER_AGENT
	Custom user-agent string.

Member Data Documentation

◆ allow_universal_access_from_file_urls

bool allow_universal_access_from_file_urls = true

Whether or not pages loaded from file:/// URLs can access content from any origin.

When true (the default), 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).

◆ background_color

Color background_color

The base color the page renders on before any page styling applies.

This is the color visible while a page loads and wherever the page itself paints nothing. Dark applications should set a dark base so pages never flash white during load. An unset color (the default) means opaque white.

Note: is_transparent takes precedence. A transparent View keeps a fully transparent base. On an opaque View a translucent color is composited over white, so the View itself stays opaque.

◆ clipboard_read_policy

ClipboardReadPolicy clipboard_read_policy = ClipboardReadPolicy::AllowForAppContent

Policy governing script-initiated clipboard reads (eg, a page's own Paste button calling document.execCommand('paste')).

AllowForAppContent (the default) grants requests from your application's own content (local file:/// pages and pages loaded from application-supplied data, eg, View::LoadHTML()) and refuses them from other pages. Allow grants requests from any page. Deny refuses them all.

Note: The library only considers requests made during a user gesture such as a click or key press. Script running outside a gesture is always refused.

Note: Pastes the user performs directly (Ctrl+V, or Editor::Execute() with EditorCommand::Paste) are never affected by this policy.

◆ display_id

uint32_t display_id = 0

A user-generated id for the display (monitor, TV, or screen) that this 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 App::Create() is used and the View is hosted in a Window. A View you create yourself in an App should use the id of the Monitor it is shown on (Monitor::display_id()).

See also: Renderer::RefreshDisplay(), Renderer::SetDisplayRefreshRate()

◆ enable_canvas_filters

bool enable_canvas_filters = true

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

Note: Reference filters (url(#x)) render unfiltered. The filter string is still readable for feature detection.

◆ enable_compositor

bool enable_compositor = true

Whether or not compositing should be enabled.

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.

◆ enable_compositor_debug_info

bool enable_compositor_debug_info = false

Whether or not to enable extra compositor debug information, specifically:

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

Note: Only valid when the compositor is enabled.

◆ enable_hidden_timer_throttling

bool enable_hidden_timer_throttling = false

Whether to throttle JavaScript timers (setTimeout / setInterval) while this View is hidden.

When false (the default), timers keep running at their normal rate while the View is hidden, so background logic continues to tick.

When true, repeating timers in a hidden View are aligned to roughly one-second boundaries (so a fast interval effectively drops to about 1 Hz), reducing CPU usage for off-screen Views. Timers return to their normal rate once the View is shown again.

Note: This does not affect requestAnimationFrame, which is always suspended while a View is hidden regardless of this setting.

See also: View::set_visible()

◆ enable_images

bool enable_images = true

Whether or not images should be enabled.

◆ enable_javascript

bool enable_javascript = true

Whether or not JavaScript should be enabled.

◆ font_family_cursive

String font_family_cursive = "Comic Sans MS"

The default font family for the CSS cursive generic.

◆ font_family_fantasy

String font_family_fantasy = "Impact"

The default font family for the CSS fantasy generic.

◆ font_family_fixed

String font_family_fixed = "Courier New"

The default monospace font family (eg, for pre and code).

◆ font_family_pictograph

String font_family_pictograph = ""

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

Leave it empty to use font_family_standard.

◆ font_family_sans_serif

String font_family_sans_serif = "Arial"

The default font family for the CSS sans-serif generic.

◆ font_family_serif

String font_family_serif = "Times New Roman"

The default font family for the CSS serif generic.

◆ font_family_standard

String font_family_standard = "Times New Roman"

The default font family (used for text that doesn't set one).

Note: App replaces these font_family_* defaults with ones that match the host OS for the Views it creates for a bare AddPanel() (see Settings::auto_font_families).

◆ font_size_default

uint32_t font_size_default = 16

The default font size, in pixels.

◆ font_size_fixed

uint32_t font_size_fixed = 13

The default font size for monospace text (eg, pre and code), in pixels.

◆ initial_device_scale

double initial_device_scale = 1.0

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.

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

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

◆ initial_focus

bool initial_focus = true

Whether or not the View should initially have input focus.

See also: View::Focus()

◆ is_accelerated

bool is_accelerated = false

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

When true, the View renders to an offscreen GPU texture using the GPU driver set with Platform::set_gpu_driver(). You can get the texture's details with View::render_target().

When false (the default), the View renders to an offscreen pixel buffer using the multithreaded CPU renderer. You can provide this pixel buffer yourself– see Platform::set_surface_factory() and View::surface().

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

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

◆ is_transparent

bool is_transparent = false

Whether or not this View should support transparency.

The page needs a transparent background too:

html, body { background: transparent; }

◆ javascript_can_open_windows_automatically

bool javascript_can_open_windows_automatically = false

Whether or not a script can open a window with window.open() without a user gesture.

When false (the default), 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 ViewListener::OnCreateChildView() handler returns one; return nullptr there to block it.

◆ match_native_editing_behavior

bool match_native_editing_behavior = false

Whether or not text editing should follow the host OS's native conventions instead of the library's cross-platform behavior.

When false (the default), 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 (eg, non-directional selections and Mac-style shift-click extension on macOS).

Note: App turns this on for the Views it creates for a bare AddPanel() (see Settings::match_native_editing_behavior). A ViewConfig you pass yourself keeps this value.

◆ max_render_fps

uint32_t max_render_fps = 0

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

This caps the View's whole frame loop: requestAnimationFrame callbacks, CSS and Web animations, smooth scrolling, and painting all advance at no more than this rate. Use it to spend less CPU and GPU on a View that is on-screen but not the focus of attention (a secondary panel, a minimap, a paused menu behind a modal).

A value of 0 (the default) leaves the View unthrottled, advancing at the display's refresh rate, the same as a normal browser tab.

Note: Page content changes (from script, the DOM API, or data bindings) also wait for the next capped frame. Input events, a resize, and showing the View paint right away.

Note: This is independent of View::set_visible() and enable_hidden_timer_throttling. Hiding a View stops it entirely. This setting slows a View that remains visible.

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

◆ preferred_color_scheme

ColorScheme preferred_color_scheme = ColorScheme::Auto

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

Auto (the default) follows the system scheme set via Renderer::set_system_color_scheme(), which is Light until you (or App) set a different one. Light or Dark pins the scheme for this View regardless of the system value.

Note: The scheme is a signal to the page, which styles itself via media queries. Built-in UI (form controls, scrollbars, the default white canvas) keeps its light appearance under a dark scheme.

Note: This is automatically managed for you when App::Create() is used (the OS setting is fed to the Renderer and tracked as it changes).

See also: View::set_preferred_color_scheme()

◆ user_agent

String user_agent = ULTRALIGHT_USER_AGENT

Custom user-agent string.

You can use this to override the default user-agent string.

Precondition: Not available in the Free edition (the default user-agent string is always used).

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

Ultralight/View.h