dear-imgui-rs 0.14.0

High-level Rust bindings to Dear ImGui v1.92.7 with docking, WGPU/GL backends, and extensions (ImPlot/ImPlot3D, ImNodes, ImGuizmo, file browser, reflection-based UI)
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
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
use crate::sys;
#[cfg(feature = "serde")]
use serde::{Deserialize, Serialize};

bitflags::bitflags! {
    /// Independent flags for table widgets.
    ///
    /// The table sizing policy is a single-choice setting represented by
    /// [`TableSizingPolicy`].
    #[repr(transparent)]
    #[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
    pub struct TableFlags: i32 {
        /// No flags
        const NONE = 0;
        /// Enable resizing columns
        const RESIZABLE = sys::ImGuiTableFlags_Resizable as i32;
        /// Enable reordering columns in header row (need calling TableSetupColumn() + TableHeadersRow() to display headers)
        const REORDERABLE = sys::ImGuiTableFlags_Reorderable as i32;
        /// Enable hiding/disabling columns in context menu
        const HIDEABLE = sys::ImGuiTableFlags_Hideable as i32;
        /// Enable sorting. Call TableGetSortSpecs() to obtain sort specs. Also see ImGuiTableFlags_SortMulti and ImGuiTableFlags_SortTristate.
        const SORTABLE = sys::ImGuiTableFlags_Sortable as i32;
        /// Disable persisting columns order, width and sort settings in the .ini file
        const NO_SAVED_SETTINGS = sys::ImGuiTableFlags_NoSavedSettings as i32;
        /// Right-click on columns body/contents will display table context menu. By default it is available in TableHeadersRow().
        const CONTEXT_MENU_IN_BODY = sys::ImGuiTableFlags_ContextMenuInBody as i32;
        /// Set each RowBg color with ImGuiCol_TableRowBg or ImGuiCol_TableRowBgAlt (equivalent of calling TableSetBgColor with ImGuiTableBgFlags_RowBg0 on each row manually)
        const ROW_BG = sys::ImGuiTableFlags_RowBg as i32;
        /// Draw horizontal borders between rows
        const BORDERS_INNER_H = sys::ImGuiTableFlags_BordersInnerH as i32;
        /// Draw horizontal borders at the top and bottom
        const BORDERS_OUTER_H = sys::ImGuiTableFlags_BordersOuterH as i32;
        /// Draw vertical borders between columns
        const BORDERS_INNER_V = sys::ImGuiTableFlags_BordersInnerV as i32;
        /// Draw vertical borders on the left and right sides
        const BORDERS_OUTER_V = sys::ImGuiTableFlags_BordersOuterV as i32;
        /// Draw horizontal borders
        const BORDERS_H = Self::BORDERS_INNER_H.bits() | Self::BORDERS_OUTER_H.bits();
        /// Draw vertical borders
        const BORDERS_V = Self::BORDERS_INNER_V.bits() | Self::BORDERS_OUTER_V.bits();
        /// Draw inner borders
        const BORDERS_INNER = Self::BORDERS_INNER_V.bits() | Self::BORDERS_INNER_H.bits();
        /// Draw outer borders
        const BORDERS_OUTER = Self::BORDERS_OUTER_V.bits() | Self::BORDERS_OUTER_H.bits();
        /// Draw all borders
        const BORDERS = Self::BORDERS_INNER.bits() | Self::BORDERS_OUTER.bits();
        /// [ALPHA] Disable vertical borders in columns Body (borders will always appears in Headers). -> May move to style
        const NO_BORDERS_IN_BODY = sys::ImGuiTableFlags_NoBordersInBody as i32;
        /// [ALPHA] Disable vertical borders in columns Body until hovered for resize (borders will always appears in Headers). -> May move to style
        const NO_BORDERS_IN_BODY_UNTIL_RESIZE = sys::ImGuiTableFlags_NoBordersInBodyUntilResize as i32;
        /// Make outer width auto-fit to columns, overriding outer_size.x value. Only available when ScrollX/ScrollY are disabled and Stretch columns are not used.
        const NO_HOST_EXTEND_X = sys::ImGuiTableFlags_NoHostExtendX as i32;
        /// Make outer height stop exactly at outer_size.y (prevent auto-extending table past the limit). Only available when ScrollX/ScrollY are disabled. Data below the limit will be clipped and not visible.
        const NO_HOST_EXTEND_Y = sys::ImGuiTableFlags_NoHostExtendY as i32;
        /// Disable keeping column always minimally visible when ScrollX is on and table gets too small. Not recommended if columns are resizable.
        const NO_KEEP_COLUMNS_VISIBLE = sys::ImGuiTableFlags_NoKeepColumnsVisible as i32;
        /// Disable distributing remainder width to stretched columns (width allocation on a 100-wide table with 3 columns: Without this flag: 33,33,34. With this flag: 33,33,33). With larger number of columns, resizing will appear to be less smooth.
        const PRECISE_WIDTHS = sys::ImGuiTableFlags_PreciseWidths as i32;
        /// Disable clipping rectangle for every individual columns (reduce draw command count, items will be able to overflow into other columns). Generally incompatible with TableSetupScrollFreeze().
        const NO_CLIP = sys::ImGuiTableFlags_NoClip as i32;
        /// Default if BordersOuterV is on. Enable outer-most padding. Generally desirable if you have headers.
        const PAD_OUTER_X = sys::ImGuiTableFlags_PadOuterX as i32;
        /// Default if BordersOuterV is off. Disable outer-most padding.
        const NO_PAD_OUTER_X = sys::ImGuiTableFlags_NoPadOuterX as i32;
        /// Disable inner padding between columns (double inner padding if BordersOuterV is on, single inner padding if BordersOuterV is off).
        const NO_PAD_INNER_X = sys::ImGuiTableFlags_NoPadInnerX as i32;
        /// Enable horizontal scrolling. Require 'outer_size' parameter of BeginTable() to specify the container size. Changes default sizing policy. Because this creates a child window, ScrollY is currently generally recommended when using ScrollX.
        const SCROLL_X = sys::ImGuiTableFlags_ScrollX as i32;
        /// Enable vertical scrolling. Require 'outer_size' parameter of BeginTable() to specify the container size.
        const SCROLL_Y = sys::ImGuiTableFlags_ScrollY as i32;
        /// Hold shift when clicking headers to sort on multiple column. TableGetSortSpecs() may return specs where (SpecsCount > 1).
        const SORT_MULTI = sys::ImGuiTableFlags_SortMulti as i32;
        /// Allow no sorting, disable default sorting. TableGetSortSpecs() may return specs where (SpecsCount == 0).
        const SORT_TRISTATE = sys::ImGuiTableFlags_SortTristate as i32;
        /// Highlight column headers when hovered (may not be visible if table header is declaring a background color)
        const HIGHLIGHT_HOVERED_COLUMN = sys::ImGuiTableFlags_HighlightHoveredColumn as i32;
    }
}

