.. _Custom Dialogs:

Custom Dialogs
==============


You can easily create your own dialogs or wizards and integrate them with scripts and flows using DVT Custom Dialogs.

**Create a Dialog**

A Custom Dialog is defined in a file with the **.swtxml** extension (see #1 below) using :ref:`SWT/XML Syntax <SWT/XML Reference>`. To simplify dialog creation, DVT includes:

- a **SWT/XML Editor** (highlight, structure, autocomplete by Ctrl+Space ...) (see #2 below)
- a **SWT/XML Preview View** for previewing the edited dialog (see #3 below)

.. figure:: ../../images/common/dvt-customdialogs-editor-preview.png
    :align: center

**Open a Dialog**

A Custom Dialog can be opened from any :ref:`Run Configuration <Run Configurations>`  by using the ${dvt_dialog_prompt:path_to_dialog.swtxml} variable. 

This variable takes as an argument the dialog descriptor file. The path to the \*.swtxml file can be specified, in order of precedence, either as an absolute path, as a path relative to the location of the run configuration file or as a path relative to the project. 

When the run configuration is executed, the ${dvt_dialog_prompt:path_to_dialog.swtxml} variable is replaced with the string produced by the dialog (i.e. the **dialog output**).

For example you can use the following command in a **DVT Generic** run configuration:

.. code-block:: console

   sh -c "echo ${dvt_dialog_prompt:path_to_dialog.swtxml}"

By default, the dialog blocks any interaction with the other application windows. To prevent this, for example in order to copy & paste text from an editor into the dialog, use the non-blocking argument, like this:

.. code-block:: console

   sh -c "echo ${dvt_dialog_prompt:non-blocking:path_to_dialog.swtxml}"

.. note:: 

 Please be aware that when using **{dvt_dialog_prompt:non-blocking}** you should have the **Launch in background** option (on the **Common** tab) unset.

You can also open a dialog using the :ref:`Command Line Interface`.

A dialog looks like this:

.. figure:: ../../images/common/dvt-customdialogs-dialog.png
    :align: center

**Use the Dialog Output**

The dialog output is a string composed by concatenating the output of each widget that has an **id** attribute specified. The output of a widget is its **id** concatenated with its value. The value differs across widgets, see :ref:`Widgets`.

For example a **Directory Chooser** defined like this:

.. code-block:: xml

    <dvt:DirectoryChooser id="+incdir+" value="/path/to/some/dir"/>

will produce:

.. code-block:: 

    +incdir+/path/to/some/dir

See :ref:`Customizing the Dialog Output` for more customization options.

You can find some comprehensive examples in the :ref:`DVT Predefined Projects <Predefined Projects>` shipped with DVT. You can start with an example dialog containing all the available widgets from menu :menuselection:`New --> Example --> DVT --> DVT Custom Dialog`.

.. toctree:: 

   quick-steps.rst
   customizing-the-dialog-output.rst
   swtxml-reference.rst
   custom-dialog-snapshots.rst
