.. _SWT/XML Reference:

SWT/XML Reference
=================


A custom dialog is described in an XML file with **.swtxml** extension. The first line must declare the file as XML:

.. code-block:: xml

    <?xml version="1.0" encoding="utf-8"?>

The topmost element must be a **Composite** widget that defines the title of the dialog (specified by its **id** attribute) and the widgets that can be used (standard SWT widgets and custom DVT widgets):

.. code-block:: xml

    <Composite xmlns="http://www.swtxml.com/swt"
        xmlns:sv="http://eda.amiq.com/xmlns/customdialog/sv"
        xmlns:dvt="http://eda.amiq.com/xmlns/customdialog"
        id="Dialog Title">
    </Composite>

A **widget** is a graphical component (e.g. Textbox, Checkbox) or a container of other widgets (e.g. Composite, Group). Each widget has a corresponding XML tag. You can use any widget to create your dialog. If you specify an **id** attribute for the widget tag, it will also produce an output in the dialog result.

.. _Layouts:

Layouts
~~~~~~~

There is a large set of layout options available. A complete reference can be found `here <http://www.eclipse.org/articles/article.php?file=Article-Understanding-Layouts/index.html>`_. The best approach to finding the desired layout is by using the extensive autocomplete provided by the **SWT/XML Editor**. Below there is a list common use-cases with examples.

**Horizonal Fill**

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

.. code-block:: xml
    
   <Composite id=" -verbosity " layout="layout:fill;">
       <Label text="Verbosity:"/>
       <Button id=" HIGH " style="RADIO" text="High"/>
       <Button id=" MEDIUM " style="RADIO" text="Medium"/>
       <Button id=" LOW " style="RADIO" text="Low"/>
   </Composite>

**Vertical Fill**

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

.. code-block::  xml

   <Composite id=" -verbosity " layout="layout:fill;type:VERTICAL;">
       <Label text="Verbosity:"/>
       <Button id=" HIGH " style="RADIO" text="High"/>
       <Button id=" MEDIUM " style="RADIO" text="Medium"/>
       <Button id=" LOW " style="RADIO" text="Low"/>
   </Composite>


**Grid**

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

.. code-block:: xml

   <Composite id=" -verbosity " layout="layout:grid;numColumns:3;">
       <Label text="Verbosity:" layoutData="horizontalSpan:3;"/>
       <Button id=" HIGH " style="RADIO" text="High"/>
       <Button id=" MEDIUM " style="RADIO" text="Medium"/>
       <Button id=" LOW " style="RADIO" text="Low"/>
   </Composite>

.. _Widgets:

Widgets
~~~~~~~

**Composite**

Composites are used for grouping other elements, and they have no visual representation. You can control how their children elements are arranged by specifying the **layout** attribute. See the :ref:`Layouts` section for information on how to control the look of the dialog.

**Group**

Groups are similar to composites, except that they are graphically delimited by a border and can have a title specified by the **text** attribute. Refer to **Radio Button** for an example.

**Label**

Labels are simple text fragments used to present information. Refer to **Textbox** for an example.

**Textbox**

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

*XML*

.. code-block:: xml

   <Label text="Seed number:"/>
   <Text id=" -seed " style="BORDER" text="123456" />

*Output*
    -seed 123456


**Checkbox**

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

*XML*

.. code-block:: xml

   <Button id=" -cov " style="CHECK" text="Collect coverage" selection="true" />
   <Button id=" -wave " style="CHECK" text="Dump wave" />
    

*Output*
    -cov


**Radio Button**

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

*XML*

.. code-block:: xml

   <Group id=" -sim " text="Simulator" layout="layout:fill;type:VERTICAL;">
       <Button id=" IUS " style="RADIO" text="IUS" selection="true"/>
       <Button id=" VCS " style="RADIO" text="VCS" />
       <Button id=" Questa " style="RADIO" text="Questa" />
   </Group>
    

*Output:*
    -sim IUS


**Directory Chooser**

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




*XML*

.. code-block:: xml

    <dvt:DirectoryChooser
        id=" -sim_dir "
        question="Sim dir"
        layoutData="horizontalAlignment:FILL;"
        value="../sim"/>

*Output:*
    -sim_dir ../sim


**File Chooser**

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




*XML*

