Skip to content

Type Settings

Jump to bottom
Sven edited this page Oct 21, 2025 · 5 revisions

ImReflect - Type Settings Reference

Version: v0.2.0

Table of Contents

  1. Quick Start
  2. Primitive Types
  3. Strings
  4. Container Types
  5. Smart Types
  6. Aggregate Types
  7. Response Handling

Quick Overview

Supported Types:

  • Primitives: int, float, double, bool, char, all standard numeric types
  • Enums: Any C++ enum (auto-reflected via magic_enum)
  • Strings: std::string
  • Containers: vector, array, list, deque, map, set, and their variants
  • Smart Pointers: shared_ptr, unique_ptr, weak_ptr
  • Utilities: pair, tuple, optional, variant
  • Custom Types: Any struct/class with IMGUI_REFLECT macro

Primitive Types

Numeric Types

Supported: int8_t, int16_t, int32_t, int64_t, uint8_t, uint16_t, uint32_t, uint64_t, float, double, int, long, short, char, and typedefs.

Widget Selection

Choose how users interact with numbers:

Method Best For Visual Style
as_input() Precise numeric entry Text field with arrows
as_slider() Visual range selection Draggable slider
as_drag() Quick adjustments by mouse Drag-to-modify field

Default: Input field

Range Control

.min(0)              // Minimum value
.max(100)            // Maximum value
.clamp(true)         // Auto-clamp to range
.step(1)             // Increment/decrement step
.step_fast(10)       // Fast step (Ctrl+click)
.speed(0.1f)         // Drag sensitivity

Display Formatting

// Common formats
.format("%.2f")           // Custom printf format
.prefix("$")              // Add prefix: "$100"
.suffix(" kg")            // Add suffix: "100 kg"

// Shortcuts
.as_decimal()             // Integer: 123
.as_hex()                 // Hex: 0x7b
.as_hex(true)             // Uppercase: 0X7B
.as_float(2)              // Float: 123.45
.as_percentage(1)         // Percent: 12.3%
.as_scientific(2)         // Scientific: 1.23e+02

// Alignment
.width(8)                 // Field width
.zero_pad(5)              // Zero padding: 00123

Advanced Options

Slider-specific:

.logarithmic()            // Logarithmic scale
.no_round_to_format()     // Preserve raw values
.no_input()               // Slider only, no text input
.wrap_around()            // Loop at boundaries
.clamp_on_input()         // Clamp during text entry
.always_clamp()           // Always enforce limits

Input-specific:

.chars_decimal()          // Only allow 0-9
.chars_hexadecimal()      // Allow hex characters
.chars_scientific()       // Allow scientific notation
.read_only()              // Display only
.auto_select_all()        // Select on focus
.enter_returns_true()     // Submit on Enter

Boolean

Supported: bool

Widget Selection

Method Visual Style Best For
as_checkbox() ☑ Checkbox General use (default)
as_radio() ◉ True / ○ False buttons Clear binary choice
as_dropdown() Dropdown: "True" / "False" Compact layouts
as_button() Toggle button: ON / OFF Action-style toggles

Text Customization

.true_text("Enabled")     // Custom text for true
.false_text("Disabled")   // Custom text for false

Enums

Supported: Any C++ enum (automatically reflected via magic_enum)

Widget Selection

Method Visual Style Best For
as_dropdown() Dropdown list (default) Many options
as_radio() Radio buttons 2-5 options, always visible
as_slider() Slider with labels Ordered progression
as_drag() Drag to cycle values Quick cycling

Settings

.speed(0.01f)     // Drag speed (for as_drag)

Strings

Supported: std::string

Display Modes

Method Description Use Case
as_singleline() Single-line text field (default) Names, short text
as_multiline() Multi-line text area Descriptions, paragraphs

Size Control

.line_count(5)        // Fixed height (5 lines)
.auto_resize(true)    // Auto-grow with content

Note: line_count(-1) uses ImGui defaults. line_count(0) enables auto-resize.

Container Types

Sequence Containers

Supported: vector, array, list, forward_list, deque, set, multiset, unordered_set, unordered_multiset

Display Options

.as_dropdown(false)           // Show/hide in collapsible tree

User Interaction

Configure what users can do with container elements:

Setting Description Default vector array list forward_list deque set multiset
reorderable(bool) Drag-drop reordering, move up/down true ✅ ✅ ✅ ❌ ✅ ❌ ❌
insertable(bool) Add new items true ✅ ❌ ✅ ✅ ✅ ✅ ✅
removable(bool) Delete items true ✅ ❌ ✅ ✅ ✅ ✅ ✅
pop_up_on_insert(bool) Show popup when adding items true ✅ ❌ ✅ ✅ ✅ ✅ ✅

