boing 0.7.0

// SPDX-License-Identifier: MPL-2.0

//! A safe wrapper over *[libui-ng-sys]*.
//!
//! ## Background
//!
//! *[libui]* is a C library that provides a neutral interface to native GUI technologies (e.g.,
//! windows, widgets) on major OSes. *[libui-ng]* is the "next generation" of *libui*, developed and
//! maintained separately. *libui-ng-sys* provides Rust bindings to *libui-ng*, and *boing* is a
//! safe yet fairly unopinionated layer on top of *libui-ng-sys*.
//!
//! ## Usage
//!
//! To get started with *boing*, see the [`Ui`] struct.
//!
//! ## Examples
//!
//! ```no_run
//! # fn main() -> Result<(), boing::Error> {
//! # use boing::Ui;
//! #
//! let ui = Ui::new()?;
//!
//! // Append a drop-down menu labeled "File" to the menubar of all windows created with
//! // `has_menubar` set to `true`; see [`Ui::create_window`] for more information.
//! let file_menu = ui.create_menu("File")?;
//! // Append a menu item labeled "Quit" (in English) to the previously-created file menu. This
//! // "Quit" item will exit the application when clicked.
//! file_menu.push_quit_item()?;
//!
//! // Create a 200x200 pixel window titled "Hello World!" with a menubar that exits the application
//! // when closed.
//! let window = ui.create_window("Hello World!", 200u16, 200u16, true, true)?;
//! // Create a button labeled "Press Me!" and set it as the main child control of the
//! // previously-created window.
//! window.set_child(ui.create_pushbutton("Press Me!")?);
//! // Present the window to the user. Calling this method is necessary for the window to appear at
//! // all.
//! window.show();
//!
//! // Enter the UI event loop. As [`Ui::run`] borrows immutably, this can be called again.
//! ui.run();
//! #
//! # Ok(())
//! # }
//! ```
//!
//! For more examples, including a control gallery, see the *[boing-examples]* crate.
//!
//! [libui-ng-sys]: https://crates.io/crates/libui-ng-sys
//! [libui]: https://github.com/andlabs/libui
//! [libui-ng]: https://github.com/libui-ng/libui-ng
//! [examples]: https://github.com/norepimorphism/boing/tree/main/boing-examples

// All *libui-ng-sys* exports violate Rust's naming conventions.
#![allow(non_upper_case_globals)]

#[macro_use]
mod prelude {
    pub use std::{ops::DerefMut, os::raw::{c_int, c_uint, c_void}};

    pub use boing_internals::*;
    pub use libui_ng_sys::*;

    pub use crate::{Container, Control, NonNegativeInt, Ui, Widget};

    pub trait Sealed {}

    pub fn bool_from_libui(value: c_int) -> bool {
        // Note: this will only trigger on debug builds.
        debug_assert!((value == 0) || (value == 1));

        // Many C programs test booleans with `if(_)`, which is shorthand for `if(_ != 0)`, so we
        // will replicate that functionality here.
        value != 0
    }

    macro_rules! call_fallible_libui_fn {
        ($fn:ident( $($arg:expr),* $(,)? )) => {
            // We probably need an `unsafe` block here, but we will defer that to the caller of this
            // macro (who knows why this is safe to do).
            $fn( $($arg),* )
                .as_mut()
                .ok_or($crate::Error::LibuiFn { name: stringify!($fn), cause: None })
        };
    }

    macro_rules! call_libui_new_fn {
        (
            ui: $ui:expr,
            fn: $fn:ident( $($arg:expr),* $(,)? ) -> $out_ty:ident $(,)?
        ) => {
            // We probably need an `unsafe` block here, but we will defer that to the caller of this
            // macro (who knows why this is safe to do).
            call_fallible_libui_fn!( $fn($($arg),*) ).map(|ptr| $ui.alloc_object({
                // SAFETY: `ptr` is ostensibly a valid control returned by *libui-ng*, and it will
                // live until either we destroy it or *libui-ng* is de-initialized.
                // Note: this does not necessarily invoke [`Control::new`], in particular if this is
                // a non-control widget.
                $out_ty::from_ptr($ui, ptr)
            }))
        };
    }
}

pub mod reexports {
    //! Re-exported items from dependencies.

    macro_rules! reexport {
        ($krate:ident) => {
            pub mod $krate {
                #![doc = concat!(
                    "Re-exported items from [`",
                    stringify!($krate),
                    "`](https://crates.io/crates/",
                    stringify!($krate),
                    ").",
                )]

                pub use ::$krate::*;
            }
        };
    }

    #[cfg(feature = "image")]
    reexport!(image);
    reexport!(libui_ng_sys);
    #[cfg(feature = "raw-window-handle")]
    reexport!(raw_window_handle);
}