/// Single-choice table sizing policy.
#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
pub enum TableSizingPolicy {
    /// Columns default to fixed/auto widths matching contents width.
    FixedFit,
    /// Fixed/auto widths matching the maximum contents width of all columns.
    FixedSame,
    /// Stretch columns with weights proportional to contents widths.
    StretchProp,
    /// Stretch columns with equal weights unless overridden per column.
    StretchSame,
}

impl TableSizingPolicy {
    #[inline]
    const fn raw(self) -> i32 {
        match self {
            Self::FixedFit => sys::ImGuiTableFlags_SizingFixedFit as i32,
            Self::FixedSame => sys::ImGuiTableFlags_SizingFixedSame as i32,
            Self::StretchProp => sys::ImGuiTableFlags_SizingStretchProp as i32,
            Self::StretchSame => sys::ImGuiTableFlags_SizingStretchSame as i32,
        }
    }
}

/// Complete table options assembled from independent flags and an optional
/// single sizing policy.
#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
pub struct TableOptions {
    pub flags: TableFlags,
    pub sizing_policy: Option<TableSizingPolicy>,
}

impl Default for TableOptions {
    fn default() -> Self {
        Self::new()
    }
}

impl TableOptions {
    pub const fn new() -> Self {
        Self {
            flags: TableFlags::NONE,
            sizing_policy: None,
        }
    }

    pub fn flags(mut self, flags: TableFlags) -> Self {
        self.flags = flags;
        self
    }