.. code-block:: xml

    <dvt:FileChooser
        id=" -mem_file "
        question="Memory init data"
        layoutData="horizontalAlignment:FILL;"
        extensions="*.bin"
        value="/common/mem/init.bin"/>

*Output:*
    -mem_file /common/mem/init.bin


**Combo Box**

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

*XML*

.. code-block:: xml

    <Combo
        id=" -test "
        text="test_reset"
        items="test_random;test_reset;test_back2back;test_1;test_2;test_3"/>

*Output:*
    -test test_reset

**Combo Box (read only)**

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

*XML*

.. code-block:: xml

    <Combo
        id=" -test "
        style="READ_ONLY"
        text="test_reset"
        items="test_random;test_reset;test_back2back;test_1;test_2;test_3"/>

*Output:*
    -test test_reset

**List**

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



*XML*

.. code-block:: xml

    <List
        id=" -verbosity "
        selection="HIGH"
        style="BORDER|V_SCROLL"
        items="HIGH;MEDIUM;LOW;NONE"/>

*Output:*
    -verbosity HIGH

**Directory Files Listing**

Lists all files/dirs that match a certain criteria in a specified folder.

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

*XML*

.. code-block:: xml

    <dvt:DirectoryFilesListing
        id=" -file "
        question="Files Listing"
        includePaths="**\*.sv;**\*.e;**\*.vhdl"
        excludePaths=""
        rootDirectory="/home/path/.."
        fileType="FILE;DIR"
        outputOption="basename"
        showHiddenFiles="true"
        timeoutSeconds="10"/>

*Output:*
    -file file_name

*Parameters*

-  includePaths (excludePaths) - include (exclude) files based on their filename
    -  *Examples*
        -  "\*\*\\\*.e;\*\*\\\*.vhd" matches all .e and .vhd files/dirs in a directory tree.
        -  "test\\\a??.sv" matches all files/dirs that start with an 'a', then two more characters and then ".sv", in a directory called test.
        -  "\*\*" matches everything in a directory tree.
        -  "\*\*\\test\\\*\*\\XYZ*" matches all files/dirs that start with "XYZ" and where there is a parent directory called test (e.g. "abc\\test\\def\\ghi\\XYZ123").
    -  Default value for 'includePaths' is '**'
-  rootDirectory - can be specified as an absolute path or relative to a project in the current workspace. The path can also contain system variables.
-  fileType - select whether files, directories or both are shown
    -  *FILE* - displays only files
    -  *DIR* - displays only directories
    -  *FILE;DIR* - displays both files and directories
    -  Default value for 'fileType' is *FILE*
-  outputOption - option to format the selected file's name
    -  'basename' - returns the file's name without extension
    -  'fullname' - returns the file's name with extension
    -  'fullpath' - returns an absolute path of the selected file
    -  'relativepath' - a path relative to 'rootDirectory'
-  showHiddenFiles - by default is false
-  timeoutSeconds - if the root directory has a large number of children, listing them is stopped after * seconds

.. note:: 

 The **includePaths** and **excludePaths** attributes use `ant-like path patterns <http://ant.apache.org/manual/dirtasks.html#patterns>`_.

**Class Selector**

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

*XML*

.. code-block:: xml

    <sv:ClassSelector
        id=" -test "
        question="Test to run"
        fieldSeparator=","
        layoutData="horizontalAlignment:FILL;
        verticalAlignment:FILL;
        grabExcessHorizontalSpace:true;
        grabExcessVerticalSpace:true;"
        baseClassName="uvm_test"/>

*Output:*
    -test test_2m_4s

.. note:: 

 This widget is only available for SystemVerilog.

**Struct selector**

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

*XML*

.. code-block:: xml

    <e:StructSelector
        id=" -env "
        question="Environments"
        fieldSeparator=","
        layoutData="horizontalAlignment:FILL;
        verticalAlignment:FILL;
        grabExcessHorizontalSpace:true;
        grabExcessVerticalSpace:true;"
        baseStructName="uvm_env"
        showWhenSubtypes="true"
        hierarchyLevels="1"/>

*Output:*
    -env UVM_ACCEL xbus_env_u

.. note:: 

 This widget is only available for e Language.

.. note:: 

 The **hierarchyLevels** attribute can either be an integer, or **all** in order to control the displayed inheritance level starting from the when subtypes.

