# Extension included in QtGrace that are NOT part of Grace

## QtGrace Version 0.2.6

### (Most extensions included by Andreas Winter <andreas.f.winter(at-nospam)web.de>.)

### Contents:

- 1. General Changes
- 2. Usage of the decimal separator
- 3. UTF-8-support
- 4. LaTeX-support
- 5. Binary data import
- 6. csv-import
- 7. Digital filtes
- 8. Output-devices
- 9. Undo/Redo
- 10. Copy / Paste / Drag and Drop
- 11. Zooming
- 12. Color(palette) management
- 13. Commands / Scripting
- 14. Comments about the font size
- 15. Further regression options
- 16. Further interpolation options
- 17. Fill area between sets
- 18. Line-Style-Selection/-Change
- 19. The Preferences-dialog
- 20. Additional selection options
- 21. Server mode (by Nimal Kailasanathan)
- 22. Haru-PDF-Library
- 23. fftw3-Library

### 1. General Changes:

QtGrace contains some minor changes in the behavior and additions in comparison to the original Grace intended to make it easier to use.

- To introduce and explain new features QtGrace has a setup-wizard-dialog. This dialog should show up the first time you start the latest version of QtGrace. If you need it again later go in the preferences (Misc-tab) and press the summon-button.
- In Grace the user has to press the Apply-button in order to confirm every change made in a dialog window. In QtGrace this is the default behaviour as well. In Preferences->QtGrace-Behavior there is now an option to activate immediate updates which means that every small change in a dialog is immediately accepted and you see the changes in the plot without having to press Apply.
- You can edit text directely inside the main window by double-clicking on it. To complete the editing, press enter; to abort just click outside or press Esc. You have to activate this feature in the preferences.
- Sets and graphs can now be highlighted. Highlighting means a thick slashed and blinking line is displayed over the highlighted object. This is just temporarly to better identify them amongst several others. To do so select them in a list and press 'h'. To stop highlighting click somewhere else or press 'h' again.
- The set-popup can be summoned in the main drawing area. You have to activate this in the preferences. The popup-menu also has additional options to edit the appearance and do some basic set-operations.
- In the set-apperance-dialog in the options-menu you can select to apply all settings or just the altered settings to a set. For one selected set this does not make a difference. But if several sets are selected, you can alter a sigular thing (like the line-width) without having to edit everything else again as well. The default is to apply all settings like in Grace. The setting (all or just altered settings) is not stored in the ini-file and therefore is specific for the current session of QtGrace.
- In all I/O-dialogs there is now a button on the right hand side in the middle of the dialog (the one showing a folder). Clicking on it will open the native file selection dialog of your operating system (This is very useful, because this dialog is usually more comfortable than the Grace-I/O-dialog.). In the upper quarter of the I/O-dialog there is also an additional button showing an arrow pointing upwards which lets you change the directory one level upwards. (On Unix-like systems this is usually done by selecting the '..'-entry in the directory-list. This does not exist on Windows-systems. Therefore I included this button.) The Filter-line and the File-line do also accept file-drops now. (Please note: If you drag-and-drop files the selection will be adjusted accordingly. If you enter a new file-name manually in the Selection-line you have to press Shift-Enter to update the selection above. Enter just reapplies the filter.)
- Drag-and-drop as well as Copy-and-paste is now possible in QtGrace (see below for further description)
- For ascii-data-import it is possible to select ',' instead of '.' as decimal separator. During drag-and-drop operations the number of '.' and ',' in a file is counted and if the number of ',' is significantly higher than the number of '.' then the user is asked whether ',' shall be used as decimal seperator. '.' is the default. For the copy-operation (copy data to clipboard) the operating systems default decimal separator is used. For the internal usage of the decimal separator see below ("Usage of the decimal separator").
- QtGrace has a history-menu showing the files you have opened recently. The history and the the other preferences are stored in an ini-file in the users home-directory. Example-files that are stored in the examples-subfolder are not included in the history list.
- Boxes and ellipses can be rotated around their center. This feature is incompatible with the original Grace and therefore files saved with QtGrace containing rotated boxes will be displayed with unrotated boxes in the original Grace. (In the implementation of this feature I made a small mistake: the direction of the rotation is clockwise for boxes and ellipses and counterclockwise for everything else. Starting with version 0.2.4 the rotation of the boxes and ellipses will also be counterclockwise. All files saved before using this feature will be shown in 0.2.4 (and above) with boxes and ellipses rotated in the wrong direction - sorry for the inconveniance!).
- You can change sizes of text, lines and objects (ellipses, boxes) with the mouse-wheel. You have to activate this in the preferences. Just use the mouse-wheel on the object itself (or in the case of axis-tick-labels on the axis itself) to change the size.
- The usage of pipes is incomplete because there doesn't seem to be a portable way of implementing this.
- The value of every slider can be edited directely by clicking on the value and entering the numerical value directely. Confirm by pressing enter.
- In View->Page setup there is a button on the top of the dialog saying "Copy page to clipboard". By pressing this button the current page is copied as a picture to the clipboard (like a screenshot - no change in resolution).
- In the Pagesetup there is an option to change the line-width with the resolution. Usually the line width is good for 72dpi. But if you for example print with 300dpi, the lines may become much to small. You could either change every line-width accordinly or just activate the option in the Pagesetup to adjust the line-width to the resolution.
- In the Pagesetup there is an option to activate antialiasing for all object. This option is separated between text and non-text. Please note, that antialiasing is not supported by all output-formats. For example postscript and pdf do antialiasing in the viewer and not in the file itself.
- Printing has been changed: "Print" will always use a physical printer. "Export to file" will save a picture to a file. The extension in the brackets in the menu shows you what file-type has been set in the Print-setup-dialog. The options "Print" and "Export" can also be included as buttons in the tool-bar (See in the preferences-section below). The Printer-settings can now be found in Preferences->Miscellaneous. HD-output boosts the resolution during the printing process, but be warned, the draw-patterns change their spacing compared to the screen.
- Concerning the default file-export-driver I included an option in Preferences->QtGrace-GUI. You may select which output format should be set at startup of QtGrace next time. You may select the last format you have set in the current session or a fixed format every time (like use 'jpeg' format for printing). It should now also be possible to start QtGrace and load a project-file and immediately click on 'File->Export to File'. The output-file is stored in the directory of the project-file loaded with the default extension of the default-output-format (same name and location as project/agr-file, but different suffix). In the "File export setup"-dialog there are now quick-selection settings for changing the current resolution.
- In the print-dialog I inserted a few new file formats to export the page to. This includes "jpg", "png" and "bmp" because they are easily derived when using Qt. I also included the option to export to pdf via the Haru-pdf-library (further details: see below).
- In the set-appearance dialog it is now possible to select a new filling option. Usually only the area between a set and the lower and upper limit of the graph or the x-axis can be filled. With QtGrace the area between two diffent sets can also be filled.
- It is possible to store one or more set-appearances in the set-popup-menu. The appearanc(es) of sets are stored internally and when applied to new sets the stored settings are applied periodically. This means if you store for example the appearances of 3 sets and select 11 other sets and apply the stored settings the 11 sets will get the appearance like {1,2,3,1,2,3,1,2,3,1,2}.
- If a Grace-project-file is to be opened (select one file in the Open-project-dialog) then the Project description is shown below the list of files and there is also the number of graphs and sets in the file displayed. Below this you will find a new button that lets you select specific sets from the file. With this new dialog you can import some sets without having to open the whole file and destroy your current graph-layout. This dialog is also presented to you if you drag and drop a Project-file (*.agr) into the QtGrace-window.
- In Data->Data Set operations... there is now an option to restrict sets to specific regions. There is also an option now to swap different columns in a set (like swap X- with Y-values).
- In Edit->Regions there is now a new dialog (Region Master...) to operate with different regions. This is effectively a combination of all the other small dialogs used to define and clear regions. In this dialog you can make a region invisible. Formerly you could only clear a region (and had to redifine it if you needed it again). You can also set different colors for the regions and edit the limiting points for the regions.
- The feature extraction dialog has been extended to let the user select different source-graphs and different sources for the abscissa (additional graph lists). The dialog has also been extended to include additional features: Y-/X-crossing means: get the X-/Y-value of the first occurence when the set passed the specified Y-/X-value; X(Y min): get the X-value where the absolute minimum of the Y-values is reached; Y(X min): get the Y-value where the absolute minimum of the X-values is reached.
- In the Plot-appearance-dialog you can edit the project description. You can also set a file-path-stamp (not only time-stamp).
- In the Graph-appearance-dialog you can now place the Legend-Box more correctely: There are different buttons to align the box with the (current) borders of the graph. There is also an option to auto-align the box with several borders - This is useful if you change the graph-size or -position.
- On closing QtGrace you can now select "Save" which lets you save the project file under the current name or use "Save As..." to select a new name (since this is just for conveniance, you can not alter the project description here; the project description can be altered in the plot-appearance-dialog).
- QtGrace is able to import data from a binary file. You have to specify the exact file structure in a separate dialog. It is also possible to define the file structures for different binary-files that can be destinguished by their suffix. If done so, these files can be imported by drag-and-drop (for further details see below).

