#include <AppCore/layout/Anchor.h>

Overview

Placement of a floating panel in a window.

An Anchor determines where a floating panel sits within an AppCore window. You pass it through ForegroundPanelOptions when adding a panel to the window's foreground layer, positioning overlays like toasts or dropdown menus.

This example floats a toast in the bottom-right corner of the window, nudged inward from the edge:

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

Placement Forms

Static factory methods define where a panel appears:

Form	Placement
Anchor::At()	Positions the panel at absolute window coordinates.
Anchor::WindowCorner()	Snaps the panel to a window corner.
Anchor::WindowCenter()	Centers the panel within the window.
Anchor::Fill()	Places the panel at the window origin.
Anchor::Below()	Hangs the panel under a rectangle in another panel.

Panels positioned with Anchor::WindowCorner() or Anchor::WindowCenter() follow the window as it resizes.

Calling Offset() on any form nudges the panel by horizontal and vertical offsets in logical pixels, applied after the form places the panel.

Anchoring Below an Element

Anchor::Below() takes a target panel and a rectangle in that panel's local logical pixels, which match the page's CSS pixels– so bounding rectangles from dom::Element::getBoundingClientRect() pass straight through without conversion.

The library updates the placement every frame from the target panel's current geometry, so the floating panel follows the target as it moves.

Two chained methods refine placement under Anchor::Below():

Align() sets cross-axis alignment against the rectangle. Left edges align by default, or you can center the panel or align its right edge.
Fit() handles panels that don't fit below the rectangle. AnchorFit::Flip places the panel above the rectangle instead.

This example positions a dropdown below a button from another panel, flipping it upward if space runs out:

dom::DOMRect box = button.getBoundingClientRect();
RefPtr<Panel> dropdown = window->foreground()->AddPanel(
    { .width = "240px", .height = "180px",
      .placement = Anchor::Below(toolbar, Rect::FromXYWH(box.x, box.y,
                                                         box.width, box.height))
                       .Fit(AnchorFit::Flip) });

Note: A floating panel's placement is fixed once the panel exists. See Foreground for how to move an existing panel.

See also: ForegroundPanelOptions::placement, Foreground::AddPanel(), dom::Element::getBoundingClientRect()

Public Types
enum class	Kind : uint8_t { Origin = 0 , At , WindowCorner , WindowCenter , Below }
	The placement form. More...

Static Public Member Functions
static Anchor	At (double x, double y)
	Place the panel's top-left corner at an absolute position in the window.
static Anchor	WindowCorner (AnchorCorner corner)
	Snap the panel's matching corner to a corner of the window.
static Anchor	WindowCenter ()
	Center the panel in the window.
static Anchor	Fill ()
	Place the panel at the window origin, the named form of the default placement.
static Anchor	Below (RefPtr< Panel > target, const Rect &rect)
	Place the panel below an anchor rectangle in a target panel (eg, a dropdown below its box).

Public Member Functions
	Anchor ()=default
	Create the default placement (the window origin).
Anchor	Offset (double dx, double dy) const
	Nudge the placement by an offset, applied after the placement form resolves (every form, At() and the default origin included).
Anchor	Align (AnchorAlign alignment) const
	Align the panel against the anchor rect's cross axis.
Anchor	Fit (AnchorFit fit) const
	Choose the fit behavior when the panel does not fit on its preferred side.
Kind	kind () const
	The placement form.
AnchorCorner	corner () const
	The window corner (WindowCorner() forms).
AnchorAlign	alignment () const
	The cross-axis alignment (Below() forms).
AnchorFit	fit_mode () const
	The fit behavior (Below() forms).
double	x () const
	The absolute x-position, in logical px (At() forms).
double	y () const
	The absolute y-position, in logical px (At() forms).
double	offset_x () const
	The x-offset applied after the placement form resolves, in logical px.
double	offset_y () const
	The y-offset applied after the placement form resolves, in logical px.
RefPtr< Panel >	target () const
	The target panel (Below() forms, null otherwise).
const Rect &	rect () const
	The anchor rect, in the target panel's local logical px (Below() forms).

Member Enumeration Documentation

◆ Kind

enum class Kind : uint8_t

strong

The placement form.

Enumerator
Origin	Window origin (Fill() with the default 100% sizes).
At	Absolute window-space logical px.
WindowCorner	A window corner, following the window.
WindowCenter	Centered in the window, following the window.
Below	Under an anchor rect in a target panel.

Constructor & Destructor Documentation

◆ Anchor()

Anchor ( )

default

Create the default placement (the window origin).

Member Function Documentation

◆ Align()

Anchor Align ( AnchorAlign alignment ) const

inlinenodiscard

Align the panel against the anchor rect's cross axis.

(Default: Start)

Under Below(), Start aligns the left edges and End aligns the right edges.

Parameters

alignment The cross-axis alignment to use.

Returns: Returns a copy of this Anchor with the alignment applied.

◆ alignment()

AnchorAlign alignment ( ) const

inline

The cross-axis alignment (Below() forms).

◆ At()

Anchor At	(	double	x,
		double	y )

inlinestatic

Place the panel's top-left corner at an absolute position in the window.

Parameters

x	The x-position, in logical px from the window's left edge.
y	The y-position, in logical px from the window's top edge.

◆ Below()

Anchor Below	(	RefPtr< Panel >	target,
		const Rect &	rect )

inlinestatic

Place the panel below an anchor rectangle in a target panel (eg, a dropdown below its box).

The placement updates every frame from the target's current geometry.

You can refine the placement with Align() and Fit().

Parameters

target	The panel the anchor rectangle belongs to.
rect	The anchor rectangle, in the target panel's local logical pixels (which equal the page's CSS pixels).

Note: Anchoring one floating panel below another can lag the target by a frame while the target moves.

Note: If the target panel is removed or has not been laid out yet, the panel stays where it was last placed.

◆ corner()

AnchorCorner corner ( ) const

inline

The window corner (WindowCorner() forms).

◆ Fill()

Anchor Fill ( )

inlinestatic

Place the panel at the window origin, the named form of the default placement.

With the default 100% sizes this fills the window.

◆ Fit()

Anchor Fit ( AnchorFit fit ) const

inlinenodiscard

Choose the fit behavior when the panel does not fit on its preferred side.

(Default: None)

Under Below(), Flip places the panel above the rect instead.

Parameters

fit	The fit behavior to use.

Returns: Returns a copy of this Anchor with the fit behavior applied.

◆ fit_mode()

AnchorFit fit_mode ( ) const

inline

The fit behavior (Below() forms).

◆ kind()

Kind kind ( ) const

inline

The placement form.

◆ Offset()

Anchor Offset	(	double	dx,
		double	dy ) const

inlinenodiscard

Nudge the placement by an offset, applied after the placement form resolves (every form, At() and the default origin included).

Parameters

dx	The horizontal nudge, in logical px.
dy	The vertical nudge, in logical px.

Returns: Returns a copy of this Anchor with the offset applied.

◆ offset_x()

double offset_x ( ) const

inline

The x-offset applied after the placement form resolves, in logical px.

◆ offset_y()

double offset_y ( ) const

inline

The y-offset applied after the placement form resolves, in logical px.

◆ rect()

const Rect & rect ( ) const

inline

The anchor rect, in the target panel's local logical px (Below() forms).

◆ target()

RefPtr< Panel > target ( ) const

inline

The target panel (Below() forms, null otherwise).

◆ WindowCenter()

Anchor WindowCenter ( )

inlinestatic

Center the panel in the window.

The panel follows the window as it resizes.

◆ WindowCorner()

Anchor WindowCorner ( AnchorCorner corner )

inlinestatic

Snap the panel's matching corner to a corner of the window.

The panel follows the window as it resizes. You can nudge it with Offset().

Parameters

corner The window corner to snap to.

◆ x()

double x ( ) const

inline

The absolute x-position, in logical px (At() forms).

◆ y()

double y ( ) const

inline

The absolute y-position, in logical px (At() forms).

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

AppCore/layout/Anchor.h

Overview

Placement Forms

Anchoring Below an Element

Public Types

Static Public Member Functions

Public Member Functions

Member Enumeration Documentation

◆ Kind

Constructor & Destructor Documentation

◆ Anchor()

Member Function Documentation

◆ Align()

◆ alignment()

◆ At()

◆ Below()

◆ corner()

◆ Fill()

◆ Fit()

◆ fit_mode()

◆ kind()

◆ Offset()

◆ offset_x()

◆ offset_y()

◆ rect()

◆ target()

◆ WindowCenter()

◆ WindowCorner()

◆ x()

◆ y()