dear_imgui_rs/widget/

popup.rs

//! Popups and modals
//!
//! Popup windows (context menus, modals) with builders and token helpers to
//! ensure balanced begin/end calls.
//!
#![allow(
    clippy::cast_possible_truncation,
    clippy::cast_sign_loss,
    clippy::as_conversions
)]
use crate::MouseButton;
use crate::sys;
use crate::ui::Ui;
use crate::window::WindowFlags;

/// # Popup Widgets
impl Ui {
    /// Instructs ImGui that a popup is open.
    ///
    /// You should **call this function once** while calling any of the following per-frame:
    ///
    /// - [`begin_popup`](Self::begin_popup)
    /// - [`popup`](Self::popup)
    /// - [`begin_modal_popup`](Self::begin_modal_popup)
    /// - [`modal_popup`](Self::modal_popup)
    ///
    /// The confusing aspect to popups is that ImGui holds control over the popup itself.
    #[doc(alias = "OpenPopup")]
    pub fn open_popup(&self, str_id: impl AsRef<str>) {
        let str_id_ptr = self.scratch_txt(str_id);
        unsafe { sys::igOpenPopup_Str(str_id_ptr, PopupFlags::NONE.bits()) }
    }

    /// Instructs ImGui that a popup is open with flags.
    #[doc(alias = "OpenPopup")]
    pub fn open_popup_with_flags(&self, str_id: impl AsRef<str>, flags: PopupFlags) {
        let str_id_ptr = self.scratch_txt(str_id);
        unsafe { sys::igOpenPopup_Str(str_id_ptr, flags.bits()) }
    }

    /// Opens a popup when the last item is clicked (typically right-click).
    ///
    /// If `str_id` is `None`, the popup is associated with the last item ID.
    #[doc(alias = "OpenPopupOnItemClick")]
    pub fn open_popup_on_item_click(&self, str_id: Option<&str>) {
        self.open_popup_on_item_click_with_flags(str_id, PopupContextOptions::new());
    }

    /// Opens a popup when the last item is clicked, with explicit flags.
    #[doc(alias = "OpenPopupOnItemClick")]
    pub fn open_popup_on_item_click_with_flags(
        &self,
        str_id: Option<&str>,
        flags: impl Into<PopupContextOptions>,
    ) {
        let options = flags.into();
        let str_id_ptr = str_id
            .map(|s| self.scratch_txt(s))
            .unwrap_or(std::ptr::null());
        unsafe { sys::igOpenPopupOnItemClick(str_id_ptr, options.raw()) }
    }

