[UPD] : update the doc for the new places system

Author: aiekick

ImGuiFileDialog.cpp

@@ -325,14 +325,23 @@ inline bool inRadioButton(const char* vLabel, bool vToggled) {
 #define defaultPlacePaneWith 150.0f
 #endif  // defaultPlacePaneWith
 #ifndef placesButtonString
-#define placesButtonString "Place"
+#define placesButtonString "Places"
 #endif  // placesButtonString
-#ifndef bookmarksGroupString
-#define bookmarksGroupString "Bookmarks"
-#endif  // bookmarksGroupString
 #ifndef placesButtonHelpString
-#define placesButtonHelpString "Place"
+#define placesButtonHelpString "Places"
 #endif  // placesButtonHelpString
+#ifndef placesBookmarksGroupName
+#define placesBookmarksGroupName "Bookmarks"
+#endif  // placesBookmarksName
+#ifndef placesBookmarksDisplayOrder
+#define placesBookmarksDisplayOrder 0
+#endif  // placesBookmarksDisplayOrder
+#ifndef placesDevicesGroupName
+#define placesDevicesGroupName "Devices"
+#endif  // placesDevicesGroupName
+#ifndef placesDevicesDisplayOrder
+#define placesDevicesDisplayOrder 10
+#endif  // placesDevicesDisplayOrder
 #ifndef addPlaceButtonString
 #define addPlaceButtonString "+"
 #endif  // addPlaceButtonString
@@ -2990,17 +2999,15 @@ IGFD::PlacesFeature::PlacesFeature() {
 #ifdef USE_PLACES_FEATURE
 void IGFD::PlacesFeature::m_InitPlaces(FileDialogInternal& vFileDialogInternal) {
 #ifdef USE_PLACES_BOOKMARKS
-    AddPlacesGroup(PLACE_BOOKMARKS_NAME, PLACE_BOOKMARKS_DISPLAY_ORDER, true);
+    AddPlacesGroup(placesBookmarksGroupName, placesBookmarksDisplayOrder, true);
 #endif  // USE_PLACES_BOOKMARK
 #ifdef USE_PLACES_DEVICES
-    AddPlacesGroup(PLACE_DEVICES_NAME, PLACE_DEVICES_DISPLAY_ORDER, false);
-    auto devices_ptr = GetPlacesGroupPtr(PLACE_DEVICES_NAME);
+    AddPlacesGroup(placesDevicesGroupName, placesDevicesDisplayOrder, false);
+    auto devices_ptr = GetPlacesGroupPtr(placesDevicesGroupName);
     if (devices_ptr != nullptr && vFileDialogInternal.fileManager.GetFileSystemInstance() != nullptr) {
         const auto& devices = vFileDialogInternal.fileManager.GetFileSystemInstance()->GetDevicesList();
-        IGFD::FileStyle style;
-        style.icon = PLACE_DEVICES_ICON;
         for (const auto& device : devices) {
-            devices_ptr->AddPlace(device.first + " " + device.second, device.first + IGFD::Utils::GetPathSeparator(), false, style);
+            devices_ptr->AddPlace(device.first + " " + device.second, device.first + IGFD::Utils::GetPathSeparator(), false);
         }
         devices_ptr = nullptr;
     }
@@ -3014,9 +3021,7 @@ void IGFD::PlacesFeature::m_DrawPlacesButton() {
 
 bool IGFD::PlacesFeature::m_DrawPlacesPane(FileDialogInternal& vFileDialogInternal, const ImVec2& vSize) {
     bool res = false;
-
     ImGui::BeginChild("##placespane", vSize);
-
     for (const auto& group : m_OrderedGroups) {
         auto group_ptr = group.second.lock();
         if (group_ptr != nullptr) {
@@ -3025,10 +3030,7 @@ bool IGFD::PlacesFeature::m_DrawPlacesPane(FileDialogInternal& vFileDialogIntern
                     ImGui::PushID(group_ptr.get());
                     if (IMGUI_BUTTON(addPlaceButtonString "##ImGuiFileDialogAddPlace")) {
                         if (!vFileDialogInternal.fileManager.IsComposerEmpty()) {
-                            PlaceStruct place;
-                            place.name = vFileDialogInternal.fileManager.GetBack();
-                            place.path = vFileDialogInternal.fileManager.GetCurrentPath();
-                            group_ptr->places.push_back(place);
+                            group_ptr->AddPlace(vFileDialogInternal.fileManager.GetBack(), vFileDialogInternal.fileManager.GetCurrentPath(), true);
                         }
                     }
                     if (group_ptr->selectedPlaceForEdition >= 0 && group_ptr->selectedPlaceForEdition < (int)group_ptr->places.size()) {
@@ -3039,7 +3041,6 @@ bool IGFD::PlacesFeature::m_DrawPlacesPane(FileDialogInternal& vFileDialogIntern
                                 --group_ptr->selectedPlaceForEdition;
                             }
                         }
-
                         if (group_ptr->selectedPlaceForEdition >= 0 && group_ptr->selectedPlaceForEdition < (int)group_ptr->places.size()) {
                             ImGui::SameLine();
                             ImGui::PushItemWidth(vSize.x - ImGui::GetCursorPosX());
@@ -3052,7 +3053,6 @@ bool IGFD::PlacesFeature::m_DrawPlacesPane(FileDialogInternal& vFileDialogIntern
                     ImGui::PopID();
                     ImGui::Separator();
                 }
-
                 if (!group_ptr->places.empty()) {
                     group_ptr->clipper.Begin((int)group_ptr->places.size(), ImGui::GetTextLineHeightWithSpacing());
                     while (group_ptr->clipper.Step()) {
@@ -3081,13 +3081,10 @@ bool IGFD::PlacesFeature::m_DrawPlacesPane(FileDialogInternal& vFileDialogIntern
                     }
                     group_ptr->clipper.End();
                 }
-
             }
         }
     }
-
     ImGui::EndChild();
-
     return res;
 }
 

ImGuiFileDialog.h

@@ -562,47 +562,6 @@ As you see the current item is flashed by default for 1 second. You can define t
 ```cpp
 ImGuiFileDialog::Instance()->SetFlashingAttenuationInSeconds(1.0f);
 ```
-
-################################################################
-## Places
-################################################################
-
-You can create/edit/call path place and load/save them.
-
-Activate this feature by uncommenting: `#define USE_PLACES_FEATURE` in your custom config file (CustomImGuiFileDialogConfig.h)
-
-More customization options:
-
-```cpp
-#define placesPaneWith 150.0f => width of the place pane
-#define IMGUI_TOGGLE_BUTTON ToggleButton => customize the Toggled button (button stamp must be : (const char* label,
-bool *toggle) #define placesButtonString "Place" => the text in the toggle button #define
-placesButtonHelpString "Place" => the helper text when mouse over the button #define addPlaceButtonString "+"
-=> the button for add a place #define removePlaceButtonString "-" => the button for remove the selected place
-```
-
-* You can select each place to edit the displayed name corresponding to a path
-* Double-click on the label to apply the place
-
-![place.gif](https://github.com/aiekick/ImGuiFileDialog/blob/master/doc/place.gif)
-
-You can also serialize/deserialize place (for example to load/save from/to a file):
-```cpp
-Load => ImGuiFileDialog::Instance()->DeserializePlaces(bookmarString);
-Save => std::string placesString = ImGuiFileDialog::Instance()->SerializePlaces();
-```
-(please see example code for details)
-
-you can also add/remove place by code :
-and in this case, you can also avoid serialization of code based place
-
-```cpp
-Add => ImGuiFileDialog::Instance()->AddPlace(places_name, places_path);
-Remove => ImGuiFileDialog::Instance()->RemovePlace(places_name);
-Save => std::string placesString = ImGuiFileDialog::Instance()->SerializePlaces(true); // true for prevent
-serialization of code based place
-```
-
 ################################################################
 ## Path Edition :
 ################################################################
@@ -1091,6 +1050,59 @@ vFileInfosPtr->tooltipMessage = toStr("%s : %s\n%s : %s",             //
 vFileInfosPtr->tooltipColumn  = 1;
 ```
 
+################################################################
+## Places
+################################################################
+
+the Places system is a generic way for add custom links in the left side pane
+
+you can organize them by groups
+
+The bookmarks and devices are now groups in the left side pane.
+
+for using it you need to
+```cpp
+#define USE_PLACES_FEATURE
+
+// for have default bookmark editable groups
+#define USE_PLACES_BOOKMARKS
+
+// for have default groups for system devices (returned by the IFileSystem interface)
+#define USE_PLACES_DEVICES
+```
+
+see the config file for more customization
+
+you can also add your custom groups editable or not like what is done
+the DemoApp branch with the "quick access" paths of win10
+
+You must add a group first, then add a place to it :
+
+```cpp
+// you must add a group first, specifu display order, and say if the user can add or remove palce like (bookmarks)
+ImGuiFileDialog::Instance()->AddPlacesGroup(group_name, display_order, can_be_user_edited);
+// then you must get the group
+auto places_ptr = ImGuiFileDialog::Instance()->GetPlacesGroupPtr(group_name);
+if (places_ptr != nullptr) {
+    // then add a place to the group
+    // you msut specify the place name, the palce path, say if the palce can be serialized, and sepcify the style
+    // for the moment the style support only the icon, can be extended if user needed in futur
+    places_ptr->AddPlace(place_name, place_path, can_be_saved, style);
+}
+```
+
+for editable group :
+* You can select each place to edit the displayed name corresponding to a path
+* Double-click on the label to apply the place
+
+You can also serialize/deserialize groups and places (for example to load/save from/to a file):
+```cpp
+Load => ImGuiFileDialog::Instance()->DeserializePlaces(placesString);
+Save => std::string placesString = ImGuiFileDialog::Instance()->SerializePlaces();
+```
+
+(please see DemoApp branch for details)
+
 ################################################################
 ## How to Integrate ImGuiFileDialog in your project
 ################################################################

ImGuiFileDialogConfig.h

@@ -130,6 +130,17 @@
 //#define placesPaneWith 150.0f
 //#define IMGUI_TOGGLE_BUTTON ToggleButton
 //#define placesButtonString "Place"
-//#define placesButtonHelpString "Place"
+//#define placesButtonHelpString "Places"
 //#define addPlaceButtonString "+"
 //#define removePlaceButtonString "-"
+
+// a group for bookmarks will be added by default, but you can also create it yourself and many more
+// #define USE_PLACES_BOOKMARKS
+// #define PLACE_BOOKMARKS_NAME "Bookmarks"
+// #define PLACE_BOOKMARKS_DISPLAY_ORDER 0  // to the first
+
+// a group for system devices (returned by IFileSystem), but you can also add yours
+// #define USE_PLACES_DEVICES
+// #define PLACE_DEVICES_NAME "Devices"
+// #define PLACE_DEVICES_DISPLAY_ORDER 10  // to the end
+// #define PLACE_DEVICES_ICON ""

README.md

@@ -493,47 +493,58 @@ ImGuiFileDialog::Instance()->SetFlashingAttenuationInSeconds(1.0f);
 
 </blockquote></details>
 
-<details open><summary><h2>Bookmarks :</h2></summary><blockquote>
+<details open><summary><h2>Places :</h2></summary><blockquote>
 
-You can create/edit/call path bookmarks and load/save them.
+the Places system is a generic way for add custom links in the left side pane
 
-Activate this feature by uncommenting: `#define USE_BOOKMARK` in your custom config file (CustomImGuiFileDialogConfig.h)
+you can organize them by groups
 
-More customization options:
+The bookmarks and devices are now groups in the left side pane.
 
+for using it you need to 
 ```cpp
-#define bookmarkPaneWith 150.0f => width of the bookmark pane
-#define IMGUI_TOGGLE_BUTTON ToggleButton => customize the Toggled button (button stamp must be : (const char* label, bool *toggle)
-#define bookmarksButtonString "Bookmark" => the text in the toggle button
-#define bookmarksButtonHelpString "Bookmark" => the helper text when mouse over the button
-#define addBookmarkButtonString "+" => the button for add a bookmark
-#define removeBookmarkButtonString "-" => the button for remove the selected bookmark
+#define USE_PLACES_FEATURE 
+
+// for have default bookmark editable groups
+#define USE_PLACES_BOOKMARKS
+
+// for have default groups for system devices (returned by the IFileSystem interface)
+#define USE_PLACES_DEVICES
 ```
 
-* You can select each bookmark to edit the displayed name corresponding to a path
-* Double-click on the label to apply the bookmark
+see the config file for more customization
+
+you can also add your custom groups editable or not like what is done 
+the DemoApp branch with the "quick access" paths of win10
 
-![bookmarks.gif](https://github.com/aiekick/ImGuiFileDialog/blob/DemoApp/doc/bookmarks.gif)
+You must add a group first, then add a place to it :
 
-You can also serialize/deserialize bookmarks (for example to load/save from/to a file):
 ```cpp
-Load => ImGuiFileDialog::Instance()->DeserializeBookmarks(bookmarString);
-Save => std::string bookmarkString = ImGuiFileDialog::Instance()->SerializeBookmarks();
+// you must add a group first, specifu display order, and say if the user can add or remove palce like (bookmarks)
+ImGuiFileDialog::Instance()->AddPlacesGroup(group_name, display_order, can_be_user_edited);
+// then you must get the group
+auto places_ptr = ImGuiFileDialog::Instance()->GetPlacesGroupPtr(group_name);
+if (places_ptr != nullptr) {
+	// then add a place to the group
+	// you msut specify the place name, the palce path, say if the palce can be serialized, and sepcify the style
+	// for the moment the style support only the icon, can be extended if user needed in futur
+	places_ptr->AddPlace(place_name, place_path, can_be_saved, style);     
+}
 ```
 
-you can also add/remove bookmark by code :
+for editable group :
+* You can select each place to edit the displayed name corresponding to a path
+* Double-click on the label to apply the place
 
-and in this case, you can also avoid serialization of code based bookmark
+![places.gif](https://github.com/aiekick/ImGuiFileDialog/blob/DemoApp/doc/places.gif)
 
+You can also serialize/deserialize groups and places (for example to load/save from/to a file):
 ```cpp
-Add => ImGuiFileDialog::Instance()->AddBookmark(bookmark_name, bookmark_path);
-Remove => ImGuiFileDialog::Instance()->RemoveBookmark(bookmark_name);
-
-// true for prevent serialization of code based bookmarks
-Save => std::string bookmarkString = ImGuiFileDialog::Instance()->SerializeBookmarks(true);
+Load => ImGuiFileDialog::Instance()->DeserializePlaces(placesString);
+Save => std::string placesString = ImGuiFileDialog::Instance()->SerializePlaces();
 ```
 
-(please see example code for details)
+(please see DemoApp branch for details)
 
 </blockquote></details>