ui::PopupRequest¶

Header: winui/ui/Element.hpp.

What Element::open_popup() floats above the tree: the content, what it hangs from, and how it behaves. The window places it after every layout, draws it over everything else and routes input inside it to it alone.

Example:

// A custom control that shows a list under itself while expanded.
class Dropdown : public ui::Element
{
public:
    void set_expanded(bool expanded)
    {
        if (!expanded)
        {
            close_popup();
            return;
        }
        open_popup({
            .content    = list_.get(), // owned by this control
            .placement  = ui::PopupPlacement::Below,
            .on_dismiss = [this](ui::PopupCloseReason) { set_expanded(false); },
        });
    }

private:
    std::unique_ptr<ui::StackControl> list_ = std::make_unique<ui::StackControl>(ui::Orientation::Vertical);
};

Field	Type	Default
`content`	`Element*`	`nullptr`	The element shown in the popup. The control that opens the popup owns it and keeps it alive while the popup is open; the window lays it out and draws it, and never owns it.
`anchor`	`const Element*`	`nullptr`	The element the popup hangs from. Unset is the element that opened it. Its bounds are read again on every layout, so the popup follows it.
`anchor_rect`	`std::optional<Rect>`		A rect inside `anchor` to hang from instead of its whole bounds, relative to the anchor's top-left corner (a part of the control, the point a tool tip opened at).
`placement`	`PopupPlacement`	`PopupPlacement::Below`	Which side of the anchor the popup opens on. The window flips it to the opposite side when there is no room.
`placement_alignment`	`PopupPlacementAlignment`	`PopupPlacementAlignment::Leading`	How the popup lines up with the anchor along that side. Leading by default, as a list under a box is; a centered popup is measured without the anchor's size as a hint.
`light_dismiss`	`bool`	`true`	Whether a press outside every open popup and its owner, or Escape, dismisses it. A popup without light dismiss stays open until its owner closes it, and an outside press reaches the tree under it.
`takes_focus`	`bool`	`false`	Whether keyboard focus moves into the popup while it is open: the window scopes the tab ring to the content, focuses its first stop, and gives focus back when it closes.
`chrome`	`PopupChrome`		The shadow the window draws behind the content.
`place`	`Callback<bool(Element& content, Size client, const MeasureContext& context)>`		Positions the popup itself instead of the anchor and placement rule: measure and arrange `content` inside a `client`-sized window and return true, or return false to use the rule. It may close the popup (a surface that fits nowhere).
`on_dismiss`	`Callback<void(PopupCloseReason reason)>`		Called when the window dismisses the popup (light dismiss, Escape). The owner closes it, at once with close_popup() or after an exit animation, and updates its own state. Unset closes it at once.