Controls

Component

The base class for every component.

It provides basic methods, that every component must implement to be properly used in Forms and Layouts.

Example

A minimally implemented button component:

class Button : Component
{
    public override Size GetSize()
    {
        var textSize = TextMeasurer.MeasureText("Click");
        return new Size(textSize.X, textSize.Y);
    }

    protected override void UpdateInternal(Rectangle contentRect)
    {
        if (ImGuiNET.ImGui.Button("Click", contentRect.Size) && Enabled)
            ; // Invoke click event
    }
}

Properties

• Id: The unique ID of the component; Is used directly in Dear ImGui, where applicable
• Visible: If the component should be rendered and acknowledged for size and spacing calculations
• Enabled: If the component is active and processes events
• AllowDragDrop: Like AllowDragDrop in Forms, allows files to be dropped on the component area only; See event DragDrop to react to this event
• ShowBorder: Renders a border around the component; Mostly intended for layout debugging

Events

• DragDrop: The event to handle component wide drag drop actions

Methods

• Update: Updates the component on every frame; Receives the absolute position and size of the component

• GetSize: Gets the size definition of the component; For the final dimensions, invoke GetWidth and GetHeight

• GetWidth: Gets the final, absolute width of the component; Needs a parent width for calculation of relative size values

• GetHeight: Gets the final, absolute height of the component; Needs a parent height for calculation of relative size values

• SetTabInactive: Invoked by custom components in child components to propagate TabPage inactivity

• UpdateInternal: Protected; Renders the component on every frame; Receives the absolute position and size of the component

• IsHoveredCore: Protected; If the mouse hovers the component

• IsActiveCore: Protected; If the component is considered active by Dear ImGui

• IsTabInactiveCore: Protected; If the component is on an unselected TabPage in TabControl

• ApplyStyles: Protected; Virtual; Pushes Dear ImGui styles, colors, and fonts for the component; Is called directly before UpdateInternal

• RemoveStyles: Protected; Virtual; Pops Dear ImGui styles, colors, and fonts for the component; Is called directly after UpdateInternal

• SetTabInactiveCore: Protected; Virtual; Should invoke SetTabInactive on child components, if they exist, to propagate TabPage inactivity

Size

Represents a relative or absolute width and height for each component.
The Size of a component may always be retrieved by GetSize.

Shorthands for common size defintions are:

• Size.Parent: Represents a size that aligns to 100% of the parent component/form in both dimensions
• Size.Content: Represents a size that aligns to its content in both dimensions
• Size.WidthAlign: Represents a size that aligns to 100% of the parent component/form in width, and to its content in height
• Size.HeightAlign: Represents a size that aligns to 100% of the parent component/form in height, and to its content in width

The width and height of Size are of type SizeValue and each represent a relative or absolute value.

Shorthands for common size values are:

• SizeValue.Parent: Represents a value that aligns to 100% of the parent component/form in the same dimension
• SizeValue.Content: Represents a value that aligns to its content in the same dimension

Create a relative size value:

// Relative size values are given in a range from 0f to 1f
SizeValue.Relative(.3f);

Create an absolute size value:

// Absolute size values are in unit pixels
SizeValue.Absolute(200);

KeyCommand

A KeyCommand is any combination of a single key and multiple modifiers (like Ctrl, Alt, etc).
Some components allow setting a KeyCommand to invoke their main event.

Usage

Creating a KeyCommand for pressing Ctrl+S:

var command = new KeyCommand(ModifierKeys.Control, Key.S);

Creating a KeyCommand for pressing Enter:

var command = new KeyCommand(Key.Enter);

Checking if a KeyCommand should be invoked (normally done in UpdateInternal of a component):

if (command.IsPressed())
    ;

Properties

• IsEmpty: If the command has any key information set
• HasModifier: If the command has any modifier set (like Ctrl, Alt, etc)
• HasKey: If the command has any other key set (not including modifiers)

Methods

• IsPressed: If the command was pressed, as per ImGui.IsKeyPressed or ImGui.IsKeyChordPressed
• IsDown: If the command keys are down, as per ImGui.IsKeyDown
• IsReleased: If the command keys were released, as per ImGui.IsKeyReleased

ArrowButton

A button with an arrow symbol on it.

Properties

