ImGuiFileDialog

Build Matrix

	Win	Linux	MacOs
Msvc
Gcc
Clang
Leak Sanitizer

Purpose

ImGuiFileDialog is a file selection dialog built for (and using only) Dear ImGui.

My primary goal was to have a custom pane with widgets according to file extension. This was not possible using other solutions.

Possible Dialog Customization

ImGui Supported Version

Note

ImGuiFileDialog follow the master and docking branch of ImGui. Currently :

Documentation :

Note

for a complete explanation and howto about ImGuiFileDialog Api, you can check the Documentation

Structure

• The library is in Master branch
• A demo app can be found in the DemoApp branch

This library is designed to be dropped into your source code rather than compiled separately.

From your project directory:

mkdir lib    <or 3rdparty, or externals, etc.>
cd lib
git clone https://github.com/aiekick/ImGuiFileDialog.git
git checkout master

These commands create a lib directory where you can store any third-party dependencies used in your project, downloads the ImGuiFileDialog git repository and checks out the Lib_Only branch where the actual library code is located.

Add lib/ImGuiFileDialog/ImGuiFileDialog.cpp to your build system and include lib/ImGuiFileDialog/ImGuiFileDialog.h in your source code. ImGuiFileLib will compile with and be included directly in your executable file.

If, for example, your project uses cmake, look for a line like add_executable(my_project_name main.cpp) and change it to add_executable(my_project_name lib/ImGuiFileDialog/ImGuiFileDialog.cpp main.cpp). This tells the compiler where to find the source code declared in ImGuiFileDialog.h which you included in your own source code.

Requirements:

You must also, of course, have added Dear ImGui to your project for this to work at all.

dirent v1.23 is required to use ImGuiFileDialog under Windows. It is included in the Lib_Only branch for your convenience.

Android Requirements : Api 21 mini

Features

• C Api (succesfully tested with CimGui)
• Separate system for call and display
  • Can have many function calls with different parameters for one display function, for example
• Can create a custom pane with any widgets via function binding
  • This pane can block the validation of the dialog
  • Can also display different things according to current filter and UserDatas
• Advanced file style for file/dir/link coloring / icons / font
  • predefined form or user custom form by lambda function (the lambda mode is not available for the C API)
• Multi-selection (ctrl/shift + click) :
  • 0 => Infinite
  • 1 => One file (default)
  • n => n files
• Compatible with MacOs, Linux, Windows, Emscripten, Android
• Supports modal or standard dialog types
• Select files or directories
• Filter groups and custom filter names
• can ignore filter Case for file searching
• Keyboard navigation (arrows, backspace, enter)
• Exploring by entering characters (case insensitive)
• Custom places (bookmarks, system devices, whatever you want)
• Directory manual entry (right click on any path element)
• Optional 'Confirm to Overwrite" dialog if file exists
• Thumbnails Display (agnostic way for compatibility with any backend, sucessfully tested with OpenGl and Vulkan)
• The dialog can be embedded in another user frame than the standard or modal dialog
• Can tune validation buttons (placements, widths, inversion)
• Can quick select a parrallel directory of a path, in the path composer (when you clikc on a / you have a popup)
• regex support for filters, collection of filters and filestyle (the regex is recognized when between (( and )) in a filter)
• multi layer extentions like : .a.b.c .json.cpp .vcxproj.filters etc..
• advanced behavior regarding asterisk based filter. like : .* .. .vcx.* ..filters .vcs.filt.* etc.. (internally regex is used)
• result modes GetFilePathName, GetFileName and GetSelection (overwrite file ext, keep file, add ext if no user ext exist)
• you can use your own FileSystem Api
  • by default Api Dirent and std::filesystem are defined
  • you can override GetDrieveList for specify by ex on android other fs, like local and SDCards

WARNINGS :

• the nav system keyboard behavior is not working as expected, so maybe full of bug for ImGuiFileDialog

Simple Usage :

void drawGui() { 
  // open Dialog Simple
  if (ImGui::Button("Open File Dialog")) {
    IGFD::FileDialogConfig config;
	config.path = ".";
    ImGuiFileDialog::Instance()->OpenDialog("ChooseFileDlgKey", "Choose File", ".cpp,.h,.hpp", config);
  }
  // display
  if (ImGuiFileDialog::Instance()->Display("ChooseFileDlgKey")) {
    if (ImGuiFileDialog::Instance()->IsOk()) { // action if OK
      std::string filePathName = ImGuiFileDialog::Instance()->GetFilePathName();
      std::string filePath = ImGuiFileDialog::Instance()->GetCurrentPath();
      // action
    }
    
    // close
    ImGuiFileDialog::Instance()->Close();
  }
}

How to build the sample app

The sample app is [here in master branch]((https://github.com/aiekick/ImGuiFileDialog/tree/master)

You need to use cMake. For the 3 Os (Win, Linux, MacOs), the cMake usage is exactly the same,

Choose a build directory. (called here my_build_directory for instance) and
Choose a Build Mode : "Release" / "MinSizeRel" / "RelWithDebInfo" / "Debug" (called here BuildMode for instance)
Run cMake in console : (the first for generate cmake build files, the second for build the binary)

cmake -B my_build_directory -DCMAKE_BUILD_TYPE=BuildMode cmake --build my_build_directory --config BuildMode

Some cMake version need Build mode define via the directive CMAKE_BUILD_TYPE or via --Config when we launch the build. This is why i put the boths possibilities

By the way you need before, to make sure, you have needed dependencies.

On Windows :

You need to have the opengl library installed

On Linux :

You need many lib : (X11, xrandr, xinerama, xcursor, mesa)

If you are on debian you can run :

sudo apt-get update sudo apt-get install libgl1-mesa-dev libx11-dev libxi-dev libxrandr-dev libxinerama-dev libxcursor-dev

On MacOs :

you need many lib : opengl and cocoa framework

Thats all folks :-)

You can check by example in this repo with the file CustomImGuiFileDialogConfig.h :

• this trick was used for have custom icon font instead of labels for buttons or messages titles
• you can also use your custom imgui button, the button call stamp must be same by the way :)

The Custom Icon Font (in CustomFont.cpp and CustomFont.h) was made with ImGuiFontStudio (https://github.com/aiekick/ImGuiFontStudio) i wrote for that :) ImGuiFontStudio is using also ImGuiFileDialog.$