pub mod area;
mod axis;
mod checkbox;
pub mod color;
mod combobox;
mod control;
pub mod font;
pub mod form;
mod grid;
mod group;
pub mod image;
mod label;
pub mod menu;
mod multiline_text_entry;
mod path;
mod progress_bar;
mod pushbutton;
mod radio_buttons;
mod separator;
mod slider;
mod spinbox;
mod tab;
// pub mod table;
mod text_entry;
mod ui;
mod window;

use std::fmt;

pub use area::Area;
pub use axis::Axis;
pub use checkbox::Checkbox;
pub use color::{Color, Picker as ColorPicker};
pub use combobox::Combobox;
pub use control::Control;
pub use font::{Font, Picker as FontPicker};
pub use form::Form;
pub use grid::Grid;
pub use group::Group;
pub use crate::image::Image;
pub use label::Label;
pub use menu::{Item as MenuItem, Menu};
pub use multiline_text_entry::MultilineTextEntry;
pub use non_negative_int::NonNegativeInt;
pub use path::Path;
pub use progress_bar::ProgressBar;
pub use pushbutton::Pushbutton;
pub use radio_buttons::RadioButtons;
pub use separator::Separator;
pub use slider::Slider;
pub use spinbox::Spinbox;
pub use tab::Tab;
// pub use table::{Model as TableModel, Table};
pub use text_entry::TextEntry;
pub use ui::Ui;
pub use window::Window;

/// The error type returned by fallible *boing* functions.
#[derive(Debug)]
pub enum Error {
    /// *libui-ng* is already initialized.
    ///
    /// This error is returned from [`Ui::new`] when called multiple times. Please ensure that
    /// [`Ui::new`] is invoked exactly once in your application.
    AlreadyInitedLibui,
    /// A C string failed to be converted to a Rust string.
    ConvertCString(std::str::Utf8Error),
    /// A Rust string failed to be converted to a C string.
    ConvertRustString(std::ffi::NulError),
    /// A *libui-ng* function failed.
    LibuiFn {
        /// The name of the function that failed.
        name: &'static str,
        /// The cause, if any, of the failure.
        cause: Option<String>,
    },
}

impl std::error::Error for Error {}
impl fmt::Display for Error {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        match self {
            Self::AlreadyInitedLibui => {
                f.write_str("libui-ng is already initialized")
            }
            Self::ConvertCString(e) => {
                write!(f, "failed to convert C string to Rust string: {e}")
            }
            Self::ConvertRustString(e) => {
                write!(f, "failed to convert Rust string to C string: {e}")
            }
            Self::LibuiFn { name, cause } => {
                write!(f, "libui-ng function {name}() failed")?;
                if let Some(cause) = cause {
                    write!(f, ": {cause}")?;
                }

                Ok(())
            }
        }
    }
}

/// A graphical element.
pub trait Widget: prelude::Sealed {
    /// The corresponding *libui-ng* type.
    type Handle;

    /// A handle to the underlying *libui-ng* object.
    ///
    /// # Safety
    ///
    /// The returned pointer is guaranteed to be non-null. Beyond that, it is your
    /// responsibility to use the handle appropriately. Consulting the *libui-ng*
    /// documentation or source code may be helpful, as well as the *boing* or
    /// *[libui-ng-sys]* source code.
    ///
    /// [libui-ng-sys]: https://github.com/norepimorphism/libui-ng-sys
    #[must_use]
    fn as_ptr(&self) -> *mut Self::Handle;
}

/// A control that contains other controls.
pub trait Container: prelude::Sealed {
    #[must_use]
    fn is_empty(&self) -> bool {
        self.child_count().to_libui() == 0
    }

    /// The number of child controls this control contains.
    ///
    /// On creation, this is 0.
    #[must_use]
    fn child_count(&self) -> NonNegativeInt;

    /// Determines if a child control at the given index exists.
    fn contains_child(&self, index: impl Into<NonNegativeInt>) -> bool {
        index.into() < self.child_count()
    }

    /// Removes the child control that was pushed last.
    ///
    /// If there are no children, this does nothing.
    ///
    /// Unlike [`remove_child`](Self::remove_child), this will not invalidate the indices of any
    /// other children.
    fn pop_child(&self) {
        let child_count = self.child_count().to_libui();
        let index = child_count - 1;

        if index >= 0 {
            // SAFETY: `index` is non-negative.
            self.remove_child(unsafe { NonNegativeInt::from_libui(index) });
        }
    }

