From: san <san@opencascade.com>
Date: Fri, 23 Apr 2010 15:30:36 +0000 (+0000)
Subject: Issue 0020580: on-line documentation for improved spin boxes
X-Git-Tag: V5_1_4rc1~21
X-Git-Url: http://git.salome-platform.org/gitweb/?a=commitdiff_plain;h=a67f51da5419336de934b91709bbed5993488264;p=modules%2Fgui.git

Issue 0020580: on-line documentation for improved spin boxes
---

diff --git a/doc/salome/gui/input/introduction_to_gui.doc b/doc/salome/gui/input/introduction_to_gui.doc
index ddbccb03f..5e3de36f3 100644
--- a/doc/salome/gui/input/introduction_to_gui.doc
+++ b/doc/salome/gui/input/introduction_to_gui.doc
@@ -62,6 +62,10 @@ Help for the GUI module provides information about standard
 </ul>
 
 \subpage setting_preferences_page "Preferences" for all Salome modules
-are also described in this section of Salome GUI Help.
+are also described in this section of SALOME GUI Help.
 
-*/
\ No newline at end of file
+\subpage using_input_widgets_page "Using input widgets" sub-section
+covers specific aspects of behavior of certain kinds of SALOME GUI
+input fields.
+
+*/
diff --git a/doc/salome/gui/input/using_input_widgets.doc b/doc/salome/gui/input/using_input_widgets.doc
new file mode 100755
index 000000000..2d0cb9bcb
--- /dev/null
+++ b/doc/salome/gui/input/using_input_widgets.doc
@@ -0,0 +1,65 @@
+/*!
+
+\page using_input_widgets_page Using input widgets
+
+This section contains some hints that might be useful when working
+with SALOME GUI input widgets.
+
+<h1>Spin boxes</h1>
+
+This type of widgets is used for numeric (integer or floating-point)
+data input. Spin boxes are used in standard \b SALOME modules in case
+if an input value has clearly defined input range (and precision in
+case of floating-point value).
+
+Input precision has specific semantics in \b SALOME floating-point
+spin boxes:
+- Positive value means that a number in a fixed-point format
+(corresponding to "f" format specifier for C printf function) is
+expected. Positive precision value is the maximum allowed number of
+digits after the decimal separator.
+- Negative precision value means that a number either in a fixed-point
+or scientific (exponetial) format is expected. This is similar to
+behavior of "g" format specifier for C printf function. Absolute
+precision value is the maximum allowed number of significant digits in
+mantissa (note that one digit is always before the decimal separator).
+
+To make the user aware of an input value constraints applied by some
+\b SALOME operation, the following basic capabilties are provided by
+spin boxes:
+- Text entered manually into a spin box by the user is checked to be a
+number of valid type (integer or floating-point).
+- The text is converted to a number and checked against the valid
+range.
+- Additionally, for floating-point data the input text is checked
+against the precision rules described above.
+
+In case if the input text in a spin box does not satisfy the
+constraints, the user is informed about this by a message shown in a
+tooltip near the spin box just as he types in it. The tooltip contains
+information about valid data range. For floating-point input, the
+tooltip also contains information about expected precision. 
+
+In standard \bSALOME modules precision value can be adjusted through
+\ref setting_preferences_page "user preferences" of correspodning  modules, and the tooltip contains a
+reference to corresponding parameter in the preferences.
+
+On-line documentation for each standard SALOME module contains the
+list of user preferences that can be used for tuning floating-point
+precision for different type of input quantities.
+
+<h2>Spin boxes and SALOME Notebook</h2>
+
+Apart from numeric input, spin boxes in some \b SALOME modules accept
+names of \b Notebook variables (see \ref using_notebook "Using Notebook" 
+page for more details about \b Notebook).
+
+If some spin box accepts variable names, then it is
+additionally checked whether the manual input text represents a variable name. Variable
+names should satisfy common naming rules for \b Python variables.
+In case if the input is neither a valid number nor a variable name,
+the tooltip is shown informing the user that variable names are
+also acceptable in this spin box.
+
+
+*/