Why some features are unavailable:

  • array: Fixed size at compile time (no insert/remove)
  • forward_list: Forward-only iteration (no reordering)
  • set/multiset: Elements maintain sorted order (no manual reordering)

User Operations

Right-click on elements to access context menu:

  • Reorder: Move up/down, to top/bottom, drag-drop
  • Insert: Above/below current element
  • Duplicate: Copy existing element
  • Remove: Delete element
  • Clear All: Empty container

Associative Containers

Supported: map, multimap, unordered_map, unordered_multimap

Display Options

.as_dropdown(false)           // Show/hide in collapsible tree

User Interaction

Setting Description Default
insertable(bool) Add new key-value pairs true
removable(bool) Delete pairs true
pop_up_on_insert(bool) Show popup when adding pairs true

Note: Maps cannot be reordered as they maintain their own key ordering.

User Operations

  • Add (+): Opens popup to enter key and value
  • Remove (-): Deletes last element
  • Context Menu: Right-click element to remove or clear all

Smart Types

Smart Pointers

Supported: std::shared_ptr<T>, std::unique_ptr<T>, std::weak_ptr<T>

Smart pointers automatically dereference and display their contained value.

Display Behavior

Pointer State Display
Valid value Shows the dereferenced object's UI
nullptr Shows <nullptr> (disabled, not editable)
Expired Shows <expired> (weak_ptr only, disabled)

Optional & Variant

std::optional

Supported: std::optional<T>

Displays a checkbox to toggle between having a value (engaged) and being empty (nullopt).

Display & Settings
.resettable(bool)     // Show reset button (default: false)
State Display
Has value ☑ Checkbox + value editor
Empty ☐ Checkbox + <nullopt> (grayed out)

When toggled on, the optional is initialized with T{} (default-constructed value).

std::variant

Supported: std::variant<Types...>

Displays a dropdown to select the active type, followed by an editor for that type's value.

Display & Settings
.as_dropdown(bool)    // Hide value editor in collapsible tree (default: false)
State Display
Valid Type selector + value editor
Valueless Type selector + <valueless> (grayed out)

Type switching:

  • Dropdown shows C++ type names (e.g., int, float, std::string)
  • Only default-constructible types can be selected
  • Switching types reconstructs the variant with T{}

Aggregate Types

Pair & Tuple

Supported: std::pair<T1, T2>, std::tuple<Types...>

Display Modes

Method Description Default
as_line() Elements in a single horizontal row true
as_grid() Elements in a grid layout false
as_dropdown() Elements in collapsible tree false

Grid Settings

.columns(int)     // Number of columns (default: 3)

Structs & Classes

Any C++ type with IMGUI_REFLECT macro

Setup

Use the IMGUI_REFLECT macro to specify which members to display:

struct GameSettings {
    int volume = 50;
    float sensitivity = 1.0f;
    bool fullscreen = false;
    std::string playerName = "Player1";
};

// Register members for reflection
IMGUI_REFLECT(GameSettings, volume, sensitivity, fullscreen, playerName)

Usage

GameSettings settings;

ImReflect::Input("Settings", settings);
// Automatically creates UI for all reflected members

Response Handling

All widgets provide response information for tracking user interactions.

Available Methods

static int my_int = 0;
ImResponse response = ImReflect::Input("my_int", my_int);
const auto& int_response = response.get<int>();

ImGui::Text("is_changed: %s", int_response.is_changed() ? "true" : "false");
ImGui::Text("is_hovered: %s", int_response.is_hovered() ? "true" : "false");
ImGui::Text("is_active: %s", int_response.is_active() ? "true" : "false");
ImGui::Text("is_focused: %s", int_response.is_focused() ? "true" : "false");
ImGui::Text("is_clicked left: %s", int_response.is_clicked(0) ? "true" : "false");
ImGui::Text("is_clicked right: %s", int_response.is_clicked(1) ? "true" : "false");
ImGui::Text("is_clicked middle: %s", int_response.is_clicked(2) ? "true" : "false");

Container-Specific Responses

For containers (vector, list, map, etc.), additional methods track structural changes:

auto& container_response = response.get<std::vector>();

if (container_response.has_inserted()) {
    size_t index = container_response.get_inserted_index();
    // Item was inserted at index
}

if (container_response.has_erased()) {
    size_t index = container_response.get_erased_index();
    // Item was removed from index
}

if (container_response.has_moved()) {
    auto info = container_response.get_moved_info();
    // Item moved from info.from to info.to
}

Clone this wiki locally