\chapter QSA Input Dialog Framework


The QSA Input Dialog Framework is a set of classes that extends QSA to
enable the user to create dialogs using Qt Script. The Input Dialog
Framework is available in the \l QSObjectFactory subclass \l
QSInputDialogFactory.

The QSA Input Dialog Framework provides two types of classes. The
first types are the ones that can be used to build up complex input
dialogs. These classes include, Dialog, CheckBox, GroupBox, LineEdit,
TextEdit, etc. These classes each have a set of properties for
describing how they appear and some of them also provide functions. 

The following is a simple example on how to use the Input Dialog
Framework to create a dialog that will query the user for their first
and last name, and echo the values they entered:

\code
var dialog = new Dialog;
dialog.caption = "Name reading dialog";
dialog.okButtonText = "Done"
dialog.cancelButtonText = "Abort";

var first = new LineEdit;
first.label = "First name: ";
dialog.add( first );

var last = new LineEdit;
last.label = "Last name: ";
dialog.add( last );

if( dialog.exec() ) {
    var fullName = last.text + ", " + first.text;
    print( "Full name is: " + fullName );
}
\endcode

Below is a list of the classes available from the Input Dialog
Framework. Each class has a short description and a list of its
properties and functions.

For String properties the default is an empty string, and for Number
properties the default is 0, unless stated otherwise.

\section1 CheckBox

\image qchkbox-w.png

The CheckBox widget provides a checkbox with a text label. CheckBox
is an option button; it can be switched on (checked) or off
(unchecked).

\section2 Properties

\list
\o checked : Boolean;
   This property holds whether the checkbox is checked.
   The default is unchecked, i.e. false.
\o text : String;
   This property holds the text shown on the button.
\o tooltip : String;
   This property holds the tool tip (balloon help) for the widget.
\o whatsThis : String;
   This property holds a simple description of the widget.
\endlist

\section1 ComboBox

\image qcombo1-w.png

The ComboBox widget is a combined button and drop-down list. A
combobox is a selection widget which displays the current item and can
drop down a list of items. A combobox may be editable in which case
the user can enter arbitrary strings.

\section2 Properties

\list
\o currentItem : String;    
   This property is used in two ways: To specify the default selected
   item in the combobox; and to get the value the user selected in the
   combobox when the dialog is closed. The default is the first item
   in the list.
\o editable : Boolean;
   This property holds whether the combobox is editable. The default
   is false.
\o itemList : Array;
   The list of items in the combobox. 
\o label : String;
   The label for the combobox.
\o tooltip : String;
   This property holds the tool tip (balloon help) for the widget.
\o whatsThis : String;
   This property holds a simple description of the widget.
\endlist

\section1 DateEdit

\image qsdateed.png 

The DateEdit class provides a date editor. DateEdit allows the user to
edit dates by using the keyboard or the arrow keys to
increase/decrease date values. The arrow keys can be used to move from
section to section within the DateEdit box. Dates appear in accordance
with the local date/time settings or in year, month, day order if the
system doesn't provide a local date order.

\section2 Properties

\list
\o date : Date;
   This property holds the editor's date value. The default is today.
\o label : String;
   The label for the date.
\o maximum : Date;
   This property holds the editor's maximum value. The default
   maximum date is 8000-12-31.
\o minimum : Date;
   This property holds the editor's minimum value. The default
   minimum date is 1752-09-14.
\o order : Order;
   This property holds the order in which the year, month and day
   appear. The default order is locale dependent.
\o tooltip : String;
   This property holds the tool tip (balloon help) for the widget.
\o whatsThis : String;
   This property holds a simple description of the widget.
\endlist

\section1 Dialog

The Dialog class is the base class of dialog windows. A dialog window
is a top-level window mostly used for short-term tasks and brief
communications with the user. Dialogs may be modal or modeless.

\section2 Properties

\list
\o caption : String;
   This property holds the window caption (title). The default is
   the application's name. 
\o cancelButtonText : String;
   This property holds the text shown on the cancel button. The default
   is "Cancel".
\o okButtonText: String; 
   This property holds the text shown on the ok button. The default
   is "Ok".
\o width : Number;
   This property holds the width of the widget excluding any
   window frame. The default is set by the layout. 
\o tooltip : String;
   This property holds the tool tip (balloon help) for the widget.
\o whatsThis : String;
   This property holds a simple description of the widget.
\endlist

\section2 Functions

\list
\o add( widget : QSWidget ); 
   Adds a widget to the dialog. Widgets are placed vertically, from
   top to bottom.
\o addSpace( space : Number ); 
   Adds vertical space, measured in pixels between, the previous
   and next added widget.
\o exec() : Boolean;
   Executes the dialog. This opens the dialog as a modal dialog,
   blocking the application until the user presses the OK button or
   the Cancel button to close the dialog. The function returns \c true
   of the user pressed OK; otherwise it returns \c{false}.