    pub fn sizing_policy(mut self, policy: TableSizingPolicy) -> Self {
        self.sizing_policy = Some(policy);
        self
    }

    pub fn bits(self) -> i32 {
        self.raw()
    }

    #[inline]
    pub(crate) fn raw(self) -> i32 {
        self.flags.bits() | self.sizing_policy.map_or(0, TableSizingPolicy::raw)
    }

    #[inline]
    pub(crate) fn validate(self, caller: &str) {
        let unsupported_flags = self.flags.bits() & !TableFlags::all().bits();
        assert!(
            unsupported_flags == 0,
            "{caller} received non-independent ImGuiTableFlags bits: 0x{unsupported_flags:X}"
        );
        let bits = self.raw();
        let sizing_mask = sys::ImGuiTableFlags_SizingMask_ as i32;
        let supported = TableFlags::all().bits() | sizing_mask;
        let unsupported = bits & !supported;
        assert!(
            unsupported == 0,
            "{caller} received unsupported ImGuiTableFlags bits: 0x{unsupported:X}"
        );
        let sizing_policy = bits & sizing_mask;
        assert!(
            is_valid_table_sizing_policy(sizing_policy),
            "{caller} received invalid table sizing policy bits: 0x{sizing_policy:X}"
        );
    }
}

#[inline]
const fn is_valid_table_sizing_policy(bits: i32) -> bool {
    bits == 0
        || bits == TableSizingPolicy::FixedFit.raw()
        || bits == TableSizingPolicy::FixedSame.raw()
        || bits == TableSizingPolicy::StretchProp.raw()
        || bits == TableSizingPolicy::StretchSame.raw()
}

impl From<TableFlags> for TableOptions {
    fn from(flags: TableFlags) -> Self {
        Self::new().flags(flags)
    }
}

#[cfg(feature = "serde")]
impl Serialize for TableFlags {
    fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
    where
        S: serde::Serializer,
    {
        serializer.serialize_i32(self.bits())
    }
}

#[cfg(feature = "serde")]
impl<'de> Deserialize<'de> for TableFlags {
    fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
    where
        D: serde::Deserializer<'de>,
    {
        let bits = i32::deserialize(deserializer)?;
        Ok(TableFlags::from_bits_retain(bits))
    }
}

bitflags::bitflags! {
    /// Independent flags accepted by `TableSetupColumn()`.
    ///
    /// The fixed/stretch width mode and indent mode are single-choice settings
    /// represented by [`TableColumnWidth`] and [`TableColumnIndent`].
    #[repr(transparent)]
    #[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
    pub struct TableColumnFlags: i32 {
        /// No flags
        const NONE = 0;
        /// Hide column and omit it from the context menu.
        const DISABLED = sys::ImGuiTableColumnFlags_Disabled as i32;
        /// Default to a hidden/disabled column.
        const DEFAULT_HIDE = sys::ImGuiTableColumnFlags_DefaultHide as i32;
        /// Default to a sorting column.
        const DEFAULT_SORT = sys::ImGuiTableColumnFlags_DefaultSort as i32;
        /// Disable manual resizing
        const NO_RESIZE = sys::ImGuiTableColumnFlags_NoResize as i32;
        /// Disable manual reordering this column
        const NO_REORDER = sys::ImGuiTableColumnFlags_NoReorder as i32;
        /// Disable ability to hide/disable this column
        const NO_HIDE = sys::ImGuiTableColumnFlags_NoHide as i32;
        /// Disable clipping for this column
        const NO_CLIP = sys::ImGuiTableColumnFlags_NoClip as i32;
        /// Disable ability to sort on this field
        const NO_SORT = sys::ImGuiTableColumnFlags_NoSort as i32;
        /// Disable ability to sort in the ascending direction
        const NO_SORT_ASCENDING = sys::ImGuiTableColumnFlags_NoSortAscending as i32;
        /// Disable ability to sort in the descending direction
        const NO_SORT_DESCENDING = sys::ImGuiTableColumnFlags_NoSortDescending as i32;
        /// TableHeadersRow() will not submit label for this column
        const NO_HEADER_LABEL = sys::ImGuiTableColumnFlags_NoHeaderLabel as i32;
        /// Disable header text width contribution to automatic column width
        const NO_HEADER_WIDTH = sys::ImGuiTableColumnFlags_NoHeaderWidth as i32;
        /// Make the initial sort direction Ascending when first sorting on this column
        const PREFER_SORT_ASCENDING = sys::ImGuiTableColumnFlags_PreferSortAscending as i32;
        /// Make the initial sort direction Descending when first sorting on this column
        const PREFER_SORT_DESCENDING = sys::ImGuiTableColumnFlags_PreferSortDescending as i32;
        /// Display an angled header for this column (when angled headers feature is enabled)
        const ANGLED_HEADER = sys::ImGuiTableColumnFlags_AngledHeader as i32;
    }
}

