Window

#include <AppCore/Window.h>

Overview

A native OS window that displays web content.

A window holds one or more panels, each showing a View, and passes mouse, keyboard, and scroll input to them. It can also use native materials, draw its own title bar, and show popups for menus and dropdowns.

Creating a Window

Use Create():

auto window = Window::Create(monitor, 1024, 768, false, WindowFlags::Titled);

Setting a WindowListener

To receive callbacks for window-related events, set a WindowListener:

class MyWindowListener : public WindowListener {
  virtual void OnClose(Window* window) override {
    printf("Window closed!\n");
  }
};
 
auto listener = new MyWindowListener();
window->set_listener(listener);

Displaying Web Content

A window's content is a layout of panels, each showing a View. Panels tile the window (see layout()), and floating panels can sit above them (see foreground()). A bare AddPanel() fills the whole window with one page:

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

Coordinate Systems

The OS may apply a device scale to a monitor or window (eg, 2x on a Retina display).

Sizes and positions in this API are in logical pixels (independent of the device scale), unless the name says device (eg, device_width()). The two are related by scale():

device_pixels = round(logical_pixels * scale)

Use LogicalToDevice() and DeviceToLogical() to convert between them.

Positions inside the window (mouse events, the layout, hit-test regions) are in window content coordinates: logical pixels from the top-left of the window's content area.

Popup Windows

Use CreatePopup() to show menus, dropdowns, and other short-lived content in their own OS window. Clicking a popup doesn't take focus away from your main window, a popup can extend past its owner's edges, and the library dismisses it the way the OS dismisses a native menu (see SetDismiss()).

// Show a context menu at (x, y) within the owner's content area:
auto menu = Window::CreatePopup(window, x, y, 220, 320);
menu->SetBackdrop(BackdropMaterial::Popup);
 
ViewConfig config;
config.is_transparent = true;
menu->AddPanel({}, config)->view()->LoadURL("file:///menu.html");

Use a popup for anything that may extend past the window (most menus and dropdowns), and a floating panel (see foreground()) for anything that stays inside it (a toast, an in-window dialog).

Dialogs

For a native message box, use ShowMessageBox() in <AppCore/Dialogs.h>. For a dialog drawn with your own HTML, use a floating panel (see foreground()) with FocusPolicy::Grab, so it takes keyboard focus when shown.

Transparent Windows

A window created with WindowFlags::Transparent shows what's behind it wherever you leave it transparent. You can use this for custom window shapes (eg, soft edges or irregular outlines).

Three layers need to be transparent for the window to be see-through:

1. The window: create it with WindowFlags::Transparent.
2. The View: set is_transparent in the panel's ViewConfig (pages draw on an opaque white background by default).
3. The page: html, body { background: transparent; }.

auto window = Window::Create(monitor, 400, 300, false,
                             WindowFlags::Borderless | WindowFlags::Transparent);
 
ViewConfig config;
config.is_transparent = true;
window->AddPanel({}, config)->view()->LoadURL("file:///shaped.html");

A transparent window has no background color until you set one (see SetBackgroundColor()).

Backdrop Materials

A window can show a native backdrop material behind its content (the blurred, theme-aware materials the OS uses for its own windows). Request one with SetBackdrop(), and tint it with a translucent background color:

auto window = Window::Create(monitor, 1024, 768, false,
                             WindowFlags::Titled | WindowFlags::Resizable);
window->SetBackdrop(BackdropMaterial::Window);
window->SetBackgroundColor("rgba(32, 32, 32, 0.5)");

The material shows wherever your content is transparent, so the View and the page need to be transparent (steps 2 and 3 in Transparent Windows above). If the platform can't render the material, the library uses the closest look it can (see SetBackdrop()).

Custom Chrome

To draw the title bar and caption buttons yourself (in HTML and CSS, like the rest of your UI), create the window with WindowFlags::CustomChrome. Your content covers the whole window, and the OS keeps its frame behaviors:

• the system shadow, rounded corners, and window animations
• the resize edges
• snap gestures and the system window menu

To build one:

1. Create the window with WindowFlags::CustomChrome.
2. Draw the title bar and caption buttons as ordinary page content.
3. Mark which areas drag the window and which act as caption buttons, either with SetHitTestRegions() or from the page with the app-region CSS property (app-region: drag / no-drag).

auto window = Window::Create(monitor, 1024, 768, false,
    WindowFlags::CustomChrome | WindowFlags::Resizable | WindowFlags::Maximizable);
 
// The top 40px drags the window; your close button sits on the right.
HitTestRegion regions[] = {
  { HitRegionRole::Caption, Rect::FromXYWH(0, 0, window->width(), 40) },
  { HitRegionRole::Close,   Rect::FromXYWH(window->width() - 46, 0, 46, 40) },
};
window->SetHitTestRegions(regions, 2);

Use SetWindowButtons() to choose which window actions are available. To restyle your chrome as the window changes, use WindowListener::OnWindowStateChanged() and WindowListener::OnActivationChanged().

Text Input

The window handles the OS input method for you, so Chinese, Japanese, and Korean input works in your pages without any code of your own. If you want to drive something else from the same signal (eg, an on-screen keyboard), use OnEditableStateChange().

Note

Password fields keep the input method off. Moving focus away during a composition commits the typed text on macOS and cancels it on Windows, matching each platform's own apps.

Inheritance diagram for Window:

Static Public Member Functions
static RefPtr< Window >	Create (Monitor *monitor, double width, double height, bool fullscreen, WindowFlags window_flags)
	Create a new Window.
static RefPtr< Window >	CreatePopup (RefPtr< Window > owner, double x, double y, double width, double height, WindowFlags window_flags=WindowFlags::None)
	Create a popup window owned by another window.

Public Member Functions
virtual void	set_listener (WindowListener *listener)=0
	Set a WindowListener to receive callbacks for window-related events.
virtual WindowListener *	listener ()=0
	Get the WindowListener (can be nullptr).
virtual double	width () const =0
	Get the window width (in logical pixels).
virtual double	height () const =0
	Get the window height (in logical pixels).
virtual uint32_t	device_width () const =0
	Get the window width (in device pixels).
virtual uint32_t	device_height () const =0
	Get the window height (in device pixels).
virtual void	MoveTo (double x, double y)=0
	Move the window to a new position on the screen.
virtual void	MoveToCenter ()=0
	Move the window to the center of the screen.
virtual double	x () const =0
	Get the x-position of the window (in logical pixels).
virtual double	y () const =0
	Get the y-position of the window (in logical pixels).
virtual bool	is_fullscreen () const =0
	Whether or not the window is fullscreen.
virtual bool	is_accelerated () const =0
	Whether or not the window renders on the GPU.
