furnace/extern/pfd-fixed/doc/message.md at master

3.3 KiB

Raw Permalink Blame History

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:

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:

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:

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:

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:

// 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:

// 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;
}