.. _hmispec:

Internal HMI files format
=========================

..  :Source: doc/hmispec.txt
    :Version: 1.2.1
    :Author: Antonio Valentino
    :Contact: a_valentino@users.sf.net
    :URL: http://bestgui.sourceforge.net
    :Revision: $Revision: 699 $
    :Date: $Date: 2008-09-28 10:43:20 +0200 (dom, 28 set 2008) $
    :License: GNU General Public License (GPL)

HMI files are used from BESTGUI to build the GUI that allow the user to specify
the processing request parameters for BEST and store them in a file.

HMI files are located in the ``config/hmi`` folder and they are text files with
a structure similar to what you would find on Microsoft Windows INI files.

They consist of sections, led by a "[section]" header and followed by
"name=value" entries.
For example::

    [The Section]
    foodir=/path/to/foodir
    dir=frob

Each BEST tool has its own HMI file. A valid HMI file for BESTGUI should have at
least two special sections, "MAIN" and "MENU" (see description below), and one
section for each parameter needed by the BEST tool.

:Note: parameters related to the AoI (Area of Interest) specification should
       never figure out in the HMI files; a special flag "has_aoi" in the "MAIN"
       section is used for tools that require the AoI specification.


Special sections
----------------

MAIN
~~~~

The "MAIN" special section is **mandatory** and it most have the following four
entries:

:title:
    must be a valid BEST tool specifier i.e. a valid section name for a
    BEST parameters file
:has_aoi:
    True if the BEST tool allows the AoI specification (allowed values:
    True/False)
:patterns_label:
    it is used in the file selection dialogs as label for the file filter
    (the filter allow to display only files that match the patterns listed in
    the "patterns" entry).
:patterns:
    comma separated list of the output file extensions of the BEST tool

Example::

    [MAIN]
    title = FULL RESOLUTION
    has_aoi = True
    patterns_label = Full Resolution Extraction
    patterns = .XTc,.XTf,.XTi,.XTr,.XTs,.XTt

MENU
~~~~

Information provided in this section are used to build the BESTGUI tools menu.
**Mandatory** section.

Example::

    [MENU]
    name = full
    label = Full Resolution Extraction
    description =
    parent = extraction
    position = 3

Parameters sections
-------------------

Like each HMI file is associated to a specific BEST tool, in the same way each
"parameter section" corresponds to a parameter that the user can specify when
runs the tool.

The parameter sections provide all the information concerning the type
(integer, string etc.) of the parameter and the appearance of the GUI used for
the input (text entry and its size, check button, radio buttons ad so on).

type
~~~~

The "type" entry is **mandatory** and must have one of the following values:

:CheckChar:
    display a check-button that allows to select one of two possible (and
    configurable) character values (es. Y:N)
:CheckString:
    display a check-button that allows to select one of two possible (and
    configurable) string values (es. Yes:No)
:RadioScalar:
    display a radio-button that allows to select a scalar value in a finite set
    of possibilities (es. 16:32:64)
:RadioChar:
    display a radio-button that allows to select a character value in a finite
    set of possibilities (es. R:G:B)
:RadioString:
    display a radio-button that allows to select a string value in a finite
    set of possibilities (es. RED:GREEN:BLUE)
:String:
    display an entry box for the input of strings
:StringVector:
    display an entry box for the input of multiple string values (comma
    separated)
:Scalar:
    display an entry box for the input of single numeric values
:Vector:
    display an entry box for the input of multiple numeric values (comma
    separated)
:File:
    used for the input of file names, display an entry box and a button that
    allow to pop up a file selection dialog
:Dir:
    used for the input of directory names, display an entry box and a button
    that allow to pop up a directory selection dialog
:Path:
    used for the input of generic paths, display an entry box and a button
    that allow to pop up a file selection dialog

name
~~~~

The "name" entry is a short and unique name associated to the parameter
(**mandatory**).

label
~~~~~

The "value" of the label entry is displayed in the GUI on the left of the input
widgets. It also represents the entry name in the BEST parameters file so it is
but arbitrary. All labels must be set referring to the "BEST User Manual".
**Mandatory**.

mandatory
~~~~~~~~~

The "mandatory" entry is used to specify whenever the parameter is mandatory
or not according to the "BEST User Manual".
Possible values are "True" or "False".

Other entries
~~~~~~~~~~~~~

Other entries in this section depend on the "type" entry value.
Please refer to the source code (and doc-strings) in ``bestgui/paramtype.py``
for details.

Example::

    [Output Dir]
    type = Dir
    name = outputDir
    label = Output Dir
    mandatory = True
    default = None
    width = 40
    position = 4
    numcheck = 1