\o newColumn();
   Creates a new column in the dialog. All widgets subsequently
   added to the dialog will be placed (vertically, from top to
   bottom), in the new column. 
\o newTab( label : String ); 
   Creates a new tab in the dialog with the given label. All
   widgets subsequently added to the dialog will be placed in
   the newly created tab, (vertically, from top to bottom). 
\endlist

\section1 GroupBox

\image qgrpbox-w.png

The GroupBox widget provides a group box frame with a title and can
displays other widgets inside itself.

\section2 Properties

\list
\o title : String; 
   This property holds the group box's title text.
\o tooltip : String;
   This property holds the tool tip (balloon help) for the widget.
\o whatsThis : String;
   This property holds a simple description of the widget.
\endlist

\section2 Functions

\list
\o add( widget : QSWidget ); 
   Adds a widget to this groupbox.
\o addSpace( space : Number ); 
   Adds vertical space, measured in pixels, between the previous
   and the next widget that is added.
\o newColumn(); 
   Creates a new column within this groupbox. All widgets
   that are added subsequently will be placed in the new column.
\o addSpace()
\endlist

\section1 LineEdit 

\image qlined-w.png

The QLineEdit widget is a single-line text editor.

\section2 Properties

\list
\o label : String; 
   The label text for this line edit.
\o text : String;
   This property holds the line edit's text.
\o tooltip : String; 
   This property holds the tool tip (balloon help) for the widget.
\o whatsThis : String;
   This property holds a simple description of the widget.
\endlist

\section1 NumberEdit

The NumberEdit class provides range checking of floating-point
numbers. NumberEdit provides an upper bound, a lower bound and a limit
on the number of digits after the decimal point.

\section2 Properties

\list
\o decimals : Number;
   This property holds the number edits's maximum number of
   digits after the decimal point.
\o label : String;
   The label text for this number edit.
\o maximum : Number;
   This property holds the number edit's maximum acceptable value.
   The default is 2,147,483,647.
\o minimum : Number;
   This property holds the number edit's minimum acceptable value.
   The default is -2,147,483,647.
\o value : Number;
   This property holds the number edit's input value. The default is 0.
\o tooltip : String;
   This property holds the tool tip (balloon help) for the widget.
\o whatsThis : String; 
   This property holds a simple description of the widget.
\endlist

\section1 RadioButton

\image qradiobt-w.png

The RadioButton widget provides a radio button with a text label.
RadioButton is an option button; it can be switched on (checked) or
off (unchecked). Sets of Radio buttons grouped together (for example
in a GroupBox), are mutually exclusive.

\section2 Properties

\list
\o checked : Boolean;
   This property holds whether the radio button is checked. The
   default is unchecked (false).
\o text : String;
  This property holds the text shown on the button.
\o tooltip : String;
   This property holds the tool tip (balloon help) for the widget.
\o whatsThis : String;
   This property holds a simple description of the widget.
\endlist

\section1 SpinBox

\image qspinbox-w.png

The SpinBox class provides a spin box widget (spin button). SpinBox
allows the user to choose an integer value either by clicking the
up/down buttons to increase/decrease the value currently displayed or
by typing the value directly into the spin box. If the value is
entered directly into the spin box, Enter (or Return) must be pressed
to apply the new value.

\section2 Properties

\list
\o label : String;
   This property holds the spinbox's label text.
\o maximum : Number;
   This property holds the maximum value of the spin box. The
   default maximum value is 2,147,483,647.
\o minimum : Number;
   This property holds the minimum value of the spin box. The
   default minimum value is -2,147,483,648.
\o value : Number;
   This property holds the value of the spin box.
\o tooltip : String;
   This property holds the tool tip (balloon help) for the widget.
\o whatsThis : String;
   This property holds a simple description of the widget.
\endlist

\section1 TextEdit

The QTextEdit widget provides a multi-line text editor.

\section2 Properties

\list
\o text : String; 
   This property holds the text of the TextEdit.
\o tooltip : String;
   This property holds the tool tip (balloon help) for the widget.
\o whatsThis : String;
   This property holds a simple description of the widget.
\endlist

\section1 TimeEdit

\image qstimeed.png

The TimeEdit class provides a time editor. TimeEdit allows the user to
edit times by using the keyboard or the arrow keys to
increase/decrease time values. The arrow keys can be used to move from
section to section within the TimeEdit box.

\section2 Properties

\list
\o label : String;
   This property holds the time edit's label text.
\o maximum : Time;
   This property holds the maximum time value.
\o minimum : Time;
   This property holds the minimum time value.
\o showAMPM : Boolean;
    If this property is false (the default), the time edit uses the 24
    hour clock; otherwise the time edit uses the 12 hour clock and
    displays AM or PM as appropriate.
\o showSeconds : Boolean;
    If this property is true (the default), the time edit displays
    seconds; otherwise it does not display seconds.
\o time : Time; 
   This property holds the editor's time value.
\o tooltip : String;
   This property holds the tool tip (balloon help) for the widget.
