Columns & Groups

Functions for organizing widgets into columns and groups

Groups

Groups allow you to lock horizontal starting position and capture the whole group bounding box into one “item”. This lets you use IsItemHovered() or layout primitives such as SameLine() on the whole group.

BeginGroup

void BeginGroup();

Lock horizontal starting position. All widgets added after this call will be treated as part of a group.

Example:

ImGui::BeginGroup();
ImGui::Text("Group Item 1");
ImGui::Text("Group Item 2");
ImGui::Text("Group Item 3");
ImGui::EndGroup();
if (ImGui::IsItemHovered())
    ImGui::SetTooltip("This is the whole group!");

EndGroup

void EndGroup();

Unlock horizontal starting position and capture the whole group bounding box into one “item”.

Always call EndGroup() for each BeginGroup(), even if the group is empty.

Group Usage Patterns

Horizontal Grouping with SameLine

ImGui::BeginGroup();
ImGui::Text("Label:");
ImGui::SameLine();
ImGui::Button("Button");
ImGui::EndGroup();

Creating Compound Widgets

ImGui::BeginGroup();
ImGui::Image(my_texture, ImVec2(64, 64));
ImGui::Text("Image Title");
ImGui::EndGroup();

// Drag and drop the entire group
if (ImGui::BeginDragDropSource())
{
    ImGui::SetDragDropPayload("MY_IMAGE", &my_data, sizeof(my_data));
    ImGui::EndDragDropSource();
}

Capturing Group Dimensions

ImVec2 group_min = ImGui::GetItemRectMin();
ImVec2 group_max = ImGui::GetItemRectMax();
ImVec2 group_size = ImGui::GetItemRectSize();

Legacy Columns API

The columns API is legacy. Use the Tables API instead for better features and performance.

Columns

void Columns(int count = 1, const char* id = NULL, bool border = true);

Setup number of columns. Use Columns(1) or Columns() to disable columns.

count · int

Number of columns (1 to disable)

id · const char*

Optional identifier

border · bool · default: "true"

Draw border between columns

NextColumn

void NextColumn();

Move to next column. If currently in the last column, move to the first column of the next row.

GetColumnIndex

int GetColumnIndex();

Get current column index (0-based).

Returns · int

Current column index

GetColumnWidth

float GetColumnWidth(int column_index = -1);

Get column width in pixels. Use -1 for current column.

column_index · int · default: "-1"

Column index (-1 for current column)

Returns · float

Column width in pixels

SetColumnWidth

void SetColumnWidth(int column_index, float width);

Set column width in pixels.

column_index · int

Column index

width · float

New width in pixels

GetColumnOffset

float GetColumnOffset(int column_index = -1);

Get position of column line in pixels from the left side of the contents region. Use -1 for current column.

column_index · int · default: "-1"

Column index (-1 for current column)

Returns · float

Column offset in pixels

SetColumnOffset

void SetColumnOffset(int column_index, float offset_x);

Set position of column line in pixels from the left side of the contents region.

column_index · int

Column index

offset_x · float

New offset in pixels

GetColumnsCount

int GetColumnsCount();

Get number of columns (1 when columns are disabled).

Returns · int

Number of active columns

Migration to Tables

Instead of using columns, prefer the Tables API:

// Old columns API
ImGui::Columns(3, "MyColumns", true);
ImGui::Text("Col 1");
ImGui::NextColumn();
ImGui::Text("Col 2");
ImGui::NextColumn();
ImGui::Text("Col 3");
ImGui::Columns(1);

// New tables API
if (ImGui::BeginTable("MyTable", 3))
{
    ImGui::TableNextColumn();
    ImGui::Text("Col 1");
    ImGui::TableNextColumn();
    ImGui::Text("Col 2");
    ImGui::TableNextColumn();
    ImGui::Text("Col 3");
    ImGui::EndTable();
}