#include <AppCore/layout/Panel.h>

Overview

A layout node that hosts a single web view.

Panels are the leaf nodes of an AppCore layout tree and the elements of its floating layer. Every panel hosts a single View, sizing the view to match its layout bounds and routing user input to the page.

This example adds a panel to a window, loads a page into its view, and gives the panel keyboard focus:

RefPtr<Panel> content = window->AddPanel({ .key = "content" });
content->view()->LoadURL("file:///app.html");
content->Focus();

Hosting a View

Call view() to access the hosted View.

You can create a panel with a new View or adopt an existing View:

New views come from AddPanel(). Calling Container::AddPanel(), Window::AddPanel(), or Foreground::AddPanel() creates a panel alongside a fresh View configured for the parent window.
Existing views are adopted into layout. Calling Container::AdoptPanel() or Foreground::AdoptPanel() creates a panel that hosts a View you created yourself, such as a View created through a Session or one that survived removal from another panel.

Warning: Never replace the editor listener on a panel's View. Replacing it disables the window's input method support and stops Window::OnEditableStateChange() from firing for that panel.

Keyboard Focus

A window directs keyboard events to one panel at a time:

Clicking a panel or calling Focus() grants keyboard focus.
Never call View::Focus() on a panel's View. Focusing the view directly bypasses the window and prevents it from routing keyboard input to the active panel.
The window tracks the active panel. Call Window::focused_panel() to retrieve the focused panel, or listen for focus transitions with Window::OnFocusChange().

Note: BringToFront() and OnDismiss() apply to floating panels only.

See also: LayoutNode, Container::AddPanel(), Container::AdoptPanel(), Foreground, Window::focused_panel(), Window::OnFocusChange()

Inheritance diagram for Panel:

Public Member Functions
virtual RefPtr< View >	view ()=0
	Get the hosted View.
virtual void	Focus ()=0
	Grant this panel exclusive keyboard focus.
virtual void	BringToFront ()=0
	Bring this floating panel to the top of the foreground layer so it paints on top of other floating panels and receives mouse input first.
virtual LayoutCallback	OnDismiss (LayoutPanelCallback callback, void *user_data, LayoutDestroyUserDataCallback destroy_user_data)=0
	Register a callback fired when the library dismisses this panel.
template<typename Callback> requires std::invocable<Callback&, Panel&> \|\| std::invocable<Callback&>
LayoutCallback	OnDismiss (Callback callback)
	Register a dismiss callback (invocable form).
Public Member Functions inherited from LayoutNode
virtual String	key () const =0
	Get the node's key (empty if unkeyed).
virtual RefPtr< Container >	parent () const =0
	Get the node's parent container (null at the root or when detached).
virtual int	index () const =0
	Get the node's index within its parent (-1 when detached).
virtual RefPtr< Panel >	AsPanel ()=0
	Get this node as a Panel (null if it is not one).
virtual RefPtr< Container >	AsContainer ()=0
	Get this node as a Container (null if it is not one).
virtual void	Hide ()=0
	Hide the node and redistribute its space to its siblings.
virtual void	Show ()=0
	Show the node again, restoring its remembered size exactly.
virtual bool	is_hidden () const =0
	Whether or not the node is hidden.
virtual Rect	bounds () const =0
	Get the node's rect from the most recent layout in container-local logical pixels (the same space SetBounds() takes).
virtual IntRect	device_bounds () const =0
	Get the node's rect from the most recent layout in window back-buffer device pixels (the space your own drawing uses).
virtual void	SetBounds (const Rect &bounds)=0
	Place this node manually.
virtual void	SetSize (Size size)=0
	Set the node's declared size along its container's axis.
virtual void	SetMinSize (Length min_size)=0
	Set the node's minimum size constraint.
virtual void	SetMaxSize (Length max_size)=0
	Set the node's maximum size constraint.
virtual LayoutCallback	OnUserResize (LayoutNodeCallback callback, void *user_data, LayoutDestroyUserDataCallback destroy_user_data)=0
	Register a callback fired when the user resizes this node with a divider.
virtual LayoutCallback	OnLayoutChange (LayoutNodeCallback callback, void *user_data, LayoutDestroyUserDataCallback destroy_user_data)=0
	Register a callback that fires after layout changes this node's bounds (at most once per frame).
template<typename Callback> requires std::invocable<Callback&, LayoutNode&> \|\| std::invocable<Callback&>
LayoutCallback	OnUserResize (Callback callback)
	Register a user-resize callback (invocable form).
template<typename Callback> requires std::invocable<Callback&, LayoutNode&> \|\| std::invocable<Callback&>
LayoutCallback	OnLayoutChange (Callback callback)
	Register a layout-change callback (invocable form).
RefPtr< LayoutNode >	next_sibling () const
	Get the sibling after this node (null at the end, at the root, or when detached).
RefPtr< LayoutNode >	previous_sibling () const
	Get the sibling before this node (null at the start, at the root, or when detached).
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	~Panel ()
Protected Member Functions inherited from LayoutNode
virtual	~LayoutNode ()
Protected Member Functions inherited from RefCounted
virtual	~RefCounted ()

Constructor & Destructor Documentation

◆ ~Panel()

virtual ~Panel ( )

protectedvirtual

Member Function Documentation

◆ BringToFront()

virtual void BringToFront ( )

pure virtual

Bring this floating panel to the top of the foreground layer so it paints on top of other floating panels and receives mouse input first.

Note: This method only applies to floating panels. A tiled panel composites in tree order, so calling BringToFront() on it does nothing and logs a warning.

◆ Focus()

virtual void Focus ( )

pure virtual

Grant this panel exclusive keyboard focus.

You should always focus a panel through this method (or a user click) rather than calling View::Focus() directly, otherwise the panel's window won't know where to route keyboard input.

Note: Focusing a hidden panel (or one inside a hidden container) is ignored with a warning. So is focusing a floating panel created with FocusPolicy::None, which never takes keyboard focus.

◆ OnDismiss() [1/2]

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

LayoutCallback OnDismiss ( Callback callback )

inlinenodiscard

Register a dismiss callback (invocable form).

Parameters

callback Any invocable. It may take the panel as Panel&, or nothing at all.

Returns: Returns a LayoutCallback controlling how long the callback stays registered.

◆ OnDismiss() [2/2]

virtual LayoutCallback OnDismiss	(	LayoutPanelCallback	callback,
		void *	user_data,
		LayoutDestroyUserDataCallback	destroy_user_data )

nodiscardpure virtual

Register a callback fired when the library dismisses this panel.

The library dismisses a panel when an auto-dismiss trigger fires on a floating panel (see ForegroundPanelOptions). An application-initiated Hide() does not fire it.

Parameters

callback	The function to call. It receives user_data and this panel.
user_data	Passed back to the callback on every fire (can be nullptr).
destroy_user_data	Called once when the registration drops user_data (can be nullptr).

Returns: Returns a LayoutCallback controlling how long the callback stays registered.

Note: Callbacks must not let exceptions propagate.

◆ view()

virtual RefPtr< View > view ( )

pure virtual

Get the hosted View.

Returns: Returns the hosted View, or null after the panel is removed or its window closes.

Note: For what happens to a View you hold after removal, see LayoutNode.

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

AppCore/layout/Panel.h

Overview

Hosting a View

Keyboard Focus

Public Member Functions

Protected Member Functions

Constructor & Destructor Documentation

◆ ~Panel()

Member Function Documentation

◆ BringToFront()

◆ Focus()

◆ OnDismiss() [1/2]

◆ OnDismiss() [2/2]

◆ view()