\o whatsThis : String;
   This property holds a simple description of the widget.
\endlist

\section1 Convenience Classes

The convenience classes provide static functions to obtain a value
from the user without using any complex widget hierarchies. Because
the functions are static they can be called directly without the need
to create an instance of the class. For example, to get a filename all
that is necessary is to call \c FileDialog.getOpenFileName().

\section1 The MessageBox class

\image messageb1.png

This class provides a simple way of popping up a message box window
for the user. The following lines of code present a pop up messagebox
with a warning and query the user to click Yes or No.

\code
var ans = MessageBox.warning( "Do you wish to save the data?", MessageBox.Yes, MessageBox.No );
if (ans == MessageBox.Yes) {
    save();
}
\endcode

\section2 Button types

The button types are used to describe what the text of the buttons
should be. The following are available.

\list
\o NoButton; No button is displayed.
\o Ok; Displays an 'OK' button.
\o Cancel; Displays a 'Cancel' button.
\o Yes; Displays a 'Yes' button.
\o No; Displays a 'No' button.
\o Abort; Displays an 'Abort' button.
\o Retry; Displays a 'Retry' button. 
\o Ignore; Displays an 'Ignore' button.
\endlist

\section2 Functions

The following is a list of message box functions. The button1, button2
and button3 parameters can be any of the Button types described above
and specify which button types will be shown in the message
box. Each function returns the button type that the user pressed.

\list
\o information( label : String, 
		button1 : ButtonType, 
		button2 : ButtonType, 
		button3 : ButtonType, 
		title : String );
   Displays an information message box with the content specified in \c label.
\o warning( label : String,
	    button1 : ButtonType,
	    button2 : ButtonType,
	    button3 : ButtonType,
	    title : String );
   Displays a warning message box with the content specified in \c label.
\o critical( label : String,
             button1 : ButtonType, 
	     button2 : ButtonType, 
   	     button3 : ButtonType,
             title : String )
   Displays a critical error message box with the content specified in \c label.
\endlist

\section1 The FileDialog class

\image filedialog.png

This class provides dialogs that allow users to select files or
directories. The following function call will open a file dialog
with that will display files with the extension \c .txt.

\code
var filename = FileDialog.getOpenFileName( "*.txt" );
if (filename) {
    processfile(filename);
}
\endcode

\section2 Functions

\list

\o getOpenFileName( filter : String, title : String ); 
   Opens an "Open" dialog. If \c filter is specified (e.g.
   "textfiles (*.txt)"), only those files which match the filter are
   shown. The function returns a string with the selected filename, or
   \c undefined if the user canceled.

\o getSaveFileName( filter : String, title : String ); 
   Opens an "Save As" dialog. If \c filter is specified (e.g.
   "textfiles (*.txt)"), only those files which match the filter are
   shown. The function returns a string with the filename selected or
   entered, or \c undefined if the user canceled.

\o getExistingDirectory( dir : String, title : String ); 
   Opens a "Find Directory" dialog for the user to select an existing
   directory. The parameter \c dir can be used to specify the initial
   directory. Returns the name of the selected directory or \c
   undefined if the user canceled.

\o getOpenFileNames( dir : String, filter : String, title : String );   
   Opens an "Open" dialog for the user to select and open one or more
   existing files. If \c dir is specified it specifies the initial
   directory. If \c filter is specified (e.g. "textfiles (*.txt)"),
   only those files which match the filter are shown. The function
   returns a list of string string with the selected filenames, or \c
   undefined if the user canceled.

\endlist


\section1 The Input class

\image inputtext.png

\image inputitem.png

This class provides convenience functions for getting simple input from
the user. The following code can be used to open a dialog that queries
the user for a text:

\code
var name = Input.getText( "What is your surname? " );
if (name) {
    processname(name);
}
\endcode

\section2 Functions

\list
\o getText( label : String, 
	    text : String,
	    title : String );
   Asks the user for a text. \c label specifies the descriptive
   label and \c text specifies the default text. The function
   returns the text entred by the user or \c undefined if the user
   canceled.

\o getNumber( label : String, 
              value : Number, 
              decimals : Number,
              minValue : Number, 
              maxValue : Number,
	      title : String );
   Asks the user for a number. \c label specifies the descriptive
   label, \c value specifies the default value, \c decimals specifies
   the number of decimals allowed, \c minValue specifies the minimum
   value and \c maxValue specifies the maximum value. The function
   returns the value entered by the user or \c undefined if the user
   canceled.

\o getItem( label : String, 
            itemList : Array, 
            current : String, 
            editable : Boolean,
	    title : String );
   Asks the user to select an item from a predefined list of values
   specified by \c itemList.
   The descriptive label is specified with \c label. \c current
   specifies the value that is selected when the dialog starts. If \c
   editable is true, the user is allowed to enter a value that is not
   in the \c itemList. The function returns the value selected or
   entered by the user or \c undefined if the user canceled.
\endlist