/// Single-choice width mode for a table column.
#[derive(Clone, Copy, Debug, PartialEq)]
pub enum TableColumnWidth {
    /// Initial value is interpreted as a fixed width in pixels.
    Fixed(f32),
    /// Initial value is interpreted as a stretch weight.
    Stretch(f32),
}

impl TableColumnWidth {
    pub const fn fixed(width: f32) -> Self {
        Self::Fixed(width)
    }

    pub const fn stretch(weight: f32) -> Self {
        Self::Stretch(weight)
    }

    #[inline]
    pub(crate) const fn raw_flags(self) -> i32 {
        match self {
            Self::Fixed(_) => sys::ImGuiTableColumnFlags_WidthFixed as i32,
            Self::Stretch(_) => sys::ImGuiTableColumnFlags_WidthStretch as i32,
        }
    }

    #[inline]
    pub(crate) const fn value(self) -> f32 {
        match self {
            Self::Fixed(value) | Self::Stretch(value) => value,
        }
    }
}

/// Single-choice indentation policy for a table column.
#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
pub enum TableColumnIndent {
    /// Use the current indent value when entering the column.
    Enable,
    /// Disable indentation for the column.
    Disable,
}

impl TableColumnIndent {
    #[inline]
    pub const fn bits(self) -> i32 {
        self.raw_flags()
    }

    #[inline]
    pub(crate) const fn raw_flags(self) -> i32 {
        match self {
            Self::Enable => sys::ImGuiTableColumnFlags_IndentEnable as i32,
            Self::Disable => sys::ImGuiTableColumnFlags_IndentDisable as i32,
        }
    }
}

bitflags::bitflags! {
    /// Flags returned by `TableGetColumnFlags()`.
    #[repr(transparent)]
    #[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
    pub struct TableColumnStateFlags: i32 {
        /// No flags
        const NONE = 0;
        /// Overriding/master disable flag: hide column and omit it from the context menu.
        const DISABLED = sys::ImGuiTableColumnFlags_Disabled as i32;
        /// Default to a hidden/disabled column.
        const DEFAULT_HIDE = sys::ImGuiTableColumnFlags_DefaultHide as i32;
        /// Default to a sorting column.
        const DEFAULT_SORT = sys::ImGuiTableColumnFlags_DefaultSort as i32;
        /// Overriding width becomes fixed width
        const WIDTH_FIXED = sys::ImGuiTableColumnFlags_WidthFixed as i32;
        /// Overriding width becomes weight
        const WIDTH_STRETCH = sys::ImGuiTableColumnFlags_WidthStretch as i32;
        /// Disable manual resizing
        const NO_RESIZE = sys::ImGuiTableColumnFlags_NoResize as i32;
        /// Disable manual reordering this column
        const NO_REORDER = sys::ImGuiTableColumnFlags_NoReorder as i32;
        /// Disable ability to hide/disable this column
        const NO_HIDE = sys::ImGuiTableColumnFlags_NoHide as i32;
        /// Disable clipping for this column
        const NO_CLIP = sys::ImGuiTableColumnFlags_NoClip as i32;
        /// Disable ability to sort on this field
        const NO_SORT = sys::ImGuiTableColumnFlags_NoSort as i32;
        /// Disable ability to sort in the ascending direction
        const NO_SORT_ASCENDING = sys::ImGuiTableColumnFlags_NoSortAscending as i32;
        /// Disable ability to sort in the descending direction
        const NO_SORT_DESCENDING = sys::ImGuiTableColumnFlags_NoSortDescending as i32;
        /// TableHeadersRow() will not submit label for this column
        const NO_HEADER_LABEL = sys::ImGuiTableColumnFlags_NoHeaderLabel as i32;
        /// Disable header text width contribution to automatic column width
        const NO_HEADER_WIDTH = sys::ImGuiTableColumnFlags_NoHeaderWidth as i32;
        /// Make the initial sort direction Ascending when first sorting on this column
        const PREFER_SORT_ASCENDING = sys::ImGuiTableColumnFlags_PreferSortAscending as i32;
        /// Make the initial sort direction Descending when first sorting on this column
        const PREFER_SORT_DESCENDING = sys::ImGuiTableColumnFlags_PreferSortDescending as i32;
        /// Use current Indent value when entering cell
        const INDENT_ENABLE = sys::ImGuiTableColumnFlags_IndentEnable as i32;
        /// Disable indenting for this column
        const INDENT_DISABLE = sys::ImGuiTableColumnFlags_IndentDisable as i32;
        /// Display an angled header for this column (when angled headers feature is enabled)
        const ANGLED_HEADER = sys::ImGuiTableColumnFlags_AngledHeader as i32;
        /// Status: is enabled == not hidden
        const IS_ENABLED = sys::ImGuiTableColumnFlags_IsEnabled as i32;
        /// Status: is visible == is enabled AND not clipped by scrolling
        const IS_VISIBLE = sys::ImGuiTableColumnFlags_IsVisible as i32;
        /// Status: is currently part of the sort specs
        const IS_SORTED = sys::ImGuiTableColumnFlags_IsSorted as i32;
        /// Status: is hovered by mouse
        const IS_HOVERED = sys::ImGuiTableColumnFlags_IsHovered as i32;
    }
}

