@ -131,8 +131,7 @@ Also see [Wiki](https://github.com/ocornut/imgui/wiki) for more links and ideas.
### Upcoming Changes
Some of the goals for 2020 are:
- Work on Tables (see [#2957](https://github.com/ocornut/imgui/issues/2957), now merged in master.
Some of the goals for 2021 are:
- Work on Docking (see [#2109](https://github.com/ocornut/imgui/issues/2109), in public [docking](https://github.com/ocornut/imgui/tree/docking) branch)
- Work on Multi-Viewport / Multiple OS windows. (see [#1542](https://github.com/ocornut/imgui/issues/1542), in public [docking](https://github.com/ocornut/imgui/tree/docking) branch looking for feedback)
- Work on gamepad/keyboard controls. (see [#787](https://github.com/ocornut/imgui/issues/787))
//---- Unless IMGUI_DISABLE_DEFAULT_FORMAT_FUNCTIONS is defined, use the much faster STB sprintf library implementation of vsnprintf instead of the one from the default C library.
// Note that stb_sprintf.h is meant to be provided by the user and available in the include path at compile time. Also, the compatibility checks of the arguments and formats done by clang and GCC will be disabled in order to support the extra formats provided by STB sprintf.
//---- Use stb_printf's faster implementation of vsnprintf instead of the one from libc (unless IMGUI_DISABLE_DEFAULT_FORMAT_FUNCTIONS is defined)
// Requires 'stb_sprintf.h' to be available in the include path. Compatibility checks of arguments and formats done by clang and GCC will be disabled in order to support the extra formats provided by STB sprintf.
// #define IMGUI_USE_STB_SPRINTF
//---- Define constructor and implicit cast operators to convert back<>forth between your math types and ImVec2/ImVec4.
// (Integer encoded as XYYZZ for use in #if preprocessor conditionals. Work in progress versions typically starts at XYY99 then bounce up to XYY00, XYY01 etc. when release tagging happens)
IMGUI_APIvoidEndTable();// only call EndTable() if BeginTable() returns true!
IMGUI_APIvoidTableNextRow(ImGuiTableRowFlagsrow_flags=0,floatmin_row_height=0.0f);// append into the first cell of a new row.
IMGUI_APIboolTableNextColumn();// append into the next column (or first column of next row if currently in last column). Return true when column is visible.
IMGUI_APIboolTableSetColumnIndex(intcolumn_n);// append into the specified column. Return true when column is visible.
// Tables: Headers & Columns declaration
// - Use TableSetupColumn() to specify label, resizing policy, default width/weight, id, various other flags etc.
// Important: this will not display anything! The name passed to TableSetupColumn() is used by TableHeadersRow() and context-menus.
// - Use TableHeadersRow() to create a row and automatically submit a TableHeader() for each column.
// Headers are required to perform: reordering, sorting, and opening the context menu (but context menu can also be available in columns body using ImGuiTableFlags_ContextMenuInBody).
// - You may manually submit headers using TableNextRow() + TableHeader() calls, but this is only useful in some advanced cases (e.g. adding custom widgets in header row).
// - Use TableSetupScrollFreeze() to lock columns (from the right) or rows (from the top) so they stay visible when scrolled.
// - Use TableHeadersRow() to create a header row and automatically submit a TableHeader() for each column.
// Headers are required to perform: reordering, sorting, and opening the context menu.
// The context menu can also be made available in columns body using ImGuiTableFlags_ContextMenuInBody.
// - You may manually submit headers using TableNextRow() + TableHeader() calls, but this is only useful in
// some advanced use cases (e.g. adding custom widgets in header row).
// - Use TableSetupScrollFreeze() to lock columns/rows so they stay visible when scrolled.
IMGUI_APIvoidTableSetupScrollFreeze(intcols,introws);// lock columns/rows so they stay visible when scrolled.
IMGUI_APIvoidTableHeadersRow();// submit all headers cells based on data provided to TableSetupColumn() + submit context menu
IMGUI_APIvoidTableHeader(constchar*label);// submit one header cell manually (rarely used)
// Tables: Sorting
// - Call TableGetSortSpecs() to retrieve latest sort specs for the table. NULL when not sorting.
// - When 'SpecsDirty == true' you should sort your data. It will be true when sorting specs have changed
// since last call, or the first time. Make sure to set 'SpecsDirty = false' after sorting, else you may
// wastefully sort your data every frame!
// - Lifetime: don't hold on this pointer over multiple frames or past any subsequent call to BeginTable().
IMGUI_APIImGuiTableSortSpecs*TableGetSortSpecs();// get latest sort specs for the table (NULL if not sorting).
// Tables: Miscellaneous functions
// - Most functions taking 'int column_n' treat the default value of -1 as the same as passing the current column index
// - Sorting: call TableGetSortSpecs() to retrieve latest sort specs for the table. Return value will be NULL if no sorting.
// When 'SpecsDirty == true' you should sort your data. It will be true when sorting specs have changed since last call, or the first time.
// Make sure to set 'SpecsDirty = false' after sorting, else you may wastefully sort your data every frame!
// Lifetime: don't hold on this pointer over multiple frames or past any subsequent call to BeginTable().
// - Functions args 'int column_n' treat the default value of -1 as the same as passing the current column index.
IMGUI_APIintTableGetColumnCount();// return number of columns (value passed to BeginTable)
IMGUI_APIintTableGetColumnIndex();// return current column index.
IMGUI_APIintTableGetRowIndex();// return current row index.
IMGUI_APIconstchar*TableGetColumnName(intcolumn_n=-1);// return "" if column didn't have a name declared by TableSetupColumn(). Pass -1 to use current column.
IMGUI_APIImGuiTableColumnFlagsTableGetColumnFlags(intcolumn_n=-1);// return column flags so you can query their Enabled/Visible/Sorted/Hovered status flags. Pass -1 to use current column.
IMGUI_APIImGuiTableSortSpecs*TableGetSortSpecs();// get latest sort specs for the table (NULL if not sorting).
IMGUI_APIvoidTableSetBgColor(ImGuiTableBgTargettarget,ImU32color,intcolumn_n=-1);// change the color of a cell, row, or column. See ImGuiTableBgTarget_ flags for details.
// Legacy Columns API (2020: prefer using Tables!)
ImGuiTableFlags_Reorderable=1<<1,// Enable reordering columns in header row (need calling TableSetupColumn() + TableHeadersRow() to display headers)
ImGuiTableFlags_Hideable=1<<2,// Enable hiding/disabling columns in context menu.
ImGuiTableFlags_Sortable=1<<3,// Enable sorting. Call TableGetSortSpecs() to obtain sort specs. Also see ImGuiTableFlags_SortMulti and ImGuiTableFlags_SortTristate.
ImGuiTableFlags_NoSavedSettings=1<<4,// Disable persisting columns order, width and sort settings in the .ini file.
ImGuiTableFlags_ContextMenuInBody=1<<5,// Right-click on columns body/contents will display table context menu. By default it is available in TableHeadersRow().
ImGuiTableFlags_Reorderable=1<<1,// Enable reordering columns in header row (need calling TableSetupColumn() + TableHeadersRow() to display headers)
ImGuiTableFlags_Hideable=1<<2,// Enable hiding/disabling columns in context menu.
ImGuiTableFlags_Sortable=1<<3,// Enable sorting. Call TableGetSortSpecs() to obtain sort specs. Also see ImGuiTableFlags_SortMulti and ImGuiTableFlags_SortTristate.
ImGuiTableFlags_NoSavedSettings=1<<4,// Disable persisting columns order, width and sort settings in the .ini file.
ImGuiTableFlags_ContextMenuInBody=1<<5,// Right-click on columns body/contents will display table context menu. By default it is available in TableHeadersRow().
// Decorations
ImGuiTableFlags_RowBg=1<<6,// Set each RowBg color with ImGuiCol_TableRowBg or ImGuiCol_TableRowBgAlt (equivalent of calling TableSetBgColor with ImGuiTableBgFlags_RowBg0 on each row manually)
ImGuiTableFlags_BordersInnerH=1<<7,// Draw horizontal borders between rows.
ImGuiTableFlags_BordersOuterH=1<<8,// Draw horizontal borders at the top and bottom.
ImGuiTableFlags_BordersInnerV=1<<9,// Draw vertical borders between columns.
ImGuiTableFlags_BordersOuterV=1<<10,// Draw vertical borders on the left and right sides.
ImGuiTableFlags_Borders=ImGuiTableFlags_BordersInner|ImGuiTableFlags_BordersOuter,// Draw all borders.
ImGuiTableFlags_NoBordersInBody=1<<11,// [ALPHA] Disable vertical borders in columns Body (borders will always appears in Headers). -> May move to style
ImGuiTableFlags_NoBordersInBodyUntilResize=1<<12,// [ALPHA] Disable vertical borders in columns Body until hovered for resize (borders will always appears in Headers). -> May move to style
ImGuiTableFlags_RowBg=1<<6,// Set each RowBg color with ImGuiCol_TableRowBg or ImGuiCol_TableRowBgAlt (equivalent of calling TableSetBgColor with ImGuiTableBgFlags_RowBg0 on each row manually)
ImGuiTableFlags_BordersInnerH=1<<7,// Draw horizontal borders between rows.
ImGuiTableFlags_BordersOuterH=1<<8,// Draw horizontal borders at the top and bottom.
ImGuiTableFlags_BordersInnerV=1<<9,// Draw vertical borders between columns.
ImGuiTableFlags_BordersOuterV=1<<10,// Draw vertical borders on the left and right sides.
ImGuiTableFlags_Borders=ImGuiTableFlags_BordersInner|ImGuiTableFlags_BordersOuter,// Draw all borders.
ImGuiTableFlags_NoBordersInBody=1<<11,// [ALPHA] Disable vertical borders in columns Body (borders will always appears in Headers). -> May move to style
ImGuiTableFlags_NoBordersInBodyUntilResize=1<<12,// [ALPHA] Disable vertical borders in columns Body until hovered for resize (borders will always appears in Headers). -> May move to style
// Sizing Policy (read above for defaults)
ImGuiTableFlags_SizingFixedFit=1<<13,// Columns default to _WidthFixed or _WidthAuto (if resizable or not resizable), matching contents width.
ImGuiTableFlags_SizingFixedSame=2<<13,// Columns default to _WidthFixed or _WidthAuto (if resizable or not resizable), matching the maximum contents width of all columns. Implicitly enable ImGuiTableFlags_NoKeepColumnsVisible.
ImGuiTableFlags_SizingStretchProp=3<<13,// Columns default to _WidthStretch with default weights proportional to each columns contents widths.
ImGuiTableFlags_SizingStretchSame=4<<13,// Columns default to _WidthStretch with default weights all equal, unless overriden by TableSetupColumn().
ImGuiTableFlags_SizingFixedFit=1<<13,// Columns default to _WidthFixed or _WidthAuto (if resizable or not resizable), matching contents width.
ImGuiTableFlags_SizingFixedSame=2<<13,// Columns default to _WidthFixed or _WidthAuto (if resizable or not resizable), matching the maximum contents width of all columns. Implicitly enable ImGuiTableFlags_NoKeepColumnsVisible.
ImGuiTableFlags_SizingStretchProp=3<<13,// Columns default to _WidthStretch with default weights proportional to each columns contents widths.
ImGuiTableFlags_SizingStretchSame=4<<13,// Columns default to _WidthStretch with default weights all equal, unless overriden by TableSetupColumn().
// Sizing Extra Options
ImGuiTableFlags_NoHostExtendX=1<<16,// 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.
ImGuiTableFlags_NoHostExtendY=1<<17,// 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.
ImGuiTableFlags_NoKeepColumnsVisible=1<<18,// Disable keeping column always minimally visible when ScrollX is off and table gets too small. Not recommended if columns are resizable.
ImGuiTableFlags_PreciseWidths=1<<19,// 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.
ImGuiTableFlags_NoHostExtendX=1<<16,// 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.
ImGuiTableFlags_NoHostExtendY=1<<17,// 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.
ImGuiTableFlags_NoKeepColumnsVisible=1<<18,// Disable keeping column always minimally visible when ScrollX is off and table gets too small. Not recommended if columns are resizable.
ImGuiTableFlags_PreciseWidths=1<<19,// 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.
// Clipping
ImGuiTableFlags_NoClip=1<<20,// Disable clipping rectangle for every individual columns (reduce draw command count, items will be able to overflow into other columns). Generally incompatible with TableSetupScrollFreeze().
ImGuiTableFlags_NoClip=1<<20,// Disable clipping rectangle for every individual columns (reduce draw command count, items will be able to overflow into other columns). Generally incompatible with TableSetupScrollFreeze().
// Padding
ImGuiTableFlags_PadOuterX=1<<21,// Default if BordersOuterV is on. Enable outer-most padding. Generally desirable if you have headers.
ImGuiTableFlags_NoPadOuterX=1<<22,// Default if BordersOuterV is off. Disable outer-most padding.
ImGuiTableFlags_NoPadInnerX=1<<23,// Disable inner padding between columns (double inner padding if BordersOuterV is on, single inner padding if BordersOuterV is off).
ImGuiTableFlags_PadOuterX=1<<21,// Default if BordersOuterV is on. Enable outer-most padding. Generally desirable if you have headers.
ImGuiTableFlags_NoPadOuterX=1<<22,// Default if BordersOuterV is off. Disable outer-most padding.
ImGuiTableFlags_NoPadInnerX=1<<23,// Disable inner padding between columns (double inner padding if BordersOuterV is on, single inner padding if BordersOuterV is off).
// Scrolling
ImGuiTableFlags_ScrollX=1<<24,// Enable horizontal scrolling. Require 'outer_size' parameter of BeginTable() to specify the container size. Changes default sizing policy. Because this create a child window, ScrollY is currently generally recommended when using ScrollX.
ImGuiTableFlags_ScrollY=1<<25,// Enable vertical scrolling. Require 'outer_size' parameter of BeginTable() to specify the container size.
ImGuiTableFlags_ScrollX=1<<24,// Enable horizontal scrolling. Require 'outer_size' parameter of BeginTable() to specify the container size. Changes default sizing policy. Because this create a child window, ScrollY is currently generally recommended when using ScrollX.
ImGuiTableFlags_ScrollY=1<<25,// Enable vertical scrolling. Require 'outer_size' parameter of BeginTable() to specify the container size.
// Sorting
ImGuiTableFlags_SortMulti=1<<26,// Hold shift when clicking headers to sort on multiple column. TableGetSortSpecs() may return specs where (SpecsCount > 1).
ImGuiTableFlags_SortTristate=1<<27,// Allow no sorting, disable default sorting. TableGetSortSpecs() may return specs where (SpecsCount == 0).
ImGuiTableFlags_SortMulti=1<<26,// Hold shift when clicking headers to sort on multiple column. TableGetSortSpecs() may return specs where (SpecsCount > 1).
ImGuiTableFlags_SortTristate=1<<27,// Allow no sorting, disable default sorting. TableGetSortSpecs() may return specs where (SpecsCount == 0).
ImGuiTableColumnFlags_DefaultHide=1<<0,// Default as a hidden/disabled column.
ImGuiTableColumnFlags_DefaultSort=1<<1,// Default as a sorting column.
ImGuiTableColumnFlags_WidthStretch=1<<2,// Column will stretch. Preferable with horizontal scrolling disabled (default if table sizing policy is _SizingStretchSame or _SizingStretchProp).
ImGuiTableColumnFlags_WidthFixed=1<<3,// Column will not stretch. Preferable with horizontal scrolling enabled (default if table sizing policy is _SizingFixedFit and table is resizable).
ImGuiTableColumnFlags_NoReorder=1<<5,// Disable manual reordering this column, this will also prevent other columns from crossing over this column.
ImGuiTableColumnFlags_NoHide=1<<6,// Disable ability to hide/disable this column.
ImGuiTableColumnFlags_NoClip=1<<7,// Disable clipping for this column (all NoClip columns will render in a same draw command).
ImGuiTableColumnFlags_NoSort=1<<8,// Disable ability to sort on this field (even if ImGuiTableFlags_Sortable is set on the table).
ImGuiTableColumnFlags_NoSortAscending=1<<9,// Disable ability to sort in the ascending direction.
ImGuiTableColumnFlags_NoSortDescending=1<<10,// Disable ability to sort in the descending direction.
ImGuiTableColumnFlags_NoHeaderWidth=1<<11,// Disable header text width contribution to automatic column width.
ImGuiTableColumnFlags_PreferSortAscending=1<<12,// Make the initial sort direction Ascending when first sorting on this column (default).
ImGuiTableColumnFlags_PreferSortDescending=1<<13,// Make the initial sort direction Descending when first sorting on this column.
ImGuiTableColumnFlags_IndentEnable=1<<14,// Use current Indent value when entering cell (default for column 0).
ImGuiTableColumnFlags_IndentDisable=1<<15,// Ignore current Indent value when entering cell (default for columns > 0). Indentation changes _within_ the cell will still be honored.
ImGuiTableColumnFlags_None=0,
ImGuiTableColumnFlags_DefaultHide=1<<0,// Default as a hidden/disabled column.
ImGuiTableColumnFlags_DefaultSort=1<<1,// Default as a sorting column.
ImGuiTableColumnFlags_WidthStretch=1<<2,// Column will stretch. Preferable with horizontal scrolling disabled (default if table sizing policy is _SizingStretchSame or _SizingStretchProp).
ImGuiTableColumnFlags_WidthFixed=1<<3,// Column will not stretch. Preferable with horizontal scrolling enabled (default if table sizing policy is _SizingFixedFit and table is resizable).
ImGuiTableColumnFlags_NoReorder=1<<5,// Disable manual reordering this column, this will also prevent other columns from crossing over this column.
ImGuiTableColumnFlags_NoHide=1<<6,// Disable ability to hide/disable this column.
ImGuiTableColumnFlags_NoClip=1<<7,// Disable clipping for this column (all NoClip columns will render in a same draw command).
ImGuiTableColumnFlags_NoSort=1<<8,// Disable ability to sort on this field (even if ImGuiTableFlags_Sortable is set on the table).
ImGuiTableColumnFlags_NoSortAscending=1<<9,// Disable ability to sort in the ascending direction.
ImGuiTableColumnFlags_NoSortDescending=1<<10,// Disable ability to sort in the descending direction.
ImGuiTableColumnFlags_NoHeaderWidth=1<<11,// Disable header text width contribution to automatic column width.
ImGuiTableColumnFlags_PreferSortAscending=1<<12,// Make the initial sort direction Ascending when first sorting on this column (default).
ImGuiTableColumnFlags_PreferSortDescending=1<<13,// Make the initial sort direction Descending when first sorting on this column.
ImGuiTableColumnFlags_IndentEnable=1<<14,// Use current Indent value when entering cell (default for column 0).
ImGuiTableColumnFlags_IndentDisable=1<<15,// Ignore current Indent value when entering cell (default for columns > 0). Indentation changes _within_ the cell will still be honored.
// Output status flags, read-only via TableGetColumnFlags()
ImGuiTableColumnFlags_IsEnabled=1<<20,// Status: is enabled == not hidden by user/api (referred to as "Hide" in _DefaultHide and _NoHide) flags.
ImGuiTableColumnFlags_IsVisible=1<<21,// Status: is visible == is enabled AND not clipped by scrolling.
ImGuiTableColumnFlags_IsSorted=1<<22,// Status: is currently part of the sort specs
ImGuiTableColumnFlags_IsHovered=1<<23,// Status: is hovered by mouse
ImGuiTableColumnFlags_IsEnabled=1<<20,// Status: is enabled == not hidden by user/api (referred to as "Hide" in _DefaultHide and _NoHide) flags.
ImGuiTableColumnFlags_IsVisible=1<<21,// Status: is visible == is enabled AND not clipped by scrolling.
ImGuiTableColumnFlags_IsSorted=1<<22,// Status: is currently part of the sort specs
ImGuiTableColumnFlags_IsHovered=1<<23,// Status: is hovered by mouse
ImGuiTableColumnFlags_NoDirectResize_=1<<30// [Internal] Disable user resizing this column directly (it may however we resized indirectly from its left edge)
ImGuiTableColumnFlags_NoDirectResize_=1<<30// [Internal] Disable user resizing this column directly (it may however we resized indirectly from its left edge)
// Obsolete names (will be removed soon)
#ifndef IMGUI_DISABLE_OBSOLETE_FUNCTIONS
//ImGuiTableColumnFlags_WidthAuto = ImGuiTableColumnFlags_WidthFixed | ImGuiTableColumnFlags_NoResize, // Column will not stretch and keep resizing based on submitted contents.
//ImGuiTableColumnFlags_WidthAuto = ImGuiTableColumnFlags_WidthFixed | ImGuiTableColumnFlags_NoResize, // Column will not stretch and keep resizing based on submitted contents.
ImGui::CheckboxFlags("ImGuiTableFlags_NoBordersInBody",&flags,ImGuiTableFlags_NoBordersInBody);ImGui::SameLine();HelpMarker("Disable vertical borders in columns Body (borders will always appears in Headers");
PopStyleCompact();
if(ImGui::BeginTable("##table1",3,flags))
if(ImGui::BeginTable("table1",3,flags))
{
// Display headers so we can inspect their interaction with borders.
// (Headers are not the main purpose of this section of the demo, so we are not elaborating on them too much. See other sections for details)
ImGui::SameLine();HelpMarker("Using the _Resizable flag automatically enables the _BordersInnerV flag as well, this is why the resize borders are still showing when unchecking this.");
ImGui::CheckboxFlags("ImGuiTableFlags_NoBordersInBodyUntilResize",&flags,ImGuiTableFlags_NoBordersInBodyUntilResize);ImGui::SameLine();HelpMarker("Disable vertical borders in columns Body until hovered for resize (borders will always appears in Headers)");
PopStyleCompact();
if(ImGui::BeginTable("##table1",3,flags))
if(ImGui::BeginTable("table1",3,flags))
{
// Submit columns name with TableSetupColumn() and call TableHeadersRow() to create a row with a header in each column.
// (Later we will show how TableSetupColumn() has other uses, optional flags, sizing weight etc.)
HelpMarker("You can pass a 'min_row_height' to TableNextRow().\n\nRows are padded with 'style.CellPadding.y' on top and bottom, so effectively the minimum row height will always be >= 'style.CellPadding.y * 2.0f'.\n\nWe cannot honor a _maximum_ row height as that would requires a unique clipping rectangle per row.");
ImGui::SameLine();HelpMarker("When sorting is enabled: allow no sorting, disable default sorting. TableGetSortSpecs() may return specs where (SpecsCount == 0).");
ocornut
4 years ago