tenant.openagents/omega

1use bitflags::bitflags;
2use thiserror::Error;
3
4use crate::{AnyWindowHandle, Bounds, Pixels, Point};
5
6/// Options for a parent-anchored popup window such as a menu, dropdown, context menu or tooltip.
7///
8/// A popup is placed relative to an anchor rectangle on its parent window rather than at an
9/// absolute screen position. The platform resolves the final position, so this works both on
10/// systems where the compositor owns window placement (Wayland) and on platforms with absolute
11/// coordinates.
12///
13/// The popup's size comes from [`WindowOptions::window_bounds`](crate::WindowOptions), whose
14/// origin is ignored. All coordinates are in logical pixels.
15#[derive(Clone, Debug, PartialEq, Eq)]
16pub struct PopupOptions {
17    /// The window the popup is anchored to.
18    pub parent: AnyWindowHandle,
19
20    /// The rectangle the popup is positioned relative to, in the parent window's coordinate
21    /// space (the same space element bounds are in). For example, a dropdown menu uses the
22    /// bounds of the button that opened it.
23    pub anchor_rect: Bounds<Pixels>,
24
25    /// Which point of [`Self::anchor_rect`] the popup is anchored to.
26    pub anchor: PopupAnchor,
27
28    /// The direction in which the popup extends away from the anchor point. A dropdown that
29    /// drops below its button anchors to [`PopupAnchor::BottomLeft`] with a gravity of
30    /// [`PopupGravity::BottomRight`] so it grows down and to the right.
31    pub gravity: PopupGravity,
32
33    /// How the platform may adjust the popup if the requested placement would put it off-screen.
34    pub constraint_adjustment: PopupConstraintAdjustment,
35
36    /// An additional offset applied to the popup after anchoring.
37    pub offset: Point<Pixels>,
38
39    /// Whether the popup should take an explicit input grab.
40    ///
41    /// Grabbing popups behave like menus: they take keyboard focus and are dismissed when the
42    /// user clicks outside of them or presses a dismissing key. Use it for menus and comboboxes,
43    /// not for tooltips or other passive popups.
44    ///
45    /// A grab must be requested while the triggering input is still active, in practice the
46    /// press of the mouse button that opens the popup. Open grabbing popups from a mouse-down
47    /// handler rather than a click handler, otherwise the grab is refused.
48    ///
49    /// Automatic dismissal only covers input aimed at other applications. A click elsewhere in
50    /// your own application still reaches it as usual, so closing the popup in that case is up
51    /// to you. Nested grabbing popups must be closed in the reverse order they were opened.
52    pub grab: bool,
53}
54
55/// The point of the anchor rectangle that a popup is anchored to.
56#[derive(Copy, Clone, Debug, Default, PartialEq, Eq)]
57pub enum PopupAnchor {
58    /// Anchor to the center of the anchor rectangle.
59    #[default]
60    Center,
61    /// Anchor to the center of the top edge.
62    Top,
63    /// Anchor to the center of the bottom edge.
64    Bottom,
65    /// Anchor to the center of the left edge.
66    Left,
67    /// Anchor to the center of the right edge.
68    Right,
69    /// Anchor to the top-left corner.
70    TopLeft,
71    /// Anchor to the bottom-left corner.
72    BottomLeft,
73    /// Anchor to the top-right corner.
74    TopRight,
75    /// Anchor to the bottom-right corner.
76    BottomRight,
77}
78
79/// The direction in which a popup extends away from its anchor point.
80///
81/// For instance, a gravity of [`PopupGravity::BottomRight`] places the popup below and to the
82/// right of the anchor point.
83#[derive(Copy, Clone, Debug, Default, PartialEq, Eq)]
84pub enum PopupGravity {
85    /// The popup is centered over the anchor point.
86    #[default]
87    Center,
88    /// The popup extends upwards from the anchor point.
89    Top,
90    /// The popup extends downwards from the anchor point.
91    Bottom,
92    /// The popup extends to the left of the anchor point.
93    Left,
94    /// The popup extends to the right of the anchor point.
95    Right,
96    /// The popup extends up and to the left of the anchor point.
97    TopLeft,
98    /// The popup extends down and to the left of the anchor point.
99    BottomLeft,
100    /// The popup extends up and to the right of the anchor point.
101    TopRight,
102    /// The popup extends down and to the right of the anchor point.
103    BottomRight,
104}
105
106bitflags! {
107    /// How a popup may be adjusted by the platform if the requested placement would put it
108    /// off-screen. If no flags are set, the popup is placed exactly as requested and may be
109    /// clipped.
110    #[derive(Copy, Clone, Debug, Default, PartialEq, Eq)]
111    pub struct PopupConstraintAdjustment: u32 {
112        /// The popup may be slid horizontally to stay on-screen.
113        const SLIDE_X = 1;
114        /// The popup may be slid vertically to stay on-screen.
115        const SLIDE_Y = 2;
116        /// The popup's anchor and gravity may be flipped horizontally to stay on-screen.
117        const FLIP_X = 4;
118        /// The popup's anchor and gravity may be flipped vertically to stay on-screen.
119        const FLIP_Y = 8;
120        /// The popup may be shrunk horizontally to stay on-screen.
121        const RESIZE_X = 16;
122        /// The popup may be shrunk vertically to stay on-screen.
123        const RESIZE_Y = 32;
124    }
125}
126
127/// Returned when the current platform has no native popup implementation yet.
128///
129/// Native popups are separate from gpui's in-window popovers, which are drawn as elements inside
130/// an existing window. A caller that wants a popup on every platform should treat this error as
131/// a cue to fall back to that in-window rendering.
132#[derive(Debug, Error)]
133#[error("popups are not supported on this platform")]
134pub struct PopupNotSupportedError;
135