    /// Construct a popup that can have any kind of content.
    ///
    /// This should be called *per frame*, whereas [`open_popup`](Self::open_popup) should be called *once*
    /// to signal that this popup is active.
    #[doc(alias = "BeginPopup")]
    pub fn begin_popup(&self, str_id: impl AsRef<str>) -> Option<PopupToken<'_>> {
        self.begin_popup_with_flags(str_id, WindowFlags::empty())
    }

    /// Construct a popup with window flags.
    #[doc(alias = "BeginPopup")]
    pub fn begin_popup_with_flags(
        &self,
        str_id: impl AsRef<str>,
        flags: WindowFlags,
    ) -> Option<PopupToken<'_>> {
        let str_id_ptr = self.scratch_txt(str_id);
        let render = unsafe { sys::igBeginPopup(str_id_ptr, flags.bits()) };

        if render {
            Some(PopupToken::new(self))
        } else {
            None
        }
    }

    /// Construct a popup that can have any kind of content.
    ///
    /// This should be called *per frame*, whereas [`open_popup`](Self::open_popup) should be called *once*
    /// to signal that this popup is active.
    #[doc(alias = "BeginPopup")]
    pub fn popup<F>(&self, str_id: impl AsRef<str>, f: F)
    where
        F: FnOnce(),
    {
        if let Some(_token) = self.begin_popup(str_id) {
            f();
        }
    }

    /// Creates a modal popup.
    ///
    /// Modal popups block interaction with the rest of the application until closed.
    #[doc(alias = "BeginPopupModal")]
    pub fn begin_modal_popup(&self, name: impl AsRef<str>) -> Option<ModalPopupToken<'_>> {
        let name_ptr = self.scratch_txt(name);
        let render = unsafe {
            sys::igBeginPopupModal(name_ptr, std::ptr::null_mut(), WindowFlags::empty().bits())
        };

        if render {
            Some(ModalPopupToken::new(self))
        } else {
            None
        }
    }

    /// Creates a modal popup with an opened-state tracking variable.
    ///
    /// Passing `opened` enables the title-bar close button (X). When clicked, ImGui will set
    /// `*opened = false` and close the popup.
    ///
    /// Notes:
    /// - You still need to call [`open_popup`](Self::open_popup) once to open the modal.
    /// - To pass window flags, use [`begin_modal_popup_config`](Self::begin_modal_popup_config).
    #[doc(alias = "BeginPopupModal")]
    pub fn begin_modal_popup_with_opened(
        &self,
        name: impl AsRef<str>,
        opened: &mut bool,
    ) -> Option<ModalPopupToken<'_>> {
        let name_ptr = self.scratch_txt(name);
        let opened_ptr = opened as *mut bool;
        let render =
            unsafe { sys::igBeginPopupModal(name_ptr, opened_ptr, WindowFlags::empty().bits()) };

        if render {
            Some(ModalPopupToken::new(self))
        } else {
            None
        }
    }

    /// Creates a modal popup builder.
    pub fn begin_modal_popup_config<'a>(&'a self, name: &'a str) -> ModalPopup<'a> {
        ModalPopup {
            name,
            opened: None,
            flags: WindowFlags::empty(),
            ui: self,
        }
    }

    /// Creates a modal popup and runs a closure to construct the contents.
    ///
    /// Returns the result of the closure if the popup is open.
    pub fn modal_popup<F, R>(&self, name: impl AsRef<str>, f: F) -> Option<R>
    where
        F: FnOnce() -> R,
    {
        self.begin_modal_popup(name).map(|_token| f())
    }

    /// Creates a modal popup with an opened-state tracking variable and runs a closure to
    /// construct the contents.
    ///
    /// Returns the result of the closure if the popup is open.
    pub fn modal_popup_with_opened<F, R>(
        &self,
        name: impl AsRef<str>,
        opened: &mut bool,
        f: F,
    ) -> Option<R>
    where
        F: FnOnce() -> R,
    {
        self.begin_modal_popup_with_opened(name, opened)
            .map(|_token| f())
    }

    /// Closes the current popup.
    #[doc(alias = "CloseCurrentPopup")]
    pub fn close_current_popup(&self) {
        unsafe {
            sys::igCloseCurrentPopup();
        }
    }

    /// Returns true if the popup is open.
    #[doc(alias = "IsPopupOpen")]
    pub fn is_popup_open(&self, str_id: impl AsRef<str>) -> bool {
        let str_id_ptr = self.scratch_txt(str_id);
        unsafe { sys::igIsPopupOpen_Str(str_id_ptr, PopupFlags::NONE.bits()) }
    }

    /// Returns true if the popup is open with flags.
    #[doc(alias = "IsPopupOpen")]
    pub fn is_popup_open_with_flags(&self, str_id: impl AsRef<str>, flags: PopupFlags) -> bool {
        let str_id_ptr = self.scratch_txt(str_id);
        unsafe { sys::igIsPopupOpen_Str(str_id_ptr, flags.bits()) }
    }

    /// Begin a popup context menu for the last item.
    #[doc(alias = "BeginPopupContextItem")]
    pub fn begin_popup_context_item(&self) -> Option<PopupToken<'_>> {
        self.begin_popup_context_item_with_flags(None, PopupContextOptions::new())
    }

    /// Begin a popup context menu for the last item with a custom label.
    #[doc(alias = "BeginPopupContextItem")]
    pub fn begin_popup_context_item_with_label(
        &self,
        str_id: Option<&str>,
    ) -> Option<PopupToken<'_>> {
        self.begin_popup_context_item_with_flags(str_id, PopupContextOptions::new())
    }

    /// Begin a popup context menu for the last item with explicit popup flags.
    #[doc(alias = "BeginPopupContextItem")]
    pub fn begin_popup_context_item_with_flags(
        &self,
        str_id: Option<&str>,
        flags: impl Into<PopupContextOptions>,
    ) -> Option<PopupToken<'_>> {
        let options = flags.into();
        let str_id_ptr = str_id
            .map(|s| self.scratch_txt(s))
            .unwrap_or(std::ptr::null());

        let render = unsafe { sys::igBeginPopupContextItem(str_id_ptr, options.raw()) };

        render.then(|| PopupToken::new(self))
    }

    /// Begin a popup context menu for the current window.
    #[doc(alias = "BeginPopupContextWindow")]
    pub fn begin_popup_context_window(&self) -> Option<PopupToken<'_>> {
        self.begin_popup_context_window_with_flags(None, PopupContextOptions::new())
    }

    /// Begin a popup context menu for the current window with a custom label.
    #[doc(alias = "BeginPopupContextWindow")]
    pub fn begin_popup_context_window_with_label(
        &self,
        str_id: Option<&str>,
    ) -> Option<PopupToken<'_>> {
        self.begin_popup_context_window_with_flags(str_id, PopupContextOptions::new())
    }

    /// Begin a popup context menu for the current window with explicit popup flags.
    #[doc(alias = "BeginPopupContextWindow")]
    pub fn begin_popup_context_window_with_flags(
        &self,
        str_id: Option<&str>,
        flags: impl Into<PopupContextOptions>,
    ) -> Option<PopupToken<'_>> {
        let options = flags.into();
        let str_id_ptr = str_id
            .map(|s| self.scratch_txt(s))
            .unwrap_or(std::ptr::null());

        let render = unsafe { sys::igBeginPopupContextWindow(str_id_ptr, options.raw()) };

        render.then(|| PopupToken::new(self))
    }

    /// Begin a popup context menu for empty space (void).
    #[doc(alias = "BeginPopupContextVoid")]
    pub fn begin_popup_context_void(&self) -> Option<PopupToken<'_>> {
        self.begin_popup_context_void_with_flags(None, PopupContextOptions::new())
    }

    /// Begin a popup context menu for empty space with a custom label.
    #[doc(alias = "BeginPopupContextVoid")]
    pub fn begin_popup_context_void_with_label(
        &self,
        str_id: Option<&str>,
    ) -> Option<PopupToken<'_>> {
        self.begin_popup_context_void_with_flags(str_id, PopupContextOptions::new())
    }

    /// Begin a popup context menu for empty space (void) with explicit popup flags.
    #[doc(alias = "BeginPopupContextVoid")]
    pub fn begin_popup_context_void_with_flags(
        &self,
        str_id: Option<&str>,
        flags: impl Into<PopupContextOptions>,
    ) -> Option<PopupToken<'_>> {
        let options = flags.into();
        let str_id_ptr = str_id
            .map(|s| self.scratch_txt(s))
            .unwrap_or(std::ptr::null());

        let render = unsafe { sys::igBeginPopupContextVoid(str_id_ptr, options.raw()) };

        render.then(|| PopupToken::new(self))
    }
}