    /// Removes the child control at the given index.
    ///
    /// # Panics
    ///
    /// Panics if the index is out of bounds.
    ///
    /// # Warning
    ///
    /// This action **will** invalidate the indices of all children after this child. For
    /// example, after removing a child with index 3, the child previously represented by index
    /// 4 now fills index 3, and removing a child with index 4 will then remove the child
    /// previously represented by index 5.
    fn remove_child(&self, index: impl Into<NonNegativeInt>);

    /// Removes all child controls.
    fn clear(&self) {
        // Note: this is essentially equivalent to calling [`pop_child`] in a loop but is a little
        // more efficient.
        for i in (0..self.child_count().to_libui()).into_iter().rev() {
            self.remove_child(unsafe { NonNegativeInt::from_libui(i) });
        }
    }
}

mod non_negative_int {
    //! The primary non-negative integer type used by *libui-ng*.

    use std::os::raw::c_int;

    macro_rules! impl_from_uints {
        ($( $ty:ty )*) => {
            $(
                impl From<$ty> for NonNegativeInt {
                    #[inline]
                    fn from(value: $ty) -> Self {
                        Self(value.into())
                    }
                }
            )*
        };
    }

    macro_rules! impl_try_from_uints {
        ($( $ty:ty )*) => {
            $(
                impl TryFrom<$ty> for NonNegativeInt {
                    type Error = std::num::TryFromIntError;

                    #[inline]
                    fn try_from(value: $ty) -> Result<Self, Self::Error> {
                        value.try_into().map(Self)
                    }
                }
            )*
        };
    }

    impl_from_uints!(u8 u16);
    impl_try_from_uints!(u32 u128 usize);

    impl NonNegativeInt {
        /// Initializes a `NonNegativeInt` with a non-negative integer returned from *libui-ng*.
        ///
        /// # Safety
        ///
        /// `value` must be non-negative (i.e., greater than or equal to zero).
        pub(crate) unsafe fn from_libui(value: c_int) -> Self {
            Self(value)
        }
    }

    /// The primary non-negative integer type used by *libui-ng*.
    ///
    /// Many *boing* functions that interface with the *libui-ng* API accept or return values of
    /// this type where non-negative (i.e., greater than or equal to zero) integers are expected.
    ///
    /// # Representation
    ///
    /// As a portable C library, *libui-ng* chose the signed `int` type to represent all integers,
    /// including those that are semantically non-negative (e.g., indices, quantities). For this
    /// reason, `NonNegativeInt` is represented by the Rust equivalent, `c_int`. However, to
    /// preserve *libui-ng* semantics, a `NonNegativeInt` can only be constructed by unsigned
    /// integer types like `u8`, `u16`, and `u32`.
    ///
    /// This is also why `NonNegativeInt` implements [`From`] for `u8` and `u16` but [`TryFrom`] for
    /// `u32`. An `c_int` cannot encode the full range of positive values of a `u32`, and in
    /// particular, the conversion will fail for `u32` values above [`c_int::MAX`].
    ///
    /// # Usage
    ///
    /// In many cases, you can treat `NonNegativeInt` as an opaque type. For example, indices of the
    /// type `NonNegativeInt` returned by allocation functions like
    /// [`Tab::push_new_page`](crate::tab::push_new_page) can be used as handles without regard to
    /// the integer values they contain. But, if you do need to obtain the value of a
    /// `NonNegativeInt`, you can use [`as_u32`](Self::as_u32). Note that although a `u32` is
    /// returned, the value will still not exceed [`c_int::MAX`].
    #[derive(Clone, Copy, Debug, Eq, Ord, PartialEq, PartialOrd)]
    #[repr(transparent)]
    pub struct NonNegativeInt(c_int);

    impl NonNegativeInt {
        /// The inner `c_int`.
        ///
        /// This function should only be used to extract `c_int`s from `NonNegativeInt`s that are
        /// guaranteed to be non-negative, such as those created from unsigned integers with
        /// [`From`] or [`TryFrom`].
        pub(crate) fn to_libui(self) -> c_int {
            self.0
        }

        /// Obtains the value as a `u32`.
        ///
        /// # Panics
        ///
        /// This function may panic in exceptional circumstances such as when a `NonNegativeInt`
        /// contains a negative integer returned by *libui-ng* where a non-negative integer was
        /// expected.
        pub fn as_u32(self) -> u32 {
            match u32::try_from(self.0) {
                Ok(it) => it,
                Err(_) => {
                    panic!(
                        "Found a negative integer ({}) where a non-negative integer was expected. \
                        \
                        I would greatly appreciate if you submitted an issue to the *boing* \
                        repository. Thanks! ~norepi",
                        self.0,
                    );
                }
            }
        }
    }
}