### 2. Usage of the decimal separator:

In the past I had some problem with different operating systems where the decimal separator is not '.'. Therefore I changed the behavior of QtGrace in responce to decimal separators in general. Internally always '.' is used. Only for display purposes and for data input something else is possible. In the Preferences->QtGrace-Behavior the decimal separator can be selected (at the moment only '.' and ',' can be used). The one you select will be used for every display of numbers (the display has been inconsisted before version 0.2.4) and for every input (keep that in mind: if you select ',' as decimal separator you have to enter all numbers with ',' as decimal separator and '.' will be ignored.). Numbers already stored in QtGrace will be redisplayed with the new decimal separator if you change the separator-preference.

For saving and reading of files '.' is used. In case of Drap-and-Drop or Paste the number of ',' is counted and if it is greater than the number of '.' in the file the user is asked whether ',' should be used for this one import-operation. For Copy-operations the default setting of the operating system is used for the decimal separator. If the user does Data->Import->Ascii... the '.' is used for import by default, but the user can select whether ',' is wanted (no counting of ',' or '.', just simple import as selected).

In some formulars ',' is used to separate different values (e.g. in the atan2-function). Therefore if ',' is used as decimal separator '|' has to be used to separate values.

### 3. UTF-8-support:

The original Grace does not support UTF-8-encoding. All supported characters/glyphs are part of the T1-font-encoding which is more or less hardcoded into Grace. This is useful in conjunction with LaTeX but not very helpful if someone wants to use characters outside the T1-encoding.

In the latest version of QtGrace the support for UTF-8-encoding is included in the following way:

The Qt-library supports UTF-8 for all input-widgets (like line-edit). Therefore it is possible to enter any UTF-8 character in any input-dialog QtGrace offers (as long as text input is allowed - some inputs only accept numbers).

The computation and the display of graphs and especially text in QtGrace is still (mostly) taken unchanged from Grace. Therefore it can not handle UTF-8 characters that are not part of the first 128 characters of the ascii-table.

To display any UTF-8 character QtGrace uses the font-library of the operating system and the painting methods of Qt.

In Preferences->QtGrace-Behavior you will find a setting for the file encoding. For all inputs UTF-8 is used; for loading and saving text from and to files the selected encoding is used. Every time data is loaded from a file (not only loading a project file) all text-entries are updated (therefore any unapplied text-changes/inputs are lost after data is loaded - sorry).

Please note, that at the moment only the output-devices that use a raster driver support the output of text with fonts other than the usual 14 Grace/T1-fonts fonts. The only exception is the svg-driver: Since svg-files are written directely with Qt, every font is supported. I hope to improve the support in the future, but this is not so easy, because it is not garanteed, that every font is present on every system. (This means for example that there is no text output with PS or EPS.)

Detailed description:

QtGrace saves every text-string in two locations. One location is used for displaying the text using as much of the original Grace functions as possible (let us call it the 'Grace'-version of a text-string). The second location is used to store the original version of every text-string. The 'original' is the text the user entered (or which has been loaded from a file) and it is always stored in UTF-8 encoding.

When text is entered via direct input in a dialog it is stored in the 'original'-location. Then the text is converted into a version that can be interpreted by the display driver. If Qt-fonts are not to be used (i.e. the original Grace-fonts are used) the original text-string is converted into the iso-latin-1 encoding, if QtFonts are to be used the text-string is just copied from 'original' to 'Grace'.

If LaTeX-commands are to be used: During the conversion the 'original' text is analyzed and the LaTeX-commands are replaced with the appropriate Grace-commands. (Remember: the original version is always stored in the 'original' location including the LaTeX-commands as entered without change.)

When text is loaded from a file the text-string is stored in the 'Grace'-loaction. This version of the string is considered as the original. To copy it into the 'original' location it is interpreted in the preselected encoding and converted to UTF-8. The preselected encoding is stored in every project-file and is used after loading text from this file. (If you open an old file with no information about the encoding used the one you selected in Preferences->QtGrace-Behavior is used.)

For interpreting the text-string in the original location the encoding that is set in Preferences->QtGrace-Behavior is used. When data is to be saved in a file the original-string is copied to the 'Grace' location and converted into the encoding set in Preferences->QtGrace-Behavior. Then the text-string in the 'Grace' location is saved.

After loading or saving the text in all string-locations is reconverted (encoding-changes and LaTeX-conversions are applied - which may cancel all unapplied text-changes as mentioned above; and again remember: the reconversion is done after EVERY load or save operation).

Changes when QtFonts as activated:

In every font selector the label on the left side saying 'Font:' will change to a command button and pressing on it will display fonts that are available for use with the Qt-drivers (This should include most of the fonts available on your operating system. This is not restricted to the T1-fonts in the QtGrace-folder.). These fonts are only used for printing when Qt is used. This is the case for the display/screen, for using the native printer dialog and printing to 'jpg', 'png' and 'bmp' files. The T1-standard-fonts are used for printing on all other devices (like 'ps'). At the beginning the combo-box will only show the standard fonts supported by the original Grace. If you want to add other fonts: click on the command button saying 'Font:' and select a font from the font dialog of your operating system (usually the font size can be selected here as well, but this setting is ignored at the moment).

When using the 'QtFonts'-option the Font-Tool will be considerably slower (I hope to improve this in future releases).
Using the Symbol-font will not have the same effect as it has with the T1-fonts: In T1 the Symbol-font contains the greek letters (only). In the Qt-fonts every font contains the greek letters (but not at the same positions as the latin-letters). That means if you want to use the QtFonts and latin and greek letters at the same time you have to enter the unicode-numbers of the greek letters or copy and paste the letters from the Font tool or use LaTeX-commands (see below). In Preferences->QtGrace-Behavior there is now an additional option to specify, that the Symbol-font is special. This is only available with QtFonts activated. If the Symbol-font is marked as special, the characters entered normally are sorted differently and replaced if the symbol font is used. This way the usage of the symbol-font is the same as with Grace.

I can not guarantee that all special font commands like "\s", "\S" or similar will work all the time (due to differences between UTF-8 and Ascii/T1-fonts). Using the LaTeX-shortcuts may also be unreliable while using QtFonts because the character positioning has been optimized for T1-fonts.

The Grace fonts and their ordering is used for the first Qt-Fonts. If new Qt-fonts are added to the list the Qt-Font-list will be longer then the Grace-Font-Liste. If a Qt-Font is used with a higher number then the amount of Grace-fonts this font can only be used with useQtFonts activated. If Grace-Fonts are to be used (use QtFonts off) there is no font with such a high number. Text in this font will be displayed in Times Roman. The QtFonts are stored in every project file. The original Grace-fonts are saved as well, but the font lists may be different.

Conversion of path-names to ascii-characters is done using the default system-encoding (as reported by the operating system), because this is necessary for the internal file-operation-functions.

### 4. LaTeX-support:

The support for simple LaTeX-commands can be activated in the Preferences dialog in Preferences->QtGrace-Behavior.