bitflags::bitflags! {
    /// Independent flags for popup functions.
    ///
    /// Context popup mouse button selection is a single-choice setting
    /// represented by [`PopupContextMouseButton`].
    #[repr(transparent)]
    #[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
    pub struct PopupFlags: i32 {
        /// No flags
        const NONE = sys::ImGuiPopupFlags_None as i32;
        /// Do not reopen the same popup if already open.
        const NO_REOPEN = sys::ImGuiPopupFlags_NoReopen as i32;
        /// For OpenPopup*(), BeginPopupContext*(): don't open if there's already a popup at the same level of the popup stack
        const NO_OPEN_OVER_EXISTING_POPUP = sys::ImGuiPopupFlags_NoOpenOverExistingPopup as i32;
        /// For BeginPopupContext*(): don't return true when hovering items, only when hovering empty space
        const NO_OPEN_OVER_ITEMS = sys::ImGuiPopupFlags_NoOpenOverItems as i32;
        /// For IsPopupOpen(): ignore the ImGuiID parameter and test for any popup
        const ANY_POPUP_ID = sys::ImGuiPopupFlags_AnyPopupId as i32;
        /// For IsPopupOpen(): search/test at any level of the popup stack (default test in the current level)
        const ANY_POPUP_LEVEL = sys::ImGuiPopupFlags_AnyPopupLevel as i32;
        /// For IsPopupOpen(): test for any popup
        const ANY_POPUP = Self::ANY_POPUP_ID.bits() | Self::ANY_POPUP_LEVEL.bits();
    }
}

/// Single mouse button used by popup context helpers.
#[derive(Clone, Copy, Debug, Default, PartialEq, Eq, Hash)]
pub enum PopupContextMouseButton {
    /// Open on left mouse release.
    Left,
    /// Open on right mouse release.
    #[default]
    Right,
    /// Open on middle mouse release.
    Middle,
}

impl PopupContextMouseButton {
    #[inline]
    const fn raw(self) -> i32 {
        match self {
            Self::Left => sys::ImGuiPopupFlags_MouseButtonLeft as i32,
            Self::Right => sys::ImGuiPopupFlags_MouseButtonRight as i32,
            Self::Middle => sys::ImGuiPopupFlags_MouseButtonMiddle as i32,
        }
    }
}

