Add a documentation folder.

Author: samhocevar

README.md

@@ -26,10 +26,10 @@ Experimental support for Emscripten is on its way.
 
 ## Documentation
 
-  * [Message Box API](https://github.com/samhocevar/portable-file-dialogs/issues/1)
-  * [Notification API](https://github.com/samhocevar/portable-file-dialogs/issues/2)
-  * [File Open API](https://github.com/samhocevar/portable-file-dialogs/issues/3)
-  * [Folder Selection Open API](https://github.com/samhocevar/portable-file-dialogs/issues/13)
+  * [Message Box API](doc/message.md)
+  * [Notification API](doc/notify.md)
+  * [File Open API](doc/open_file.md)
+  * [Folder Selection Open API](select_folder.md)
 
 ## Screenshots (Windows 10)
 

doc/message.md

@@ -0,0 +1,97 @@
+## Message Box API
+
+Displaying a message box is done using the `pfd::message` class. It can be provided a title, a
+message text, a `choice` representing which buttons need to be rendered, and an `icon` for the
+message:
+
+```cpp
+pfd::message::message(std::string const &title,
+                      std::string const &text,
+                      pfd::choice choice = pfd::choice::ok_cancel,
+                      pfd::icon icon = pfd::icon::info);
+
+enum class pfd::choice { ok, ok_cancel, yes_no, yes_no_cancel };
+
+enum class pfd::icon { info, warning, error, question };
+```
+
+The pressed button is queried using `pfd::message::result()`. If the dialog box is closed by any
+other means, the `pfd::button::cancel` is assumed:
+
+```cpp
+pfd::button pfd::message::result();
+
+enum class pfd::button { ok, cancel, yes, no };
+```
+
+It is possible to ask the dialog box whether the user took action using the `pfd::message::ready()`
+method, with an optional `timeout` argument. If the user did not press a button within `timeout`
+milliseconds, the function will return `false`:
+
+```cpp
+bool pfd::message::ready(int timeout = pfd::default_wait_timeout);
+```
+
+## Example 1: simple notification
+
+The `pfd::message` destructor waits for user action, so this operation will block until the user
+closes the message box:
+
+```cpp
+pfd::message("Problem", "An error occurred while doing things",
+             pfd::choice::ok, pfd::icon::error);
+```
+
+## Example 2: retrieving the pressed button
+
+Using `pfd::message::result()` will also wait for user action before returning. This operation will block and return the user choice:
+
+```cpp
+// Ask for user opinion
+auto button = pfd::message("Action requested", "Do you want to proceed with things?",
+                           pfd::choice::yes_no, pfd::icon::question).result();
+// Do something with button…
+```
+
+## Example 3: asynchronous message box
+
+Using `pfd::message::ready()` allows the application to perform other tasks while waiting for
+user input:
+
+```cpp
+// Message box with nice message
+auto box = pfd::message("Unsaved Files", "Do you want to save the current "
+                        "document before closing the application?",
+                        pfd::choice::yes_no_cancel,
+                        pfd::icon::warning);
+
+// Do something while waiting for user input
+while (!box.ready(1000))
+    std::cout << "Waited 1 second for user input...\n";
+
+// Act depending on the selected button
+switch (box.result())
+{   
+    case pfd::button::yes:    std::cout << "User agreed.\n"; break;
+    case pfd::button::no:     std::cout << "User disagreed.\n"; break;
+    case pfd::button::cancel: std::cout << "User freaked out.\n"; break;
+}   
+```
+
+## Screenshots
+
+Windows 10:
+![warning-win32](https://user-images.githubusercontent.com/245089/47136607-76919a00-d2b4-11e8-8f42-e2d62c4f9570.png)
+
+Mac OS X (dark theme):
+![warning-osx-dark](https://user-images.githubusercontent.com/245089/56053001-22dba700-5d53-11e9-8233-ca7a2c58188d.png)
+
+Mac OS X (light theme):
+![warning-osx-light](https://user-images.githubusercontent.com/245089/56053055-49014700-5d53-11e9-8306-e9a03a25e044.png)
+
+Linux (GNOME desktop):
+![warning-gnome](https://user-images.githubusercontent.com/245089/47140824-8662ab80-d2bf-11e8-9c87-2742dd5b58af.png)
+
+Linux (KDE desktop):
+![warning-kde](https://user-images.githubusercontent.com/245089/47149255-4dcccd00-d2d3-11e8-84c9-f85612784680.png)
+

doc/notify.md

@@ -0,0 +1,41 @@
+## Notification API
+
+Displaying a desktop notification is done using the `pfd::notify` class. It can be provided a
+title, a message text, and an `icon` for the notification style:
+
+```cpp
+pfd::notify::notify(std::string const &title,
+                    std::string const &text,
+                    pfd::icon icon = pfd::icon::info);
+
+enum class pfd::icon { info, warning, error };
+```
+
+## Example
+
+Displaying a notification is straightforward. Emoji are supported:
+
+```cpp
+pfd::notify("System event", "Something might be on fire 🔥",
+            pfd::icon::warning);
+```
+
+The `pfd::notify` object needs not be kept around, letting the object clean up itself is enough.
+
+## Screenshots
+
+Windows 10:
+![notify-win32](https://user-images.githubusercontent.com/245089/47142453-2ff76c00-d2c3-11e8-871a-1a110ac91eb2.png)
+
+Mac OS X (dark theme):
+![image](https://user-images.githubusercontent.com/245089/56053188-bc0abd80-5d53-11e9-8298-68aa96315c6c.png)
+
+Mac OS X (light theme):
+![image](https://user-images.githubusercontent.com/245089/56053137-92ea2d00-5d53-11e9-8cf2-049486c45713.png)
+
+Linux (GNOME desktop):
+![notify-gnome](https://user-images.githubusercontent.com/245089/47142455-30900280-d2c3-11e8-8b76-ea16c7e502d4.png)
+
+Linux (KDE desktop):
+![notify-kde](https://user-images.githubusercontent.com/245089/47149206-27a72d00-d2d3-11e8-8f1b-96e462f08c2b.png)
+

doc/open_file.md

@@ -0,0 +1,89 @@
+## File Open API
+
+The `pfd::open_file` class handles file opening dialogs. It can be provided a title, a starting
+directory and/or pre-selected file, an optional filter for recognised file types, and an optional
+flag to allow multiple selection:
+
+```cpp
+pfd::open_file::open_file(std::string const &title,
+                          std::string const &initial_path,
+                          std::vector<std::string> filters = { "All Files", "*" },
+                          bool allow_multiselect = false);
+```
+
+The selected files are queried using `pfd::open_file::result()`. If the user canceled the
+operation, the returned list is empty:
+
+```cpp
+std::vector<std::string> pfd::open_file::result();
+```
+
+It is possible to ask the file open dialog whether the user took action using the
+`pfd::message::ready()` method, with an optional `timeout` argument. If the user did not validate
+the dialog within `timeout` milliseconds, the function will return `false`:
+
+```cpp
+bool pfd::open_file::ready(int timeout = pfd::default_wait_timeout);
+```
+
+## Example 1: simple file selection
+
+Using `pfd::open_file::result()` will wait for user action before returning. This operation will
+block and return the user choice:
+
+```cpp
+auto selection = pfd::open_file("Select a file").result();
+if (!selection.empty())
+    std::cout << "User selected file " << selection[0] << "\n";
+```
+
+## Example 2: filters
+
+The filter list enumerates filter names and corresponded space-separated wildcard lists. It
+defaults to `{ "All Files", "*" }`, but here is how to use other options:
+
+```cpp
+auto selection = pfd::open_file("Select a file", ".",
+                                { "Image Files", "*.png *.jpg *.jpeg *.bmp",
+                                  "Audio Files", "*.wav *.mp3",
+                                  "All Files", "*" },
+                                true).result();
+// Do something with selection
+for (auto const &filename : dialog.result())
+    std::cout << "Selected file: " << filename << "\n";
+```
+
+## Example 3: asynchronous file open
+
+Using `pfd::open_file::ready()` allows the application to perform other tasks while waiting for
+user input:
+
+```cpp
+// File open dialog
+auto dialog = pfd::open_file("Select file to open");
+
+// Do something while waiting for user input
+while (!dialog.ready(1000))
+    std::cout << "Waited 1 second for user input...\n";
+
+// Act depending on the user choice
+std::cout << "Number of selected files: " << dialog.result().size() << "\n";
+```
+
+## Screenshots
+
+Windows 10:
+![open-win32](https://user-images.githubusercontent.com/245089/47155865-0f8cd900-d2e6-11e8-8041-1e20b6f77dee.png)
+
+Mac OS X (dark theme):
+![image](https://user-images.githubusercontent.com/245089/56053378-39363280-5d54-11e9-9583-9f1c978fa0db.png)
+
+Mac OS X (light theme):
+![image](https://user-images.githubusercontent.com/245089/56053413-4fdc8980-5d54-11e9-85e3-e9e5d0e10772.png)
+
+Linux (GNOME desktop):
+![open-gnome](https://user-images.githubusercontent.com/245089/47155867-0f8cd900-d2e6-11e8-93af-275636491ec4.png)
+
+Linux (KDE desktop):
+![open-kde](https://user-images.githubusercontent.com/245089/47155866-0f8cd900-d2e6-11e8-8006-f14b948afc55.png)
+

doc/select_folder.md

@@ -0,0 +1,51 @@
+## Folder Selection API
+
+The `pfd::select_folder` class handles folder opening dialogs. It can be provided a title, and an
+optional starting directory:
+
+```cpp
+pfd::select_folder::select_folder(std::string const &title,
+                                  std::string const &default_path = "");
+```
+
+The selected folder is queried using `pfd::select_folder::result()`. If the user canceled the
+operation, the returned string is empty:
+
+```cpp
+std::string pfd::select_folder::result();
+```
+
+It is possible to ask the folder selection dialog whether the user took action using the
+`pfd::message::ready()` method, with an optional `timeout` argument. If the user did not validate
+the dialog within `timeout` milliseconds, the function will return `false`:
+
+```cpp
+bool pfd::select_folder::ready(int timeout = pfd::default_wait_timeout);
+```
+
+## Example 1: simple folder selection
+
+Using `pfd::select_folder::result()` will wait for user action before returning. This operation
+will block and return the user choice:
+
+```cpp
+auto selection = pfd::select_folder("Select a folder").result();
+if (!selection.empty())
+    std::cout << "User selected folder " << selection << "\n";
+```
+
+## Example 2: asynchronous folder open
+
+Using `pfd::select_folder::ready()` allows the application to perform other tasks while waiting for user input:
+
+```cpp
+// Folder selection dialog
+auto dialog = pfd::select_folder("Select folder to open");
+
+// Do something while waiting for user input
+while (!dialog.ready(1000))
+    std::cout << "Waited 1 second for user input...\n";
+
+// Act depending on the user choice
+std::cout << "Selected folder: " << dialog.result() << "\n";
+```