The LaTeX-support is meant for the input of simple LaTeX-commands declared by '$$' at the beginning and the end of the command (without'). Only text-input-widgets that are ment for comments/labels do accept the LaTeX-commands and only if the option is activated in Preferences->QtGrace-Behavior. This should be helpful to write formulas for people who know how to use LaTeX. For Example: You can enter something like '$$E=(\frac{1}{2}\pm\nu)\cdot\hbar\omega$$' and this command will internally be translated in the Grace-typesetting language (there is no real LaTeX-typesetter included - just some sort of makro-translator). At the moment the translation is one-way only. The original input is stored and you can switch between the original and the translated version. Usually the original will be shown. If you want to edit the translated text click on the label on the left of the text-input-widget. The text will be shown in red then. If you edit something in the converted version and click on Apply or press Enter while Immediate Update is on the text containing the Grace-font-setting-commands will be stored as original and your LaTeX-input is lost.

I did not copy every command from a LaTeX-handbook - I only included commands I thought could be useful and that are simple enough to include. (Take a look into ListOfLatexCommands.cpp if you want to know which commands are recognized at the moment.) Complex commands (like special braces like \underbrace or \overbrace) are not recognized at the moment and the overall translation is not completely fail-save. Don't use it in critical situations and save often. (If you enter a command and it is not recognized correctly try experimenting with spaces before or after it.) Nevertheless I would be very interested in your experiences in using this feature. I also would like to know which commands would be most useful to you if they were included. Font attributes are copied. Please notice: there is no font-command for making a font bold. Therefore characters that use the symbol font can not be displayed in bold. Sorry.

### 5. Binary data import:

To import data from a binary file go to: Data->Import->Binary...

This will open a dialog. Be aware, that you have to know exactly (!) how the structure of the file is that you want to open. You have to tell the import-filter the exact format once and afterwards you may chose to save this format-information to reuse it later (currently the format is saved in a specification file version 2; the old version 1 can still be read from QtGrace, but saved format specifications will always be version 2; Version 1 only consisted of numbers which where hard to read, version 2 contains comments to tell the user what different settings mean. Therefore the format specifications version 2 can easily be edited by the user.). As an example I have included the file-format-specification of wav-files: Click 'Load Format Settings' in the settings-menu and select 'wav_format.fmt' in the bin-folder or click 'Load Std. Import Settings' and choose the wav-format. To select the actual binary file click on 'Browse...' on the right hand side of 'Datafile:' (or drag-and-drop a file into the Datafile-line). By default it is assumed that the binary file also contains a header that has some information about the data present (e.g. this is the case for wav-files).

The first part of telling the filter about the file format is to define the header-contents (byte for byte). This is done by adding a token to the list (click on '+') and tell the filter the format of the token (usually this is the kind of numerical representation of a number in a C-like format). The 'Bytes' box is only used for 'Offset' tokens that are ignored during data import later. It is possible (but not strictly necessary for every file type) to tell the filter how to use the header-information via the ComboBox 'InputAs'. In case you have done something wrong you are able to delete a token by clicking on '-'.

By clicking 'TestLoad' you can check whether your input has been correct (I always recommend clicking 'TestLoad' since it is needed for some files). The 'File-Info'-tab contains the data read from the header.

The second part is setting the Data-Format. It is assumed, that the data is present after the header in the file as a stream of bytes (no additional information in-between). It is also assumed, that the data-points are either present one after the other or one channel after the other. You have to set the format of every channel present in the file and whether or not this channel shall be imported.

The last step is to set the destination for the import: set-type and graph-number. It is also possible for data and header to be present in different files. You may select both of them in this case. For the header-information two versions are supported yet: header-information in binary format or in the format of ini-files (like system settings: '[Data] t0=5 dt=0.1' separated by new lines).

Experiment with binary import on wav-files. This may give you a good idea of how I meant it to work.

You may import more than one set at once. In order to do so set more than one import-channel to the same column (like one 'X' and three times 'Y').

Beginning with v0.2.2 it is possible to select several files for binary import at the same time. Doing so, the import filter will assume the files to have the same format and import the selected data from every file into a new set (or new sets). You may also activate an option to tell QtGrace to look for a seperate header file for each data file. Otherwise one header is used for several files. If you select multiple data-files and no header files, but tell QtGrace, that header files are present in ini-format, then QtGrace will look for ini-files at the same location and with the same name as the data-file but with an ini-suffix. If you select a different header-format than ini you have to select at least one header for QtGrace in order to tell the import filter the suffix of the header file(s). If you select more than one header file for multiple data files and tell QtGrace that there are seperate header files for each data file, than the number of headers have to match the number of data-files. In this case the first header is used for the first data file, the second header for the second data file and so on. If the number of header files does not match the number of data files, then just the suffix of the first header is used and it is assumed, that the headers have the same name as the data files. If you do not select "separate header file for every data file", then the number of header files is not importand, always the first one is used. If the header format is not ini, then you have to select at least one header. If you select ini-format and select a header file, then the suffix of this header is used, but the contents of this files are assumed to be in ini-format.

One channel in a file can be declared as a trigger channel. This channel is used as a reference for the x-axis. You can use rising edge/falling edge or whatever edge is the first to cross the trigger-level and you have to set a trigger level if a trigger channel is selected. After the data import the x-position of the trigger-edge is detected and all imported sets are shifted to set the position of this edge to x=0. By default the trigger channel is not imported, but if you want it to, then select "Keep trigger channel" in the Data-Format-tab. The trigger channel is interpreted as a Y-channel.

There is also a binary-export-dialog for saving sets. I included a file format specification for these files as well ("grace_binary_format.fmt"). Please remember to select "Read Data until EOF" in the Data-Format settings if you operate with data files of different lengths and do not want to set the exact number of data points for every file.

With the new format specification verison 2 it is now possible to define a standard-input-format for binary files. These special format specifiers are stored in the bin-subfolder under the name "QtGrace_std_bin_format_*.fmt" with the "*" replaced by a user selected standard name. Files with this name in the bin-subfolder are loaded by QtGrace at startup to determine the format of (for you) common binary files. With this formats known to QtGrace it is then possible to drag-and-drop binary files into the QtGrace-Window to be loaded automatically. If a binary file is recognized during drag-and-drop QtGrace tries to find a matching standard import format (the match is done via the file suffix only!!). If one is found, then the settings in the format specifier version 2 is used to import data from these files. This is very conveniant if you use the same binary file format regularely. You just have to prepare the QtGrace_std_bin_format_*.fmt-file. In order to do so, just use the Binary-Import-Filter-dialog for one of your binary files and set everything like you need it to be for your binary file and try if it is imported correctely by pressing Apply. If everything works, use "Save Std.-Format" and select a simple name for the specifier (only a word, no suffix or anything, just the thing, that will go instead of the "*" in the format specifiers file name). Afterwards I recommend you to open the new specifier-file in the bin-subfolder with a text-editor and edit the file to include more channels, just in case you later have files with more channels than you used, when you set the import format.

The automatic import of files depends on the fact, that usually somewhere in the header the number of data points and channels is stored. Otherwise, the binary format has to be very simple to be understood by QtGrace.

If you have specified a std-bin-import-format for a data file and an associated header file, then please remember, that during drag-and-drop QtGrace looks at the files one after the other. This means, that if you drop a header file QtGrace tries to find the matching data file and imports the data. If you drop a data-file the associated header is searched and the data imported. This means that if you drag-and-drop header- and data-file then this data is loaded twice, because QtGrace tries to match both files. Therefore please only drag-and-drop the data-files you want to load, the header-files are found automatically, if the filenames match (and only the suffixes differ). Other naming shemes for header files are not supported at the moment.

Any suggestions for improvements are welcome.

### 6. csv-import:

To import data from a file with comma-separated values go to: Data->Import->CSV...

This will open a dialog. In the Filename box you may enter the name of the file (the complete path!) you want to load data from. Although: The usual method would be for you to click on "Select CSV file" and use the operating systems file selection dialog. After selecting a file or clicking on "Re-guess columns" the first lines (ending with a new-line-character) of the files are loaded and shown in the File contents box. You may also notice a "-#-#-#-#-#-#-#-#-" somewhere in this box. This indicates the separation between a header (which is ignored) and the actual data columns below.

On the right hand side of the dialog you can select the target graph data will be imported into.

In the middle of the dialog you have to set the file format yourself (since there is no standard for csv, the files are different depending on how they have been generated).

At first you have to set how many lines at the beginning of the file are to be ignored (please note, that these header lines have to be separated by newline-characters or they may not be recognized as actual lines). The Data-set-separator specifies the ending of every data point. It is assumed, that every point consists of a number of values and in the file the end of one point and the beginning of a new point is announced by a special character like a newline-character. A newline has to be entered as '\n'; a tab-character as '\t'; except this all separators have to be single characters! Different (column-)values of one data point are separated by the Column-separator; Strings are indicated by a text-separator-character at the beginning an the end of the string (internally the string separator for Grace is always " therefore the use of the Text-separator or " inside the strings is very dangerous).

After entering all these format settings it is strictly advised to click on "Re-guess columns" since this will show whether the import filter works correctly. The guessed column-formats are shown in the contents-box below the first six data lines below '...'. It is possible to use ',' instead of '.' as decimal separator during import operation (usage of ',' as a column- or Data-set-separator is not advisable in this case). The guessing also sets the presumed number of data sets present in the file (=Number of data columns-1) and the formats in the column import selectors above the Apply/Accept/Close-buttons. The standard-import targets are set to: import first column as X-value for all new sets, import all following columns as Y-Values for new sets. If you set higher target columns (like Y1, Y2, ...) the set-type of the new sets will be adjusted automatically in order for the set to represent enough columns. If you need more sets than the guessed ones you can alter the "Number of sets to read". Strings can not be imported, they can only be recognized as columns between real values.

In short: suggested workflow:
Select a csv-file; Enter the separator-characters and the number of header-lines and press "Re-guess columns"; Set the import-format and import-targets for every column in the file; Press "Apply".

### 7. Digital filtes:

I noticed the lack of proper low-pass or high-pass filters for measurement data in Grace. Therefore I included a filter-dialog that uses fourier-transformations and filter functions in frequency space. The user has to select source and target sets and what kind of filter is to be used and how to realize this. Then the cut-off-frequency/frequencies and the order of the filter have to be selected (hint: a Brickwall-filter is a filter with infinite order). There has to be a linear relation between the current X-axis of the selected sets and the time in s. The formula to convert the x-axis into time in s has to be specified (if a wrong faktor is given here the selected cut-off-frequncies are not correct). Since internally the filtering is done by multiplying a filter function with the frequency-values in frequency-space (FFT data, multiplication, inverse FFT) and the fast fourier algorithm is used the number of data points in the data sets have to be a power of 2 (at least if you are not using the fftw-library). In order to arrange it to be so the method for extending the number of data points has to be selected (to increase the number of points to the next power of 2). If interpolation is selected oversampling may be selected. For nonperiodic data it may be helpful to select the "absolute value"-option in order to remove phase-shifts. (Please note, that starting with v0.2.6 the sign of the phase of the transfer function has been changes. In previous versions the filter violated causality. Now the filtered data is usually shifted in positive direction in time.) In case debug is selected intermediate data in the procession of the data is preserved (like the filter function and the fourier-transformed data).

Simply experiment with this dialog and you may see how it works.

It is also possible to use the filters in scripts (=Commands-dialog): Either you do a filter and use the "Translate selection to commands"-button in the UnDo-List or you enter the following command in the Commands-dialog
`#QTGRACE_SPECIAL FILTER_SET <nr_of_source_sets>,<nr_of_target_sets>{<first_source_graph>,<first_source_set>;<second_source_graph>,<second_source_set>;...}{<first_destination_graph>,<first_destination_set>;...}{<type>;<realization>;<order_first_cutoff>;<order_second_cutoff>;<absolute_values>;<debug>;<point_extension>;<oversampling>;<region_nr>;<negate_region>;<first_frequency(Hz)>;<second_frequency(Hz)>;<chebychev_ripples(dB)>;<x_transformation_formula>}`
You have to enter all entries in this command, although depending on the settings not all entries are used. All entries (apart from the x-transformation-formula) are numbers. Please relate to the Filter-dialog for what number represent what: on check-boxes: 0=not checked, 1=checked; on combo-boxes: first entry=0, the further below in the combo-selection-list the higher the number (e.g. "Band-Stop"=3); for the restriction: no restriction=-1, inside graph=-2, Region0=0, Region1=1 and so on. Example:
`#QTGRACE_SPECIAL FILTER_SET 1,1{0,0}{0,1}{0;1;2;2;1;0;0;0;-1;0;10000.0;100000.0;10.0;1}`
This means a 10 kHz Low-Pass-filter on set G0.S0 and the result will be written in G0.S1. A second order butterworth-filter using only absolute-values is used and the x-values are already in time in s (i.e. x-transformation-formula="1" - see last entry). No oversampling is used and the points are to be interpolated to the next power of 2. No debug-output, no restriction (the "-1"-entry), no negated restriction. The second frequency is entered as 100 KHz with order 2 and the Chebychev-rippels are entered as 10.0 dB but these three values are unused.

Suggestions for improvements are welcome.

### 8. Output-devices:

This sections gives a short overview of the different output-formats QtGrace can use. You can set an output-device via "File->Print/Export Setup...". Do not forget to set the output-dimensions and resolution and press Apply. An output into a file is initiated by pressing "Export to File" in the File-menu and in the File/Export Setup.

- Portable Document Format (PDF)
  This device produces a screenshot in pdf-format. The advantage is, that you get exactely the picture you see on the screen. The disadvantage is, that you get a limited resolution and a large filesize. See also the Haru-PDF-library below.
- Scalable Vector Graphics (SVG)
  This device produces an output containing vector-graphics. The original Grace-SVG-driver produces SVG-files that are outdated (i.e. can not be displayed by most modern svg-display-programs like firefox or safari-browser). Therefore I deactivated the old SVG-driver and activated the SVG-driver of Qt. This should produce up-to-date SVG-files.
- Joint Photographic Experts Group (JPEG)
  This device produces a raster-graphic in the well known jpg-format. This is like a screenshot in a specified resolution. Drawback is the occurance of compression-artefacts. PNG-format should be preferend for files consisting of lines and simple geometric elements.
- Portable Network Graphics (PNG)
  This device produces a raster-graphic like jpg, but in png-format. This should be the prefered raster-graphic-format, because its compression handles the output of pictures consisting of simple geometric elements very well.
- Windows BitMaP (BMP)
  This device produces a Windows-Bitmap-file. Like JPG and PNG this is like a screenshot, but uncompressed (therefore it has a very large file size).
- PostScript (PS)
  Since postscript is a vector-graphic-format it supports only the classical 14 T1-fonts from Grace and no QtFonts. Anything else should work.
- Encapsulated PostScript (EPS)
  This behaves exactely like postscript, but also includes information about the bounding box of the page.
- Maker Interchange Format (MIF)
  Outdated format. Used seldomly. Should behave similar to postscript.
- Portable Anymap (PNM)
  This is a format in binary encoding. This device does not support non-Ascii-characters (at the moment). Since I think that this format is not very common, I do not intend to change anything here.
- Grace Metafile format (Metafile)
  This filetype is mainly used for debug-purposes and useless for the normal user.
- Portable Document File - Haru-library (PDF(Haru))
  Only available if the Haru-library is available as dynamic or static library. It produces pdf-files as an output containing text and lines and not only pictures. This works for all text in the Grace-standard-fonts and not with the QtFonts. Fill-Patterns and Draw-Patterns are not supported by the Haru-PDF-library. The output-quality is very high!

### 9. Undo/Redo:

Starting with version v0.1.3 I have included a feature to Undo and later Redo some operations the user does with graphs and data sets. It is deactivated as a default because it is of an experimental nature at this point. It will be activated as a default in a later release when I am sure that no harm is done by this function. To activate it: Go to Edit->UndoList and set the "Undo active"-option. This option will be saved in the ini-preference-file and will be restored at every startup of QtGrace (keep this in mind: if you activate Undo/Redo, it will stay active until you deactivate it again!). I do not recommend activating this option for Graphs that include large datasets (>100.000 points) since it may consume a lot of memory because the undo saves up to 100 states of your work. Since you now have been warned, let us get to the nice stuff: What is possible with this feature?

When "Undo active" is activated, every supported operation is recorded as can be seen in the UndoList. In this list you will find a description of what you have done (the last one is the one on the bottom) and at the beginning of one line the letter 'U' or the letter 'R'. Actions marked as such are the actions that will be Undone or Redone when you use Edit->UnDo or Edit->ReDo respectively. You may also select one or more actions in the list and click on "Undo" below the list. Undo will undo the actions form the last one upwards. Redo will undo the actions from upper most selected action downwards. Every UnDo- or ReDo- operation is considered as some sort of toggle-operation. After an action has been undone a "(*)" will appear at the beginning of the description in the UndoList. This means, that you already have made this undone. Clicking on it and clicking Undo afterwards will effectively redo it. This is also the case, when you use Edit->UnDo. An action that has already been made undone will be redone, when it is reached by the Edit->Undo-operation. Doing a normal operation in QtGrace will set the 'U'-marker to the last operation in the list. This means that by clicking Edit->UnDo the last operation will be made undone and the 'U' will go to the operation before this one. The 'R' for Redo will then be set at the last operation. Clicking multiple times on Edit-UnDo will set the 'U'-marker one operation back(=upwards) until the end of the list is reached or a new normal operation is done in QtGrace. You can always do a manual undo via the list. Manual operations do not alter the 'U'-marker. Using Edit->ReDo will Undo the Undo-operations until the end of the list is reached. Give it a try and you will see what I mean. The shortcuts Ctrl+Z and Ctrl+Shift+Z are used for Undo and Redo. Please note: In Grace Ctrl+Z is normally used for Zoom-operations. I use Ctrl+Z for an undo and Alt+Z for zooming.

One further warning: Operations that change the ordering of the sets in a graph or the ordering of graphs (like swap-operations or pack-sets) are a bit dangerous if you do manual undo. At the moment the undo-function does not check whether the set-number has been changed since the operation you want to undo. Doing a chronological undo with Edit->Undo should be save, manual undo can sometimes have unexpected results.

Simple description of what Undo/Redo does: Undo does set the state before the action has been performed, Undo again will set the state after the action has been performed. (Undo and Redo are only different with respect to the chronological order in which operations are made undone.) Undo/Redo does usually NOT really do the action again (there are some exceptions), only data is restored. Please use the manual undo-operation only for emergencies or if you really know what you want. Don't manually undo and redo several operations in arbitrary order to often, because unexpected results will be guaranteed. Chronological Undo via Edit->Undo or Edit->Redo is preferred.

Any suggestions are as always very welcome! Bug-reports as well.

### 10. Copy/Paste/Drag and Drop:

For an improved interaction with other software (especially spreadsheet-applications) I implemented copy and paste as well as drag and drop into QtGrace. In order to work it is necessary, that the user only uses data in the usual spreadsheet format (multiple columns and rows without text-comments; only comments starting with '#' are allowed). It is for example possible to select a block of cells containing numerical data in a spreadsheet-edit-program and drag it over the QtGrace-window and drop it. It is also possible to copy the same data into the clipboard (Crtl+C) in your external application and click in the draw-area of QtGrace (a graph should be selected) and press Crtl+V. By doing so, the data will be imported as one or multiple new sets (depending on the shape of the data: empty lines are interpreted as a separation between sets and if more than two columns are present, the first column is interpreted as x-axis and the other columns are interpreted as the y-axes of several sets) in the current gaph. You may also select the "paste"-option in the context menu summoned by right-clicking in any set-list. Internally the data to be imported via drag-and-drop or paste is copied in a temporal file and then loaded via the usual ascii-import function. You may also drag and drop files directely from your file-browser into the QtGrace-window. If you select an ascii-file (or multiple files at the same time) the data is simply loaded via ascii-import. If the file is recognised as being binary (this is done on the basis as guesswork ;-) ) the binary import filter dialog is summoned and the user has to select the import-parameters (i.e. tell QtGrace the data structure of the binary file) to start the import. If a standard-binary-import-format has been set and the file dropped into QtGrace matches the set file extension, then the binary file can be imported automatically (see also the chapter about the binary import filter).

