/*
 * Project: MoleCuilder
 * Description: creates and alters molecular systems
 * Copyright (C)  2010 University of Bonn. All rights reserved.
 * Please see the LICENSE file or "Copyright notice" in builder.cpp for details.
 */

/**
 * \file queries.dox
 *
 * Created on: Jan 20, 2013
 *    Author: ankele
 */


/** \page queries Queries
 *
 * \section description General description
 *
 * Queries represent the process of asking the user to input a value as an
 * option for \ref actions. How that is done depends on the current UI and
 * the type of the value.
 *
 * \section internals Internals
 *
 * What happens when an action needs, say, an integer valued Parameter?
 *  - the action object has an element of type Parameter<int> declared in its .def file (including a validator defining the constraints)
 *  - the action's call() requests the current UI (for example QT) to create a dialog. The QT GUI creates a QtDialog
 *  - Action::call() also calls Dialog::query<T>() for each of its parameters telling the dialog what to ask from the user later on (in this case query<Parameter<int>>() )
 *  - Action::call() calls Dialog::display()
 *  - for each query Dialog::display() calls Query::handle() (in non QT UIs this will read temporary input from the user)
 *  - Dialog::display() then tests if the temporary values in all queries are valid (Query::isValid() )
 *  - if all values are correct, they are stored in the Parameter objects (Query::setValue() )
 *  - Action::performCall() (really perform the action)
 *
 * QtDialog needs to be more interactive:
 *  - it has its own QtDialog::display()
 *  - QtDialog::display() shows the dialog box and waits till the user closes it
 *  - the int query is shown as an QSpinBox, any user input will call QtDialog::update()
 *  - QtDialog::update() tests if all values are valid and enables/disables the OK button accordingly
 *
 * The internal workings of queries:
 *  - Dialog::query<T>() in turn calls the virtual Dialog::queryInt(), so effectivly QtDialog::queryInt() is being called
 *  - QtDialog::queryInt() creates a new IntQtQuery object and stores it in the dialog's query list
 *  - class hierarchy: IntQtQuery - QtQuery<int> - TQuery<int> - Query
 *  - the base class Query only stores additional info for the user
 *  - TQuery stores the Parameter and the temporary value
 *  - QtQuery is used to ignore the handle() call
 *  - IntQtQuery sets up the input box and handles the GUI signals
 *
 * List queries (like QtIntsQuery) are a bit more tricky. It creates a QtIntQuery as a child. The value from the child query can be added to QtIntsQuery's list of values. To handle communication between parent and child the child is being embedded in its own (special) dialog owned by the parent.
 *
 * \date 2013-01-29
 *
 */