Saving .ini settings with Last Used Date information

[ocornut]

I'm adding a new feature and this is a general informational thread for visibility feedback.

The general idea is to track and store low-footprint quantized dates in certain .ini entries:

[Window][Dear ImGui Demo]
Pos=147,225
Size=621,987
Collapsed=0
LastUsed=20260703     <--- this

• When looking at .ini data it makes contexts usually easier to grasp.
• If allows creating tools to manual/automatically discard old entries. Many apps can create non-finite amounts of windows/contents that never gets discarded. While the system generally holds itself well, it can adds up a bit of runtime overhead. It can also create cognitive overhead to have lots of unused data in memory/files.
• Being able to have eviction policies makes it possible to consider saving more contents in .ini files (e.g. More general ini file support? #437 but also e.g. tree nodes open state).

The expectation is that people would use policies such "discard data for stuff that have been unused for 6 months".

Current code enable saving/loading that data but has no eviction policy are enabled by default, and I don't expect to enable anything by default in the foreseeable future.

There are corners cases related to storing persistent data (e.g. docking layouts) where I would expect feedback to happen. There is a (yet internal) CleanupIniSettings(ImGuiSettingsCleanupArgs* args) function that provide tools to e.g. mark data as current if needed. So if you have eviction policies you may want to load your .ini templates and apply current date to them.

Changelog

Settings:

• Windows/Tables settings entries can now record the last used date in YYYYMMDD format, allowing cleanup tools to run to e.g. delete entries that haven't been used in X months.
• Added bool io.ConfigIniSettingsSaveLastUsedDate to disable saving that info.
• Added int io.ConfigIniSettingsAutoDiscardMonths to enable a mode where unused settings are automatically discard after xx months.
• Added a trimming tool under Metrics->Settings, along with a yet-unexposed function.
• The current system date is fed through ImGuiPlatformIO::Platform_SessionDate, which is automatically set by a call to time() done during context creation.
• Added IMGUI_DISABLE_TIME_FUNCTIONS to disable setting platform_io.Platform_SessionDate. A custom backend may still set it manually.

Sample .ini data:

[Window][Dear ImGui Demo]
Pos=147,225
Size=621,987
Collapsed=0
LastUsed=20260703

[Table][0x86C9FC97,3]
Column 0  Weight=1.0000 ID=0xCBD049FD
Column 1  Weight=1.0000 ID=0xB39C48B7
Column 2  Weight=1.0000 ID=0x07ECE4EB
LastUsed=20260702

[Table][0x95990F63,3]
RefScale=23
Column 0  Width=108 ID=0xCBD049FD
Column 1  Width=108 ID=0xB39C48B7
Column 2  Width=108 ID=0x07ECE4EB
LastUsed=20260702

Details

The general design of the feature is:

• Date footprints are 2 bytes. They are designed to be small, easy to manipulate, and easy view in debuggers.
• We intentionally only store days and not time. It is smaller, but also less noisy (e.g. you don't get constant .ini changes).
• We intentionally only store a unique "session" date. It is less noisy, arguably more synthetically useful, and reduces backend overhead (date is only polled once at init time).
• This is optional and may be disabled, although currently I am defaulting it to enabled.

In imgui_internal.h:

// [Internal] Store a date in a way that is efficient to read/write in text form. If we stored e.g. number of days since Epoch we'd need costlier back and forth.
// This is specifically designed to be able to prune old .ini data.
struct ImGuiPackedDate
{
    ImU16   Year : 7;   // Year since 2000      // We can change to another offset e.g. 1970 but this is easier to watch in debugger.
    ImU16   Month : 4;  // Month (1-12)
    ImU16   Day : 5;    // Day (1-31)

[ocornut]

There are corners cases related to storing persistent data (e.g. docking layouts) where I would expect feedback to happen. There is a (yet internal) CleanupIniSettings(ImGuiSettingsCleanupArgs* args) function that provide tools to e.g. mark data as current if needed. So if you have eviction policies you may want to load your .ini templates and apply current date to them.

From my own records and for discovery, here's code that use the internal Cleanup helper to discard table .ini settings that are missing a last used date. ImGuiSettingsCleanupArgs contains other tools.

ImGui::Begin("Test #9460");
ImGui::BeginTable("#BLAH", 3, ImGuiTableFlags_Reorderable | ImGuiTableFlags_Resizable | ImGuiTableFlags_Hideable | ImGuiTableFlags_Sortable);
ImGui::TableSetupColumn("One");
ImGui::TableSetupColumn("Two");
ImGui::TableSetupColumn("Three");
ImGui::TableHeadersRow();
ImGui::EndTable();

if (ImGui::Shortcut(ImGuiKey_F1))
{
    ImGui::LoadIniSettingsFromDisk("imgui.ini");
    ImGuiSettingsCleanupArgs cleanup_args;
    cleanup_args.TypeHashFilter = ImHashStr("Table");
    cleanup_args.DiscardWhenMissingDate = true;
    ImGui::CleanupIniSettings(&cleanup_args);
}
ImGui::End();

[ocornut]

Just came up with a thought, writing it down here: it may be interesting when running "discard old data" pass to use a threshold dynamically set based on the last known session date.