If you drag and drop a QtGrace project file (*.agr) a special dialog is shown that lets you select specific sets from the project file to import or open the whole file. This dialog can also be opened in the open-project-dialog.

A drag-and-drop operation from QtGrace to another application is not supported (no drag-out, only drag-into).

To get data from one or several sets from QtGrace to another program the user has to use the clipboard: select the data sets concerned and right-click in any set-list. This summons the context-menu and the user has to select the "copy"-option. The data is stored in the clipboard as ascii-data and can be paste in any other application that is able to use the clipboard (e.g. any spreadsheet editor). As decimal separator the default setting of the operating system is used.

On an experimental level some files in the LabView-Diadem-format can be imported by drag-and-drop (very rudimentary). The same goes for trace-files (*.dat) from Gould-oscilloscopes. Use at your own risk and the import may be incomplete at the moment (work-in-progress).

### 11. Zooming:

#### Zooming in general:

In XmGrace/Grace as well as in QtGrace you can zoom in and out via the buttons Zz and zz in the tool bar on the left hand side of the main window. If the axis-scaling is not linear (like logarithmical) the zooming can result in invalid values along the axis (like negative values for logarithmic scale). QtGrace does the zooming for nonlinear axes a bit differently so that the axes stay inside appropiade limits. The same goes for panning of the graph-area.

