<!doctype linuxdoc system>

<!-- This is the complement of Grace User's Guide for GraceGTK -->

<article>

<title>GraceGTK complement (GraceGTK.0.0.b3 development version)</title>
<author>P. Vincent</author>
<date>08.04.2010</date>
<abstract>
  This document describes differences between Grace and GraceGTK
</abstract>

<toc>

<!-- **************************************** -->
<sect>Introduction
<p>

<sect1>What is GraceGTK?
  <p>
    GraceGTK is an evolution of Grace (grace-5) using the GTK Application 
    Programming Interface  (API) instead of Motif.
    You must have a look to Grace documentation before reading this.

    The natural operating system for GTK is Unix/Linux, but
    the use of GTK allows to build a standalone distribution for MS
    Windows. 

    The starting point for developing GraceGTK is Grace-5.1.22.
    This document intend to describe the changes and new features
    introduced since that version.

<sect1>Copyright statement
  <p>
 For Grace:
<tscreen><verb>
Copyright (&copy;) 1991-1995 Paul J Turner, Portland, OR
Copyright (&copy;) 1996-2007 Grace Development Team
Maintained by Evgeny Stambulchik
 For GraceGTK: 
Copyright (&copy;) 2009-2010 Patrick Vincent and the Grace Development Team


                         All Rights Reserved

This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
</verb></tscreen>

   <p>
     For certain libraries required to build Grace
     (which are therefore even included in a suitable version)
     there may be different Copyright/License statements. Though their
     License may by chance match the one used for Grace,
     the Grace Copyright holders can not influence or change them.

   <p>
   <table loc="htbp">
     <tabular ca="ll">
       <hline>
       Package        |  License  @
       <hline>
       cephes library |  Free     @
       T1lib          |  LGPL     @
       GTK+           |  GPL      @
       libundo        |  GPL      @
       <hline>
     </tabular>
     <caption>
       Licenses
     </caption>
   </table>
 <P>

<sect>Installation guide
  <p>

  <sect1>Installing from sources
    <p>
      <itemize>
        <item> Requirements.
	    Instead of the M*tif API, you should have
	    a running version of GTK+-2.12 or above.
	    It should work also with GTK+-2.10, but without the
	    tooltips. 
	    GTK can be found at <url url="http://www.gtk.org">.
	      For other requirements, see the Grace User's Guide.

	<item> Hints. 
           If the <tt>./configure</tt> does not work for you,
	   try to soft link <tt>ac-tools/configure.in</tt> in the main
		gracegtk directory and to run  <tt>autoconf</tt> to regenerate
		the configure file.
       </item>
	<item> Under Windows XP and Vista:
	   you must have MinGW, MSYS and GTK+ installed. 
	   GTK+-2.18 seems buggy. It gives:
<verb>
Gdk-CRITICAL **: _gdk_drawable_get_source_drawable: 
                 assertion `GDK_IS_DRAWABLE (drawable)' failed
</verb>
	    messages when running. 
	    Using 2.16 revision for Windows does not gives this message.
	    You can have to hack autotools files to get  a working configure.
            and some features does not works under MW Windows.
	  </item>
       </itemize>
    </sect1>
    <sect1><heading>Binary installation</heading>
      <p>
       Up to now, no binary build is available.
     </p>
    </sect1>
</sect>
<!-- **************************************** -->

<sect><heading>Getting started</heading>
  <p>
    Each time it is possible without to much complexity, the original
    <tt>grace-5</tt> menus are conserved and should work as described in the 
    <tt>grace-5</tt> documentation.
    From the end user point of view,
    the main novelties are the new toolbar buttons and the Explorer/TreeView
    window dialog. 
    Try the Help/Examples/GraceGTK menu entries to discover some of them.
  </p><p>
    GraceGTK evolution is to add features copied from grace-5.99, the beta version
    of grace-6. Thus, you can also have a look on grace-5.99 and try it.
  </p><p>
    One of the main novelty in GraceGTK is the development of the management
    of "geometrical" objects: arcs, boxes, lines ans strings, inspired by the
    well known free program <tt>xfig</tt>
  </p>
<sect><heading> Left toolbar</heading>
      <p>
  The new toolbar buttons are inspired by the <tt>xfig</tt> well-known program.

  The Help/Examples/GraceGTK/explain menu entry as well as tooltips 
   shows short explanations about the use of the toolbar buttons.
  Here is some details.
   <itemize>
     <item>
       <tt>Edit</tt> button pops up the explorer with the object 
       selected with the mouse.
       It is not true for graphs, which are a special case.
       To select a set in a graph, the graph must be the active graph and
       you must click on a point of the set, not the interpolating line.
     </item>
     <item>
      <tt>Import</tt> button is a direct access to the <tt>Import ASCII data</tt>
      dialog.
     </item>
     <item>
      <tt>TreeView</tt> pops up the explorer window.
     </item>
   </itemize>
</sect>

<sect><heading>Explorer window</heading>
  <sect1><heading>Left pane</heading>
      <p>
    The first column gives a tree view of the drawing components.
    Visible components are in bold normal and hidden in light italic.
    <p>
    Clicking one component with the left button shows the corresponding
    menu in the right pane.
    <p>
    Multiple selections are allowed to raise a contextual menu with
    mouse button 3 but works only if all the elements
    selected have the same type: graph or set.
    Selecting several elements is made using the GTK standard:
    shift to select all elements between two rows,
    control to add a clicked element to the list.
    
    <p>
    The <tt>Label</tt> column  is  editable: double-click on the item to edit it
    and press enter to record the change.
     <itemize>
     <item>
        For graphs, axis, sets and string this allows to edit graph title,
        axis label, set legend and the string.
     </item>
     <item>
        For project, arcs, lines and boxes the <tt>pars.yacc</tt> file is not yet updated 
       thus the label (which is not visible) will not be recorded in <tt>.agr</tt> files 
       and will be lost when the program is stopped.
     </item>
     <item>
        For time stamp, legend boxes and templates, editing the label is not relevant and it will 
         return to its initial state when you press the enter key.
     </item>
     </itemize>
  </sect1>

  <sect1><heading>Right pane menus</heading>
    <p>
    Up to now, these menus are copied from <tt>grace-5</tt> with few changes, but it can be
    changed in future versions.
    You must click on the bottom <tt>Apply</tt> button to make your changes effective.
    The <tt>Close</tt> button hide the explorer window with no change; if no  item
    selection is made during the interval,
    rising again the explorer with the <tt>TreeView</tt> button will show the window
    in the state it had when  you hide it.

    Some details about menus in the right pane.
     <itemize>
     <item>
        The <tt>Project</tt> menu is intend to manage global settings and the <tt>Apply</tt> 
        button does not behave here like for the other menus.
     <itemize>
     	<item>
     	   The <tt>Page</tt> tab  is applied each time the button is clicked.
     	</item>
     	<item>
     	   The <tt>Layout</tt> tab is applied only if the tab is the visible tab.
     	</item>
     	<item>
           Specialized buttons are placed in other tabs to make an action.
     	</item>
     </itemize>
     </item>
     <item>
      The <tt>Graph</tt> menu has a new <tt>Sets</tt> tab for collective actions
      on selected sets in the graph.
     </item>
     <item>
      The <tt>Axis</tt> menu has a dangerous option: if you choose to apply to more
      axes than for the current one, <bf>all</bf> the properties will be applied,
      the ones in the invisible tab as well as the others.
     </item>
     <item>
       The <tt>Set</tt> menu has a new <tt>Edit</tt> tab to replace the old
        point explorer menu. It is not yet achieved and the "point location"
        frame is only informative, showing the point selected in the spin box
        with a black rectangle.

        The <tt>Main</tt> tab has a new option for interpolating between points
        with spline, using a temporary set. Try Help/Examples/GraceGTK/Spline.
     </item>
     </itemize>
  </sect1>
</sect>

<sect><heading>New behavior of old menus </heading>
  <sect1><heading>Command window and follow-me mode</heading>
    <p>
   The command window is rewritten to take advantage of the GTK widget possibilities.
    You can edit it directly and execute only the lines selected
    with the mouse.
   The ambiguity in grace-5 where sometimes command lines must begin with a @
   (in script files) and sometime not is removed:
   command lines always begin by a @.
    <p>
    A "follow me" mode is added: each change in the parameters of objects
   validated by a "Apply" in the right pane menu is printed in the windows.
   This is incomplete, but gives a help to write your own <tt>.agr</tt> scripts.
   You can read in files and save the content of the window with the "File" menu
   at the top of the command window.
  </sect1>
  <sect1><heading>Fourier transformation</heading>
    <p>
      The Fourier transform window is now inspired by grace-5.99 with some
      changes: try Help/Examples/GraceGTK/Fourier and look at Help/Fourier
      (doc/fourier.pdf) for details.
      The main novelty is that you can take into account the translation
      needed by the FFT to get the true Fourier transform of the function
      and not the transform of the translated one.
    <p>
      It should work with library FFTW2 as well as  FFTW3.
      Legacy code for FFT is not operational thus it is recommended
      to use FFTW to take the transform of lengthy sets.
  </sect1>
</sect>


<sect><heading>Undo and Redo</heading>
  If you have compiled with the libundo library, it is possible to use
  the Undo/Redo buttons in the Edit menu.
  The method is inspired by the follow-me mode: each time a change in the
  parameters is detected, two command lines (using the grace .agr
  language) are recorded: one with the old values for the undo action,
  one with the new ones for the redo action.
  <p>
  This feature works only when two reciprocal commands exists and if the
  registering is programmed: e.g.
  data transformations and  killings are excluded.
  </p>
</sect>

<sect><heading>Command interpreter</heading>
  The undo/redo programing has shown that graph-5 language lacks
  parameters changing commands for geometrical objects (arcs, boxes,
  lines and strings): it was only possible to set parameters at the
  creation time (with undocumented commands) but not to change them after.
  This is now possible by defining new commands build on the model off
  the existing ones with a id number added.
  <p>
    Let us define <it>objtyp</it>
    <table loc="htbp">
      <tabular ca="lll">
        <hline>
          Name | Values | Remarks @
        <hline>
	  <it> objtyp </it> | ARC, BOX, LINE ,STRING | for creation only  @
	  <it> objtyp </it> | ARC <it>id</it>, BOX <it>id</it>, LINE <it>id</it> ,STRING <it>id</it> | for update  @
      </tabular>
      <caption>
        <label id="geom">
          <it>objtyp</it> definition
      </caption>
    </table>
  </p><p>
    used in the following commands
    where &lt A &verbar B &gt means that A or B are the two possibilities:
    <table loc="htbp">
      <tabular ca="lll">
        <hline>
          Command | Description | Remarks @
       <hline>
	  <it>objtyp</it> HIDDEN <it>onoff</it> |  |   @
	  <it>objtyp</it> LOCTYPE  &lt WORLD &verbar VIEW &gt | object coordinates are  in world ones or in view ones |   @
          <it>objtyp</it> :  <it>x1 ,y1 ,x2 ,y2</it>   | object coordinates | the : is needed @
	  <it>objtyp</it> LINESTYLE <it>style</it>     | <it>style</it> 0: no line, 1: continuous, etc | @
	  <it>objtyp</it> LINEWIDTH <it>width</it>     | | except for strings @
	  <it>objtyp</it> COLOR &lt<it>n</it> &verbar<it>"colorname"</it>&gt | |  @
	  <it>objtyp</it> FILL COLOR &lt<it>n</it> &verbar<it>"colorname"</it>&gt | | for boxes and filled arcs  @
	  <it>objtyp</it> FILL PATTERN &lt<it>n</it> &verbar<it>"colorname"</it>&gt | | for boxes and filled arcs  @
	  <it>objtyp</it> ARROW <it>n</it>             | 0: no arrows, 1: at start, 2: end, 3: both |  for arcs and lines @
	  <it>objtyp</it> ARROW LENGTH <it>length</it> | |  for arcs and lines @
	  <it>objtyp</it> ARROW TYPE   <it>type</it>   | |  for arcs and lines @
	  <it>objtyp</it> ARROW LAYOUT <it>a , b</it>  | |  for arcs and lines @
	  ARC <it>id </it>TYPE  <it>n</it>                         | Arc subtype|  for arcs only @
	  STRING <it>id</it> ROT  <it>angle</it>       | in degrees | @
	  STRING <it>id</it> FONT <it>n</it>           | font selection | @
	  STRING <it>id</it> CHAR SIZE  <it>size</it>  |   | @
	  STRING <it>id</it> JUST <it>n</it>           | justification  | @
	  STRING <it>id</it> "<it>the string itself</it>" |  | @
      </tabular>
      <caption>
        <label id="geom1">
          Commands related to geometrical objects.
      </caption>
    </table>
  </p>
  Anyway, you are encouraged to hack the examples files and use the follow-me mode
  to write your own scripts. In particular, Fourier examples show how to create
  sets from formulas. 
</sect>

</article>
<!-- End of GraceGTK.sgml -->
