Parameters

Options

Optional Arguments

Description

This widget arranges its push button child widgets according to the current button order.

The button order depends on what UI is used and (optionally) what desktop environment the UI currently runs in.

The Qt and NCurses UIs use the KDE / Windows button order:

[OK] [Apply] [Cancel] [Custom1] [Custom2] ... [Help]

[Continue] [Cancel]

[Yes] [No]

The Gtk UI uses the GNOME / MacOS button order:

[Help] [Custom1] [Custom2] ... [Apply] [Cancel] [OK]

[Cancel] [Continue]

[No] [Yes]

Certain buttons have a predefined role:

- okButton: Positive confirmation: Use the values from the dialog to do whatever the dialog is all about and close the dialog.

- applyButton: Use the values from the dialog, but leave the dialog open.

- cancelButton: Discard all changes and close the dialog.

- helpButton: Show help for this dialog.

In a [Continue] [Cancel] dialog, [Continue] has the okButton role. In a [Yes] [No] dialog, [Yes] has the okButton role, [No] has the cancelButton role.

The UI automatically recognizes standard button labels and assigns the proper role. This is done very much like assigning function keys (see UI::SetFunctionKeys()). The UI also has some built-in heuristics to recognize standard button IDs like `id(`ok), `id("ok"), `id(`yes), etc.

Sometimes it makes sense to use something like [Print] or [Delete] for the okButton role if printing or deleting is what the respective dialog is all about. In that case, the application has to explicitly specify that button role: Use `opt(`okButton).

Similarly, there are `opt(`cancelButton), `opt(`applyButton), `opt(`helpButton).

By default, a ButtonBox with more than one button is required to have one okButton and one cancelButton. `opt(`relaxSanityCheck) relaxes those requirements: It does not check for one okButton and one cancelButton. This should be used very sparingly -- use your common sense. One Example where this is legitimate is a pop-up dialog with [OK] [Details] for error messages that can be explained in more detail. Most dialogs with more than just an [OK] or a [Close] button should have a [Cancel] button.

ButtonBox widgets can have no other child widgets than PushButton widgets. ButtonBox widgets are horizontally stretchable and vertically non-stretchable. If there is more space, their layout policy (depending on KDE or GNOME button order) specifies whether to center or right-align the buttons.

Usage

 	`ButtonBox(`PushButton( `id( `ok ), "OK" ), `PushButton( `id( `cancel ), "Cancel" ) )
 

Examples

          // Example for ButtonBox
{
    UI::OpenDialog(`VBox(
			 `HVCenter(
				   `Label( "Hello, world!" )
				   ),
			 `ButtonBox(
				    `PushButton(`id(`doit1), "Do &Something Very Cool" ),
				    `PushButton(`id(`doit2), `opt(`key_F10, `customButton), "Do &More" ),
				    `PushButton(`id(`help), "&Help" ),
				    `PushButton(`id(`ok), "&OK" ),
				    `PushButton(`id(`cancel), "&Cancel" ),
				    `PushButton(`id(`apply), "&Apply" )
				    )
			 )
		   );
    UI::UserInput();
    UI::CloseDialog();
}