#### Zooming multiple graphs:

On the upper left hand side of the QtGrace-window there is now a new graph-selector. This selector shows all graphs present and the currently active graph is selected. Any change in graph-selection/activation is represented here. You can also change the current graph by using this selector. The main purpose of this is to be able to select more than one graph for zoom-in and zoom-out. All zoom-operations that are shown in the toolbar use this selector for determining on what graph(s) they should be used. Please mind, that internally Grace supports only one active/selected graph. This one is usually shown with focus-markers. This new graph-selector will only work with the zoom-buttons in the toolbar and is meant for people who use superimposed graphs and want to zoom in and out simultaneously.

#### Zoom-Slider:

I added a zoom-slider in the toolbar on the lower left hand side of the QtGrace-window. You will find it just above the 'Exit'-Button. The slider-value is changed logarithmically and can be set between 0.1 and 10.0. (The internal values of the slider range between -100 and +100 and the actual zoom-factor is calculated by 10^(value*0.01). The current value of the slider is saved in the QtGrace-ini-file as "PageViewZoom". (If you have problems resetting the page zoom to 1, set this value in the ini-file manually back to 0. To reset the slider to factor 1.00 you may use the shortcut 'Crtl+1'.) The setting only effects the visual display on screen. Print-commands are unaffected by this. There is also no Undo for changing the slider setting because this in nondestructive. The setting is saved when QtGrace is closed and will be reset to the last value at the next startup. I intended this for people who have uncommon display-resolutions. QtGrace calculates the size of the visual page according to the resolution of the computer-screen used. This is ok for most users. It is very inconvenient for people using notebooks with small screens (like 12") because they will not be able to see the whole page. With this new zoom-slider you can reduce the page size for the display according to your needs. You are still able to produce hardcopies (in Print or in Files) with an exact resolution.
Please note: The Zoom-Slider is deactivated if QtGrace is started with the '-free' option, because it is useless in this case!
The 'Fit'-Button below the page-zoom-slider sets the zoom-slider in order to fit the page-size to the available space of the window. (Thank you jhenin for suggesting this and supplying the source-code which I modified a bit.)

#### Zooming with mouse-wheel:

In the preferences you can activate the zooming with the mouse-wheel. If you scroll the mouse-wheel while the cursor is inside a graph you can zoom in and out a the cursor-location. The graph does not have to be the current graph for the zooming. Please note, that the selection ihn the graph list is not used for mouse-wheel-zooming. Just one graph is zoomed. If the cursor is outside a graph while the mouse-wheel is used, nothing will be done.

### 12. Color(palette) management:

In the original Grace it was possible to use more than the 16 colors preset in Grace, but you had to enter them in the file header manually. I wanted to have a more convenient method.

In the Preferences-dialog you can change the current Color palette used for the project. In the upper part you can select a color from the current palette and edit it. You may enter the red/green/blue-color-components and the color name. Below you will see a preview of the edited color. You have three options for the single color: delete the color with the specified number from the palette, add the color as a new color to the palette or replace the color with the specified number with the new color (Edit color). The option 'Define color' lets you select a color from the color-selector-dialog of your operating system. If you want to add this new color to the current palette use add or edit (to replace an existing one).

You may also edit the whole palette in one go. You may set the palette for example to a specified spectrum of colors. You may use predefined spectra or set your own spectrum. By selecting 'Custom...' and setting a number of path-points you may define the spectrum by specified colors that have to be part of the spectrum. For each path point you have to specify a color via 'Current path point' and 'Color'. Below you will see a preview of the spectrum. Please note, that the first two colors in the spectrum will always be white and black because otherwise you will get very irritating results. If you don't want this: set a spectrum and edit the first two colors afterwards (but consider yourself as having been warned).

Please note also: everything you edit in the Color management dialog only effects the color-palette of the color selector in this dialog. If you want the change to take effect in the current project you have to click Apply or Accept (no immediate update here!).

### 13. Commands / Scripting:

I included an option in the Undo-List-dialog: If some of the entries in the undo-list are selected the button below the list may be pressed. This will convert the undo-entries into appropriate commands in the Command-dialog. By doing so it is possible to record a script of what has been done (Do something in the normal way while Undo is active. Then afterwards select the actions that should make up a script and then press the button. In the Commands-dialog you may then alter the commands, save and load them.). Unfortunately this feature is still incomplete at the moment. Loading and saving data is not fully supported yet. The scripting works concerning style-changes in things like Graph-Appearance, Set-Appearance and so on.

In the commands-dialog I inserted a set-selector for source and destination set and a new command-button: "Replay replacing set-Ids". By pressing this button the list of commands is executed as would be the case with the Replay-button, but in contrast to this every set-id in the command is replaced by the selected ids (separated in source and destination). This is very useful for scripting complicated commands like regression or filtering.

I also included an option to use special let us call them "clipboard-commands": remember value (including the last formula used in fits or for evaluate expression), add/multiply/substract/divide by last or remembered formula/saved formula/saved value. This can be used for example for generating scripts to remove offsets and process measurements: load measurement (without script) and define a region for the offset-correction (an area where your signal is zero, but background signal is not zero), then use a script command for regression in this area (maybe without displaying the result); the resulting formula is automatically remembered internally as the last formula; then use the special command "Minus last formula" to substract the offset from the complete set; following this you may for example use the filter (scriptable as well). (I have used this scripting method to remove the offset and used the filter on 100 sets at the same time by only one click on the "Replay replacing set-Ids"-button.)

Concerning "Replay replacing set-Ids": For some complicated scripts I included options for the set-ids in the scripts: If a set-id is given in the usual way (e.g. g0.s0, please do not use a shortened form here) it is replaced by the selected set-id. If you do not want an id to be replaces write a '$' after it (e.g. "G0.S0$.Y", not "G0.S0.Y$" or "G0$.S0"); in this case the operation will be done with the same set every time regardless which sets are selected (like the standard "Replay"-button does). If a '#' is typed after a set-id the given number is taken as the first id to be used with the first selected set, but the number will be increased for every other selected set. For example: if you select S0, S1 and S2 in G0 as source and destination and have a command like "G0.S0.Y=G0.S0.Y+G0.S3#.Y" and click on "Replay replacing set-Ids" then the set s3 is added to set s0, the set s4 is added to s1 and s5 is added to s2. These extensions will only work in the Commands-dialog if "Replay replacing set-Ids" is used (nowhere else!).

I also included an option to get the set-id or graph-id: Type S# or G# to get the number, i.e. if you select a source set S5 and use S# in the commands somewhere you only get a 5. This is useful if you did feature extraction and want to use every feature-value in the list with a different set: A formula like x=x-G0.S5$.Y[S#] works in this case. This type of formula can also be used in the Data->Transformations->Evaluate Expression-dialog (without the $). Example: Take some measurements and do Feature-extraction: zero-crossing. Now you have your measurements and a new data-set containing the x-value where the measurements cross the x-axis. To shift all measurements in order to cross the x-axis at x=0 select every measurement set in source- and destination-list in the Evaluate-expression-dialog and type: x=x-S7.Y[S#] (the S7 should be the number of the last set, i.e. the one with the zero-crossing-values in it, just replace the 7 with the number of measurements you have) and press apply.

If you need a new set or a new graph, please type S0N or G0N in a command. The number in the id is up to you and is used to refer to the same new id every time you type this command. If you are using this in the commands dialog or the evaluate expression dialog, then the new set or graph is only generated once, even if you selected 50 sets to work on and the command(s) you entered are evaluated 50 times. The set or graph is generated at the first time and the set- or graph-id of the new set or graph is used the remaining times. If you press Apply again, new sets and graphs will be generated again. You can use G0.S0N and G0.S1N and this will generate two new sets in graph 0 and you can work with the identifiers G0.S0N and G0.S1N like with usual set ids. If you use G2N a new graph will be generated. If you use G2N.S3 it is the same as G2N.S3N and it reults in a new graph and a new set, but they are not treated equally if you use both ids in one commands (or list of commands). Then one new graph, but two new sets will be generated. For example: if you have a graph G0 and nothing else and use something like G0N.S3 you will get a new graph G1 and a new set G1.S0. You can refer to this new set as G0N.S3 or G1.S0 and both should work. For new graphs and their sets please use the id you used to create them. If you just create a new set in an existing graph, it is ok to use the usual set-id as well. For example: you have a graph with S0, S1 and S2 and use something like S0N. The internally S0N is always replaced by S3 (the next unused set-id). In commands after the generation of the new set you may then use S3 normaly, because S3 exists then (but be aware of one thing: if you use replay-replacing-set-ids then S3 is replaced and S0N not). You may also use S0N if you like to refer to S3. It does not matter in which order you enter the new commands, just the name is important. If you use S1N and afterwards S0N, then S1N will be the first new set and S0N the second (even with different numbers in the id) because QtGrace does not look ahead. You may as well use an id like S1371N and just get something like S3 as a new set. The number is just to refer to the new set always by an unique identifier. (I hope this was understandable.)

I included an example on the advanced scripting. Try this and you may see how the advanced scripting works.

### 14. Comments about the font size:

Because the coordinates in Grace/QtGrace are usually relative to the smaller page-dimension (viewport-coordinates) there is no simple transformation formula between Grace/QtGrace and other applications. Let us assume a page in landscape orientation with the x-y-dimensions a x b in pixels (like 792 x 612 pixels for a Letter-page in 72dpi). In this case b is the smaller dimension and Grace/QtGrace will scale everything in relation to this value (viewport-coordinate '1' corresponds to b pixels in this case; generally: viewport-coordinate '1' corresponds to the smaller page dimension).

In comparison with other applications which give font-sizes in points (pt) I have derived a rough formula for converting font-sizes:

(Grace-char-size) = 445/9*fontsize(pt)*resolution(dpi)/(lower page dimension in Grace)

Or for example in two simple cases:
(Grace-char-size) = 5.817*fontsize(pt) (for letter-pages in 72 dpi)
(Grace-char-size) = 5.983*fontsize(pt) (for A4-pages in 72 dpi)

If you use a letter-page in 72 dpi and want a font-size of 20 pt you have to set the char-size in QtGrace/Grace to 116. As mentioned before: This is a rough conversion based on experimental values. Suggestions for improvements are welcome here as well.

### 15. Further regression options:

For the regression I created the possibility to generate sets with an arbitrary abscissa. Like with "Create set->by formula" you may now enter values for a paramter $t and a formular that generates x-values form $t (default: "Load x as $t"). In this way you may for example generate sets with x-values increasing as powers of 10 ("Load x as 10^$t" and set start=-5 and stop=5 for x-values between 0.00001 and 100000) which is handy for logarithmic scaling of the x-axis.

This new option is also included in the NonLinearFit-Dialog.

I also included the possibility to just do a regression without producing a new set. Just select "Load: None". This may be useful if you want to use the regression inside a script.

In the same way the filters can be used in the Commands-Dialog you may also use the regression by the following command (you may also use the UnDo-List to automatically generate a command for a script):

`#QTGRACE_SPECIAL REGRESSION <nr_of_source_sets>,<nr_of_target_sets>{<first_source_graph>,<first_source_set>;<second_source_graph>,<second_source_set>;...}{<Type_of_fit>,<restriction>,<invert_region>,<nr_of_points>,<Load>,<start>,<stop>,<x_$t_formula>}`

Like with the filter-command (see above) please refer to the regression dialog on what numerical values to enter. Example:

`#QTGRACE_SPECIAL REGRESSION 1,1{0,2}{0,4}{1;-1;0;250;2;-8.0;-1.0;10^$t}`

This will do a linear regression on set G0.S0 and save the result to G0.S4. No restriction is to be used and no inversion. The new set will have 250 points and the x-values will be calculated via "10^$t" with $t ranging from -8 to -1 which results in x-values from 0.00000001 to 0.1. The Load-options is 2 here which means, that the new set will be calculated by a function.

### 16. Further interpolation options:

In the Interpolation-dialog I included a few extra options: it is now possible to select a set from a diffent graph as the source-set for the new abcissa.
There is an option to increase the setlength to the next power of 2 (if the setlength is already a power of 2 nothing is changed). If this options is activated, the field for entering the new length is disabled.
For sampling you may now select "Linear in original bounds". This will disable the fields for Start- and Stop-entry and take the minimum and maximum values of x as start and stop. The new set will have the new length as entered (i.e. the value entered in the Length-field or the next power of 2 if this option has been selected). This is different from the Grace-standard-option "Linear mesh" in combination with the "Strict"-option. These settings can reduce the actual length of the interpolated set if start and stop are outside the original source bounds.
The last new option "Expand bounds, keep stepping" will pad the original set with new points (or remove points) by extrapolating the set at the beginning and the end in order to increase (or decrease) the setlength to the Length entered.

### 17. Fill area between sets

In QtGrace it is possible to fill the area between two sets (in Grace only the area between a set and y=0 or y=ymax or other constant values can be filled).

To do so open the set-appearance-dialog for the first set and go to the Line-Tab. Select Type="As polygon" in the Fill properties and select the second set as Polygon base set.

Please note: This option is specific for QtGrace and will not be used if the file with this filling-option is opened in the original Grace.

### 18. Line-Style-Selection/-Change

I want to start this section with a warning: I do not recommend using the options to change the line-style-setup. Only use this if you absolutely have to. The predefined Grace-linestyles should be enough.

You can find the linestyle-selection in the Preferences-dialog. In this tab you can edit different dash-patterns of the current list of linestyles/dash-patterns.

You have to modify each linestyle separately and press one of the command buttons (Edit, Insert, Append) to store the modified linestyles in the list in this dialog. To make your changes effect QtGrace itself you have to press Apply (or Accept). Otherwise your changes will be lost if you close the preferences-dialog.

At the top of the dialog you will find a list with four entries: Current, from project file, from ini file, Grace default. These are the four linestyle lists QtGrace knows at the moment.

"Current" is the list currently used to display lines. If you edit something here it will immediately show in your plot after you press Apply (or Accept). The current list of linestyles is saved into the project-file. On loading a project file the current list of linestyles will be replaced by the list found in the project file to get the same display as was shown when the file was created. If no list of linestyles is stored in the project file, then the list from the ini-file is used.

"from project file" is the list loaded from the project file (if one was present in the file, otherwise this should be the same as the list from the ini-file). This entry is used as a backup in case you edited something and want to go back to the last default of this project.

"from ini file" is the list loaded from the ini-file used to store all general setting of QtGrace. This list is a fallback-option used, if no list of linestyles is stored in the project file.

"Grace default" is the list of linestyles traditionally used by Grace. This list can not be edited - just examined and copied.

In the second line of the dialog you will find a usual linestyle selector. Selecting one of the dash-patterns here will show you the settings for this pattern: the position in the list of patterns, the length of the definition (how many black and white blocks) and a representation of the elemental blocks for this pattern. Every pattern is defined by a number of blocks (like pixels) in either black or white. You can change the color of a block by clicking onto one of the rectangular fields below the "Length" selector. This will just change the current display in this dialog to show you how this edited linestyle would look like. To actually change the list currently selected, you have to use Edit, Insert or Append. Edit changes the linestyle at the currently selected position, Insert moves all following linestyles one number downwards and inserts the newly edited linestyle. Append just appends the new linestyle at the end of the list. Every editing just effects the list currently selected. You may also delete some linestyles or change the order by using Up or Down to move the linestyles inside a list.

Please note, that editing the "from project file"-list is (in most cases) useless, because this list is not used and not saved (it is just ment as a backup). Editing the "from ini file"-list will change the general fallback default list for the future. Changing the Current list will take effect immediately and these settings will be stored in the project file on the next save operation.

To copy one list, you have to use the buttons "Use these linestyles as current" or "Use these linestyles as current and general defaults". In this way you can for example reset the linestyles to the Grace-styles. Using just current, means, that this effects only the current project. With General defaults, this will also effect the linestyles stored in the ini-file.

### 19. The Preferences-dialog

QtGrace starting from v0.2.5 has a largely extended Preferences dialog.

The first tab (Grace) contains the standard preferences from Grace. The tabs QtGrace-GUI and QtGrace-Behavior and Miscellaneous contain specific options for QtGrace, the Defaults-tab contains the defaults used by QtGrace to initialize new items and the last two tabs are the Color-Management and Line-Style-Selector (see separate chapters for these two tabs).

One important thing to remember about the Preferences dialog: The Apply/Accept-buttons do effect the tabs from Grace to Miscellaneousa and not Defaults/Linestyles/Colors. These tabs have their own Apply/Accept-buttons. This is for safety in order not to change something involuntarily.

The GUI-tab and the Behavior-tab contain settings about the behavior of QtGrace and about the appearance of the dialogs. You can set here what encoding and what decimal separator you want to use. You can also set whether you want to use the QtFonts and whether you want to use the LaTeX commands. Immediate updates let every change you make immediately be represented in the plot. The drawback is, that you also get a lot more entries in the undo-list. You can select the font used for all dialogs (or reset it to the systems-default). Usually the background of the main Window is of the same color as any dialog. The plot area is usually white. You can change the background-color of the widget around the draw area to the Plot/Page-background-color or any other color you like. The other options should be self-explanatory.

The interface customization concerns the main dialog of QtGrace. You can activate or deactivate different features in the tool-bar on the left hand side and edit what is displayed in the status bar on the right hand side.

The gui-settings at the bottom of this preferences-tab take effect after you restart QtGrace. This includes for example the setting of the dialog language (please note, that appart from english only german is listed here at the moment, but the german translation is faaar from being complete - I will improve this, when I have some time - maybe next release). The default printing device is used as a standard setting for the print setup. You may also select "Last selection" which means, that the setting you used the last time will be set at the next restart of QtGrace.

You may also select here the default-project-file QtGrace uses if you restart QtGrace or when you do File->New (this setting has an immediate effect: after pressing apply the file that is loaded when you do File->New is the one that is set here). Please note, that the default file has be placed in the bin-subfolder. Also keep in mind, that the settings in the Defaults-tab only effect new items. The settings for the first graph and for the plot are stored in the default file that is loaded on startup. If you for example want to change the default fonts everywhere, you have to alter the Default.agr-file and the settings in the Defaults-tab.

Finally there are the settings about the size and position of QtGrace on startup. You can set the current size and position as default if you like or set some specific values. To take effect you have to press Apply, close QtGrace and restart it. Closing QtGrace is important here, because these settings are stored in the ini-file and this file is written to only when QtGrace closes normally. For savety reasons the x- and y-values that can be set here are limited to 90% of your screen size and the height and width is limited to your screen size. Please note, that if the set dimensions or positions do not fit your screen, your operating system might ignore some of these settings.

In the Miscellaneous-tab you can choose to open help-files in a specific browser (instead of the defult browser of your system). The Show/hide workaround is sometimes needed on Linux-system, but I think it should not be neccessary. You can also set, that you want to use a print-command instead of the native printer dialog of your operating system. For the physical printer there are two output-quality options. Either use the screen-resolution or the much higher printer resolution. If you activate the HD-output-option, then the maximum printer resolution is used. Please note: the higher resolution results in finer fill patterns. You may also set a few other things that should speak for themselves. You can alter the settings about the external libraries libFFTW3 and libHaru.

If the external libraries are not compiled in statically and you want to use them you have to set the path to the dynamic libraries (*.dll on Windows and *.dylib on Mac OS X) here. After library files have been chosen, QtGrace checks, whether the functions needed are inside the selected libraries. If this is the case you should see a green box stating, that the library is usable. If you want to use it, you also have to check the "Use FFTW3"- / "Use libHaru"- Box. If the libraries are included statically during compilation, then you only have to choose whether you want to use them or not.

The Defaults-tab contains the settings used when new elements like graphs or sets are generted. There are different defaults here: the Current ones used at the moment, the ones loaded from the project file, the ones loaded from the ini-file and the Grace-default. The defaults are stored in every project file, but there is also a set of defaults stored in the ini-file. QtGrace uses the defaults stored in the ini-file. The settings loaded from the project-file are remembered and saved in the file again, if you resave it. The current settings will be saved in the ini-file if you close QtGrace. To alter the defaults stored in the project file, use the button "Use there defaults for this project file". To replace the current defaults use the button "Use these defaults as current defaults". I hope this is understandable for you and you understand why I did it this way: I wanted to have just one set of defaults (the one in the ini-file that is used constantly), but I did not want to lose the old settings. Suggestions for improvements are always welcome!

### 20. Additional selection options

In every popup-menu (summonded via right-clicking) for graph- or set-lists there is a Selection-item at the bottom.

There are now additional options. Every one of the following options is an additional selection - already selected sets or graphs will be kept selected.

- Select even This selects every set (or graph) in the current list that has an even graph-/set-id. Please mind: this relates to the id, not the place in the list. If you have a list like {S0, S1, S2, S4, S5, S6} and use "Select even", then afterward S0,S2,S4 and S6 will be selected - it does not matter, that S3 is missing.
- Select odd Same as above, but with odd graph-/set-ids.
- Select n-th (from n0) This is a general periodic selection. With this you can select every n-th set in the list, starting from a specific start-index n0. This also relates to the graph-/set-id not the place in the list. This is for example very useful if you imported several measurement channels from different measurements and you have an order like {Set0=M0,Ch0; S1=M0,Ch1; Set2=M0,Ch2; S3=M0,Ch3; Set4=M1,Ch0; S5=M1,Ch1; Set6=M1,Ch2; S7=M1,Ch3; Set8=M2,Ch0; S9=M2,Ch1; Set10=M2,Ch2; S11=M2,Ch3} and want to select only Channel 2. Then you have to enter n=4 and n0=2 (every fourth, because every measurement has 4 channels in this example; n0=2 because we want channel 2).
- Select visible This selects all graphs/sets that are currently visible.
- Select invisible Same as above, but with invisble graphs/sets.

### 21. Server mode (by Nimal Kailasanathan)

QtGrace can now communicate with external programs (clients) using a QTcpSocket connection. QtGrace is setup as a TCP socket-based server using the QTcpServer class from Qt.

In order to communicate with QtGrace, QtGrace has to be started in ServerMode with 2 extra arguments. The first argument is the QTcpSocket port used to write data to QtGrace from the client, and the second argument is the port used to read data from QtGrace to the client (QtGrace uses the LocalHost as address). It's a requirement that the client uses a QTcpSocket connection to communicate with QtGrace. In the QtGrace client example a communication protocol has been implemented for the user to see how to read and write from/to QtGrace via a QTcpSocket connection (see qtclient-folder in the examples-folder).

In conclusion, QtGrace acts as a server when it reads the data from the client and QtGrace is therefore processing the data. When QtGrace sends data, QtGrace is using a new socket to communicate with the client. Therefore the client is processing the data received from QtGrace.

Please refer to the Qt-documentation for further information about the QTcpSocket communication protocol.

In the following section the low-level communication protocol in the QtGrace client example is explained (I will not give a description on how the TCP-communication and the internal states work.)

Each communication with the client is initiated with a command to tell QtGrace how to handle incoming/outgoing data. The client can send the following 10 commands to QtGrace (please see the communcationsProtocol.ccp file in the QtGrace client example):

- PLOT_INFO, number: 1 The first command is used to send the plot info (colour of plot, point size, line width etc.). In order to send the plot info command the following function is used: `// Clear the plot and send the graph and set information to QtGrace cleanPlot();`
- WRITE_DATAVEC, number: 2 This command is used to set the communication function to data mode and is required as the first command before sending data. After sending command 2 we have to send command 12 in order to tell QtGrace that all data has been sent from the client.
- WRITE_DATAVEC_FINISHED, number: 12 The above two commands and the data can be send by using the following low-level function: `sendDataVector(int dataLength, double*xData,double*yData )`
- REDRAW, number: 4 This command has to be sent after all the plot info and data set has been submittet. This command is used to plot the plot layout (plot info sent earlier) and the data set. `setRedrawMode();`
- PS_FILENAME, number: 5 This command is used to change the export file name. `sendPSFileName();`
- SET_SCALING_MODE, number: 6 This command it used to tell QtGrace how the scaling should be: `sendScalingModeInfo(int graphNo, int mode, double xStart_value, double xEnd_value);` The client can send 3 different types of scaling (mode): `DEFAULT_LAYOUT, number 0 //do nothing AUTOSCALE_ALL_AXES_OR_JOIN_PLOT, number 1 /* autoscale all axis - default*/ AUTOSCALE_Y_AXIS_OR_OVERLAY, number 2/* autoscale y axis (send xStart_value and xEnd_valuea */`
- REDRAW_AND_WRITEPS, number: 7 This command is used to export a plot to a .ps file. This command is mainly used in batch mode in order to plot and export the plot to a .ps file without using the QtGrace GUI. `setRedrawAndWritePSMode();`
- SET_LAYOUT_MODE, number: 8 This command it used to tell QtGrace how the graph layout should be: `sendLayoutModeInfo(int graphNo, int layout, int col, int numGraphs)` The client can send 4 different types of layouts: DEFAULT_LAYOUT,number 0 //do nothing AUTOSCALE_ALL_AXES_OR_JOIN_PLOT, number 1 // join plot AUTOSCALE_Y_AXIS_OR_OVERLAY,number 2 //overlay GRAPH_POSITION, number 3 //Set graph position, i.e. numbers of columns and rows.
- KILL_CHILD, number: 42 This command is used to terminate the communication between QtGrace and the client. `killChild();`
- END_COMM number: 99 This command is used to tell QtGrace that we are ready to update the plot, that no further data will be sent and that we can close the socket connection. It is important to send this command after each plot. `endTransmission();`
- High level function to send data to QtGrace For the simplicity a high-level function has been implemented which the user can use to send a plot to QtGrace without worrying about the communication: `sendDataSetToQtGrace(double *x,double*y);`
- Read from QtGrace The user can read the plot parameters from QtGrace using the high-level function: `readPlotParametersFromQtGrace();` The function returns a QString with the plot parameters.

### 22. Haru-PDF-Library

QtGrace has now the option to export the current plot as a pdf-file using the Haru-PDF-Library. You have to activate the usage in the Preferences-dialog. The Haru-PDF-library is NOT distributed with QtGrace, but can be downloaded as a dynamic library (*.dll for windows, *.dylib for Mac OS X) from the internet. (Please use the 32-bit-library for windows.) Download the library or compile it yourself and tell QtGrace in the Preferences-dialog where to find the library. It is also possible to compile QtGrace yourself and include the Haru-PDF-library statically. In order to do so, you have to remove the '#' at the beginning of two lines in the scr.pro-file (there is a comment in the file telling you which lines). On unix-systems everything should be ok as it is. On Windows you have to enter the path to the library in the second of these lines, run qmake and recompile QtGrace. Do not forget to compile the Haru-PDF-library with the appropriate number of bits (32 or 64 bits) according to your system (probably 64bit for Linux and Mac OS X, but 32bit for Windows if you are using the MinGW-compiler). To use it just select "PDF(Haru)" in the device-setup-dialog (File->Print/Export setup...). Drawbacks: driver does not support line-patterns (dash-patterns are supported) or fill-patterns (only solid fill). No QtFonts! Just the classic Grace-fonts (because they are the default fonts that are supported by every pdf-viewer). Have a look at the following sites for more information: libharu.org, github/libHaru License: Haru Free PDF Library Haru is distributed under the ZLIB/LIBPNG License. Because ZLIB/LIBPNG License is one of the freest licenses, You can use Haru for various purposes. The license of Haru is as follows. Copyright (c) 1999-2006 Takeshi Kanno Copyright (c) 2007-2009 Antony Dovgal It is provided "as is" without express or implied warranty. In no event will the authors be held liable for any damages arising from the use of this software. Permission is granted to anyone to use this software for any purpose,including commercial applications, and to alter it and redistribute it freely, subject to the following restrictions: 1. The origin of this software must not be misrepresented; you must not claim that you wrote the original software. If you use this software in a product, an acknowledgment in the product documentation would be appreciated but is not required. 2. Altered source versions must be plainly marked as such, and must not be misrepresented as being the original software. 3. This notice may not be removed or altered from any source distribution.

### 23. fftw3-Library

QtGrace can now use the FFTW3-library to do fourier-transformations. You have to activate the usage in the Preferences-dialog. The advantage is, that you do not have to worry about the number of points beeing a power of two for fft anymore (in fact dft and fft are the same with FFTW3). Also the fftw3-library is faster than the internal fourier-algorithm. The fftw3-library is NOT distributed with QtGrace, but can be downloaded as a dynamic library (*.dll for windows, *.dylib for Mac OS X) from the internet. (Please use the 32-bit-library for windows.) Download the library or compile it yourself and tell QtGrace in the Preferences-dialog where to find the library. It is also possible to compile QtGrace yourself and include the fftw3-library statically. In order to do so, you have to remove the '#' at the beginning of two lines in the scr.pro-file (there is a comment in the file telling you which lines). On unix-systems everything should be ok as it is. On Windows you have to enter the path to the library in the second of these lines, run qmake and recompile QtGrace. Do not forget to compile the fftw3-library with the appropriate number of bits (32 or 64 bits) according to your system (probably 64bit for Linux and Mac OS X, but 32bit for Windows if you are using the MinGW-compiler). Have a look at the following sites for more information: www.fftw.org, Download fftw. Copyright notice: Copyright (c) 2003, 2007-14 Matteo Frigo Copyright (c) 2003, 2007-14 Massachusetts Institute of Technology 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., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA