# GraceGTK complement (GraceGTK.0.0.b3 development version)

## P. Vincent

08.04.2010

This document describes differences between Grace and GraceGTK

## 1. Introduction

- 1.1 What is GraceGTK?
- 1.2 Copyright statement

## 2. Installation guide

- 2.1 Installing from sources
- 2.2 Binary installation

## 3. Getting started

## 4. Left toolbar

## 5. Explorer window

- 5.1 Left pane
- 5.2 Right pane menus

## 6. New behavior of old menus

- 6.1 Command window and follow-me mode
- 6.2 Fourier transformation

## 7. Undo and Redo

## 8. Command interpreter

## 1. Introduction

## 1.1 What is GraceGTK?

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.

## 1.2 Copyright statement

For Grace:

> `

>     Copyright (©) 1991-1995 Paul J Turner, Portland, OR
>     Copyright (©) 1996-2007 Grace Development Team
>     Maintained by Evgeny Stambulchik
>      For GraceGTK:
>     Copyright (©) 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.

> `

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.

Package | License
cephes library | Free
T1lib | LGPL
GTK+ | GPL
libundo | GPL

Licenses

## 2. Installation guide

## 2.1 Installing from sources

- 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 http://www.gtk.org. For other requirements, see the Grace User's Guide.
- Hints. If the `./configure` does not work for you, try to soft link `ac-tools/configure.in` in the main gracegtk directory and to run `autoconf` to regenerate the configure file.
- Under Windows XP and Vista: you must have MinGW, MSYS and GTK+ installed. GTK+-2.18 seems buggy. It gives:

      Gdk-CRITICAL **: _gdk_drawable_get_source_drawable:
                       assertion `GDK_IS_DRAWABLE (drawable)' failed

  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.

## 2.2 Binary installation

Up to now, no binary build is available.

## 3. Getting started

Each time it is possible without to much complexity, the original `grace-5` menus are conserved and should work as described in the `grace-5` 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.

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.

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 `xfig`

## 4. Left toolbar

The new toolbar buttons are inspired by the `xfig` 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.

- `Edit` 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.
- `Import` button is a direct access to the `Import ASCII data` dialog.
- `TreeView` pops up the explorer window.

## 5. Explorer window

## 5.1 Left pane

The first column gives a tree view of the drawing components. Visible components are in bold normal and hidden in light italic.

Clicking one component with the left button shows the corresponding menu in the right pane.

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.

The `Label` column is editable: double-click on the item to edit it and press enter to record the change.

- For graphs, axis, sets and string this allows to edit graph title, axis label, set legend and the string.
- For project, arcs, lines and boxes the `pars.yacc` file is not yet updated thus the label (which is not visible) will not be recorded in `.agr` files and will be lost when the program is stopped.
- 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.

## 5.2 Right pane menus

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

Some details about menus in the right pane.

- The `Project` menu is intend to manage global settings and the `Apply` button does not behave here like for the other menus.
  - The `Page` tab is applied each time the button is clicked.
  - The `Layout` tab is applied only if the tab is the visible tab.
  - Specialized buttons are placed in other tabs to make an action.
- The `Graph` menu has a new `Sets` tab for collective actions on selected sets in the graph.
- The `Axis` menu has a dangerous option: if you choose to apply to more axes than for the current one, all the properties will be applied, the ones in the invisible tab as well as the others.
- The `Set` menu has a new `Edit` 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 `Main` tab has a new option for interpolating between points with spline, using a temporary set. Try Help/Examples/GraceGTK/Spline.

## 6. New behavior of old menus

## 6.1 Command window and follow-me mode

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 @.

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 `.agr` scripts. You can read in files and save the content of the window with the "File" menu at the top of the command window.

## 6.2 Fourier transformation

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.

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.

## 7. Undo and Redo

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.

This feature works only when two reciprocal commands exists and if the registering is programmed: e.g. data transformations and killings are excluded.

## 8. Command interpreter

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.

Let us define objtyp

Name | Values | Remarks
objtyp | ARC, BOX, LINE ,STRING | for creation only
objtyp | ARC id, BOX id, LINE id ,STRING id | for update

objtyp definition

used in the following commands where < A | B > means that A or B are the two possibilities:

Command | Description | Remarks
objtyp HIDDEN onoff |  |
objtyp LOCTYPE < WORLD | VIEW > | object coordinates are in world ones or in view ones |
objtyp : x1 ,y1 ,x2 ,y2 | object coordinates | the : is needed
objtyp LINESTYLE style | style 0: no line, 1: continuous, etc |
objtyp LINEWIDTH width |  | except for strings
objtyp COLOR <n |"colorname"> |  |
objtyp FILL COLOR <n |"colorname"> |  | for boxes and filled arcs
objtyp FILL PATTERN <n |"colorname"> |  | for boxes and filled arcs
objtyp ARROW n | 0: no arrows, 1: at start, 2: end, 3: both | for arcs and lines
objtyp ARROW LENGTH length |  | for arcs and lines
objtyp ARROW TYPE type |  | for arcs and lines
objtyp ARROW LAYOUT a , b |  | for arcs and lines
ARC id TYPE n | Arc subtype | for arcs only
STRING id ROT angle | in degrees |
STRING id FONT n | font selection |
STRING id CHAR SIZE size |  |
STRING id JUST n | justification |
STRING id "the string itself" |  |

Commands related to geometrical objects.
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.