impl From<TableColumnFlags> for TableColumnStateFlags {
    fn from(flags: TableColumnFlags) -> Self {
        Self::from_bits_retain(flags.bits())
    }
}

impl TableColumnFlags {
    #[inline]
    pub(crate) fn validate_for_setup(
        self,
        caller: &str,
        width: Option<TableColumnWidth>,
        indent: Option<TableColumnIndent>,
    ) {
        let unsupported_flags = self.bits() & !TableColumnFlags::all().bits();
        assert!(
            unsupported_flags == 0,
            "{caller} received non-independent ImGuiTableColumnFlags bits: 0x{unsupported_flags:X}"
        );
        let bits = self.bits()
            | width.map_or(0, TableColumnWidth::raw_flags)
            | indent.map_or(0, TableColumnIndent::raw_flags);
        let width_mask = sys::ImGuiTableColumnFlags_WidthMask_ as i32;
        let indent_mask = sys::ImGuiTableColumnFlags_IndentMask_ as i32;
        let supported = TableColumnFlags::all().bits() | width_mask | indent_mask;
        let unsupported = bits & !supported;
        assert!(
            unsupported == 0,
            "{caller} received unsupported ImGuiTableColumnFlags bits: 0x{unsupported:X}"
        );
        assert!(
            (bits & width_mask).count_ones() <= 1,
            "{caller} accepts at most one table column width policy"
        );
        assert!(
            (bits & indent_mask).count_ones() <= 1,
            "{caller} accepts at most one table column indent policy"
        );
    }
}

#[cfg(feature = "serde")]
impl Serialize for TableColumnFlags {
    fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
    where
        S: serde::Serializer,
    {
        serializer.serialize_i32(self.bits())
    }
}

#[cfg(feature = "serde")]
impl<'de> Deserialize<'de> for TableColumnFlags {
    fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
    where
        D: serde::Deserializer<'de>,
    {
        let bits = i32::deserialize(deserializer)?;
        Ok(TableColumnFlags::from_bits_retain(bits))
    }
}

#[cfg(feature = "serde")]
impl Serialize for TableColumnStateFlags {
    fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
    where
        S: serde::Serializer,
    {
        serializer.serialize_i32(self.bits())
    }
}

#[cfg(feature = "serde")]
impl<'de> Deserialize<'de> for TableColumnStateFlags {
    fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
    where
        D: serde::Deserializer<'de>,
    {
        let bits = i32::deserialize(deserializer)?;
        Ok(TableColumnStateFlags::from_bits_retain(bits))
    }
}