Skip to main content

dear_imgui_cte/
text_diff.rs

1use crate::{
2    CteError, CteResult, Language, Palette,
3    context::CteContextBinding,
4    error::c_string,
5    sys,
6    validation::{
7        validate_finite_f32, validate_finite_vec2, validate_render_flags, validate_tab_size,
8    },
9};
10use dear_imgui_rs::{ChildFlags, Context, ContextId, Ui, WindowFlags};
11use std::{marker::PhantomData, ptr::NonNull, rc::Rc};
12
13/// An owned, context-bound syntax-highlighted text diff.
14///
15/// The diff is intentionally neither [`Send`] nor [`Sync`]. Every native call is
16/// made while its originating Dear ImGui context is current.
17pub struct TextDiff {
18    raw: NonNull<sys::TextDiff>,
19    binding: CteContextBinding,
20    _not_send_sync: PhantomData<Rc<()>>,
21}
22
23impl TextDiff {
24    /// Creates a text diff bound to `context`.
25    pub fn try_create(context: &Context) -> CteResult<Self> {
26        let binding = CteContextBinding::new(context);
27        let raw = binding.try_with_bound_context("TextDiff::try_create", || unsafe {
28            sys::TextDiff_TextDiff()
29        })?;
30        let raw = NonNull::new(raw).ok_or(CteError::CreationFailed { object: "TextDiff" })?;
31        Ok(Self {
32            raw,
33            binding,
34            _not_send_sync: PhantomData,
35        })
36    }
37
38    /// Creates a text diff and panics if native allocation fails.
39    pub fn create(context: &Context) -> Self {
40        Self::try_create(context).expect("failed to create cimCTE TextDiff")
41    }
42
43    /// Returns the stable identity of the owning Dear ImGui context.
44    pub fn context_id(&self) -> ContextId {
45        self.binding.id()
46    }
47
48    /// Returns the raw text-diff pointer.
49    ///
50    /// # Safety
51    ///
52    /// The pointer may only be used while the owning Dear ImGui context is current. The
53    /// caller must preserve every cimCTE precondition, ownership and pointer-lifetime rule,
54    /// and invariant relied on by this safe wrapper. In particular, the caller must not
55    /// destroy the diff, retain borrowed pointers, set a zero tab size, or install a language
56    /// pointer that can become invalid.
57    pub unsafe fn as_raw(&self) -> *mut sys::TextDiff {
58        self.raw.as_ptr()
59    }
60
61    /// Replaces both documents after validating both strings.
62    pub fn set_text(&mut self, left: &str, right: &str) -> CteResult<()> {
63        const OPERATION: &str = "TextDiff::set_text";
64        let left = c_string(OPERATION, left)?;
65        let right = c_string(OPERATION, right)?;
66        self.with_context(OPERATION, |raw| unsafe {
67            sys::TextDiff_SetText(raw, left.as_ptr(), right.as_ptr())
68        });
69        Ok(())
70    }
71
72    /// Sets the tab width in columns, in `1..=255` to fit upstream glyph storage.
73    pub fn set_tab_size(&mut self, value: usize) -> CteResult<()> {
74        validate_tab_size("TextDiff::set_tab_size", "value", value)?;
75        self.with_context("TextDiff::set_tab_size", |raw| unsafe {
76            sys::TextDiff_SetTabSize(raw, value)
77        });
78        Ok(())
79    }
80
81    pub fn tab_size(&self) -> usize {
82        self.with_context("TextDiff::tab_size", |raw| unsafe {
83            sys::TextDiff_GetTabSize(raw)
84        })
85    }
86
87    /// Sets line spacing. The native widget clamps finite values to `1.0..=2.0`.
88    pub fn set_line_spacing(&mut self, value: f32) -> CteResult<()> {
89        validate_finite_f32("TextDiff::set_line_spacing", "value", value)?;
90        self.with_context("TextDiff::set_line_spacing", |raw| unsafe {
91            sys::TextDiff_SetLineSpacing(raw, value)
92        });
93        Ok(())
94    }
95
96    pub fn line_spacing(&self) -> f32 {
97        self.with_context("TextDiff::line_spacing", |raw| unsafe {
98            sys::TextDiff_GetLineSpacing(raw)
99        })
100    }
101
102    pub fn set_language(&mut self, language: Option<Language>) {
103        let language = language.map_or(std::ptr::null(), Language::as_raw);
104        self.with_context("TextDiff::set_language", |raw| unsafe {
105            sys::TextDiff_SetLanguage(raw, language)
106        });
107    }
108
109    pub fn language(&self) -> Option<Language> {
110        self.with_context("TextDiff::language", |raw| unsafe {
111            Language::from_raw(sys::TextDiff_GetLanguage(raw))
112        })
113    }
114
115    /// Sets the packed ImGui colors used for added and deleted lines.
116    pub fn set_colors(&mut self, added: u32, deleted: u32) {
117        self.with_context("TextDiff::set_colors", |raw| unsafe {
118            sys::TextDiff_SetColors(raw, added, deleted)
119        });
120    }
121
122    /// Copies a Rust palette into the text diff.
123    pub fn set_palette(&mut self, palette: &Palette) -> CteResult<()> {
124        self.with_context("TextDiff::set_palette", |raw| {
125            palette.with_native(|native| unsafe { sys::TextDiff_SetPalette(raw, native) })
126        })
127    }
128
129    /// Returns an owned copy of the text-diff palette.
130    pub fn palette(&self) -> Palette {
131        self.with_context("TextDiff::palette", |raw| unsafe {
132            Palette::copy_from_raw(sys::TextDiff_GetPalette(raw))
133        })
134    }
135
136    /// Requests keyboard focus on the next render.
137    pub fn focus(&mut self) {
138        self.with_context("TextDiff::focus", |raw| unsafe {
139            sys::TextDiff_SetFocus(raw)
140        });
141    }
142
143    fn with_context<R>(
144        &self,
145        operation: &'static str,
146        f: impl FnOnce(*mut sys::TextDiff) -> R,
147    ) -> R {
148        self.try_with_context(operation, f)
149            .unwrap_or_else(|error| panic!("{error}"))
150    }
151
152    fn try_with_context<R>(
153        &self,
154        operation: &'static str,
155        f: impl FnOnce(*mut sys::TextDiff) -> R,
156    ) -> CteResult<R> {
157        let raw = self.raw.as_ptr();
158        self.binding.try_with_bound_context(operation, || f(raw))
159    }
160}
161
162macro_rules! bool_property {
163    ($setter:ident, $getter:ident, $raw_setter:path, $raw_getter:path) => {
164        impl TextDiff {
165            pub fn $setter(&mut self, value: bool) {
166                self.with_context(concat!("TextDiff::", stringify!($setter)), |raw| unsafe {
167                    $raw_setter(raw, value)
168                });
169            }
170
171            pub fn $getter(&self) -> bool {
172                self.with_context(concat!("TextDiff::", stringify!($getter)), |raw| unsafe {
173                    $raw_getter(raw)
174                })
175            }
176        }
177    };
178}
179
180bool_property!(
181    set_side_by_side,
182    is_side_by_side,
183    sys::TextDiff_SetSideBySideMode,
184    sys::TextDiff_GetSideBySideMode
185);
186bool_property!(
187    set_word_wrap_enabled,
188    is_word_wrap_enabled,
189    sys::TextDiff_SetWordWrapEnabled,
190    sys::TextDiff_IsWordWrapEnabled
191);
192bool_property!(
193    set_show_whitespaces,
194    shows_whitespaces,
195    sys::TextDiff_SetShowWhitespacesEnabled,
196    sys::TextDiff_IsShowWhitespacesEnabled
197);
198bool_property!(
199    set_show_spaces,
200    shows_spaces,
201    sys::TextDiff_SetShowSpacesEnabled,
202    sys::TextDiff_IsShowSpacesEnabled
203);
204bool_property!(
205    set_show_tabs,
206    shows_tabs,
207    sys::TextDiff_SetShowTabsEnabled,
208    sys::TextDiff_IsShowTabsEnabled
209);
210bool_property!(
211    set_show_scrollbar_minimap,
212    shows_scrollbar_minimap,
213    sys::TextDiff_SetShowScrollbarMiniMapEnabled,
214    sys::TextDiff_IsShowScrollbarMiniMapEnabled
215);
216
217impl Drop for TextDiff {
218    fn drop(&mut self) {
219        let raw = self.raw;
220        let _ = self
221            .binding
222            .try_with_bound_context("TextDiff::drop", || unsafe {
223                sys::TextDiff_destroy(raw.as_ptr())
224            });
225        // If context teardown already started, touching CTE state is no longer proven safe.
226        // The native handle is intentionally leaked rather than calling into a dead context.
227    }
228}
229
230/// Builder for one TextDiff render submission.
231#[must_use = "call build() to render the text diff"]
232pub struct TextDiffRenderer<'ui, 'diff> {
233    ui: &'ui Ui,
234    diff: &'diff mut TextDiff,
235    title: String,
236    size: [f32; 2],
237    child_flags: ChildFlags,
238    window_flags: WindowFlags,
239}
240
241impl TextDiffRenderer<'_, '_> {
242    pub(crate) fn new<'ui, 'diff>(
243        ui: &'ui Ui,
244        diff: &'diff mut TextDiff,
245        title: String,
246    ) -> TextDiffRenderer<'ui, 'diff> {
247        TextDiffRenderer {
248            ui,
249            diff,
250            title,
251            size: [0.0, 0.0],
252            child_flags: ChildFlags::empty(),
253            window_flags: WindowFlags::NO_MOVE,
254        }
255    }
256
257    pub fn size(mut self, size: [f32; 2]) -> Self {
258        self.size = size;
259        self
260    }
261
262    pub fn child_flags(mut self, flags: ChildFlags) -> Self {
263        self.child_flags = flags;
264        self
265    }
266
267    /// Sets additional window flags while preserving the widget's required `NO_MOVE` flag.
268    pub fn window_flags(mut self, flags: WindowFlags) -> Self {
269        self.window_flags = flags | WindowFlags::NO_MOVE;
270        self
271    }
272
273    pub fn build(self) -> CteResult<()> {
274        const OPERATION: &str = "TextDiffRenderer::build";
275        self.diff.binding.require_ui(OPERATION, self.ui)?;
276        validate_finite_vec2(OPERATION, "size", self.size)?;
277        validate_render_flags(OPERATION, self.child_flags, self.window_flags)?;
278        let title = c_string(OPERATION, &self.title)?;
279        let child_flags = self.child_flags.bits() as i32;
280        self.diff.try_with_context(OPERATION, |raw| unsafe {
281            sys::TextDiff_Render(
282                raw,
283                title.as_ptr(),
284                self.size.into(),
285                child_flags,
286                self.window_flags.bits(),
287            )
288        })
289    }
290}
291
292#[cfg(test)]
293mod tests {
294    use super::*;
295    use dear_imgui_rs::{Context, FramePrepareOptions};
296
297    #[test]
298    fn renderer_preserves_the_upstream_no_move_flag() {
299        let mut context = Context::create();
300        context.prepare_frame(FramePrepareOptions::new([640.0, 480.0], 1.0 / 60.0));
301        context
302            .font_atlas()
303            .try_claim_legacy_renderer()
304            .expect("headless CTE tests require the legacy font-atlas capability")
305            .build();
306        let mut diff = TextDiff::create(&context);
307        let ui = context.frame();
308
309        let renderer = TextDiffRenderer::new(ui, &mut diff, "Diff".to_owned());
310        assert_eq!(renderer.window_flags, WindowFlags::NO_MOVE);
311
312        let renderer = renderer.window_flags(WindowFlags::NO_SAVED_SETTINGS);
313        assert!(renderer.window_flags.contains(WindowFlags::NO_MOVE));
314        assert!(
315            renderer
316                .window_flags
317                .contains(WindowFlags::NO_SAVED_SETTINGS)
318        );
319    }
320}