Update 5.md

Author: gammasoft71

docs/documentation/tips_and_tricks/5.md

@@ -1,6 +1,6 @@
 # Getting special folders (🟢 Beginner)
 
-How to get special folders such : Home, Desktop, Program Files, ...
+Quickly get the paths to your user’s Desktop, Home, or Program Files folder—cross-platform, in just a few lines of code!
 
 ## Win32
 
@@ -30,7 +30,7 @@ std::string get_known_folder_path(int id) {
 }
 
 auto main() -> int {
-  std::println("Desktop path = \"{}\"", get_known_folder_path(CSIDL_DESKTOP));
+  std::println("Desktop = \"{}\"", get_known_folder_path(CSIDL_DESKTOP));
   std::println("Program Files = \"{}\"", get_known_folder_path(CSIDL_PROGRAM_FILES));
   std::println("Home = \"{}\"", get_known_folder_path(CSIDL_HOME));
 }
@@ -39,34 +39,129 @@ auto main() -> int {
 ```cpp
 // This code can produce the following output:
 //
-// Desktop path = "C:\Users\gammasoft71\Desktop"
+// Desktop = "C:\Users\gammasoft71\Desktop"
 // Program Files = "C:\Program Files"
 // Home = "C:\Users\gammasoft71"
 ```
 
-*	La method `get_environment_variable ` retourne la valeur pour une variable d'environment donnée.
-*	La method `get_known_folder_path` retourne le path pour une valeur CSIDL donnée.
+* This Win32 example demonstrates how to retrieve special folders by using system APIs.  
+* For standard folders like Desktop or Program Files, we use `SHGetFolderPath`.  
+* For Home, which doesn’t have a standard CSIDL, we construct the path from environment variables.
 
 ## Qt
 
 ```cpp
+#include <QApplication>
+#include <QStandardPaths>
+#include <QString>
+#include <QDebug>
 
+#if defined(Q_OS_WIN)
+#include <shlobj.h>
+#pragma comment(lib, "shell32.lib")
+#endif
+
+QTextStream& qCout() {
+  static auto ts = QTextStream {stdout};
+  return ts;
+}
+
+QString programFilesPath() {
+#if defined(Q_OS_WIN)
+  auto path = std::string(MAX_PATH, '\0');
+  if (SHGetFolderPath(nullptr, CSIDL_PROGRAM_FILES, nullptr, SHGFP_TYPE_CURRENT, path.data()) != S_OK)
+    throw std::runtime_error("Failed to get known folder path");
+  return path.substr(0, path.find('\0'));
+#elif defined(Q_OS_MAC)
+  return "/Applications";
+#else
+  return QDir("/opt").exists() ? "/opt" : "/usr/local";
+#endif
+}
+
+auto main(int argc, char* argv[]) -> int {
+  auto application = QApplication {argc, argv};
+  
+  qCout() << "Desktop = \"" << QStandardPaths::writableLocation(QStandardPaths::DesktopLocation) << "\"" << Qt::endl;
+  qCout() << "Program Files = \"" << programFilesPath() << "\"" << Qt::endl;
+  qCout() << "Home = \"" << QStandardPaths::writableLocation(QStandardPaths::HomeLocation) << "\"" << Qt::endl;
+}
+```
+
+```cpp
+// This code can produce the following output:
+//
+// Desktop = "C:\Users\gammasoft71\Desktop"
+// Program Files = "C:\Program Files"
+// Home = "C:\Users\gammasoft71"
+```
+
+*	This Qt example shows how to get special folders using the built-in `QStandardPaths` for Home and Desktop.  
+* For Program Files, we still rely on a system call (`SHGetFolderPath`) on Windows, while macOS and Linux use conventional paths.  
+* It illustrates that Qt simplifies some folders but isn’t fully unified across all platforms.
+
+## xtd
+
+```cpp
+#include <xtd/xtd>
+
+auto main() -> int {
+  console::write_line("Desktop = {}", environment::get_folder_path(environment::special_folder::desktop).quoted());
+  console::write_line("Program Files = {}", environment::get_folder_path(environment::special_folder::program_files).quoted());
+  console::write_line("Home = {}", environment::get_folder_path(environment::special_folder::home).quoted());
+}
 ```
 
 ```cpp
 // This code can produce the following output:
 //
+// Desktop = "C:\Users\gammasoft71\Desktop"
+// Program Files = "C:\Program Files"
+// Home = "C:\Users\gammasoft71"
 ```
 
+*	This xtd example demonstrates how to retrieve special folders in a fully cross-platform way.  
+* With just three lines of code, we can get Desktop, Home, or Program Files without any platform-specific calls or `#ifdef` logic.  
+* It highlights xtd’s simplicity and unified API compared to Win32 and Qt.
+
 ## Conclusion
 
+Whether you use Win32, Qt or xtd, it is always possible to get the special folders. 
+The main difference lies in:
+*	Win32 : verbose, sometimes deprecated API, manual management of special cases (such as Home).
+*	Qt : simplifies some folders (Home, Desktop) but still requires system calls for others (Program Files).
+*	Xtd : unified, cross-platform, clear and readable approach, without #ifdef or explicit native calls.
+
+With xtd, the focus is on the essentials: writing code that works everywhere, without worrying about the implementation details specific to each OS.
 
 > **Did you know?**
 >
-> 
+> *	On Windows, the `Program Files` folder can change depending on the system language or if the user has moved it.
+> *	On macOS, the concept of `Program Files` does not exist: the convention wants applications to be in `/Applications`.
+> *	On Linux, there is no strict equivalent: `/opt` and `/usr/local` are often used for third-party applications.
+> *	[xtd::environment::get_folder_path](https://gammasoft71.github.io/xtd/reference_guides/latest/classxtd_1_1environment.html#a465e71972e122d4bbdaa943ae02d4cd8) automatically manages these particularities according to the platform.
 
 ## To go further
 
+*	See [xtd::environment::special_folder](https://gammasoft71.github.io/xtd/reference_guides/latest/classxtd_1_1environment.html#a2fb2b59eded52f8745b88b44ae9e7057) documentation.
+*	The following code shows how to simple combine path with special folder using [xtd::io::path::combine](https://gammasoft71.github.io/xtd/reference_guides/latest/classxtd_1_1io_1_1path.html#ae64bf12dad2f160ad85a951b9d011023) :
+
+```cpp
+#include <xtd/xtd>
+
+auto main() -> int {
+  console::write_line("My target file = {}", path::combine(environment::get_folder_path(environment::special_folder::home), "MyAppData", "settings.txt").quoted());
+}
+
+// This code can produce the following output on Windows:
+// My target file = "C:\Users\gammasoft71\MyAppData\settings.txt"
+//
+// This code can produce the following output on macOS:
+// My target file = "/Users/gammasoft71/MyAppData/settings.txt"
+//
+// This code can produce the following output on Linux:
+// My target file = "/home/gammasoft71/MyAppData/settings.txt"
+```
 
 ## See also