# Dialog definitions¶

Dialogs can be defined with Dialog definitions inside the extension's XML.

See Using Dialogs in Java Code below for information on how to access those dialogs in Java.

The definition of dialogs can be done in a mf:dialogs block inside a property file:

<mf:dialogs>
...
</mf:dialogs>


## Defining a Dialog¶

Each dialog is identified by an unique number ID allowing to reference them on Java side and to overwrite them in other extensions. Each dialog must be defined inside an own mf:dialog block.

The following properties apply to all dialogs:

### Type¶

The dialog type affects the default icon and the default title.
Possible values are:
• "info"
• "warn"
• "question"
• "error"

### Title¶

Every dialog has a default title depending on the dialog type. Setting the title explicitly can be done with the property title. Values can be either real texts or message keys.

### Text¶

The default text for dialogs is empty. Setting the text explicitly can be done with the property text. Values can be either real texts or message keys.

### Modality¶

Per default all dialogs are modal, i.e. the invoking thread is halted unless the dialog will be closed. This behaviour can be changed with the modal property whose value must be either true or false.

### Class¶

Every dialog is an instance of net.mumie.mathletfactory.appletskeleton.util.dialog.DefaultDialog unless the class property is set. Its value must be an existing fully qualified Java class.

### Examples¶

Example of an error dialog using a text referenced by a message key:

<mf:dialog id="3" type="error" text="runtime.newer_java_version_needed">
...
</mf:dialog>


Example of an info dialog with a text and a title referenced by message keys:

<mf:dialog id="53" type="info" text="exercise.saving_successful.remote"
title="exercise.saving_successful.title">
...
</mf:dialog>


Example of an info dialog referencing a custom dialog class:

<mf:dialog id="1" type="info" title="About"
...
</mf:dialog>


## Defining Dialog Actions¶

A dialog action is expressed by buttons reflecting each a certain action. The action can be requested on Java side if necessary. Actions must be defined with a mf:action block and can only be used inside mf:dialog blocks.

### Action Type¶

The action type affects the default button text and the dialog's default visibility upon hiting the button.

Possible values for action types and their corresponding (English) default texts are:
• approve - "Approve"
• cancel - "Cancel"
• close - "Close"
• ignore - "Ignore"
• retry - "Retry"
• apply - "Apply"
• none - user defined action

### Action Text¶

The default action text can be replaced with the text property. Values can be either real texts or message keys.

### Dialog Visibility¶

Per default dialogs will be closed upon hiting an action button. This behaviour can be controlled with the hide property whose value must be either true or false.

### Examples¶

Example of a simple "Close" action:

<mf:dialog ...>
<mf:action type="close"/>
</mf:dialog>


Example of two actions, the first has a custom text:

<mf:dialog ...>
<mf:action type="approve" text="exercise.view_receipt"/>
<mf:action type="close"/>
</mf:dialog>


## Using Dialogs in Java Code¶

The mathlet's basic interface MathletUIContext offers the method showDialog(int dialogID, Object[] params) returning the selected action as an instance of DialogAction. The first parameter is the dialog ID, the second one is an optional list of parameters for the dialog. This is especially useful when creating custom dialogs with dynamic content. The optional parameters may be null.\\
Note that the method showDialog returns null if the user did not select an option but closed the dialog via one of the closing mechanisms of the windowing system (e.g. the "X" button in the title bar of the dialog).

Outside a mathlet class, dialogs can be accessed by the MathletRuntime:

MathletRuntime.getRuntime().showDialog(dialogID, params)


It is recommended to define an interface holding static references to dialog IDs (as this is done in the library by the class DialogIDIF).

### Examples¶

showDialog(DialogIDIF.EXERCISE_SAVING_SUCCESSFUL_LOCAL, null);

DialogAction action = showDialog(DialogIDIF.EXERCISE_SAVING_SUCCESSFUL_RECEIPT_RECEIVED, null);