#include <Ultralight/dom/Window.h>

Overview

The viewport of a DOM document.

A Window is a handle to the visual window that displays a document. You use it to inspect viewport dimensions and to listen for events that fire only on the window, such as load and resize.

This example updates a native HUD when the viewport resizes:

dom::Window window = document.defaultView();
window.addEventListener("resize", [window] {
  FitHud(window.innerWidth(), window.innerHeight(),
         window.devicePixelRatio());
});

Getting a Window

You can access a window through the View or a specific document:

Pass a View to Window(view) for the main frame.
Call Document::defaultView() on any frame's document. This returns the window of that specific frame inside the page.

You should obtain a Window in LoadListener::OnDOMReady() or later. Before your first page loads, a View holds only the frame's initial blank page, and its window goes away when the new page loads.

Viewport Coordinates

Viewport sizes and scroll positions use CSS pixels. To convert CSS pixels to View pixels, multiply by View::device_scale() (or devicePixelRatio()), or divide View pixels by the scale factor to convert back.

Window Events

Events such as load and resize fire on the window only, so document listeners never receive them. Viewport scroll events fire on the document first and bubble up to the window.

Listeners receive resize and scroll events when the View next paints, rather than during the call that caused the change.

A load listener added in LoadListener::OnDOMReady() still receives the page's load event, which fires once all external resources finish loading.

Note: Like other DOM handles, a Window is Valid, Empty, or Gone, and never keeps its page alive (see dom::Element).

See also: dom::Document::defaultView(), LoadListener::OnDOMReady(), dom::Element::addEventListener(), View::device_scale()

Static Public Member Functions
static Window	Adopt (ULDOMWindow handle)
	Wrap a C handle you own, taking ownership of it.
static Window	FromBorrowed (ULDOMWindow handle)
	Wrap a C handle the library owns, adding a reference.

Public Member Functions
	Window ()=default
	Create an empty Window.
	Window (View *view)
	Get the window of a View's main frame.
	Window (const Window &other)
	Copy constructor (both handles refer to the same window).
	Window (Window &&other) noexcept
	Move constructor (other becomes empty).
Window &	operator= (Window other) noexcept
	Assignment (copies or moves).
	~Window ()
	Destroy this handle (the window itself isn't affected).
	operator bool () const
	Whether or not this Window is valid (see IsAlive()).
bool	IsEmpty () const
	Whether or not this Window is empty (it holds no handle).
bool	IsAlive () const
	Whether or not this Window is valid (it isn't empty and its page is still alive).
int	innerWidth () const
	Get the viewport width (innerWidth).
int	innerHeight () const
	Get the viewport height (innerHeight).
double	devicePixelRatio () const
	Get the ratio of device pixels to CSS pixels (devicePixelRatio).
double	scrollX () const
	Get the viewport's horizontal scroll position (scrollX).
double	scrollY () const
	Get the viewport's vertical scroll position (scrollY).
void	scrollTo (double x, double y) const
	Scroll the viewport to a position (scrollTo).
void	scrollBy (double x, double y) const
	Scroll the viewport by an offset (scrollBy).
ComputedStyle	getComputedStyle (const Element &element) const
	Get an element's computed style (getComputedStyle).
Document	document () const
	Get the window's document (document).
Selection	getSelection () const
	Get the page's selection (getSelection), the caret or the highlighted text.
bool	dispatchEvent (std::string_view type, const EventInit &init={}) const
	Dispatch a synthetic event to the window (dispatchEvent).
bool	dispatchCustomEvent (std::string_view type, std::string_view event_detail, const EventInit &init={}) const
	Dispatch a synthetic CustomEvent with a string payload to the window.
template<typename F>
EventListener	addEventListener (std::string_view type, F &&callback, const AddEventListenerOptions &options={}) const
	Listen for an event on the window (addEventListener).
template<typename F>
EventListener	addEventListener (std::string_view type, F &&callback, EventListenerFlags flags) const
	Listen for an event on the window, with options as flags (eg, dom::Once \| dom::Capture).
template<typename C, typename M> requires (std::is_class_v<C> && std::is_member_function_pointer_v<M> && !LockableHolder<C>)
EventListener	addEventListener (std::string_view type, C &receiver, M method, const AddEventListenerOptions &options={}) const
	Listen by calling a member function on an object you keep alive.
template<typename C, typename M> requires (std::is_class_v<C> && std::is_member_function_pointer_v<M> && !LockableHolder<C>)
EventListener	addEventListener (std::string_view type, C &receiver, M method, EventListenerFlags flags) const
	Listen by calling a member function on an object you keep alive, with options as flags.
template<typename H, typename M> requires (LockableHolder<H> && std::is_member_function_pointer_v<M>)
EventListener	addEventListener (std::string_view type, H holder, M method, const AddEventListenerOptions &options={}) const
	Listen by calling a member function through a smart pointer that's checked before each call.
template<typename H, typename M> requires (LockableHolder<H> && std::is_member_function_pointer_v<M>)
EventListener	addEventListener (std::string_view type, H holder, M method, EventListenerFlags flags) const
	Listen by calling a member function through a smart pointer, with options as flags.
ULDOMWindow	raw () const
	Get the C handle, for passing to the <Ultralight/CAPI/CAPI_DOMWindow.h> functions.
ULDOMWindow	LeakRef ()
	Give up ownership of the C handle and return it.

Protected Member Functions
	Window (ULDOMWindow handle)

Constructor & Destructor Documentation

◆ Window() [1/5]

Window ( )

default

Create an empty Window.

◆ Window() [2/5]

Window ( View * view )

inlineexplicit

Get the window of a View's main frame.

To get the window of a frame inside the page, call Document::defaultView() on that frame's document.

Parameters

view	The View to get the window from (nullptr gives an empty Window).

Note: Before your first page commits, this is the window of the frame's initial blank page, and it goes away when your page commits. Get it in LoadListener::OnDOMReady() or later.

◆ Window() [3/5]

Window ( const Window & other )

inline

Copy constructor (both handles refer to the same window).

Parameters

other The Window to copy.

◆ Window() [4/5]

Window ( Window && other )

inlinenoexcept

Move constructor (other becomes empty).

Parameters

other The Window to move from.

◆ ~Window()

~Window ( )

inline

Destroy this handle (the window itself isn't affected).

◆ Window() [5/5]

Window ( ULDOMWindow handle )

inlineexplicitprotected

Member Function Documentation

◆ addEventListener() [1/6]

template<typename C, typename M>
requires (std::is_class_v<C> && std::is_member_function_pointer_v<M> && !LockableHolder<C>)

EventListener addEventListener	(	std::string_view	type,
		C &	receiver,
		M	method,
		const AddEventListenerOptions &	options = {} ) const

inline

Listen by calling a member function on an object you keep alive.

Parameters

type	The event type to listen for.
receiver	The object to call method on.
method	The member function to call, taking (dom::Event) or ().
options	The listener's options (see AddEventListenerOptions).

Returns: Returns a handle for removing the listener, which you can ignore. It's empty when nothing was added (the page is gone or options.signal is already aborted).

Warning: The listener calls receiver for as long as it lives, so receiver must outlive the page, or the listener must be added with the signal of an AbortController that receiver owns. The smart-pointer overload with a std::weak_ptr skips calls once the object is gone instead.

◆ addEventListener() [2/6]

template<typename C, typename M>
requires (std::is_class_v<C> && std::is_member_function_pointer_v<M> && !LockableHolder<C>)

EventListener addEventListener	(	std::string_view	type,
		C &	receiver,
		M	method,
		EventListenerFlags	flags ) const

inline

Listen by calling a member function on an object you keep alive, with options as flags.

Parameters

type	The event type to listen for.
receiver	The object to call method on.
method	The member function to call, taking (dom::Event) or ().
flags	The listener's options (see EventListenerFlags).

Returns: Returns a handle for removing the listener, which you can ignore (empty when the page is gone).

Warning: The listener calls receiver for as long as it lives, so receiver must outlive the page. To tie the listener to receiver instead, use the options overload with the signal of an AbortController that receiver owns.

◆ addEventListener() [3/6]

template<typename F>

EventListener addEventListener	(	std::string_view	type,
		F &&	callback,
		const AddEventListenerOptions &	options = {} ) const

inline

Listen for an event on the window (addEventListener).

This works like Element::addEventListener(). The window receives load, resize, and viewport scroll events (see the Window class).

Parameters

type	The event type to listen for (eg, resize).
callback	The callable to run on each event, taking (dom::Event) or ().
options	The listener's options (see AddEventListenerOptions).

Returns: Returns a handle for removing the listener, which you can ignore. It's empty when nothing was added (the page is gone or options.signal is already aborted).

Note: A load or viewport scroll event reports the document as its target, so Event::target() reads empty.

◆ addEventListener() [4/6]

template<typename F>

EventListener addEventListener	(	std::string_view	type,
		F &&	callback,
		EventListenerFlags	flags ) const

inline

Listen for an event on the window, with options as flags (eg, dom::Once | dom::Capture).

Parameters

type	The event type to listen for.
callback	The callable to run on each event, taking (dom::Event) or ().
flags	The listener's options (see EventListenerFlags).

Returns: Returns a handle for removing the listener, which you can ignore (empty when the page is gone).

◆ addEventListener() [5/6]

template<typename H, typename M>
requires (LockableHolder<H> && std::is_member_function_pointer_v<M>)

EventListener addEventListener	(	std::string_view	type,
		H	holder,
		M	method,
		const AddEventListenerOptions &	options = {} ) const

inline

Listen by calling a member function through a smart pointer that's checked before each call.

Parameters

type	The event type to listen for.
holder	A shared_ptr, a weak_ptr, or another smart pointer with a HolderTraits specialization (see LockableHolder). While it's expired, events are skipped.
method	The member function to call, taking (dom::Event) or ().
options	The listener's options (see AddEventListenerOptions).

Returns: Returns a handle for removing the listener, which you can ignore. It's empty when nothing was added (the page is gone or options.signal is already aborted).

◆ addEventListener() [6/6]

template<typename H, typename M>
requires (LockableHolder<H> && std::is_member_function_pointer_v<M>)

EventListener addEventListener	(	std::string_view	type,
		H	holder,
		M	method,
		EventListenerFlags	flags ) const

inline

Listen by calling a member function through a smart pointer, with options as flags.

Parameters

type	The event type to listen for.
holder	A shared_ptr, a weak_ptr, or another smart pointer with a HolderTraits specialization (see LockableHolder). While it's expired, events are skipped.
method	The member function to call, taking (dom::Event) or ().
flags	The listener's options (see EventListenerFlags).

Returns: Returns a handle for removing the listener, which you can ignore (empty when the page is gone).

◆ Adopt()

Window Adopt ( ULDOMWindow handle )

inlinestatic

Wrap a C handle you own, taking ownership of it.

Parameters

handle A handle from the C API that you would otherwise destroy with ulDestroyDOMWindow() (NULL gives an empty Window).

Returns: Returns a Window that destroys handle when it's done.

◆ devicePixelRatio()

double devicePixelRatio ( ) const

inline

Get the ratio of device pixels to CSS pixels (devicePixelRatio).

Returns: Returns the View's device scale (see View::device_scale()).

◆ dispatchCustomEvent()

bool dispatchCustomEvent	(	std::string_view	type,
		std::string_view	event_detail,
		const EventInit &	init = {} ) const

inline

Dispatch a synthetic CustomEvent with a string payload to the window.

This works like Element::dispatchCustomEvent().

Parameters

type	The event type to dispatch.
event_detail	The payload as UTF-8 text, which listeners read as the event's detail (see Element::dispatchCustomEvent()).
init	The event's bubbles, cancelable, and composed flags (see EventInit).

Returns: Returns false if a listener canceled the event with Event::preventDefault() (which needs init.cancelable), or true otherwise.

◆ dispatchEvent()

bool dispatchEvent	(	std::string_view	type,
		const EventInit &	init = {} ) const

inline

Dispatch a synthetic event to the window (dispatchEvent).

This works like Element::dispatchEvent().

Parameters

type	The event type to dispatch.
init	The event's bubbles, cancelable, and composed flags (see EventInit).

Returns: Returns false if a listener canceled the event with Event::preventDefault() (which needs init.cancelable), or true otherwise.

◆ document()

Document document ( ) const

inline

Get the window's document (document).

Returns: Returns the document (empty if this Window is empty).

◆ FromBorrowed()

Window FromBorrowed ( ULDOMWindow handle )

inlinestatic

Wrap a C handle the library owns, adding a reference.

Parameters

handle The borrowed handle (NULL gives an empty Window).

Returns: Returns a Window with its own reference.

◆ getComputedStyle()

ComputedStyle getComputedStyle ( const Element & element ) const

inline

Get an element's computed style (getComputedStyle).

This is the same as dom::getComputedStyle(), which you can call without a Window.

Parameters

element The element to read.

Returns: Returns a read-only view of the element's computed style (see ComputedStyle).

◆ getSelection()

Selection getSelection ( ) const

inline

Get the page's selection (getSelection), the caret or the highlighted text.

Returns: Returns the selection of this window's document (the same one Document::getSelection() returns).

Note: Include <Ultralight/dom/Selection.h> (or <Ultralight/DOM.h>) to use this.

◆ innerHeight()

int innerHeight ( ) const

inline

Get the viewport height (innerHeight).

Returns: Returns the height in CSS pixels, including the horizontal scrollbar if there is one.

◆ innerWidth()

int innerWidth ( ) const

inline

Get the viewport width (innerWidth).

Returns: Returns the width in CSS pixels, including the vertical scrollbar if there is one.

◆ IsAlive()

bool IsAlive ( ) const

inline

Whether or not this Window is valid (it isn't empty and its page is still alive).

Note: Safe to call from any thread.

◆ IsEmpty()

bool IsEmpty ( ) const

inline

Whether or not this Window is empty (it holds no handle).

◆ LeakRef()

ULDOMWindow LeakRef ( )

inline

Give up ownership of the C handle and return it.

This Window becomes empty.

Returns: Returns the handle. You must call ulDestroyDOMWindow() when finished.

◆ operator bool()

operator bool ( ) const

inlineexplicit

Whether or not this Window is valid (see IsAlive()).

◆ operator=()

Window & operator= ( Window other )

inlinenoexcept

Assignment (copies or moves).

Parameters

other The Window to assign from.

Returns: Returns this Window.

◆ raw()

ULDOMWindow raw ( ) const

inline

Get the C handle, for passing to the <Ultralight/CAPI/CAPI_DOMWindow.h> functions.

Returns: Returns the handle (NULL for an empty Window). This Window still owns it, so don't destroy it.

◆ scrollBy()

void scrollBy	(	double	x,
		double	y ) const

inline

Scroll the viewport by an offset (scrollBy).

The page scrolls the same way as with scrollTo().

Parameters

x	The horizontal offset in CSS pixels.
y	The vertical offset in CSS pixels.

◆ scrollTo()

void scrollTo	(	double	x,
		double	y ) const

inline

Scroll the viewport to a position (scrollTo).

The page scrolls at once (CSS scroll-behavior is ignored), and the position stays within the scrollable area.

Parameters

x	The horizontal position in CSS pixels (any fraction is dropped).
y	The vertical position in CSS pixels (any fraction is dropped).

◆ scrollX()

double scrollX ( ) const

inline

Get the viewport's horizontal scroll position (scrollX).

Returns: Returns the position in CSS pixels (the library currently reports whole pixels).

◆ scrollY()

double scrollY ( ) const

inline

Get the viewport's vertical scroll position (scrollY).

Returns: Returns the position in CSS pixels (the library currently reports whole pixels).

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

Ultralight/dom/Window.h
Ultralight/dom/Selection.h

Overview

Getting a Window

Viewport Coordinates

Window Events

Static Public Member Functions

Public Member Functions

Protected Member Functions

Constructor & Destructor Documentation

◆ Window() [1/5]

◆ Window() [2/5]

◆ Window() [3/5]

◆ Window() [4/5]

◆ ~Window()

◆ Window() [5/5]

Member Function Documentation

◆ addEventListener() [1/6]

◆ addEventListener() [2/6]

◆ addEventListener() [3/6]

◆ addEventListener() [4/6]

◆ addEventListener() [5/6]

◆ addEventListener() [6/6]

◆ Adopt()

◆ devicePixelRatio()

◆ dispatchCustomEvent()

◆ dispatchEvent()

◆ document()

◆ FromBorrowed()

◆ getComputedStyle()

◆ getSelection()

◆ innerHeight()

◆ innerWidth()

◆ IsAlive()

◆ IsEmpty()

◆ LeakRef()

◆ operator bool()

◆ operator=()

◆ raw()

◆ scrollBy()

◆ scrollTo()

◆ scrollX()

◆ scrollY()