Chapter 29. Dialogs

Chapter 29. Dialogs
Prev	Part I. Tutorial	Next

Index

Dialog identifiers and configuration settings
Other dialog creation parameters
Standard dialog callbacks
File dialogs
Showing and hiding dialogs
Modal dialogs
x::w::main_windows own references on their dialogs
Custom dialogs
Ad-hoc error message dialogs

menu.C from Chapter 24, Menus also demonstrates how to create dialogs. Dialogs are stand-alone, top level windows, represented by x::w::dialog objects.

An x::w::dialog is similar to an x::w::main_window, except that it doesn't have menus and some window managers may not draw a title bar for the dialog. In most other respects a dialog is the same as a main window, and one of its public class members is a:

const x::w::main_window dialog_window;

So, “dialog->dialog_window->show_all()” shows the dialog, and “dialog->dialog_window->show_all()” hides it.

Another difference between dialogs and main windows is while x::w::main_windows get created by themselves, x::w::dialogs get created by one of the methods from an existing x::w::main_window or another x::w::dialog (by accessing its dialog_window).

The following x::w::main_window methods create dialogs with a standard, theme-defined layout:

create_ok_dialog(): create_ok_dialog() returns a new x::w::dialog with an icon, a text label, and an “Ok” button.
create_ok_cancel_dialog(): create_ok_cancel_dialog() returns a new x::w::dialog with an icon, a text label, and “Ok” and “Cancel” buttons.
create_input_dialog(): create_input_dialog() returns a new x::w::input_dialog with an icon, a text label, an x::w::input_field, and “Ok” and “Cancel” buttons.
create_file_dialog(): create_file_dialog() returns a new x::w::file_dialog which implements a basic interface for selecting a file to open or create.

Dialog identifiers and configuration settings

These methods have several common parameters. The first parameter is either an x::w::create_dialog_args (for create_dialog() and create_custom_dialog() methods) or an x::w::standard_dialog_args (for create_ok_dialog() and other standard dialog methods), and sets the dialog identifier and the modal dialog flag.

Both x::w::create_dialog_args and x::w::standard_dialog_args are constructible from a single literal string parameter that sets the dialog's identifier, which serves as an identifying label. Each x::w::main_window (or a x::w::dialog) can create many dialogs as long as each dialog has a unique identifier label. Creating another dialog with the same identifier label replaces the existing dialog with that label.

Dialog identifiers are opaque, unique labels. For future use, dialog identifier labels should use the following naming conventions. Applications should use identifier labels formatted as Internet hostnames or E-mail addresses using domain names that belong to the application. An application developed by example.com can use “dialog1@example.com”, or “confirmation@app1.example.com”, as an example. LibCXXW's internal dialog identifiers use “@libcxx.com” to avoid application conflicts:

x::w::dialog d=main_window->create_ok_dialog("ok@example.com",
                                             "alert",
                                             []
                                             (const x::w::gridfactory &f)                                             {
                                                  //...
                                             },
                                             []
                                             (ONLY IN_THREAD,
                                              const x::w::ok_cancel_callback_args &)
                                             {
                                                 // ...
                                             });

Alternatively, to pass in the dialog configuration parameter explicitly:

x::w::create_dialog_args params{"ok@example.com"};

x::w::dialog d=main_window->create_ok_dialog(params,
                                             "alert",
                                             []
                                             (const x::w::gridfactory &f)                                             {
                                                  //...
                                             },
                                             []
                                             (ONLY IN_THREAD,
                                              const x::w::ok_cancel_callback_args &)
                                             {
                                                 // ...
                                             });

The other value in the configuration parameter is a bool that specifies whether the new dialog is a modal dialog:

x::w::dialog d=main_window->create_ok_dialog({"ok@example.com", true},
                                             "alert",
                                             []
                                             (const x::w::gridfactory &f)                                             {
                                                  //...
                                             },
                                             []
                                             (ONLY IN_THREAD,
                                              const x::w::ok_cancel_callback_args &args)
                                             {
                                                 // ...
                                             });

Additional settings in an x::w::create_dialog_args and x::w::standard_dialog_args control where the dialog opens, in relation to the main window, see the section called “Initial dialog position” for more information.

Prev	Up	Next
Ensuring visibility of widgets in a peephole	Table Of Contents	Other dialog creation parameters