virtual uint32_t	render_buffer_id () const =0
	Get the ID of the render buffer the window draws into (0 if the window doesn't render on the GPU).
virtual double	scale () const =0
	Get the window's device scale (eg, 2.0 on a Retina display).
virtual void	SetTitle (const char *title)=0
	Set the window title.
virtual void	SetCursor (ultralight::Cursor cursor)=0
	Set the cursor.
virtual void	SetIcon (RefPtr< Bitmap > icon)=0
	Set the window icon (shown in the title bar and taskbar).
virtual void	Show ()=0
	Show the window (if it was hidden).
virtual void	Hide ()=0
	Hide the window.
void	ShowWhenReady (double timeout_seconds=0.5)
	Show the window once its pages have settled.
virtual bool	is_visible () const =0
	Whether or not the window is visible (not hidden).
virtual bool	is_maximized () const =0
	Whether or not the window is maximized.
virtual bool	is_minimized () const =0
	Whether or not the window is minimized.
virtual void	Maximize ()=0
	Maximize the window.
virtual void	Minimize ()=0
	Minimize the window.
virtual void	Restore ()=0
	Restore the window from the minimized or maximized state.
void	Invalidate ()
	Redraw the window on an upcoming frame, even if no View has changed.
void	SetBackgroundColor (const Color &color)
	Set the window background color.
void	SetBackdrop (BackdropMaterial material, const BackdropOptions &options={})
	Request a native backdrop material for this window.
BackdropMaterial	backdrop () const
	Get the backdrop material you requested.
BackdropOptions	backdrop_options () const
	Get the backdrop options you requested.
BackdropMaterial	effective_backdrop () const
	Get the backdrop material in effect: the requested material while anything shows (a live material or the fallback fill), else BackdropMaterial::None.
BackdropVariant	effective_backdrop_variant () const
	Get the look of the backdrop material in effect (BackdropVariant::Auto when none is).
void	SetBackdropState (BackdropState state)
	Set whether the backdrop material shows its active or inactive look.
BackdropState	backdrop_state () const
	Get the backdrop look you requested with SetBackdropState() (not necessarily what the OS is showing).
void	SetCaptionColor (const Color &color)
	Set the title bar color.
void	SetHitTestRegions (const HitTestRegion *regions, size_t count)
	Mark which areas of your custom chrome drag the window or act as caption buttons.
void	SetWindowButtons (WindowButtons buttons)
	Set which window actions are available to the user.
WindowButtons	window_buttons () const
	Get the window actions available to the user.
virtual bool	BeginDragMove ()
	Start moving the window with the mouse, the way dragging a title bar does.
virtual bool	BeginDragResize (ResizeEdge edge)
	Start resizing the window from an edge or corner with the mouse.
virtual Rect	window_control_bounds () const
	Get the area the native window buttons cover (in window content coordinates), so you can leave room for them.
void	SetWindowControlInset (double x, double y)
	Move the native window buttons on a macOS custom-chrome window (other windows ignore this).
void	SetCornerStyle (CornerStyle style)
	Set the window's corner style (see CornerStyle).
CornerStyle	corner_style () const
	Get the window's corner style.
void	SetAcceptsKeyInput (bool accepts)
	Set whether a popup can take keyboard focus.
bool	accepts_key_input () const
	Whether or not a popup can take keyboard focus.
void	SetDismiss (Dismiss dismiss)
	Set whether the library dismisses this popup automatically.
Dismiss	dismiss () const
	Get the auto-dismiss setting.
RefPtr< Container >	layout ()
	Get the window's root layout container (a column that fills the window).
RefPtr< Foreground >	foreground ()
	Get the window's foreground layer, the floating panels displayed above the window's layout (eg, a toast, an in-window dialog, or a command palette).
RefPtr< Container >	BuildLayout (const ContainerOptions &root_options)
	Configure the window's root container and get it.
template<typename... Children> requires (LayoutBuildable<Children> && ...)
RefPtr< Container >	BuildLayout (const ContainerOptions &root_options, Children... children)
	Configure the root container and add builder elements to it (see <AppCore/layout/Builder.h>).
RefPtr< Panel >	AddPanel (const PanelOptions &options={})
	Add a panel to the window's root container (shorthand for layout()->AddPanel()).
RefPtr< Panel >	AddPanel (const PanelOptions &options, const ViewConfig &view_config)
	Add a panel with a caller-supplied ViewConfig to the window's root container.
ViewConfig	default_view_config () const
	Get the ViewConfig this window uses for a bare AddPanel().
RefPtr< Panel >	AdoptPanel (RefPtr< View > view, const PanelOptions &options={})
	Add a panel adopting an existing View to the window's root container.
template<typename ViewRef> requires std::convertible_to<ViewRef&&, RefPtr<View>>
RefPtr< Panel >	AddPanel (ViewRef &&view, const PanelOptions &options={})
	Add a panel that hosts an existing View (same as AdoptPanel()).
void	SetDividerStyle (const DividerStyle &style)
	Set the default divider style for every resizable container in this window (see <AppCore/layout/DividerStyle.h>).
RefPtr< Panel >	FindPanel (const String &key)
	Find a panel by key anywhere in the window: the tiled layout first, then the foreground layer.
RefPtr< Panel >	focused_panel () const
	Get the panel holding keyboard focus (null when none does).
void	ClearFocus ()
	Take keyboard focus away from every panel.
LayoutCallback	OnFocusChange (LayoutFocusCallback callback, void *user_data, LayoutDestroyUserDataCallback destroy_user_data)
	Register a callback fired when the window's focused panel changes (the new panel may be null).
template<typename Callback> requires std::invocable<Callback&, Panel*> || std::invocable<Callback&>
LayoutCallback	OnFocusChange (Callback callback)
	Register a focus-change callback (invocable form).
LayoutCallback	OnEditableStateChange (LayoutEditableStateCallback callback, void *user_data, LayoutDestroyUserDataCallback destroy_user_data)
	Register a callback fired when the focused panel's editable state changes.
template<typename Callback> requires std::invocable<Callback&, Panel*, const EditableState&> || std::invocable<Callback&, const EditableState&>
LayoutCallback	OnEditableStateChange (Callback callback)
	Register an editable-state callback (invocable form).
virtual void	Close ()=0
	Close the window.
int	LogicalToDevice (double val) const
	Convert logical pixels to device pixels using the window's device scale (rounded to the nearest pixel).
double	DeviceToLogical (int val) const
	Convert device pixels to logical pixels using the window's device scale.
virtual void	DrawSurface (int x, int y, Surface *surface)
	Copy a CPU-rendered surface into the window.
virtual RefPtr< Bitmap >	TakeScreenshot ()
	Capture a screenshot of the window.
virtual void *	native_handle () const =0
	Get the native window handle: an HWND on Windows, an NSWindow* on macOS, and a GLFWwindow* on Linux.
virtual void	EnableFrameStatistics ()
	Show frame statistics (eg, FPS and frame times) after the window title.
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.

Additional Inherited Members
Protected Member Functions inherited from RefCounted
virtual	~RefCounted ()

Member Function Documentation

accepts_key_input()

bool accepts_key_input

(

)

const

Whether or not a popup can take keyboard focus.

See also

SetAcceptsKeyInput()

AddPanel() [1/3]

RefPtr< Panel > AddPanel	(	const PanelOptions &	options,
		const ViewConfig &	view_config )

Add a panel with a caller-supplied ViewConfig to the window's root container.

Parameters

options	The panel's layout options.
view_config	Configuration details for the panel's View.

Returns

Returns a ref-pointer to the new Panel.

See also

Container::AddPanel()

AddPanel() [2/3]

RefPtr< Panel > AddPanel

(

const PanelOptions &

options = {}

)

Add a panel to the window's root container (shorthand for layout()->AddPanel()).

A bare AddPanel() fills the whole window:

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

Parameters

options

The panel's layout options.

Returns

Returns a ref-pointer to the new Panel.

AddPanel() [3/3]

template<typename ViewRef>
requires std::convertible_to<ViewRef&&, RefPtr<View>>

RefPtr< Panel > AddPanel ( ViewRef && view, const PanelOptions & options = {} )

inline

Add a panel that hosts an existing View (same as AdoptPanel()).

Parameters

view	The View the panel will host.
options	The panel's layout options.

Returns

Returns a ref-pointer to the new Panel.

AdoptPanel()

RefPtr< Panel > AdoptPanel	(	RefPtr< View >	view,
		const PanelOptions &	options = {} )

Add a panel adopting an existing View to the window's root container.

Parameters

view	The View the panel will host.
options	The panel's layout options.

Returns

Returns a ref-pointer to the new Panel.

See also

Container::AdoptPanel()

backdrop()

BackdropMaterial backdrop

(

)

const

Get the backdrop material you requested.

See also

SetBackdrop()

backdrop_options()

BackdropOptions backdrop_options

(

)

const

Get the backdrop options you requested.

See also

SetBackdrop()

backdrop_state()

BackdropState backdrop_state

(

)

const

Get the backdrop look you requested with SetBackdropState() (not necessarily what the OS is showing).

BeginDragMove()

virtual bool BeginDragMove ( )

inlinevirtual

Start moving the window with the mouse, the way dragging a title bar does.

Call this while handling a left mouse-button press (eg, from WindowListener::OnMouseEvent()). The OS then moves the window until the button is released, and any press in progress on the page is canceled.

Returns

Returns whether or not the move started (false if the left button isn't down or the window is fullscreen).

BeginDragResize()

virtual bool BeginDragResize ( ResizeEdge edge )

inlinevirtual

Start resizing the window from an edge or corner with the mouse.

Call this while handling a left mouse-button press. macOS doesn't support this (the OS provides its own resize edges).

Parameters

edge	The edge or corner to resize from.

Returns

Returns whether or not the resize started (false on macOS, if the left button isn't down, or if the window is fullscreen, maximized, or not resizable).

BuildLayout() [1/2]

RefPtr< Container > BuildLayout

(

const ContainerOptions &

root_options

)

Configure the window's root container and get it.

The root is always a column that fills the window, so the sizing fields and fixed in root_options are ignored; key, resizable, gap, padding, and hidden apply.

Each call applies the whole options struct (an unset length or empty key resets that field). To add children without reconfiguring the root, use layout()->Build().

Parameters

root_options

The options to apply to the root container.

Returns

Returns the root container.

BuildLayout() [2/2]

template<typename... Children>
requires (LayoutBuildable<Children> && ...)

RefPtr< Container > BuildLayout ( const ContainerOptions & root_options, Children... children )

inline

Configure the root container and add builder elements to it (see <AppCore/layout/Builder.h>).

This appends, so calling it twice adds the children twice. To start over, call layout()->RemoveAll() first.

window->BuildLayout({},
  panel({ .key = "toolbar", .size = "44px", .fixed = true }, &toolbar),
  row({ .key = "body", .resizable = true },
    panel({ .key = "sidebar", .size = "240px" }, &sidebar),
    panel({ .key = "content" }, &content)));

Parameters

root_options	The options to apply to the root container.
children	The builder elements to add to the root.

Returns

Returns the root container (so you can chain calls).

ClearFocus()

void ClearFocus

(

)

Take keyboard focus away from every panel.

As with View::Unfocus(), the page's focused element gets a blur event but stays focused in the document, and shows focus again the next time you call Panel::Focus().

Note

If a panel had focus, the window's focus-change callback fires with a null panel.

See also

Panel::Focus(), OnFocusChange()

Close()

virtual void Close ( )

pure virtual

Close the window.

WindowListener::OnClose() fires, the popups this window owns close with it, and the window's panels and layout handles stop working. Calling this again does nothing.

corner_style()

CornerStyle corner_style

(

)

const

Get the window's corner style.

See also

SetCornerStyle()

Create()

RefPtr< Window > Create ( Monitor * monitor, double width, double height, bool fullscreen, WindowFlags window_flags )

static

Create a new Window.

Parameters

monitor	The monitor to create the Window on.
width	The width (in logical pixels).
height	The height (in logical pixels).
fullscreen	Whether or not to create the window fullscreen.
window_flags	How the window looks and behaves (see WindowFlags).

Returns

Returns a ref-pointer to a new Window instance.

Note

The window is shown right away unless you pass WindowFlags::Hidden (call Show() to show it later).

CreatePopup()

RefPtr< Window > CreatePopup ( RefPtr< Window > owner, double x, double y, double width, double height, WindowFlags window_flags = WindowFlags::None )

static

Create a popup window owned by another window.

Popups are borderless, transparent windows that stay above their owner and don't appear in the taskbar. Clicking one doesn't take focus away from the owner, and the library dismisses it like a native menu (see SetDismiss()). Use them for menus, dropdowns, and other short-lived content.

Parameters

owner	The window that owns the popup. The popup stays above it, positions relative to it, and hides with it.
x	The x-position (in logical pixels) from the left of the owner's content area.
y	The y-position (in logical pixels) from the top of the owner's content area.
width	The width (in logical pixels).
height	The height (in logical pixels).
window_flags	Extra window flags (eg, WindowFlags::Hidden for a popup you create once and show when needed).

Returns

Returns a ref-pointer to a new Window instance, or null if owner is null.

Note

Popups always position relative to their owner's content area (this includes MoveTo(), x(), and y()), so you can place one at an element's position in the owner's page without converting it. The position stays correct when the owner's device scale changes.

Note

When the owner closes, its popups close with it (WindowListener::OnClose() fires for each). The popup handle stays valid, but Show() and MoveTo() then only log a warning, so create reusable popups on a window that outlives them.

Note

Popups get rounded corners and a drop shadow by default. For a sharp, shadow-free popup, call SetCornerStyle() with CornerStyle::Square.

See also

SetBackdrop()

default_view_config()

ViewConfig default_view_config

(

)

const

Get the ViewConfig this window uses for a bare AddPanel().

The window fills in what it or the app's Settings decide, and leaves the rest at the defaults:

• initial_device_scale (the window's scale)
• display_id (the window's display)
• is_accelerated (whether the window composites on the GPU)
• match_native_editing_behavior (from Settings::match_native_editing_behavior)
• the font_family_* picks for the host OS (while Settings::auto_font_families is set)

You can use this as a starting point for a View you create yourself:

ViewConfig config = window->default_view_config();
config.enable_javascript = false;
window->AdoptPanel(renderer->CreateView(w, h, config, nullptr));

Returns

Returns a copy of the current values (a later device scale change won't update it).

device_height()

virtual uint32_t device_height ( ) const

pure virtual

Get the window height (in device pixels).

device_width()

virtual uint32_t device_width ( ) const

pure virtual

Get the window width (in device pixels).

DeviceToLogical()

double DeviceToLogical

(

int

val

)

const

Convert device pixels to logical pixels using the window's device scale.

dismiss()

Dismiss dismiss

(

)

const

Get the auto-dismiss setting.

See also

SetDismiss()

DrawSurface()

virtual void DrawSurface ( int x, int y, Surface * surface )

inlinevirtual

Copy a CPU-rendered surface into the window.

The library calls this for you to present CPU-rendered panels; you don't need to call it.

effective_backdrop()

BackdropMaterial effective_backdrop

(

)

const

Get the backdrop material in effect: the requested material while anything shows (a live material or the fallback fill), else BackdropMaterial::None.

See also

SetBackdrop()

effective_backdrop_variant()

BackdropVariant effective_backdrop_variant

(

)

const

Get the look of the backdrop material in effect (BackdropVariant::Auto when none is).

See also

SetBackdrop()

EnableFrameStatistics()

virtual void EnableFrameStatistics ( )

inlinevirtual

Show frame statistics (eg, FPS and frame times) after the window title.

You can't turn this off again.

FindPanel()

RefPtr< Panel > FindPanel

(

const String &

key

)

Find a panel by key anywhere in the window: the tiled layout first, then the foreground layer.

Parameters

key	The panel key to look for.

Returns

Returns a ref-pointer to the matching Panel, or null if no panel in this window has that key.

focused_panel()

RefPtr< Panel > focused_panel

(

)

const

Get the panel holding keyboard focus (null when none does).

foreground()

RefPtr< Foreground > foreground

(

)

Get the window's foreground layer, the floating panels displayed above the window's layout (eg, a toast, an in-window dialog, or a command palette).

auto toast = window->foreground()->AddPanel({ .width = "320px", .height = "80px",
  .placement = Anchor::WindowCorner(AnchorCorner::BottomRight).Offset(-16, -16),
  .focus = FocusPolicy::None });

Floating panels clip to the window. For menus and dropdowns that need to extend outside it, use CreatePopup() instead.

See also

Foreground

height()

virtual double height ( ) const

pure virtual

Get the window height (in logical pixels).

Hide()

virtual void Hide ( )

pure virtual

Hide the window.

Note

Hiding a window also hides the popups it owns.

Invalidate()

void Invalidate

(

)

Redraw the window on an upcoming frame, even if no View has changed.

You can use this to animate content you draw from WindowListener::OnClear() or WindowListener::OnPaint().

is_accelerated()

virtual bool is_accelerated ( ) const

pure virtual

Whether or not the window renders on the GPU.

is_fullscreen()

virtual bool is_fullscreen ( ) const

pure virtual

Whether or not the window is fullscreen.

is_maximized()

virtual bool is_maximized ( ) const

pure virtual

Whether or not the window is maximized.

is_minimized()

virtual bool is_minimized ( ) const

pure virtual

Whether or not the window is minimized.

is_visible()

virtual bool is_visible ( ) const

pure virtual

Whether or not the window is visible (not hidden).

layout()

RefPtr< Container > layout

(

)

Get the window's root layout container (a column that fills the window).

Build the window's content by adding panels and nested containers to it:

auto body = window->layout()->AddRow({ .key = "body", .resizable = true });
body->AddPanel({ .key = "sidebar", .size = "240px" });
body->AddPanel({ .key = "content" });

listener()

virtual WindowListener * listener ( )

pure virtual

Get the WindowListener (can be nullptr).

LogicalToDevice()

int LogicalToDevice

(

double

val

)

const

Convert logical pixels to device pixels using the window's device scale (rounded to the nearest pixel).

Maximize()

virtual void Maximize ( )

pure virtual

Maximize the window.

Popups ignore this with a warning.

Note

On macOS, maximizing a window that isn't resizable changes is_maximized() (and fires WindowListener::OnWindowStateChanged()) without changing the window's size, since the OS only zooms resizable windows. On Windows the window resizes either way.

Minimize()

virtual void Minimize ( )

pure virtual

Minimize the window.

Popups ignore this with a warning.

MoveTo()

virtual void MoveTo ( double x, double y )

pure virtual

Move the window to a new position on the screen.

Parameters

x	The new x-position (in logical pixels).
y	The new y-position (in logical pixels).

Note

Positions are global screen coordinates (one space across all monitors). Popups position relative to their owner's content area instead (see CreatePopup()).

MoveToCenter()

virtual void MoveToCenter ( )

pure virtual

Move the window to the center of the screen.

Note

Popups ignore this with a warning (they position relative to their owner).

native_handle()

virtual void * native_handle ( ) const

pure virtual

Get the native window handle: an HWND on Windows, an NSWindow* on macOS, and a GLFWwindow* on Linux.

OnEditableStateChange() [1/2]

template<typename Callback>
requires std::invocable<Callback&, Panel*, const EditableState&> || std::invocable<Callback&, const EditableState&>

LayoutCallback OnEditableStateChange ( Callback callback )

inlinenodiscard

Register an editable-state callback (invocable form).

Parameters

callback

The callback to fire. It may take the focused panel and state as (Panel*, const EditableState&), or just the state.

Returns

Returns a LayoutCallback controlling how long the callback stays registered.

OnEditableStateChange() [2/2]

LayoutCallback OnEditableStateChange ( LayoutEditableStateCallback callback, void * user_data, LayoutDestroyUserDataCallback destroy_user_data )

nodiscard

Register a callback fired when the focused panel's editable state changes.

This is the window-level form of EditorListener::OnChangeEditableState(): one callback reports the focused panel's state, so a multi-panel app doesn't need to listen on each View (see EditableState in <Ultralight/Editor.h>). You can use it to show and hide an on-screen keyboard, for example.

The callback fires when:

• keyboard focus moves to or from an editable element in the focused panel
• the focused element's inputmode or enterkeyhint changes
• the focused panel's View gains or loses focus
• focus moves to a panel with a different state (removing the focused panel reports a default, nothing-editable state)

Parameters

callback	The callback to fire.
user_data	Pointer to user-defined data, passed back to the callback.
destroy_user_data	Called once when the registration ends, so you can release user_data.

Returns

Returns a LayoutCallback controlling how long the callback stays registered.

Note

The window uses each panel's editor listener to track this (see View::set_editor_listener()). If you replace it on a hosted View, that View's changes stop reaching this callback and the window's input method handling.

Note

Callbacks must not let exceptions propagate.

OnFocusChange() [1/2]

template<typename Callback>
requires std::invocable<Callback&, Panel*> || std::invocable<Callback&>

LayoutCallback OnFocusChange ( Callback callback )

inlinenodiscard

Register a focus-change callback (invocable form).

Parameters

callback

The callback to fire. It may take the newly focused panel as Panel* (null when none), or take nothing at all.

Returns

Returns a LayoutCallback controlling how long the callback stays registered.

OnFocusChange() [2/2]

LayoutCallback OnFocusChange ( LayoutFocusCallback callback, void * user_data, LayoutDestroyUserDataCallback destroy_user_data )

nodiscard

Register a callback fired when the window's focused panel changes (the new panel may be null).

Parameters

callback	The callback to fire.
user_data	Pointer to user-defined data, passed back to the callback.
destroy_user_data	Called once when the registration ends, so you can release user_data.

Returns

Returns a LayoutCallback controlling how long the callback stays registered.

Note

Callbacks must not let exceptions propagate.

render_buffer_id()

virtual uint32_t render_buffer_id ( ) const

pure virtual

Get the ID of the render buffer the window draws into (0 if the window doesn't render on the GPU).

You can use this with the GPUDriver interface to draw into the window (see WindowListener::OnClear()).

Restore()

virtual void Restore ( )

pure virtual

Restore the window from the minimized or maximized state.

Popups ignore this with a warning.

scale()

virtual double scale ( ) const

pure virtual

Get the window's device scale (eg, 2.0 on a Retina display).

set_listener()

virtual void set_listener ( WindowListener * listener )

pure virtual

Set a WindowListener to receive callbacks for window-related events.

Parameters

listener

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

SetAcceptsKeyInput()

void SetAcceptsKeyInput

(

bool

accepts

)

Set whether a popup can take keyboard focus.

(Default: false)

Popups normally never take focus: clicking one leaves focus with the owner, and key presses keep going to the owner, the way native menus work. Turn this on for popups with text fields.

Parameters

accepts

Whether or not the popup can take keyboard focus.

Note

Only popups use this; other windows ignore it.

SetBackdrop()

void SetBackdrop	(	BackdropMaterial	material,
		const BackdropOptions &	options = {} )

Request a native backdrop material for this window.

(Default: BackdropMaterial::None)

// A main window with the native window material, tinted by a translucent dark
// background:
window->SetBackdrop(BackdropMaterial::Window);
window->SetBackgroundColor("rgba(32, 32, 32, 0.5)");

Not every platform, OS version, or window can render a live material. When one can't, the library uses the nearest look it can, down to a solid fallback fill in the theme's color. You can read back what's showing:

What shows	effective_backdrop()	effective_backdrop_variant()
A live translucent material	the requested material	BackdropVariant::Frosted
An opaque wallpaper material	the requested material	BackdropVariant::Matte
The fallback fill	the requested material	BackdropVariant::Matte
Nothing	BackdropMaterial::None	BackdropVariant::Auto

On Windows and macOS, CPU-rendered and fullscreen windows can't show a material at all and report BackdropMaterial::None. Linux always shows at least the fallback fill.

The material shows untinted until you set a background color. To tint it, set a translucent one: the lower the alpha, the more of the material shows through.

See also

SetBackgroundColor()

Parameters

material	The material to request (BackdropMaterial::None removes it).
options	Optional settings: the look, the light/dark theme, the fallback color, and the style (see BackdropOptions).

Note

To react when what's showing changes later, listen for WindowListener::OnBackdropChanged().

SetBackdropState()

void SetBackdropState

(

BackdropState

state

)

Set whether the backdrop material shows its active or inactive look.

By default the material follows the window, like native windows do. Popups always show the active look by default, since a popup is never the active window.

Parameters

state

The look to show.

Note

Linux ignores this. So do titled windows on newer Windows 11 builds, where the OS draws the material itself and controls its inactive look.

SetBackgroundColor()

void SetBackgroundColor

(

const Color &

color

)

Set the window background color.

The background is drawn beneath the window's content each frame and shows wherever no View covers the window.

An unset color (the default) means:

Window	Unset background
Plain opaque	Opaque white
Transparent	Nothing: the window is see-through
Backdrop material in effect	Nothing: the material shows untinted

A color you set always draws. On transparent windows and over a backdrop material its alpha is used (over a material, it acts as the material's tint). On plain opaque windows the alpha is ignored.

Parameters

color

The new background color. Pass an unset color to go back to the default; an invalid color is ignored with a warning.

Note

On Windows and macOS, while a backdrop material is in effect, setting a background color also stops the material from following later OS light/dark theme changes, so the colors you picked keep matching it.

SetCaptionColor()

void SetCaptionColor

(

const Color &

color

)

Set the title bar color.

The title text color is picked automatically for contrast. This only works on Windows 11; other platforms, and windows without a system title bar (eg, custom-chrome windows), ignore it.

Parameters

color

The new title bar color. Pass an unset color to go back to the system color; an invalid color is ignored with a warning.

Note

A set title bar color covers any backdrop material there; unset lets the material show through the title bar.

SetCornerStyle()

void SetCornerStyle

(

CornerStyle

style

)

Set the window's corner style (see CornerStyle).

(Default: CornerStyle::Default)

On transparent windows the library rounds the window's content to match.

Parameters

style

The corner style to use.

Note

On macOS this only affects transparent windows; other windows keep the OS's own corners and shadow.

SetCursor()

virtual void SetCursor ( ultralight::Cursor cursor )

pure virtual

Set the cursor.

Parameters

cursor

The cursor to show over the window.

Note

The library sets the cursor for web content automatically (link hands, the text I-beam, CSS cursor rules), so you don't need to call this for pages. A cursor you set here lasts until the mouse next moves over a page.

SetDismiss()

void SetDismiss

(

Dismiss

dismiss

)

Set whether the library dismisses this popup automatically.

(Default: Dismiss::Auto for popups)

With Dismiss::Auto, the library hides the popup when the OS would dismiss a native menu:

• a click in the owner, outside the popup
• a click on the owner's title bar or border (where the platform reports these)
• the owner starting a move or resize, scrolling, or becoming inactive
• Esc while the owner has focus (a popup that takes key input also closes on Esc while it has focus; see SetAcceptsKeyInput())

Dismissing hides the popup but doesn't destroy it, so you can show it again. WindowListener::OnDismiss() fires each time.

Parameters

dismiss

Whether or not to dismiss the popup automatically.

Note

Only popups use this; other windows ignore it.

Note

The library checks for dismissal before WindowListener sees the event, so consuming the event doesn't stop the popup from being dismissed.

SetDividerStyle()

void SetDividerStyle

(

const DividerStyle &

style

)

Set the default divider style for every resizable container in this window (see <AppCore/layout/DividerStyle.h>).

Fields you leave unset keep the library's defaults, and Container::SetDividerStyle() overrides them per container. The change takes effect on the next layout.

Parameters

style

The divider style to use as this window's default.

SetHitTestRegions()

void SetHitTestRegions	(	const HitTestRegion *	regions,
		size_t	count )

Mark which areas of your custom chrome drag the window or act as caption buttons.

Only custom-chrome windows use this; other windows ignore it with a warning. See the Custom Chrome section in the class overview for an example.

Regions are in window content coordinates. They don't move or scale with the window, so set them again whenever your chrome's layout changes (WindowListener::OnResize() is a good place).

• Caption regions act like a real title bar: dragging moves the window, double-clicking maximizes or restores it, and the page under them gets no mouse input. On Windows, right-clicking one opens the system window menu.
• Button regions still send hover to the page (so your chrome can style :hover), but a click performs the window action. Style pressed states from hover or the window state callbacks.

Parameters

regions	The full list of regions, replacing any previous list (pass a nullptr to clear it).
count	The number of entries in regions (0 clears the list).

Note

Where regions overlap, later entries win. The resize edges always win over regions, and a button region for an action you turned off with SetWindowButtons() is ignored. Pages can also mark drag areas with the app-region CSS property; regions you set here win where the two overlap.

SetIcon()

virtual void SetIcon ( RefPtr< Bitmap > icon )

pure virtual

Set the window icon (shown in the title bar and taskbar).

Parameters

icon	A 32-bit BGRA bitmap with straight (unpremultiplied) alpha. Pass a nullptr to restore the default icon (Settings::app_icon when set, else the platform's standard icon).

Note

macOS windows don't show an icon (the Dock icon comes from Settings::app_icon or your app bundle), so this does nothing there.

SetTitle()

virtual void SetTitle ( const char * title )

pure virtual

Set the window title.

Parameters

title

The new title, as a UTF-8 string.

Note

Custom-chrome windows don't draw a system title bar, but the OS still shows the title elsewhere (eg, the taskbar and window switcher).

SetWindowButtons()

void SetWindowButtons

(

WindowButtons

buttons

)

Set which window actions are available to the user.

This covers every way to trigger an action: native and custom caption buttons, double-clicking the title bar, the system window menu, and OS shortcuts and snap gestures. By default Close is available, and Minimize and Maximize are available when the window was created with WindowFlags::Maximizable.

Parameters

buttons

The actions to make available.

Note

Popups ignore this with a warning.

SetWindowControlInset()

void SetWindowControlInset	(	double	x,
		double	y )

Move the native window buttons on a macOS custom-chrome window (other windows ignore this).

Parameters

x	The offset (in logical pixels) from the leading edge of the content area (mirrored automatically in right-to-left layouts).
y	The offset (in logical pixels) from the top of the content area.

Note

The offset positions the buttons' frames, which extend a little past the visible circles.

See also

window_control_bounds()

Show()

virtual void Show ( )

pure virtual

Show the window (if it was hidden).

Note

On macOS, showing a minimized window briefly brings it on screen (and takes focus) before it minimizes to the Dock. On Windows it appears minimized directly.

ShowWhenReady()

void ShowWhenReady

(

double

timeout_seconds = 0.5

)

Show the window once its pages have settled.

Call this instead of Show() on a window created hidden (WindowFlags::Hidden), after adding panels and starting their page loads. This avoids displaying a blank or half-loaded first frame.

While waiting, the window stays hidden– its pages continue to load, run scripts, and lay out.

The window shows once every page in a visible panel has settled (LoadListener::OnPageSettled()).

A panel with no page loaded does not delay showing the window.

If the pages have not settled when the timeout elapses, the window shows anyway.

Parameters

timeout_seconds

The maximum time to wait, in seconds. Pass 0 to show the window immediately.

Note

Calling Show() or Hide() before the window shows cancels the wait– Show() shows the window immediately, while Hide() keeps it hidden.

Note

If the window is already visible, this call does nothing.

TakeScreenshot()

virtual RefPtr< Bitmap > TakeScreenshot ( )

inlinevirtual

Capture a screenshot of the window.

Returns

Returns a Bitmap with the window's pixels in BGRA8_UNORM_SRGB format, or an empty ref-pointer if the capture fails.

Note

This captures what was last shown on screen, so anything drawn since the last frame isn't included.

width()

virtual double width ( ) const

pure virtual

Get the window width (in logical pixels).

window_buttons()

WindowButtons window_buttons

(

)

const

Get the window actions available to the user.

See also

SetWindowButtons()

window_control_bounds()

virtual Rect window_control_bounds ( ) const

inlinevirtual

Get the area the native window buttons cover (in window content coordinates), so you can leave room for them.

Only macOS custom-chrome windows have these buttons over their content (the traffic lights). Other windows, and macOS windows in fullscreen (where the buttons hide), get an empty rect.

The area changes with SetWindowControlInset(), device scale changes, and fullscreen, so read it again after calling SetWindowControlInset() and in WindowListener::OnResize().

x()

virtual double x ( ) const

pure virtual

Get the x-position of the window (in logical pixels).

See also

MoveTo()

y()

virtual double y ( ) const

pure virtual

Get the y-position of the window (in logical pixels).

See also

MoveTo()

---

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

• AppCore/Window.h