Selectables

Selectable widgets and multi-selection for Dear ImGui

Selectable Widgets

A selectable highlights when hovered, and can display another color when selected. Neighbors selectable extend their highlight bounds in order to leave no gap between them.

Selectable

bool ImGui::Selectable(const char* label, bool selected = false, ImGuiSelectableFlags flags = 0, const ImVec2& size = ImVec2(0, 0))

Selectable widget. selected carries the selection state (read-only). Returns true when clicked.

label · const char*

Selectable label

selected · bool · default: "false"

Current selection state (read-only)

flags · ImGuiSelectableFlags · default: "0"

Selectable flags (see ImGuiSelectableFlags_)

size · const ImVec2& · default: "ImVec2(0, 0)"

Size (0.0f = use remaining width/height, >0.0f = specify)

return · bool

True when clicked (modify your selection state)

// Example
static int selected = -1;
for (int n = 0; n < 10; n++) {
    char buf[32];
    sprintf(buf, "Object %d", n);
    if (ImGui::Selectable(buf, selected == n)) {
        selected = n;
    }
}

Selectable (pointer)

bool ImGui::Selectable(const char* label, bool* p_selected, ImGuiSelectableFlags flags = 0, const ImVec2& size = ImVec2(0, 0))

Selectable with pointer to selection state (read-write), as a convenient helper.

label · const char*

Selectable label

p_selected · bool*

Pointer to selection state (read-write)

flags · ImGuiSelectableFlags · default: "0"

Selectable flags

size · const ImVec2& · default: "ImVec2(0, 0)"

Size

return · bool

True when clicked

// Example
static bool selection[5] = { false, false, false, false, false };
for (int n = 0; n < 5; n++) {
    char buf[32];
    sprintf(buf, "Object %d", n);
    ImGui::Selectable(buf, &selection[n]);
}

Multi-Selection

Multi-selection system for Selectable(), Checkbox(), TreeNode() functions. This enables standard multi-selection/range-selection idioms (Ctrl+Mouse/Keyboard, Shift+Mouse/Keyboard, etc.).

BeginMultiSelect

ImGuiMultiSelectIO* ImGui::BeginMultiSelect(ImGuiMultiSelectFlags flags, int selection_size = -1, int items_count = -1)

Begin multi-selection scope.

flags · ImGuiMultiSelectFlags

Multi-select flags (see ImGuiMultiSelectFlags_)

selection_size · int · default: "-1"

Current number of selected items (-1 if expensive to compute)

items_count · int · default: "-1"

Total number of items (-1 if expensive to compute)

return · ImGuiMultiSelectIO*

Multi-select I/O structure with requests to apply

// Example
static ImGuiSelectionBasicStorage selection;
ImGuiMultiSelectIO* ms_io = ImGui::BeginMultiSelect(ImGuiMultiSelectFlags_None, selection.Size, items.Size);
// Apply selection requests
for (int n = 0; n < items.Size; n++) {
    ImGui::SetNextItemSelectionUserData(n);
    bool is_selected = selection.Contains((ImGuiID)n);
    ImGui::Selectable(items[n].Name, is_selected);
}
ms_io = ImGui::EndMultiSelect();
// Apply post-selection requests

EndMultiSelect

ImGuiMultiSelectIO* ImGui::EndMultiSelect()

End multi-selection scope.

return · ImGuiMultiSelectIO*

Multi-select I/O structure with post-loop requests

SetNextItemSelectionUserData

void ImGui::SetNextItemSelectionUserData(ImGuiSelectionUserData selection_user_data)

Set selection user data for the next item. This is typically an item index within your current view.

selection_user_data · ImGuiSelectionUserData

User data (typically item index)

IsItemToggledSelection

bool ImGui::IsItemToggledSelection()

Was the last item selection state toggled? Useful if you need the per-item information before reaching EndMultiSelect().

return · bool

True if item selection was toggled

Selectable Flags

ImGuiSelectableFlags_

Flags for Selectable().

Flag	Description
ImGuiSelectableFlags_None	Default
ImGuiSelectableFlags_NoAutoClosePopups	Clicking this doesn’t close parent popup window
ImGuiSelectableFlags_SpanAllColumns	Frame will span all columns of container table
ImGuiSelectableFlags_AllowDoubleClick	Generate press events on double clicks too
ImGuiSelectableFlags_Disabled	Cannot be selected, display grayed out text
ImGuiSelectableFlags_AllowOverlap	Hit testing to allow subsequent widgets to overlap
ImGuiSelectableFlags_Highlight	Make the item be displayed as if it is hovered
ImGuiSelectableFlags_SelectOnNav	Auto-select when moved into (unless Ctrl is held)

// Examples

