Creating Views

Create offscreen Views, configure display and rendering settings, and update them at runtime.

A View loads and renders web-pages to an offscreen target. It is completely isolated from the OS windowing system and must be forwarded all input events.

You create Views through the Renderer, drawing content either to a CPU pixel buffer or GPU render-target.

📘 Views in AppCore

When using AppCore, each Panel creates a View for you. See Laying Out Panels.

#Creating a View

To create a View, call Renderer::CreateView() on the Renderer's thread:

RefPtr<View> view;

void CreateView() {
  ///
  /// An 800x600 View with default settings, using the default
  /// Session (nullptr).
  ///
  view = renderer->CreateView(800, 600, ViewConfig(), nullptr);

  view->LoadURL("file:///app.html");
}

Dimensions are specified in device pixels.

Renderer::CreateView() returns a RefPtr<View> (a ref-counted pointer to the View). You should retain the pointer to keep the View alive.

Call View::LoadURL() or View::LoadHTML() to begin loading content into the View. To know when the page is ready, see Handling View Events.

📘 Sessions and Site Data

Site data like cookies, local storage, and cached resources are stored in the View's Session. You should specify a Session during creation or pass nullptr to use the default Session. See Sessions and Site Data.

#Configuring a View

A ViewConfig struct defines initial settings for a View and remain fixed unless the View provides a runtime setter.

Most applications configure three common settings: is_accelerated for GPU rendering, initial_device_scale for high-DPI displays, and is_transparent for transparent overlays.

When using is_transparent, the page must also clear its own background in CSS:

html, body { background: transparent; }

The following function configures an accelerated, transparent View for a 2x display:

void CreateHudView() {
  ViewConfig config;
  config.is_accelerated = true;
  config.initial_device_scale = 2.0;
  config.is_transparent = true;

  ///
  /// The page lays out at 640x360 and renders 1280x720 pixels.
  ///
  view = renderer->CreateView(1280, 720, config, nullptr);
}

🚧 Register a GPU Driver First

You must register a GPUDriver on Platform before creating an accelerated View. Creating an accelerated View without a GPU driver terminates the process with an error. See GPU Renderer Overview.

#ViewConfig Options

The table below lists every option available on ViewConfig and its default value.

#Updating Settings at Runtime

You can update several View properties after creation using dedicated methods on View.

Every other ViewConfig property is fixed at creation. To change any other setting, you must destroy the View and create a new one.