[q-lang-cvs] qcalc/doc guiexamples2.png, NONE, 1.1 guiexamples3.png, NONE, 1.1 qcalc.xml, 1.21, 1.22

[Albert G. <ag...@us...>]

Update of /cvsroot/q-lang/qcalc/doc
In directory sc8-pr-cvs16.sourceforge.net:/tmp/cvs-serv8006

Modified Files:
	qcalc.xml 
Added Files:
	guiexamples2.png guiexamples3.png 
Log Message:
update documentation

--- NEW FILE: guiexamples3.png ---
(This appears to be a binary file; contents omitted.)

--- NEW FILE: guiexamples2.png ---
(This appears to be a binary file; contents omitted.)

Index: qcalc.xml
===================================================================
RCS file: /cvsroot/q-lang/qcalc/doc/qcalc.xml,v
retrieving revision 1.21
retrieving revision 1.22
diff -C2 -d -r1.21 -r1.22
*** qcalc.xml	25 Nov 2007 13:43:12 -0000	1.21
--- qcalc.xml	29 Nov 2007 00:19:17 -0000	1.22
***************
*** 325,337 ****
  
  <para>
! These functions allow you to populate spreadsheet cells with basic GUI elements.
  </para>
  
  <para>
! <literal>public checkbox ARGS, combobox ARGS, comboedit ARGS, spinbox ARGS, hslider ARGS, vslider ARGS, pushbutton ARGS, togglebutton ARGS;</literal>
  </para>
  
  <para>
! Currently supported widget types are checkboxes, comboboxes (both non-editable and editable), spinboxes, horizontal and vertical sliders, push buttons and toggle buttons. The argument tuple <literal>ARGS</literal> depends on the specific kind of widget:
  </para>
  
--- 325,382 ----
  
  <para>
! QCalc provides a fairly comprehensive set of functions which allow you to populate spreadsheet cells with various useful GUI elements:
  </para>
  
  <para>
! <literal>public label ARGS, pixmap ARGS, checkbox ARGS, combobox ARGS, comboedit ARGS, spinbox ARGS, hslider ARGS, vslider ARGS, pushbutton ARGS, togglebutton ARGS;</literal>
  </para>
  
  <para>
