imgui_data_loader

A configurable file / folder open dialog widget in python

install · quick start · examples · configuration · issues

The full example — a source selector, a two-column action grid, and a formats panel.

About

Built on imgui-file-dialog and imgui-bundle. It gives you:

• a small, styled launcher window — your title, help/info content, and buttons that open the OS-native picker (via portable_file_dialogs)
• configurable buttons — open a file, many files, a folder, or save
• customizable file-type filters, theme, an info card, and an options popup
• one-shot use that returns the picked path, or embed it as a panel in a larger app

What you can do with imgui is endless, I often take inspiration from this list of imgui examples.

Install

imgui_data_loader is on PyPI:

pip install imgui_data_loader

The only dependency is imgui-bundle (which provides imgui, hello_imgui, immapp, portable_file_dialogs and the FontAwesome icon font).

Quick start

from imgui_data_loader import run_file_dialog, FileDialogConfig

result = run_file_dialog(FileDialogConfig())   # default Open File(s) / Select Folder

if result:                      # truthy only for a real selection
    print(result.paths)         # list[str]
    print(result.path)          # first path, or None
else:
    print("cancelled")

run_file_dialog opens the window, blocks until the user picks something or quits, and returns a DialogResult.

Examples

See all examples in examples/.

name	file	preview
dialog_minimal	dialog_minimal.py
dialog_full_example	dialog_full_example.py
dialog_themes	dialog_themes.py

Configuration reference

FileDialogConfig fields:

Draw slots

header_draw, top_draw, info, body_draw, options_draw, and footer_draw let you render your own content in specific regions — the header block, a row above the buttons, the info card, a full-width area under the card, the options popup, and the footer. The footer stays at the bottom of the window; everything above it scrolls when it outgrows the window. Each runs inside a live imgui frame, so any widget bundled with imgui-bundle works: animated toggles, rotary knobs, spinners, markdown, command palettes, cool bars, and the rest. Pair them with the library's themed helpers (center_text, icon_button, push_button_style, …) and dlg.theme so your additions match the dialog's styling.

Files on disk

Everything the library writes lives under one dot directory, ~/.imgui_data_loader/ (override the location with the IMGUI_DATA_LOADER_HOME env var):

Assets resolution: the dialog needs FontAwesome 6 (fonts/Font_Awesome_6_Free-Solid-900.otf) for its icons. ensure_assets() never replaces an assets folder your app already configured — if the font resolves, nothing is touched; otherwise ~/.imgui_data_loader/assets and then imgui-bundle's bundled assets are added as search paths. Passing config.assets_folder explicitly does set the assets folder to that path.

Embedding apps with their own app dir (e.g. one that keeps everything under ~/.myapp) should point both knobs there: config.ini_path for the layout file and a custom PreferenceStore (or JsonPreferenceStore(path=...)) for recents — nothing then touches ~/.imgui_data_loader.

Notes

• Buttons open the OS-native dialog, so a desktop session is required (no in-window file browser).
• Icons come from FontAwesome 6 (Solid only), which ships inside imgui-bundle; a few non-solid glyphs render as a blank box — pick a solid icon if one shows empty.
• Draw callbacks run inside an active imgui frame — only call imgui from them.

Acknowledgements

This dialog started life inside mbo_utilities at the Miller Brain Observatory, where the original file/folder loader was built.

License

MIT