dear_imgui_rs/dock_space/ui.rs
1use super::flags::{DockNodeFlags, validate_dock_node_flags};
2use super::validation::{assert_finite_vec2, assert_nonzero_id};
3use super::window_class::WindowClass;
4use crate::ui::Ui;
5use crate::{Id, sys};
6use std::ptr;
7
8/// Docking-related functionality
9impl Ui {
10 /// Creates a dockspace over the main viewport
11 ///
12 /// This is a convenience function that creates a dockspace covering the entire main viewport.
13 /// It's equivalent to calling `dock_space` with the main viewport's ID and size.
14 ///
15 /// # Parameters
16 ///
17 /// * `dockspace_id` - The ID for the dockspace (use 0 to auto-generate)
18 /// * `flags` - Dock node flags
19 ///
20 /// # Returns
21 ///
22 /// The ID of the created dockspace
23 ///
24 /// # Example
25 ///
26 /// ```no_run
27 /// # use dear_imgui_rs::*;
28 /// # let mut ctx = Context::create();
29 /// # let ui = ctx.frame();
30 /// let dockspace_id = ui.dockspace_over_main_viewport_with_flags(
31 /// 0.into(),
32 /// DockNodeFlags::PASSTHRU_CENTRAL_NODE
33 /// );
34 /// ```
35 #[doc(alias = "DockSpaceOverViewport")]
36 pub fn dockspace_over_main_viewport_with_flags(
37 &self,
38 dockspace_id: Id,
39 flags: DockNodeFlags,
40 ) -> Id {
41 validate_dock_node_flags("Ui::dockspace_over_main_viewport_with_flags()", flags);
42 unsafe {
43 Id::from(sys::igDockSpaceOverViewport(
44 dockspace_id.into(),
45 sys::igGetMainViewport(),
46 flags.bits(),
47 ptr::null(),
48 ))
49 }
50 }
51
52 /// Creates a dockspace over the main viewport with default settings
53 ///
54 /// This is a convenience function that creates a dockspace covering the entire main viewport
55 /// with passthrough central node enabled.
56 ///
57 /// # Returns
58 ///
59 /// The ID of the created dockspace
60 ///
61 /// # Example
62 ///
63 /// ```no_run
64 /// # use dear_imgui_rs::*;
65 /// # let mut ctx = Context::create();
66 /// # let ui = ctx.frame();
67 /// let dockspace_id = ui.dockspace_over_main_viewport();
68 /// ```
69 #[doc(alias = "DockSpaceOverViewport")]
70 pub fn dockspace_over_main_viewport(&self) -> Id {
71 self.dockspace_over_main_viewport_with_flags(
72 Id::from(0u32),
73 DockNodeFlags::PASSTHRU_CENTRAL_NODE,
74 )
75 }
76
77 /// Creates a dockspace with the specified ID, size, and flags
78 ///
79 /// # Parameters
80 ///
81 /// * `id` - The non-zero ID for the dockspace. Use [`Ui::get_id`] to create one.
82 /// * `size` - The size of the dockspace in pixels
83 /// * `flags` - Dock node flags
84 /// * `window_class` - Optional window class for docking configuration
85 ///
86 /// # Returns
87 ///
88 /// The ID of the created dockspace
89 ///
90 /// # Example
91 ///
92 /// ```no_run
93 /// # use dear_imgui_rs::*;
94 /// # let mut ctx = Context::create();
95 /// # let ui = ctx.frame();
96 /// let dockspace_id = ui.get_id("MyDockspace");
97 /// let dockspace_id = ui.dock_space_with_class(
98 /// dockspace_id,
99 /// [800.0, 600.0],
100 /// DockNodeFlags::NO_DOCKING_SPLIT,
101 /// Some(&WindowClass::new(Id::from(1u32)))
102 /// );
103 /// ```
104 #[doc(alias = "DockSpace")]
105 pub fn dock_space_with_class(
106 &self,
107 id: Id,
108 size: [f32; 2],
109 flags: DockNodeFlags,
110 window_class: Option<&WindowClass>,
111 ) -> Id {
112 validate_dock_node_flags("Ui::dock_space_with_class()", flags);
113 assert_nonzero_id("Ui::dock_space_with_class()", "id", id);
114 assert_finite_vec2("Ui::dock_space_with_class()", "size", size);
115 unsafe {
116 let size_vec = sys::ImVec2 {
117 x: size[0],
118 y: size[1],
119 };
120 let imgui_window_class =
121 window_class.map(|class| class.to_imgui("Ui::dock_space_with_class()"));
122 let window_class_ptr = imgui_window_class
123 .as_ref()
124 .map_or(ptr::null(), |wc| wc as *const _);
125 Id::from(sys::igDockSpace(
126 id.into(),
127 size_vec,
128 flags.bits(),
129 window_class_ptr,
130 ))
131 }
132 }
133
134 /// Creates a dockspace with the specified ID and size
135 ///
136 /// # Parameters
137 ///
138 /// * `id` - The non-zero ID for the dockspace
139 /// * `size` - The size of the dockspace in pixels
140 ///
141 /// # Returns
142 ///
143 /// The ID of the created dockspace
144 ///
145 /// # Example
146 ///
147 /// ```no_run
148 /// # use dear_imgui_rs::*;
149 /// # let mut ctx = Context::create();
150 /// # let ui = ctx.frame();
151 /// let dockspace_id = ui.get_id("MyDockspace");
152 /// let dockspace_id = ui.dock_space(dockspace_id, [800.0, 600.0]);
153 /// ```
154 #[doc(alias = "DockSpace")]
155 pub fn dock_space(&self, id: Id, size: [f32; 2]) -> Id {
156 self.dock_space_with_class(id, size, DockNodeFlags::NONE, None)
157 }
158
159 /// Sets the dock ID for the next window with condition
160 ///
161 /// This function must be called before creating a window to dock it to a specific dock node.
162 ///
163 /// # Parameters
164 ///
165 /// * `dock_id` - The ID of the dock node to dock the next window to
166 /// * `cond` - Condition for when to apply the docking
167 ///
168 /// # Example
169 ///
170 /// ```no_run
171 /// # use dear_imgui_rs::*;
172 /// # let mut ctx = Context::create();
173 /// # let ui = ctx.frame();
174 /// let dockspace_id = ui.dockspace_over_main_viewport();
175 /// ui.set_next_window_dock_id_with_cond(dockspace_id, Condition::FirstUseEver);
176 /// ui.window("Docked Window").build(|| {
177 /// ui.text("This window will be docked!");
178 /// });
179 /// ```
180 #[doc(alias = "SetNextWindowDockID")]
181 pub fn set_next_window_dock_id_with_cond(&self, dock_id: Id, cond: crate::Condition) {
182 unsafe {
183 sys::igSetNextWindowDockID(dock_id.into(), cond as i32);
184 }
185 }
186
187 /// Sets the dock ID for the next window
188 ///
189 /// This function must be called before creating a window to dock it to a specific dock node.
190 /// Uses `Condition::Always` by default.
191 ///
192 /// # Parameters
193 ///
194 /// * `dock_id` - The ID of the dock node to dock the next window to
195 ///
196 /// # Example
197 ///
198 /// ```no_run
199 /// # use dear_imgui_rs::*;
200 /// # let mut ctx = Context::create();
201 /// # let ui = ctx.frame();
202 /// let dockspace_id = ui.dockspace_over_main_viewport();
203 /// ui.set_next_window_dock_id(dockspace_id);
204 /// ui.window("Docked Window").build(|| {
205 /// ui.text("This window will be docked!");
206 /// });
207 /// ```
208 #[doc(alias = "SetNextWindowDockID")]
209 pub fn set_next_window_dock_id(&self, dock_id: Id) {
210 self.set_next_window_dock_id_with_cond(dock_id, crate::Condition::Always)
211 }
212
213 /// Sets the window class for the next window
214 ///
215 /// This function must be called before creating a window to apply the window class configuration.
216 ///
217 /// # Parameters
218 ///
219 /// * `window_class` - The window class configuration
220 ///
221 /// # Example
222 ///
223 /// ```no_run
224 /// # use dear_imgui_rs::*;
225 /// # let mut ctx = Context::create();
226 /// # let ui = ctx.frame();
227 /// let window_class = WindowClass::new(Id::from(1u32)).docking_always_tab_bar(true);
228 /// ui.set_next_window_class(&window_class);
229 /// ui.window("Classed Window").build(|| {
230 /// ui.text("This window has a custom class!");
231 /// });
232 /// ```
233 #[doc(alias = "SetNextWindowClass")]
234 pub fn set_next_window_class(&self, window_class: &WindowClass) {
235 unsafe {
236 let imgui_wc = window_class.to_imgui("Ui::set_next_window_class()");
237 sys::igSetNextWindowClass(&imgui_wc as *const _);
238 }
239 }
240
241 /// Gets the dock ID of the current window
242 ///
243 /// # Returns
244 ///
245 /// The dock ID of the current window, or 0 if the window is not docked
246 ///
247 /// # Example
248 ///
249 /// ```no_run
250 /// # use dear_imgui_rs::*;
251 /// # let mut ctx = Context::create();
252 /// # let ui = ctx.frame();
253 /// ui.window("My Window").build(|| {
254 /// let dock_id = ui.get_window_dock_id();
255 /// if dock_id != 0.into() {
256 /// ui.text(format!("This window is docked with ID: {}", dock_id.raw()));
257 /// } else {
258 /// ui.text("This window is not docked");
259 /// }
260 /// });
261 /// ```
262 #[doc(alias = "GetWindowDockID")]
263 pub fn get_window_dock_id(&self) -> Id {
264 unsafe { Id::from(sys::igGetWindowDockID()) }
265 }
266
267 /// Checks if the current window is docked
268 ///
269 /// # Returns
270 ///
271 /// `true` if the current window is docked, `false` otherwise
272 ///
273 /// # Example
274 ///
275 /// ```no_run
276 /// # use dear_imgui_rs::*;
277 /// # let mut ctx = Context::create();
278 /// # let ui = ctx.frame();
279 /// ui.window("My Window").build(|| {
280 /// if ui.is_window_docked() {
281 /// ui.text("This window is docked!");
282 /// } else {
283 /// ui.text("This window is floating");
284 /// }
285 /// });
286 /// ```
287 #[doc(alias = "IsWindowDocked")]
288 pub fn is_window_docked(&self) -> bool {
289 unsafe { sys::igIsWindowDocked() }
290 }
291}