nodui 0.2.1

An egui-based visual graph editor
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129

//! The graph editor.

mod connections;
mod response;
mod show;
pub mod stages;
mod state;

use egui::Id;

use crate::{
    misc::viewport::ViewportSize,
    viewport::{CanvasPos, Grid, Viewport},
    Pos, RenderedSocket,
};

pub use connections::ConnectionsUi;
pub use response::GraphResponse;
pub use show::{GraphUi, NodeResponse, NodeUi};

use state::EditorState;

/* -------------------------------------------------------------------------- */

/// A node based graph editor.
///
/// The following methods must be called in order:
///
/// - [`new`][Self::new]: Creates the graph editor.
/// - [`show`][Self::show]: Allocates the space in the ui and renders the viewport and the nodes.
/// - [`show_connections`][Self::show_connections]: Renders the connections between the sockets and returns the [`GraphResponse`].
///
/// ```
/// # #[derive(Clone, PartialEq)]
/// # struct SocketId;
/// fn show_graph_editor(ui: &mut egui::Ui) {
///     let response: nodui::GraphResponse::<SocketId> = nodui::GraphEditor::new("a unique id")
///         .show(ui, |ui| {
///             /* This is where you add the nodes */
///         })
///         .show_connections(|ui| {
///             /* This is where you add the connections between sockets */
///         });
/// }
/// ```
pub struct GraphEditor<Stage> {
    /// The id used to store data from one frame to the other.
    id: Id,
    /// The current stage of the editor.
    stage: Stage,
}

impl GraphEditor<stages::Settings> {
    /// Creates a new [`GraphEditor`].
    #[inline]
    pub fn new(id_salt: impl core::hash::Hash) -> Self {
        Self {
            id: Id::new(id_salt),
            stage: stages::Settings {
                show_grid: false,
                look_at: None,
                can_connect_socket: true,
                viewport: ViewportSize::default(),
            },
        }
    }

    /// Move the viewport to make `pos` on the center of the viewport.
    #[inline]
    #[must_use]
    pub fn look_at(mut self, pos: Pos) -> Self {
        self.stage.look_at = Some(pos);
        self
    }

    /// Should show the grid.
    ///
    /// Default to `false`.
    #[inline]
    #[must_use]
    pub fn show_grid(mut self, show_grid: bool) -> Self {
        self.stage.show_grid = show_grid;
        self
    }

    /// If `true` the user can drag-n-drop a socket to create a connection.
    ///
    /// Can be useful to prevent user to edit the graph.
    ///
    /// Default to `true`.
    #[inline]
    #[must_use]
    pub fn can_connect_socket(mut self, can_connect_socket: bool) -> Self {
        self.stage.can_connect_socket = can_connect_socket;
        self
    }

    /// `width / height` ratio of the editor region.
    ///
    /// By default no fixed aspect ratio is set (and width/height will fill the ui it is in).
    #[inline]
    #[must_use]
    pub fn view_aspect(mut self, view_aspect: f32) -> Self {
        self.stage.viewport = self.stage.viewport.view_aspect(view_aspect);
        self
    }

    /// Width of the editor. By default it will fill the ui it is in.
    ///
    /// If you set [`Self::view_aspect`], the width can be calculated from the height.
    #[inline]
    #[must_use]
    pub fn width(mut self, width: f32) -> Self {
        self.stage.viewport = self.stage.viewport.width(width);
        self
    }

    /// Height of the editor. By default it will fill the ui it is in.
    ///
    /// If you set [`Self::view_aspect`], the height can be calculated from the width.
    #[inline]
    #[must_use]
    pub fn height(mut self, height: f32) -> Self {
        self.stage.viewport = self.stage.viewport.height(height);
        self
    }
}

/* -------------------------------------------------------------------------- */