// Span all columns in a table
if (ImGui::BeginTable("table", 3)) {
    for (int row = 0; row < 5; row++) {
        ImGui::TableNextRow();
        ImGui::TableNextColumn();
        ImGui::Selectable("Row", false, ImGuiSelectableFlags_SpanAllColumns);
    }
    ImGui::EndTable();
}

// Disabled selectable
ImGui::Selectable("Disabled", false, ImGuiSelectableFlags_Disabled);

// Allow double-click
if (ImGui::Selectable("Double-click me", false, ImGuiSelectableFlags_AllowDoubleClick)) {
    if (ImGui::IsMouseDoubleClicked(0)) {
        // Double-clicked
    }
}

// Highlight
ImGui::Selectable("Highlighted", false, ImGuiSelectableFlags_Highlight);

Multi-Select Flags

ImGuiMultiSelectFlags_

Flags for BeginMultiSelect().

Flag	Description
ImGuiMultiSelectFlags_None	Default
ImGuiMultiSelectFlags_SingleSelect	Single selection mode (default is multi-select)
ImGuiMultiSelectFlags_NoSelectAll	Disable select all (Ctrl+A)
ImGuiMultiSelectFlags_NoRangeSelect	Disable range select (Shift+Click)
ImGuiMultiSelectFlags_NoAutoSelect	Disable auto-select on navigation
ImGuiMultiSelectFlags_NoAutoClear	Disable auto-clear on click in empty space
ImGuiMultiSelectFlags_NoAutoClearOnReselect	Disable auto-clear when re-clicking selected item
ImGuiMultiSelectFlags_BoxSelect1d	Enable 1D box-select (within a single axis)
ImGuiMultiSelectFlags_BoxSelect2d	Enable 2D box-select
ImGuiMultiSelectFlags_BoxSelectNoScroll	Disable scrolling when box-selecting
ImGuiMultiSelectFlags_ClearOnEscape	Clear selection on Escape key
ImGuiMultiSelectFlags_ClearOnClickVoid	Clear selection when clicking in void

// Single selection mode
ImGuiMultiSelectIO* ms_io = ImGui::BeginMultiSelect(ImGuiMultiSelectFlags_SingleSelect);
// ...
ImGui::EndMultiSelect();

// Disable Ctrl+A
ms_io = ImGui::BeginMultiSelect(ImGuiMultiSelectFlags_NoSelectAll);
// ...
ImGui::EndMultiSelect();

List Boxes

List boxes are thin wrappers around BeginChild() with the ImGuiChildFlags_FrameStyle flag.

BeginListBox

bool ImGui::BeginListBox(const char* label, const ImVec2& size = ImVec2(0, 0))

Open a framed scrolling region. Only call EndListBox() if BeginListBox() returns true.

label · const char*

List box label

size · const ImVec2& · default: "ImVec2(0, 0)"

Size (0 = default size)

return · bool

True if list box is open

// Example
const char* items[] = { "Apple", "Banana", "Cherry", "Kiwi", "Mango", "Orange", "Pineapple", "Strawberry", "Watermelon" };
static int item_current = 1;

if (ImGui::BeginListBox("Items")) {
    for (int n = 0; n < IM_COUNTOF(items); n++) {
        const bool is_selected = (item_current == n);
        if (ImGui::Selectable(items[n], is_selected)) {
            item_current = n;
        }
        if (is_selected) {
            ImGui::SetItemDefaultFocus();
        }
    }
    ImGui::EndListBox();
}

EndListBox

void ImGui::EndListBox()

Close list box. Only call if BeginListBox() returned true.

ListBox (simple)

bool ImGui::ListBox(const char* label, int* current_item, const char* const items[], int items_count, int height_in_items = -1)

Simple list box helper.

label · const char*

List box label

current_item · int*

Pointer to current selected item index

items · const char* const[]

Array of item strings

items_count · int

Number of items in array

height_in_items · int · default: "-1"

Height in number of items (-1 = default ~7)

return · bool

True when selection has been modified

// Example
const char* items[] = { "Apple", "Banana", "Cherry" };
static int item_current = 1;
ImGui::ListBox("Fruits", &item_current, items, IM_COUNTOF(items), 4);

ListBox (callback)

bool ImGui::ListBox(const char* label, int* current_item, const char* (*getter)(void* user_data, int idx), void* user_data, int items_count, int height_in_items = -1)

List box with callback to get item strings.

label · const char*

List box label

current_item · int*

Pointer to current selected item index

getter · const char* (*)(void*, int)

Callback function to get item string

user_data · void*

User data passed to callback

items_count · int

Number of items

height_in_items · int · default: "-1"

Height in number of items

return · bool

True when selection has been modified