• KeyAction: The KeyCommand to invoke the Clicked event
• Direction: The direction of the arrow or none
• Padding: The padding between the component border and the arrow icon

Events

• Clicked: For when the button was clicked

Button

A button with text on it.

Properties

• Text: The localizable text on the button
• Tooltip: The localizable tooltip text, when the mouse hovers over the button
• Font: The font for the localizable text and tooltip
• KeyAction: The KeyCommand to invoke the Clicked event
• Padding: The padding between the button border and text
• Width: The width of the button, unaffected by the text length

Events

• Clicked: For when the button was clicked

CheckBox

A checkbox with right-side text.

Properties

• Text: The localizable text on the checkbox
• Tooltip: The localizable tooltip text, when the mouse hovers over the checkbox
• Font: The font for the localizable text and tooltip
• Checked: If the checkbox is checked; Invokes the `CheckChanged`` event

Events

• CheckChanged: For when the checkbox was changed

ComboBox

A dropdown with integrated searching and auto-completion.
Each item holds a text and associated data entry. The data entry is of a generic type per ComboBox.
A value of type T can implicitly convert to DropDownItem<T>.

Example

Setup a ComboBox with 2 items:

var combobox = new ComboBox<int>
{
    Items =
    {
        new DropDownItem<int>(1, "Number 1"),
        new DropDownItem<int>(2, "Number 2")
    }
}

Properties

• Items: The items to show and select from
• SelectedItem: The currently selected item, or null; Does not invoke the SelectedItemChanged event
• Width: The width of the ComboBox, unaffected by the text length in the items
• MaxCharacters: The maximum amount of characters allowed in the input
• MaxShowItems: The amount of items shown in the dropdown; Dropdown is scrollable, if more items are available

Events

• SelectedItemChanged: For when an item was selected

Expander

An expandable component with a header.

Properties

• Caption: The localizable text on the header
• Size: The size of the expander
• Content: The Component to show or hide
• Expanded: If the component is expanded; Does not invoke the ExpandedChanged event

Events

• ExpandedChanged: For when the component changes the expansion state

ImageButton

A button with an image.

Properties

• Tooltip: The localizable tooltip text, when the mouse hovers over the button
• KeyAction: The KeyCommand to invoke the Clicked event
• Image: The image shown on the button
• ImageSize: The size of the image on the button; Effectively chganges the size of the button along Padding
• Padding: The padding between the border of the button and the image

Events

• Clicked: For when the button was clicked

Label

A simple text label.

Properties

• Text: The localizable text on the label
• Font: The font for the localizable text
• LineDistance: The amount of pixels between each line in the localizable text
• TextColor: The color of the localizable text
• Width: The width of the label, unaffected by the text length

MultiLineTextBox

A textbox with multiple lines.

Properties

• Size: The size of the multiline textbox
• Text: The non-localizable text, input by the user, or preset by code; Invokes the TextChanged event
• IsReadOnly: If the multiline textbox can be written into by the user
• MaxCharacters: The maximum amount of characters allowed in the input

Events

• TextChanged: For when the text was changed

Panel

A container to control the size of components that may not directly support changing their size otherwise.

Properties

• Content: The Component to render
• Size: The size of the Content component

PictureBox

Shows a themed image.

Properties

• Size: The size of the component
• Image: The themed image to show

ProgressBar

Shows a fillable bar for progress reporting.

Properties

• Text: The localizable text on the progress bar
• Font: The font for the localizable text
• Size: The size of the component
• ProgressColor: The color of the filled progress bar
• Minimum: The minimum value; Progress bar is empty, when Value smaller equals Minimum
• Maximum: The maximum value; Progress bar is full, when Value greater equals Maximum
• Value: The current progress value

Splitter

A simple splitter line to set between components for visual categorization.

Properties

• Alignment: The alignment of the splitter; Vertical or horizontal
• Length: The length of the splitter in the alignment direction

TabControl

A container with multiple tabs to select from.

Properties

• Pages: A list of TabPages for the tabs to select from; Add and remove via methods AddPage and RemovePage respectively
• SelectedPage: The currently selected TabPage; Does not invoke SelectedPageChanged event

Events

• SelectedPageChanged: For when the selected TabPage was changed
• PageRemoving: For when a TabPage is attempted to be removed; Can cancel the removal
• PageRemoved: For when a TabPage was removed

Methods

• AddPage: Adds a TabPage to Pages
• RemovePage: Removes a TabPage from Pages

TabPage

A single tab in a TabControl.

Properties

• Title: A localizable text, shown on the tab area
• Content: The Component to show in the tab
• HasChanges: Shows a mark, if the content of the tab has changes to be persisted; Has to be manually set

TextBox

A textbox with a single line.

Properties

• Text: The non-localizable text, input by the user, or preset by code; Invokes the TextChanged event
• Width: The width of the textbox, unaffected by the text length
• Padding: The padding between the textbox border and text
• Font: The font for the non-localizable text and placeholder
• IsMasked: Masks the text for obscurity, like passwords
• IsReadOnly: If the multiline textbox can be written into by the user
• AllowedCharacters: Restricts the input to certain characters; Is based on Dear ImGui's native restriction flags for decimal and hexadecimal characters
• MaxCharacters: The maximum amount of characters allowed in the input
• Placeholder: A localizable text shown, when Text is empty

Events

• TextChanged: For when the text was changed
• FocusLost: For when the textbox lost focus, eg on pressing enter

TextEditor

A full-fledged text editor with an Undo history and syntax highlighting.
Can be compared to Notepad++. Credits to BalazsJako for the original version in C++.

Properties

• TabSize: The amount of spaces are used per tabulator
• LineSpacing: The space between two lines
• LeftMargin: The space from the left border to the text
• IsReadOnly: If the text can be modified
• IsOverwrite: If the text at the cursor is overwritten when typing
• IsColorizerEnabled: If the syntax highlighting is active
• IsShowingLineNumbers: If line numbers should be displayed
• IsShowingWhitespaces: If the whitespace characters should be made visible
• IsHandleMouseInputsEnabled: If the editor should react to mouse inputs
• IsHandleKeyboardInputsEnabled: If the editor should react to keyboard inputs

Events

• TextChanged: For when the text was changed; Provides the changed text as event argument
• CursorPositionChanged: For when the cursor changed position by any action; Provides the new cursor position as event argument

TreeView

A list of nested nodes in a tree structure.

Usage

Create a tree view:

var treeview = new TreeView<int>
{
    Nodes =
    {
        new TreeNode<int>
        {
            Text = "Parent",
            Nodes =
            {
                new TreeNode<int>
                {
                    Text = "Nested"
                }
            }
        }
    }
};

Properties

• Size: The size of the tree view
• Nodes: The list of nodes in the root layer of the tree view
• SelectedNode: The currently selected node in the tree view; Invokes the SelectedNodeChanged event
• ContextMenu: A ContextMenu, when a node is right-clicked

Events

• SelectedNodeChanged: For when the selected node changed
• NodeExpanded: For when a node was expanded
• NodeCollapsed: For when a node was collapsed

TreeNode

A single tree node in a tree view.
Contains a data entry of type T when using TreeNode<T>.

Usage

Create a nested tree node:

var treenode = new TreeNode<int>
{
    Text = "Parent",
    Data = 1,
    Nodes =
    {
        new TreeNode<int>
        {
            Text = "Nested",
            Data = 2,
        }
    }
}

Properties

TreeNode:

• Text: The localizable text on the node
• TextColor: The ThemedColor of the localizable text
• Font: The font for the localizable text
• IsExpanded: If the node is expanded or collapsed; Invokes the NodeExpanded and NodeCollapsed event respectively

TreeNode (contains the above):

• IsRoot: If the node is in the root of the tree view
• Nodes: The child nodes under this tree node
• Parent: The parent node of this tree node or null, if IsRoot is true
• Data: The data of type T for this tree node

Methods

• EnumerateNodes: Enumerate the direct child nodes of this tree node
• Remove: Removes this tree node from the tree view

ZoomablePictureBox

Shows a themed image and allows scaling and translation.

Hold right-click to move the image with your mouse through the component area defined by Size.
Scroll one the mouse wheel to zoom in or out of the image.

Properties

• Image: The image shown in the picture box
• Size: The size of the picture box

Events

• MouseScrolled: For when the component registers mouse scrolling; Before the image was zoomed in or out