imnodes 0.5.0

#![deny(missing_docs)]
#![warn(rustdoc::broken_intra_doc_links)]

/*!
High-level, safe bindings for [imnodes](https://github.com/Nelarius/imnodes),
a node editor extension for [imgui-rs](https://github.com/imgui-rs/imgui-rs).

Based on the C API bindings generated by [cimnodes](https://github.com/cimgui/cimnodes).

# Usage

1. Create an [`imnodes::Context`](crate::Context) once at application startup.
2. Create an [`imnodes::EditorContext`](crate::EditorContext) for each node editor you want to display.
3. In your UI loop, call [`EditorContext::set_as_current_editor`] before defining the editor UI.
4. Use the [`imnodes::editor`](crate::editor) function to define the node editor content.

```no_run
# use imgui;
# use imnodes;
# struct State { editor_context: imnodes::EditorContext }
# let mut state: State = unimplemented!();
# let ui: &imgui::Ui = unimplemented!();
// Before calling editor:
state.editor_context.set_as_current_editor();
let mut node_id_gen = state.editor_context.new_identifier_generator();

let outer_scope = imnodes::editor(&mut state.editor_context, |mut editor_scope| {
    editor_scope.add_node(node_id_gen.next_node(), |mut node_scope| {
        node_scope.add_titlebar(|| ui.text("My Node"));
        node_scope.add_input(node_id_gen.next_input_pin(), imnodes::PinShape::Circle, || {
             ui.text("Input Pin");
        });
        node_scope.add_output(node_id_gen.next_output_pin(), imnodes::PinShape::Triangle, || {
             ui.text("Output Pin");
        });
    });
    // Add more nodes and links...
});

// Handle events after the editor scope ends
if let Some(link) = outer_scope.links_created() {
   // handle new link creation
}
if let Some(dropped_link_id) = outer_scope.get_destroyed_link() {
    // handle link deletion
}



Identifiers

imnodes requires unique integer IDs for nodes, pins (attributes), and links.
The [IdentifierGenerator] struct provides a convenient way to generate these unique IDs within an editor context.
*/

use imnodes_sys as sys;

/// Re-export the low-level FFI bindings if the feature is enabled.
/// Use with caution.
#[cfg(feature = "include_low_level_bindings")]
pub mod internal {
    pub use imnodes_sys::*;
}

mod context;
pub use context::*;

mod helpers;
// Helpers are exposed directly on EditorContext or as standalone functions where appropriate.

mod styling;
pub use styling::*;

mod scopes;
pub use scopes::*;

// Re-export essential types from the sys crate or imgui crate
pub use sys::{ImNodesIO, ImVec2}; // Re-export ImNodesStyle via the wrapper 'Style' in styling.rs

/// Provides unique identifiers for nodes, pins, attributes, and links within an editor context.
///
/// Create one generator per [EditorContext] using [EditorContext::new_identifier_generator].
#[derive(Debug)]
pub struct IdentifierGenerator {
    current_node: i32,
    // Input pins, output pins, and static attributes share the same ID space in imnodes.
    current_attribute: i32,
    current_link: i32,
}

impl IdentifierGenerator {
    /// Creates a new identifier generator, starting all IDs from 0.
    /// Intended to be called via [EditorContext::new_identifier_generator].
    pub(crate) fn new() -> Self {
        Self {
            current_node: 0,
            current_attribute: 0,
            current_link: 0,
        }
    }

    /// Generates the next unique ID for a node.
    pub fn next_node(&mut self) -> NodeId {
        let id = self.current_node;
        self.current_node = self.current_node.checked_add(1).unwrap();
        NodeId { id }
    }

    /// Generates the next unique ID for an input pin.
    pub fn next_input_pin(&mut self) -> InputPinId {
        let id = self.current_attribute;
        self.current_attribute = self.current_attribute.checked_add(1).unwrap();
        InputPinId { id }
    }

    /// Generates the next unique ID for an output pin.
    pub fn next_output_pin(&mut self) -> OutputPinId {
        let id = self.current_attribute;
        self.current_attribute = self.current_attribute.checked_add(1).unwrap();
        OutputPinId { id }
    }

    /// Generates the next unique ID for a static attribute (one without a pin).
    pub fn next_attribute(&mut self) -> AttributeId {
        let id = self.current_attribute;
        self.current_attribute = self.current_attribute.checked_add(1).unwrap();
        AttributeId { id }
    }

    /// Generates the next unique ID for a link.
    pub fn next_link(&mut self) -> LinkId {
        let id = self.current_link;
        self.current_link = self.current_link.checked_add(1).unwrap();
        LinkId { id }
    }
}

/// Identifier for a static attribute within a node (an attribute without a pin).
///
/// IDs must be unique within the editor context. Generated using [IdentifierGenerator::next_attribute].
#[repr(C)]
#[derive(Debug, Copy, Clone, Hash, Eq, PartialEq)]
pub struct AttributeId {
    id: i32,
}

impl From<AttributeId> for i32 {
    fn from(val: AttributeId) -> Self {
        val.id
    }
}

/// Specifies the coordinate system for getting or setting node positions.
///
/// The node's position can be expressed in three coordinate systems:
/// * ScreenSpace: The origin (0,0) is the top-left corner of the main application window. Useful for placing nodes relative to the entire window or other ImGui elements.
/// * EditorSpace: The origin (0,0) is the top-left corner of the node editor canvas (the area within the imnodes::editor block). Node positions are relative to this canvas, ignoring panning.
/// * GridSpace: The origin (0,0) is the logical origin of the node grid, taking into account the current panning of the editor canvas. This is often the most intuitive system for saving/loading node layouts, as positions remain consistent regardless of the view's pan offset. See [EditorContext::get_panning()] and [EditorContext::reset_panning()].
#[derive(Debug, Clone, Copy, Hash, Eq, PartialEq)]
pub enum CoordinateSystem {
    /// Origin at the top-left of the application window.
    ScreenSpace,
    /// Origin at the top-left of the node editor canvas.
    EditorSpace,
    /// Origin at the top-left of the node editor canvas, adjusted by panning.
    GridSpace,
}

/// Identifier for a Node.
///
/// IDs must be unique within the editor context. Generated using [IdentifierGenerator::next_node].
#[repr(C)]
#[derive(Debug, Copy, Clone, Hash, Eq, PartialEq)]
pub struct NodeId {
    id: i32,
}

impl NodeId {
    /// Sets whether this node can be dragged by the user.
    #[doc(alias = "SetNodeDraggable")]
    #[must_use]
    pub fn set_draggable(&self, draggable: bool) -> &Self {
        // Safety: C API call with a valid node ID.
        unsafe { sys::imnodes_SetNodeDraggable(self.id, draggable) };
        self
    }

    /// Pans the editor view to center on this node.
    #[doc(alias = "EditorContextMoveToNode")]
    #[must_use]
    pub fn move_editor_to(&self) -> &Self {
        // Safety: C API call with a valid node ID.
        // Assumes the editor context owning this node is current.
        unsafe {
            sys::imnodes_EditorContextMoveToNode(self.id);
        }
        self
    }

    /// Gets the dimensions (width, height) of this node.
    ///
    /// Note: This must be called *after* the node has been submitted in the current frame,
    /// otherwise the dimensions might be outdated or zero.
    #[doc(alias = "GetNodeDimensions")]
    #[must_use]
    pub fn get_dimensions(&self) -> ImVec2 {
        let mut dimension = ImVec2 { x: 0.0, y: 0.0 };
        // Safety: C API call. `dimension` is written to by the function.
        unsafe {
            sys::imnodes_GetNodeDimensions(core::ptr::from_mut(&mut dimension), self.id);
        }
        dimension
    }

    /// Sets the position of the top-left corner of this node in the specified coordinate system.
    #[doc(
        alias = "SetNodeScreenSpacePos",
        alias = "SetNodeEditorSpacePos",
        alias = "SetNodeGridSpacePos"
    )]
    #[must_use]
    pub fn set_position(&self, x: f32, y: f32, coordinate_system: CoordinateSystem) -> &Self {
        let pos = ImVec2 { x, y };
        // Safety: C API calls with a valid node ID and position.
        match coordinate_system {
            CoordinateSystem::ScreenSpace => unsafe {
                sys::imnodes_SetNodeScreenSpacePos(self.id, pos);
            },
            CoordinateSystem::EditorSpace => unsafe {
                sys::imnodes_SetNodeEditorSpacePos(self.id, pos);
            },
            CoordinateSystem::GridSpace => unsafe {
                sys::imnodes_SetNodeGridSpacePos(self.id, pos);
            },
        };
        self
    }

    /// Gets the position of the top-left corner of this node in the specified coordinate system.
    ///
    /// Note: This must be called *after* the node has been submitted in the current frame,
    /// otherwise the position might be outdated.
    #[doc(
        alias = "GetNodeScreenSpacePos",
        alias = "GetNodeEditorSpacePos",
        alias = "GetNodeGridSpacePos"
    )]
    #[must_use]
    pub fn get_position(&self, coordinate_system: CoordinateSystem) -> ImVec2 {
        let mut pos = ImVec2 { x: 0.0, y: 0.0 };
        // Safety: C API calls. `pos` is written to by the function.
        match coordinate_system {
            CoordinateSystem::ScreenSpace => unsafe {
                sys::imnodes_GetNodeScreenSpacePos(core::ptr::from_mut(&mut pos), self.id);
            },
            CoordinateSystem::EditorSpace => unsafe {
                sys::imnodes_GetNodeEditorSpacePos(core::ptr::from_mut(&mut pos), self.id);
            },
            CoordinateSystem::GridSpace => unsafe {
                sys::imnodes_GetNodeGridSpacePos(core::ptr::from_mut(&mut pos), self.id);
            },
        };
        pos
    }

    /// Aligns the node's top-left corner to the grid lines.
    /// Requires the [`StyleFlags::GridSnapping`] flag to be enabled in the style.
    #[doc(alias = "SnapNodeToGrid")]
    #[must_use]
    pub fn snap_to_grid(&self) -> &Self {
        // Safety: C API call with a valid node ID.
        unsafe { sys::imnodes_SnapNodeToGrid(self.id) };
        self
    }

    /// Selects this node.
    #[doc(alias = "SelectNode")]
    #[must_use]
    pub fn select(&self) -> &Self {
        // Safety: C API call with a valid node ID.
        unsafe { sys::imnodes_SelectNode(self.id) };
        self
    }

    /// Deselects this node.
    /// If no other nodes are selected, this is equivalent to [`EditorContext::clear_node_selection`].
    #[doc(alias = "ClearNodeSelection_Int")]
    #[must_use]
    pub fn deselect(&self) -> &Self {
        // Safety: C API call with a valid node ID.
        unsafe { sys::imnodes_ClearNodeSelection_Int(self.id) };
        self
    }

    /// Checks if this node is currently selected.
    #[doc(alias = "IsNodeSelected")]
    #[must_use]
    pub fn is_selected(&self) -> bool {
        // Safety: C API call with a valid node ID.
        unsafe { sys::imnodes_IsNodeSelected(self.id) }
    }
}

impl From<NodeId> for i32 {
    fn from(val: NodeId) -> Self {
        val.id
    }
}

/// Generic identifier for either an input or output pin.
///
/// Corresponds to attribute_id in the C++ source.
/// Can be obtained by converting from [InputPinId] or [OutputPinId].
#[derive(Debug, Copy, Clone, Hash, Eq, PartialEq)]
pub struct PinId {
    id: i32,
}

impl PinId {
    /// Checks if the user started dragging a new link from this pin in the current frame.
    ///
    /// Call this after [crate::editor()] has returned.
    #[doc(alias = "IsLinkStarted")]
    #[must_use]
    pub fn is_start_of_link(&self, scope: &OuterScope) -> bool {
        Some(*self) == scope.from_where_link_started()
    }

    /// Checks if the user dropped a dragged link originating from this pin without connecting it.
    ///
    /// Call this after [`crate::editor()`] has returned.
    ///
    /// # Arguments
    /// * `including_detached_links`: If `true`, also returns `true` if an existing link was detached from this pin and then dropped. If `false`, only triggers for newly created links that are dropped.
    #[doc(alias = "IsLinkDropped")]
    #[must_use]
    pub fn dropped_link(&self, including_detached_links: bool, scope: &OuterScope) -> bool {
        Some(*self) == scope.from_where_link_dropped(including_detached_links)
    }
}

/// Identifier for an input pin (rendered on the left side of a node).
///
/// IDs must be unique within the editor context. Generated using [IdentifierGenerator::next_input_pin].
#[derive(Debug, Copy, Clone, Hash, Eq, PartialEq)]
pub struct InputPinId {
    id: i32,
}

impl From<InputPinId> for i32 {
    fn from(val: InputPinId) -> Self {
        val.id
    }
}

impl From<InputPinId> for PinId {
    fn from(val: InputPinId) -> Self {
        Self { id: val.id }
    }
}

/// Identifier for an output pin (rendered on the right side of a node).
///
/// IDs must be unique within the editor context. Generated using [IdentifierGenerator::next_output_pin].
#[derive(Debug, Copy, Clone, Hash, Eq, PartialEq)]
pub struct OutputPinId {
    id: i32,
}

impl From<OutputPinId> for i32 {
    fn from(val: OutputPinId) -> Self {
        val.id
    }
}

impl From<OutputPinId> for PinId {
    fn from(val: OutputPinId) -> Self {
        Self { id: val.id }
    }
}

