rungui 0.4.0

Small portable native GUI library: a thin layer over GTK3, Win32 and Cocoa with hand-declared FFI
Documentation
//! Operations common to every widget (`impl Widget`).

use super::*;

impl Widget {
    /// The widget's id.
    pub fn id(&self) -> WidgetId {
        self.0
    }
    /// False after `destroy`, or if creation failed (see [`crate::last_error`]).
    pub fn is_alive(&self) -> bool {
        core::is_alive(self.0)
    }
    /// Destroy this widget and all its children. (Destroying many siblings one at a time costs time
    /// proportional to how many are left each; to clear a container, destroy the container.)
    pub fn destroy(&self) {
        core::destroy(self.0)
    }
    /// Enable or disable the widget and everything inside it.
    pub fn set_enabled(&self, v: bool) {
        core::set_flag(self.0, false, v)
    }
    /// Whether the widget itself is enabled (a disabled ancestor still disables it on screen).
    pub fn enabled(&self) -> bool {
        core::read(self.0, |n| n.enabled).unwrap_or(false)
    }
    /// Hidden widgets take no layout space. Hiding a box hides everything inside it.
    pub fn set_visible(&self, v: bool) {
        core::set_flag(self.0, true, v)
    }
    /// Whether the widget itself is shown (a hidden ancestor still hides it).
    pub fn visible(&self) -> bool {
        core::read(self.0, |n| n.visible).unwrap_or(false)
    }
    /// Set the tooltip text (empty removes it); also the default accessible description.
    pub fn set_tooltip(&self, t: &str) {
        core::set(
            self.0,
            false,
            |n| n.tooltip = t.to_string(),
            Prop::Tooltip(t),
        );
    }
    /// Move keyboard focus to the widget.
    pub fn focus(&self) {
        core::set(self.0, false, |_| {}, Prop::Focus);
    }
    /// Share of spare space along the parent stack's axis (0 = natural size, 1 = take a share).
    pub fn set_expand(&self, weight: f32) {
        // NaN counts as 0 and infinity as the largest weight, so the weights always sum finitely
        let weight = if weight.is_nan() {
            0.0
        } else {
            weight.clamp(0.0, MAX_EXPAND)
        };
        core::update(self.0, true, |n| n.lay.expand = weight);
    }
    /// Alignment inside the parent's cell/cross axis (default `Fill`).
    pub fn set_align(&self, a: Align) {
        core::update(self.0, true, |n| n.lay.align = a);
    }
    /// Minimum laid-out size. On a [`Window`] this is the minimum CLIENT size: the user cannot
    /// resize below it (where the platform allows) and layout never goes below it.
    pub fn set_min_size(&self, w: i32, h: i32) {
        let min = Size::new(px(w), px(h));
        if core::update(self.0, true, |n| n.lay.min = min) == Some(Kind::Window) {
            B::set(
                self.0,
                &Prop::MinSize(Size::new(
                    min.w.min(MAX_WINDOW_PX),
                    min.h.min(MAX_WINDOW_PX),
                )),
            );
        }
    }
    /// Force the natural size (overrides the toolkit's preferred size).
    pub fn set_fixed_size(&self, w: i32, h: i32) {
        core::update(self.0, true, |n| {
            n.lay.fixed = Some(Size::new(px(w), px(h)))
        });
    }
    /// Space between children (stacks/grids/containers).
    pub fn set_spacing(&self, px: i32) {
        core::update(self.0, true, |n| n.lay.spacing = self::px(px));
    }
    /// Inner margin of a container.
    pub fn set_padding(&self, px: i32) {
        core::update(self.0, true, |n| n.lay.padding = self::px(px));
    }
    /// Explicit grid cell in the parent [`Grid`] (otherwise children auto-flow).
    pub fn set_cell(&self, col: usize, row: usize, colspan: usize, rowspan: usize) {
        core::update(self.0, true, |n| {
            n.lay.cell = Some((
                col.min(MAX_CELL),
                row.min(MAX_CELL),
                colspan.clamp(1, MAX_CELL),
                rowspan.clamp(1, MAX_CELL),
            ))
        });
    }
    /// Last laid-out bounds, relative to the nearest native parent (logical pixels).
    pub fn bounds(&self) -> Rect {
        core::read(self.0, |n| n.bounds).unwrap_or_default()
    }
    /// Accessible name override (otherwise derived from the widget text / preceding label).
    pub fn set_a11y_name(&self, s: &str) {
        core::update(self.0, false, |n| n.a11y.name = Some(s.to_string()));
    }
    /// Override the accessible description (otherwise the tooltip).
    pub fn set_a11y_description(&self, s: &str) {
        core::update(self.0, false, |n| n.a11y.desc = Some(s.to_string()));
    }
    /// Override the accessible role (otherwise the kind's default).
    pub fn set_a11y_role(&self, r: A11yRole) {
        core::update(self.0, false, |n| n.a11y.role = Some(r));
    }
    /// The accessibility overrides set on the widget.
    pub fn a11y(&self) -> A11yProps {
        core::read(self.0, |n| n.a11y.clone()).unwrap_or_default()
    }
    /// Attach a [`PopupMenu`] shown on right-click / Menu key / Shift+F10 (children without their own
    /// menu inherit it). Works on any widget and on windows.
    pub fn set_context_menu(&self, popup: impl Into<WidgetId>) {
        let p = popup.into();
        core::modify(self.0, |n| n.context_menu = Some(p));
    }
    /// Detach the context menu.
    pub fn clear_context_menu(&self) {
        core::modify(self.0, |n| n.context_menu = None);
    }
    /// Called with window-client coordinates just before the context menu is shown (and even when no
    /// menu is attached), so the app can rebuild/enable items or attach a different menu.
    pub fn on_context_menu(&self, mut f: impl FnMut(i32, i32) + 'static) {
        on(self.0, Ev::ContextMenu, move |e| {
            if let Event::ContextMenu { x, y } = e {
                f(*x, *y)
            }
        });
    }
    /// The raw GtkWidget* / HWND / NSView* (or HMENU/NSMenu for menus) for platform-specific code.
    pub fn native_handle(&self) -> Option<NativeHandle> {
        core::native_handle(self.0)
    }
}