Foreground

#include <AppCore/layout/Foreground.h>

Overview

Floating layer that displays panels above a window's layout.

The foreground layer hosts overlays like heads-up displays and dialogs without shifting the panels beneath them. You reach it through Window::foreground().

Call AddPanel() to float a panel with a new View:

RefPtr<Panel> hud = window->foreground()->AddPanel(
    { .width = "200px", .height = "120px", .placement = Anchor::At(24, 24) });
hud->view()->LoadURL("file:///hud.html");

Adding Floating Panels

A floating panel is an ordinary Panel without a parent container (see Panel). Call AdoptPanel() to float a View you already have.

Size and Placement

Set dimensions and placement through ForegroundPanelOptions when adding a panel (see Anchor). The options also configure auto-dismissal and keyboard focus behavior.

A floating panel's size and placement are fixed at creation.

To move or resize a panel, re-adopt its View with updated options:

RefPtr<View> hud_view = hud->view();  // before Remove(), which drops it
window->foreground()->Remove(hud);
hud = window->foreground()->AdoptPanel(
    hud_view, { .width = "200px", .height = "120px",
                .placement = Anchor::WindowCenter() });

Stacking and Removal

Floating panels stack in the order you add them, with the newest panel on top. Call Panel::BringToFront() to move a panel to the top of the layer so it paints on top and receives mouse input first.

Dropping a panel handle doesn't remove it from the layer. Call Remove() to detach a floating panel.

Calls on a handle stay safe and do nothing after a panel is removed or after the window closes, and Panel::view() returns null (see LayoutNode).

Note

Floating panels clip to the window (use Window::CreatePopup() for menus and dropdowns that extend past it).

See also

Window::foreground(), ForegroundPanelOptions, Anchor, Panel::BringToFront(), Window::CreatePopup()

Inheritance diagram for Foreground:

Public Member Functions
virtual RefPtr< Panel >	AddPanel (const ForegroundPanelOptions &options={})=0
	Create a floating panel with a new View (window-default view configuration).
virtual RefPtr< Panel >	AddPanel (const ForegroundPanelOptions &options, const ViewConfig &view_config)=0
	Create a floating panel with a caller-supplied ViewConfig (the same rules as Container::AddPanel()).
virtual RefPtr< Panel >	AdoptPanel (RefPtr< View > view, const ForegroundPanelOptions &options={})=0
	Create a floating panel that adopts an existing View (including a View created through a Session, or one that survived Remove()).
template<typename ViewRef> requires std::convertible_to<ViewRef&&, RefPtr<View>>
RefPtr< Panel >	AddPanel (ViewRef &&view, const ForegroundPanelOptions &options={})
	Adopt an existing View (shorthand for AdoptPanel()).
virtual bool	Remove (RefPtr< Panel > panel)=0
	Remove a floating panel from the foreground layer.
virtual int	panel_count () const =0
	Get the number of floating panels (hidden panels included).
virtual RefPtr< Panel >	panel_at (int index) const =0
	Get the floating panel at an index in current z-order, bottom-most first.
virtual RefPtr< Panel >	FindPanel (const String &key)=0
	Find a floating panel by key.
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.

Protected Member Functions
virtual	~Foreground ()
Protected Member Functions inherited from RefCounted
virtual	~RefCounted ()

Constructor & Destructor Documentation

~Foreground()

virtual ~Foreground ( )

protectedvirtual

Member Function Documentation

AddPanel() [1/3]

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

pure virtual

Create a floating panel with a caller-supplied ViewConfig (the same rules as Container::AddPanel()).

Parameters

options	The panel's declared options.
view_config	The configuration for the new View. The fields describing the hosting window are filled in from the window for you.

Returns

Returns the new panel (see LayoutNode if the window has closed).

AddPanel() [2/3]

virtual RefPtr< Panel > AddPanel ( const ForegroundPanelOptions & options = {} )

pure virtual

Create a floating panel with a new View (window-default view configuration).

Parameters

options

The panel's declared options.

Returns

Returns the new panel (see LayoutNode if the window has closed).

AddPanel() [3/3]

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

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

inline

Adopt an existing View (shorthand for AdoptPanel()).

Parameters

view	The View to host.
options	The panel's declared options.

Returns

Returns the new panel (see LayoutNode if the window has closed).

AdoptPanel()

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

pure virtual

Create a floating panel that adopts an existing View (including a View created through a Session, or one that survived Remove()).

The panel takes a reference to the View and resizes it to the panel's bounds.

Parameters

view	The View to host.
options	The panel's declared options.

Returns

Returns the new panel (see LayoutNode if the window has closed).

Note

The panel replaces the View's editor listener with its own (see Panel).

FindPanel()

virtual RefPtr< Panel > FindPanel ( const String & key )

pure virtual

Find a floating panel by key.

Parameters

key	The key to look for.

Returns

Returns the matching panel, or null when nothing matches. With duplicate keys the most recently created match wins.

panel_at()

virtual RefPtr< Panel > panel_at ( int index ) const

pure virtual

Get the floating panel at an index in current z-order, bottom-most first.

Parameters

index

The zero-based index in z-order.

Returns

Returns the panel, or null when the index is out of range.

panel_count()

virtual int panel_count ( ) const

pure virtual

Get the number of floating panels (hidden panels included).

Remove()

virtual bool Remove ( RefPtr< Panel > panel )

pure virtual

Remove a floating panel from the foreground layer.

Removal drops the panel's reference to its View. A View the application holds a RefPtr to survives and can be adopted elsewhere. For what removed handles do afterwards, see LayoutNode.

Parameters

panel

The floating panel to remove. A panel that is not one of this window's floating panels is a no-op with a warning.

Returns

Returns whether or not the panel was one of this window's floating panels and was removed.

---

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

• AppCore/layout/Foreground.h