/// Identifier for a link between two pins.
///
/// IDs must be unique within the editor context. Generated using [IdentifierGenerator::next_link].
#[derive(Debug, Copy, Clone, Hash, Eq, PartialEq)]
pub struct LinkId {
    id: i32,
}

impl LinkId {
    /// Checks if this link was destroyed (detached) by the user in the current frame.
    ///
    /// Call this after [crate::editor()] has returned.
    #[doc(alias = "IsLinkDestroyed")]
    #[must_use]
    pub fn is_destroyed(&self, scope: &OuterScope) -> bool {
        Some(*self) == scope.get_destroyed_link()
    }

    /// Selects this link.
    #[doc(alias = "SelectLink")]
    #[must_use]
    pub fn select(&self) -> &Self {
        // Safety: C API call with a valid link ID.
        unsafe { sys::imnodes_SelectLink(self.id) };
        self
    }

    /// Deselects this link.
    /// If no other links are selected, this is equivalent to [`EditorContext::clear_link_selection`].
    #[doc(alias = "ClearLinkSelection_Int")]
    #[must_use]
    pub fn deselect(&self) -> &Self {
        // Safety: C API call with a valid link ID.
        unsafe { sys::imnodes_ClearLinkSelection_Int(self.id) };
        self
    }

    /// Checks if this link is currently selected.
    #[doc(alias = "IsLinkSelected")]
    #[must_use]
    pub fn is_selected(&self) -> bool {
        // Safety: C API call with a valid link ID.
        unsafe { sys::imnodes_IsLinkSelected(self.id) }
    }
}

impl From<LinkId> for i32 {
    fn from(val: LinkId) -> Self {
        val.id
    }
}

/// Trait implemented by elements that can be hovered over by the mouse.
pub trait Hoverable {
    /// Checks if this UI element is being hovered over by the mouse cursor in the current frame.
    ///
    /// Call this after [crate::editor()] has returned.
    /// For checking editor canvas hovering, see [crate::scopes::EditorScope::is_hovered()].
    #[doc(
        alias = "IsPinHovered",
        alias = "IsNodeHovered",
        alias = "IsLinkHovered"
    )]
    fn is_hovered(&self, scope: &OuterScope) -> bool;
}

impl Hoverable for OutputPinId {
    /// Checks if the pin is hovered.
    #[doc(alias = "IsPinHovered")]
    fn is_hovered(&self, scope: &OuterScope) -> bool {
        Some(PinId { id: self.id }) == scope.get_hovered_pin()
    }
}

impl Hoverable for InputPinId {
    /// Checks if the pin is hovered.
    #[doc(alias = "IsPinHovered")]
    fn is_hovered(&self, scope: &OuterScope) -> bool {
        Some(PinId { id: self.id }) == scope.get_hovered_pin()
    }
}

impl Hoverable for NodeId {
    /// Checks if the node is hovered.
    #[doc(alias = "IsNodeHovered")]
    fn is_hovered(&self, _scope: &OuterScope) -> bool {
        // Can be checked globally, doesn't need the scope.
        Some(*self) == get_hovered_node()
    }
}

impl Hoverable for LinkId {
    /// Checks if the link is hovered.
    #[doc(alias = "IsLinkHovered")]
    fn is_hovered(&self, scope: &OuterScope) -> bool {
        Some(*self) == scope.get_hovered_link()
    }
}

/// Returns the ID of the node currently being hovered over, if any.
/// This can be called outside the [OuterScope] if needed.
#[doc(alias = "IsNodeHovered")]
#[must_use]
pub fn get_hovered_node() -> Option<NodeId> {
    let mut id: i32 = -1;
    // Safety: C API call. id is potentially written to.
    let ok = unsafe { sys::imnodes_IsNodeHovered(core::ptr::from_mut(&mut id)) };
    if ok && id >= 0 {
        Some(NodeId { id })
    } else {
        None
    }
}

/// Represents a link successfully created by the user in the current frame.
///
/// Obtained from [OuterScope::links_created()]. Contains the start and end pins
/// as well as the start and end nodes involved in the link creation.
#[derive(Debug, Copy, Clone, Hash, Eq, PartialEq)]
pub struct Link {
    /// The ID of the node where the link started.
    pub start_node: NodeId,
    /// The ID of the node where the link ended.
    pub end_node: NodeId,
    /// The ID of the output pin where the link started.
    pub start_pin: OutputPinId,
    /// The ID of the input pin where the link ended.
    pub end_pin: InputPinId,
    /// Flag indicating if the link was created by snapping to a pin node when [AttributeFlags::EnableLinkCreationOnSnap] is enabled.
    pub created_from_snap: bool,
}