impl From<MouseButton> for PopupContextMouseButton {
    fn from(button: MouseButton) -> Self {
        match button {
            MouseButton::Left => Self::Left,
            MouseButton::Right => Self::Right,
            MouseButton::Middle => Self::Middle,
            MouseButton::Extra1 | MouseButton::Extra2 => {
                panic!(
                    "Dear ImGui popup context helpers only support left, right, and middle buttons"
                )
            }
        }
    }
}

/// Complete popup options assembled from independent flags and optional
/// single mouse button.
#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
pub struct PopupContextOptions {
    pub flags: PopupFlags,
    pub mouse_button: PopupContextMouseButton,
}

impl PopupContextOptions {
    pub const fn new() -> Self {
        Self {
            flags: PopupFlags::NONE,
            mouse_button: PopupContextMouseButton::Right,
        }
    }

    pub fn flags(mut self, flags: PopupFlags) -> Self {
        self.flags = flags;
        self
    }

    pub fn mouse_button(mut self, button: impl Into<PopupContextMouseButton>) -> Self {
        self.mouse_button = button.into();
        self
    }

    pub fn bits(self) -> i32 {
        self.raw()
    }

    #[inline]
    pub(crate) fn raw(self) -> i32 {
        self.flags.bits() | self.mouse_button.raw()
    }
}

impl Default for PopupContextOptions {
    fn default() -> Self {
        Self::new()
    }
}

impl From<PopupFlags> for PopupContextOptions {
    fn from(flags: PopupFlags) -> Self {
        Self::new().flags(flags)
    }
}

impl From<PopupContextMouseButton> for PopupContextOptions {
    fn from(button: PopupContextMouseButton) -> Self {
        Self::new().mouse_button(button)
    }
}

impl From<MouseButton> for PopupContextOptions {
    fn from(button: MouseButton) -> Self {
        Self::new().mouse_button(button)
    }
}

/// Builder for a modal popup
#[derive(Debug)]
#[must_use]
pub struct ModalPopup<'ui> {
    name: &'ui str,
    opened: Option<&'ui mut bool>,
    flags: WindowFlags,
    ui: &'ui Ui,
}

impl<'ui> ModalPopup<'ui> {
    /// Sets the opened state tracking variable
    pub fn opened(mut self, opened: &'ui mut bool) -> Self {
        self.opened = Some(opened);
        self
    }

    /// Sets the window flags
    pub fn flags(mut self, flags: WindowFlags) -> Self {
        self.flags = flags;
        self
    }

    /// Begins the modal popup
    pub fn begin(self) -> Option<ModalPopupToken<'ui>> {
        let name_ptr = self.ui.scratch_txt(self.name);
        let opened_ptr = self
            .opened
            .map(|o| o as *mut bool)
            .unwrap_or(std::ptr::null_mut());

        let render = unsafe { sys::igBeginPopupModal(name_ptr, opened_ptr, self.flags.bits()) };

        if render {
            Some(ModalPopupToken::new(self.ui))
        } else {
            None
        }
    }
}

/// Tracks a popup that can be ended by calling `.end()` or by dropping
#[must_use]
pub struct PopupToken<'ui> {
    _ui: &'ui Ui,
}

impl<'ui> PopupToken<'ui> {
    /// Creates a new popup token
    fn new(ui: &'ui Ui) -> Self {
        PopupToken { _ui: ui }
    }

    /// Ends the popup
    pub fn end(self) {
        // The drop implementation will handle the actual ending
    }
}

impl<'ui> Drop for PopupToken<'ui> {
    fn drop(&mut self) {
        unsafe {
            sys::igEndPopup();
        }
    }
}

/// Tracks a modal popup that can be ended by calling `.end()` or by dropping
#[must_use]
pub struct ModalPopupToken<'ui> {
    _ui: &'ui Ui,
}

impl<'ui> ModalPopupToken<'ui> {
    /// Creates a new modal popup token
    fn new(ui: &'ui Ui) -> Self {
        ModalPopupToken { _ui: ui }
    }

    /// Ends the modal popup
    pub fn end(self) {
        // The drop implementation will handle the actual ending
    }
}

impl<'ui> Drop for ModalPopupToken<'ui> {
    fn drop(&mut self) {
        unsafe {
            sys::igEndPopup();
        }
    }
}