! The currently supported widget types are text labels, pixmaps, checkboxes, comboboxes (both non-editable and editable), spinboxes, horizontal and vertical sliders, push buttons and toggle buttons. The argument tuple <literal>ARGS</literal> depends on the specific kind of widget, as detailed below.
! </para>
! 
! <para>
! NOTE: These functions will <emphasis>not</emphasis> work if they are run asynchronously (i.e., in a secondary Q thread of the user script). They <emphasis>must</emphasis> be executed, either directly or indirectly, from a formula in a spreadsheet cell.
! </para>
! 
! <para>
! The following GUI elements are used to display formatted text and pixmaps in a cell:
! </para>
! 
! <itemizedlist>
! 
! <listitem>
! <para>
! <literal>label S</literal> or <literal>label (S,A)</literal>, where <literal>S</literal> is the text (a string) to be shown, and <literal>A</literal> (optionally) denotes the alignment of the text within the cell. The text is actually a Qt "rich text" element, which may contain a limited set of html tags as described on the QStyleSheet page in the Qt manual. Hence this element allows you to have formatted text in a cell, as well as embedded images.
! </para>
! <para>
! The alignment is specified as a string of at most two characters specifying the horizontal and/or vertical alignment, respectively. The known horizontal alignments are <literal>"a"</literal> ("auto", which may be either "left" or "right" depending on the current locale), <literal>"c"</literal> (center), <literal>"l"</literal> (left) and <literal>"r"</literal> (right), the vertical alignments are <literal>"c"</literal> (center), <literal>"t"</literal> (top) and <literal>"b"</literal> (bottom). A singleton <literal>"c"</literal> denotes both horizontal and vertical alignment. The horizontal alignment defaults to <literal>"a"</literal>, the vertical alignment to <literal>"c"</literal>.
! </para>
! </listitem>
! 
! <listitem>
! <para>
! <literal>pixmap S</literal> or <literal>pixmap (S,A,B)</literal>, where <literal>S</literal> is the name of a pixmap file to be shown, <literal>A</literal> denotes the alignment (specified in the same fashion as with labels, see above), and <literal>B</literal> is a numeric value indicating the desired rendering of the pixmap. The possible values for the <literal>B</literal> parameter are 1 ("scaled", i.e., the pixmap is scaled to fill all the available space in the cell), 2 ("animated", which can be used to animate a pixmap in mng or gif format consisting of multiple images), and 0 (no scaling or animation, which is also the default). Both the <literal>A</literal> and <literal>B</literal> parameters are optional.
! </para>
! <para>
! Note that label elements can also have embedded pixmaps (employing the <literal>&lt;img&gt;</literal> tag) and thus offer pretty much the same functionality, minus the animation feature. On the other hand, labels are much more versatile in that you can combine text and images and that they also give you more options for the placement and scaling of images. Dedicated pixmap elements are most useful for showing animated mng and gif images.
! </para>
! </listitem>
! 
! </itemizedlist>
! 
! <para>
! Here is a screenshot showing the label and pixmap elements in a spreadsheet:
! <screenshot>
! <graphic fileref="guiexamples2.png" align="center"/>
! </screenshot>
! </para>
! 
! <para>
! Text label and pixmap elements are normally used for display purposes only, but the corresponding cells do have a value which can be queried in other formulas, which is the text of the element or the name of the pixmap as a string, respectively. The <literal>S</literal>, <literal>A</literal> and <literal>B</literal> parameters can also be computed values, and in addition the text or filename can be changed with <literal>setval</literal> and friends, to update the cell contents dynamically, as described in further detail below.
! </para>
! 
! <para>
! The remaining GUI elements are typically used for value input in various forms:
  </para>
  
***************
*** 411,415 ****
  
  <para>
! The following screenshot shows some of the GUI elements in action:
  <screenshot>
  <graphic fileref="guiexamples.png" align="center"/>
--- 456,460 ----
  
  <para>
! The following screenshot shows some of these GUI elements in action:
  <screenshot>
  <graphic fileref="guiexamples.png" align="center"/>
***************
*** 418,426 ****
  
  <para>
! NOTE: These functions will <emphasis>not</emphasis> work if they are run asynchronously (i.e., in a secondary Q thread of the user script). They <emphasis>must</emphasis> be executed, either directly or indirectly, from a formula in a spreadsheet cell.
! </para>
! 
! <para>
! The parameters of all GUI elements can be computed values which may also depend on other cell values (including other GUI elements). In this case the GUI element will be updated automatically whenever any of the requisite cells changes. In particular, you can also use GUI elements to <emphasis>display</emphasis> values from other cells by specifying the corresponding cell as the INIT parameter of the widget, or you can define "buddies" which always change values in concert, like a slider and an associated spinbox.
  </para>
  
--- 463,467 ----
  
  <para>
! The parameters of all GUI elements can be computed values which may also depend on other cell values (including other GUI elements). In this case the GUI element will be updated automatically whenever any of the requisite cells changes. In particular, you can also use GUI elements to <emphasis>display</emphasis> values from other cells by specifying the corresponding cell as the <literal>INIT</literal> parameter of the widget, or you can define "buddies" which always change values in concert, like a slider and an associated spinbox.
  </para>
  
***************
*** 486,490 ****
  
  <para>
! Examples for the use of action and task buttons can be found in the <filename>guiexamples.qcalc</filename> spreadsheet included in the QCalc distribution.
  </para>
  
--- 527,534 ----
  
  <para>
! Examples for the use of action and task buttons can be found in the <filename>guiexamples.qcalc</filename> spreadsheet included in the QCalc distribution. The screenshot below shows these elements in action.
! <screenshot>
! <graphic fileref="guiexamples3.png" align="center"/>
! </screenshot>
  </para>