# &app; manual.

# &app; Manual V&manrevision;

2005-2016
Jean Bréfort

&legal;

GNOME Documentation Project
Jean
Bréfort

     jean.brefort@normalesup.org

&app; Manual V&manrevision;
&date;

Jean Bréfort jean.brefort@normalesup.org

GNOME Documentation Project

&app; Manual V0.14.0
September 2012

Jean Bréfort jean.brefort@normalesup.org

GNOME Documentation Project

&app; Manual V0.12.0
April 2010

Jean Bréfort jean.brefort@normalesup.org

GNOME Documentation Project

&app; Manual V0.10.0
September 2008

Jean Bréfort jean.brefort@normalesup.org

GNOME Documentation Project

&app; Manual V0.8.2
July 2007

Jean Bréfort jean.brefort@normalesup.org

GNOME Documentation Project

&app; Manual V0.8.0
June 2007

Jean Bréfort jean.brefort@normalesup.org

GNOME Documentation Project

&app; Manual V0.6
August 2005

Jean Bréfort jean.brefort@normalesup.org

GNOME Documentation Project

&app; Manual V0.4
January 2004

Jean Bréfort jean.brefort@ac-dijon.fr

GNOME Documentation Project

&app; Manual V0.2
July 2002

Jean Bréfort jean.brefort@ac-dijon.fr

GNOME Documentation Project

This manual describes version &appversion; of &app;.

## Feedback

To report a bug or make a suggestion regarding the &app; application or this manual, go to the &app; home page.

&app; allows you to draw and display 2D chemical structures.

## Introduction

The &app; application is a simple chemical 2D-structures editor. You can use &app; to create and edit chemistry related files.

## Getting started

### To Start &app;

You can start &app; in the following ways:

Applications list

  Choose Chemical Structures Editor. It might be listed either in the Education or Science category.

Command line

  Type `gchempaint`, then press Return.

GChemPaint can also be run as a Goffice component. This makes possible to embed some chemistry in Abiword.

When using the command line, some options are available:

`-e`
`--edit-residue`

  Open residues dialog.

`-F`
`--full-screen`

  Open new windows full screen.

`-M`
`--maximize`

  Open new window maximized.

`-?`
`--help`

  Show application help options.

### When You Start &app;

When you start &app;, an empty document window and a toolbox are displayed:

#### &app; main window

Screenshot of the GChemPaint document window.

A &app; document window contains the following elements:

Menubar

  The menus on the menubar contain all of the commands you need to work with files in &app;.

Toolbar

  The toolbar contains a subset of the commands that you can access from the menubar.

Display area

  The display area contains the contents of the file that you are editing.

Statusbar

  The statusbar displays information about current &app; activity and contextual information about the menu items.

#### &app; toolbox

Screenshot of the GChemPaint toolbox.

The toobox contains buttons for every available tool, a current element selector and a property page for the currently selected element. The screenshot shows the box with the selection tool selected (this is the default); its property box contains four buttons.

The toolbox is always displayed along with the active document window.

### To Open a File

To open a file, choose File Open to display the Open File dialog. Select the file that you want to open, then click OK. The file is displayed in a new &app; document window.

To Open a recently opened file, choose the appropriate entry in File Open recent

GChemPaint can open files on a distant server using the Gnome Virtual File System. If the file is read-only, the File Save menu item and the corresponding tool button are disabled.

GChemPaint can open several file formats. Available formats are:

- Native format (*.gchempaint)

- Chemical Markup Language files (*.cml)

- MDL MOL files (*.mol;*.mdl)

- PDB files (*.pdb;*.ent)

- ChemDraw eXchange files (*.cdx)

- ChemDraw eXchange XML files (*.cdxml)

- PubChem ASN.1 ASCII Format files (*.asn)

- PubChem ASN.1 Binary Format files (*.asn;*.val)

- PubChem ASN.1 XML Format files (*.pc)

- XYZ Co-ordinate Animation Format (*.xyz)

For some formats, only reading might be supported.

GChemPaint can also support formats not listed here provided they have a known mime type, they are supported by OpenBabel and you add the mime type, one per line to the $HOME/.gchempaint/mime-types file.

Only native format files are opened in the embedded version.

You can open multiple files in &app;. The application displays each file in its own window.

### To Open Multiple Files from a Command Line

You can run &app; from a command line and open a single file or multiple files. To open multiple files from a command line, type the following command, then press Return:

`gchempaint file1 file2 file3` where file1 and others are relative or absolut paths or uris.

When the application starts, the files that you specified are displayed in the &app; main window.

## General operations

### To Create a New File

To create a new file, choose File New . The application displays a new file in the &app; window. The new file uses the default theme.

To create a new file with a differnet theme, choose File New File with theme... , choose the appropriate theme and valid.

#### New File with Theme Dialog

Screenshot of the New File with Theme Dialog Box.

This version of &app; is shipped with only one theme, the default one.

For more informations about &app; themes, see the Themes editing section.

### To Save a File

You can save files in the following ways:

- To save changes to the current file, choose File Save or click Save on the toolbar. If the file does not have a filename, &app; displays the Save As dialog. Enter a name for the file in the Save As dialog, choose a file format, then click OK.

- To save a new file or to save an existing file under a new filename, choose File Save As . Enter a name for the file in the Save As dialog box, choose a file format, then click OK.

Available file formats are:

- Native format (*.gchempaint)

- Chemical Markup Language files (*.cml)

- MDL MOL files (*.mol;*.mdl)

- PDB files (*.pdb;*.ent)

- XYZ Co-ordinate Animation Format (*.xyz)

Of course, only 2D data are exported, even if most formats support 3D coordinates.

The native format is supported directly by GChemPaint, Chemdraw formats and CML are supported through plugins, and other files are saved (and read) using the OpenBabel library .

Saving in a file format other than the native format is unsafe because not all features are supported either by the plugins or the OpenBabel library.

Other formats might be supported, depending on the OpenBabel version as explained in the section To Open a File.

### To Edit the Document Properties

You can edit the document properties as follows:

Use the menu item View Tools to open the document properties dialog box.

#### Document Properties Dialog

Screenshot of the Periodic Table Dialog Box.

The fields in this dialog box are:

Title

  The title of the document.

Author's Name

  The default value is the environment variable USERNAME.

Author's E-Mail Address

  The default value is the environment variable E_MAIL if it exists.

Creation Date

  The time when the file was created. This field cannot be edited.

Revision Date

  The last time the file was saved. This field cannot be edited.

Theme

  The theme used by the document. Changing the theme of an existing document is not a recommended operation. Bond lengths and some other data will not be updated according to the new theme.

  For more informations about &app; themes, see the Themes editing section.

Comments

  This field can contain any useful text.

Dates are created automatically and saved with the file. The other fields are optionnal and are saved only if they are not empty.

### To Print the Document

To print a document, choose File Print... .

File Preview opens a window with a preview of the printed output.

To tune the printed output, choose File Page setup... as explained below.

#### The page setup dialog.

the first tab of the dialog concerns the paper and margins setup. Headers and footers are not supported in the version of &app;

##### The Page Setup tab.

Screenshot of page setup dialog.

The second tab allows you to choose the scale of the output. With no scaling or scaling at 100%, the output will have the same size in points as the size in pixels on the screen. If you choose automatic scaling, you can make the output fill the available space either horizontally, vertically, or both (none of the options is equivalent to no scaling).

Printing to more than one page is not supported in this version of &app;

##### The Print Scale tab.

Screenshot of the printing scale page.

### To Export an image

To export the current file to an image, use File Save As Image .

Available formats are SVG, EPS, PS, PDF, and the formats with write support in GdkPixbuf.

To choose a format, you can use an appropriate extension in the file name, or explicitly select a format in the combo box. With the first method, if &app; does not recognize an extension, the exported file will be a SVG file. &app; will add an extension to the file name if needed.

### To Edit the Preferences

You can change the current settings using Edit Preferences :

#### Preferences Dialog

Screenshot of the Preferences Dialog Box.

#### Global settings

&app; has two global settings:

Compression level

  The compression level used when saving native files. If not 0 the file will be compressed using gzip.

Invert wedge hashes

  If set, the wedge hashes bonds will follow the usual convention which put the narrow end at start and the large end at the farest end. Default convention in &app; is just the inverse, because it is more consistent with perspective rules.See the Stereo bond tools section for more information.

Use colored atomic symbols in new documents

  Whether atomic symbol should use the element symbolic color when displayed. Attached hydrogen atoms will use the same color.

#### Editing Themes.

Each document has an associated theme. When a document is opened, &app; searches if a theme already exists with the same name and the same settings. If found the existing theme is used, otherwise a new theme is added to the themes set and used only for this file. It is possible, although not recomended, to change the theme associated with the file using it's Properties Dialog.

When the Preferences Dialog Box is opened, the active document theme is selected.

For each theme, the various settings are spread on several pages.

##### General settings.

This page presents the settings which did not fit well elsewhere.

Name

  The name of the theme. This name can be changed for user define themes and themes specific to a file. Not for the default Theme or other pre-defined ones.

Scale

  Scale used to convert real distance to canvas distance expressed in pm per pixel.

General padding

  Padding used around text objects such as atoms, texts and other typographic signs in pixels.

Object padding

  Default padding in pixels added between consecutive objects during an alignment operation.

Stoichiometry padding

  Extra padding between a stoichiometric coefficient and its associated molecule in pixels.

Sign padding

  Padding between a '+' sign in a reaction equation and reactants symbols in pixels.

##### Arrows related settings.

###### Arrows Page

Screenshot of the Arrows page in the Preferences Dialog Box.

Length

  Default arrow length (in pm just like bond lengths). Changing this parameter will have no effect on the lengths of exisiting arrows.

Width

  Arrow line width (in pixels).

Distance

  Distance in pixels between two parallel lines (either two arrows or one arrow with two lines).

Padding

  Padding added at each end of an arrow (in pixels).

Arrow head A

  Distance in pixels from tip of arrowhead to center.

Arrow head B

  Distance in pixels from tip of arrowhead to trailing point, measured along shaft.

Arrow head C

  Distance in pixels of arrowhead trailing points from outside edge of shaft.

##### Atoms related settings.

###### Atoms Font Page

Screenshot of the Atoms font page in the Preferences Dialog Box.

Using this property page, it is possible to select the font used for atoms and other residues.

###### Atoms Extra Page

Screenshot of the Atoms extra page in the Preferences Dialog Box.

Charge sign size

  The size in pixels of a localized charge sign, including the surrounding circle.

##### Bonds related settings.

###### Bonds Page

Screenshot of the Bonds page in the Preferences Dialog Box.

Length

  Default bond length (pm). Changing this parameter will have no effect on the lengths of exisiting bonds

Angle

  Default angle between two consecutive bonds in a chain.

Width

  Bond line width (in pixels).

Distance

  Distance in pixels between two lines representing a multiple bond.

Stereo bond width

  Width in pixels at the largest end.

Hash width

  Width of hashes in pixels.

Hash distance

  Distance between hashes in pixels.

##### Text related settings.

###### Text Page

Screenshot of the Text page in the Preferences Dialog Box.

This font selector gives the default font selected when creating a new text object, unless an other font has been selected in the text tool property page.

### To Select and Move Objects

To select objects, you can either use the Edit Select All menu command or activate the Selection Tool. With the selection tool, you can also move or rotate objects. When you use the Edit Select All menu command, the Selection Tool is automatically activated.

#### Selection Tool

Screenshot of the Selection Tool button.

This tool is used to select one or several molecules or objects. To select an object, just click on it. Molecules and other groups of objects are considered single objects and you cannot select only some part of a molecule with this tool. To selct only a portion of an object, use the lasso tool:

#### Lasso Tool

Screenshot of the Lasso Tool button.

The allowed actions for a partial selection depend upon what is selected. The main use it for modifying a molecule by translating or rotating a portion of it.

Otherwise, you can select all objects at least partially lying inside a rectangle by pressing the left button, dragging the mouse from one corner of the rectangle to the opposite one and releasing the button. Selected objects have their color changed from black to cyan.

Selected objects can be moved with the mouse, flipped, rotated, deleted by pressing the delete key, or copied.

When the selection tool is selected, the tools box looks like:

#### &app; toolbox when the selection tool is selected

Screenshot of the &app; toolbox when the selection tool is selected.

The property page of this tools contains four buttons:

Horizontal flip button

  Use this button to flip horizontally the current selection.

Vertical flip button

  Use this button to flip vertically the current selection.

Rotate button

  When this toggle button is active, dragging the mouse over the selecton will rotate it instead of moving it to a new position.

Molecules merging button

  Use this button to merge the two selected molecules. When the selection does not consist in just two molecules, the button is not sensitive.

### To Copy, Cut, and Paste Objects

To add, modify or delete objects, you can use the appropriate tool. You can also use the Edit menu.

To copy objects to a buffer, you can choose Edit Copy . If you select objets with the mouse they will also be copied to another buffer.

If you choose Edit Cut the selected objects will be copied and deleted.

To paste an object, choose Edit Paste . The pasted objects will appear selected and centered in the window. You can also paste objects by clicking with the middle button, objects will appear centered at the point where you clicked. Text can also be pasted in a text zone if you paste while editing a text object. You cannot paste anything inside a fragment. Unless if you paste text in an already existing text, the Selection Tool will be activated on pasting.

### To Undo or Redo Operations

To undo a change, choose Edit Undo . To redo an change, choose Edit Redo . The number of previous changes that you can undo is unlimited in &app;

If you are editing a text or a fragment, you can undo/redo each change done since the begin of your edition operation. If you end the edition of such an object, you can only undo or redo the whole edition operation.

### To Delete Objects

To delete objects, you can activate the Eraser Tool:

#### Eraser Tool

Screenshot of the Eraser Tool button.

When you drag the mouse cursor, this tool being active, the objects which would be deleted after clicking are highlighted in red.

To erase a bond or an atom, click on it when this tool is active. An atom is suppressed with all its bonds. While the button is pressed, the objects to delete appear coloured in red if the pointer remains near them and revert to black if the mouse pointer is moved away. When the left button is released, the objects coloured in red are deleted.

You can also delete whole molecules and groups of objects at once with the help of the Selection Tool.

Automatic objects cannot be deleted with this tool.

The eraser tool has an empty property page.

### To Flip or Rotate Objects

To flip or rotate objects, you can use the following buttons:

#### Flip and Rotate Buttons

Screenshot of the Flip and Rotate Buttons.

To flip or rotate objects, select them and click on the appropriate button.

To rotate the selected objects, drag the mouse on the view until you obtain the wanted orientation. Grouped objects cannot be rotated or flipped in this version of &app;

### To Group and/or Align Objects

To group and/or align object, choose Group and/or align objects in the popup menu. The dialog box below will pop up.

#### Group and/or Align Dialog Box.

Screenshot of the Group and/or Align Dialog Box.

The fields in this dialog box are:

Group

  Whether to create or not a group.

Align

  Whether to align selected objects or not.

  If you choose to align the objects, you must select the alignment mode in the list. Available modes are:

  Normal

    This is the most usual mode. Texts will have the same baseline and other objects will be aligned on a horizontal line passing in the middle of a C character in the font used for chemical symbols.

    You can choose which part of a molecule (bond, atom or fragment) will be used for normal alignment: move the mouse cursor to the bond, atom, or fragment, right click and select Select alignment item in the popup menu.

  Top

    Align object according to their top borders.

  Mid-height

    Align object according to their vertical centers.

  Bottom

    Align object according to their bottom borders.

  Left

    Align object according to their left borders.

  Center

    Align object according to their horizontal centers.

  Right

    Align object according to their right borders.

Space evenly

  Whether to space evenly aligned objects or not. This option is available only if you align the objects. You must choose the distance to use to space the objects in the spin button on the right.

If grouped, objects will stay aligned when a change occur.

Groups cannot be flipped or rotated in this version of &app;.

To ungroup objects or change alignment, choose Group properties in the contextual menu to display the dialog, uncheck Group and validate.

## Editing molecules.

### To Change the Current Element

You can change the current element with the keyboard or with the Periodic Table Combo Button in the tools box.

#### Using the keyboard.

When no text is being edited, typing a lowercase character will change the current element. Only 26 elements can be selected this way:

##### One character shortcuts for elements.

a: Al | b: B | c: C | d: Na
e: Se | f: F | g: Ge | h:H
i: I | j: Ti | k: K | l: Li
m: Mg | n: N | o: O | p: P
q: Si | r: Br | s: S | t: Pt
u: Cu | v: V | w: W | x: Cl
y: Y | z: Zr |  |

All elements can be accessed by typing an uppercase character. A popup menu appears which list all the known symbols starting with this character. The second character is used as a shortcut in the menu. As a sample, this is what you get when you type 'P':

##### Element popup menu.

Screenshot of the Element popup menu.

Changing the current element using the keyboard might modify the atom under the mouse cursor if any, see Modifying Atoms.

#### Using the Periodic Table Combo Button.

##### Chosing an element

Screenshot of the Periodic Table combo button poped up.

Just click on the wanted element, and it becomes the current element.

The symbol of the selected element also appears on the Element tool button. Every new atom created with all tools are atoms of the default element. Carbon is the selected element when the application starts.

### To Use or Manage Templates

To use or manage templates, you can activate the Template Tool:

#### Templates Tool

Screenshot of the Templates Toolbar.

When the template tool is activated, the tools box looks like:

#### &app;Toolbox when the templates tool is selected

Screenshot of the &app; toolbox when the selection tool is selected.

When the template tool is active, yo can add the molecule corresponding to the active template in your document by clicking where you want to add it unless the new template dialog is opened. The new molecule will be centered around where you release the mouse button. The molecule will be scaled so that it's median bond length is equal to the current document theme bond length.

#### Managing Templates

To select a template, use the drop down list.

When a template is selected in the tree, a preview is available in the toolbox.

User's templates can be deleted with the Remove button. For system wide installed templates, the button is deactivated.

To add a new template, choose Add. The New Template dialog will be opened.

#### Adding a New Template

##### New Template Dialog

Screenshot of the New Template Dialog.

To add a new template, you must provide a name, a category (you can choose an existing category or create a new one), and a molecule.

To create the molecule for the template, draw it in a document and while the dialog is opened and the templates tool is active, click on the molecule. The molecule is copied to the new template dialog.

### To Manage Residues

In &app;, Residues are atoms groups with a symbol, such as Ph for phenyl. &app; comes with a list of predefined group symbols, but you can define new residues in needed. When importing a file with unknown symbols, either a &app; file, or a ChemDraw® file, new symobls are added to the user define symbols list.

To define a new symbol, choose Tools/Edit residues..., the following dialog will pop up:

#### Residues dialog

Screenshot of the Residues dialog box.

You can choose either a new residue (the default) or an already known symbol in the dropdown list at top left of the dialog box. Selecting "Ph" leads to:

#### Phenyl residue

Screenshot of the Residues dialog showing the phenyl residue.

The entries and the check box are greyed because this residue is standard and can't be edited.

The name must be unique, but several symbols can be defined. The various symbols must be separated by semicolons. Generic residues correspond to symbols which may represent various structures such as R for alkyle, Ar for aryle, X for a halogen atom, or M for a metal atom.

If you display the structure page for the phenyl aresidue, you get:

#### Phenyl structure

Screenshot of the Residues dialog showing the phenyl structure.

The bullet represents the attachment point of th residue. It is linked to the first atom by a single bond. Multiple bonds are not allowed in this version of &app;.

When you want to create a new residue, you might first select an existing one with a similar structure. When you select "New" in the list, the structure is conserved. When the dialog box is created, the default structure is a methyl. For generic residues the structure should represent a simple case.

When you have the new strucutre and filled the name and symbol for it, you have to click on the Save button to save it to the database.

The Delete button is used for removing the selected residue from the database and is enabled only when the residue can be securely deleted.

### To Add or Modify an Atom

To add or modify an atom, you can activate the Element Tool or the Fragment Tool:

#### To Add or Modify an Single Atom

##### Element Tool

Screenshot of the Element Tool button.

With this tool, you can add an atom everywhere on the canvas or change the nature of an already existing atom. The element is chosen with the periodic table available in the view menu or by double clicking on the tool's button. The symbol of the currently selected element appears in the button of this tool. By default, carbon is the current element as shown on the screenshot above. While the left button remains pressed, the new atom or label appears coloured in green. If you move the mouse away from where the left button was pressed, the new atom disappears. The changes are effective when the button is released while the pointer stays on the new or changed atom. Attached hydrogens are automatically added for non metals.

To change the default element,use the Periodic Table Button.

It is also possible to change the nature of an atom using the keyboard: put the mouse cursor on the atom you want to modify, and then select the new element as described there. Note that this will also change the current element.

A local charge and explicit single electrons or electrons pairs can be added to the atom with the appropriate tool.

Carbon atom are normally not displayed when they have at least one bond. You can change this behaviour for each carbon atom using File Display symbol in the contextual menu.

When a non metal has implicit hydrogen atoms, &app; tries to infer if they should appear on the left or the right of the atomic symbol. If the automatic behavior is not what you wish, you can force a left or right position using File Hydrogen atoms position in the contextual menu. The following dialog will pop up:

##### Hydrogen atoms position dialog box

Hydrogen atoms position dialog box.

Choose one of the options (Left, Right, Top, Bottom, or Auto). The chosen option will be instantly applied.

#### To Add or Modify a Group of Atoms

##### Fragment Tool

Screenshot of the Fragment Tool button.

With this tool, you can add a formula just by typing some text. In &app;, such text representing atoms is called a fragment. What you type with this tool is only partially analyzed. You must first type a valid atomic or group symbol. The fragment will be aligned on the center of this symbol and this allows you to include the fragment in a molecule by adding a bond. Fragments cannot have more than one single bond in the present version of &app;. The bond can be added to any atom in the fragment. The bonded atom is the reference atom of the fragment. When editing, you must always have a valid symbol at its position.

This tool has several input modes. To switch between modes, you need to use the appropriate key combinations. Current mode is displayed in the status bar. Typing the shortcut for current mode always select normal mode.

Available modes:

- Normal mode (ControlSpace): in this mode, &app; tries to interpret the string according to knwon rules.

- Stoichiometry mode (Controln): text entered in this mode is displayed as subscript and considered as a stoichiometric coefficient. &app; does not check what is entered in this version, but this will change in the future.

- Charge mode (Control+): text entered in this mode is considered as charge and displayed as superscript. &app; checks what is entered and complains when it does not cosider the entered text as a valid charge. Currently, a valid charge is either a number or a single character (might be a unicode character like δ followed by either + or −.

- Subscript mode (Control_): text entered as subscript, but with no stoichiometry meaning. Should nevertheless have a chemical meaning since &app; might check it in the future.

- Superscript mode (Control^): text entered as superscript, but with no charge meaning. Should nevertheless have a chemical meaning since &app; might check it in the future.

In normal mode, figures are automatically displayed smaller than symbols and slightly lowered unless they are part of a charge. To add a charge in the fragment, first type the sign and then, either the figures or other signs: typing a + increments the current charge and typing a - decrements it.

To obtain Fe2+, you can type Fe+2 or Fe++.

Fragments also support local charges, but only if no charge is indicated in the fragment itself.

It is also possible to force some text to appear and be considered as a charge by switching to the charge input mode. Inside charges the - sign is replaced by an unicode minus character (−). &app; will check if the entered text looks like a charge.

The fragment tool also converts existing atoms to fragment. This might be useful to change the position of attached hydrogens or to display terminal carbon atoms. In the other way, the Element Tool can also be used on fragments. It tries to replace the symbol at the position of the click by the current element symbol if there is no bond. If there is a bond, the symbol of the bonded atom is changed whereever you click. To transform a whole fragment into an ordinary atom, press the Control key while clicking on the fragment.

Saving a file containing fragments in a format different from the native one is very unsafe.

### To Add or Modify a Local Charge

To add or modify a localized charge, you can activate one of the following tools:

#### Charge Tools

Screenshot of the Charge Tools button.

The tools can be used to increment or decrement the local charge of an atom by clicking on the atom while the appropriate tool is active. Local charges can also be added to atoms located in fragments with the following restrictions: only one atom in a fragment can bear a local charge; if the fragment has a bond, only the bonded atom can bear the charge; and if charges are already present in the fragment, no other local charge can be supported by the fragment. In fragments, local charges are limited to -1 and +1 in this version of &app;.

To display the charge at a position different from the default one, drag the charge to the wanted position while pressing the mouse button. Pressing the Shift key and/or the Control key change the behavior while dragging.

### To Add Unbound Electrons to Atoms

To add unbound electrons to an atom, you can activate one of the following tools:

#### Electrons Tools

Screenshot of the Electrons Tools button.

The tools can be used to add explicit electrons to an atom by clicking on the atom while the appropriate tool is active.

To display the electron or the electron pair at a position different from the default one, drag the charge to the wanted position while pressing the mouse button. Pressing the Shift key and/or the Control key change the behavior while dragging.

### To Add or Modify Orbitals representations

It is possible to add an orbital representation to an atom such as:

#### Orbital sample

Screenshot of an orbital representation.

To add one such representation, select the orbital tool:

#### Orbital tool

Screenshot of the orbital tool.

When this tool is selected the toolbox looks like:

#### Toolbox with orbital tool selected

Screenshot of the toolbox with the orbitaltool selected.

The available options are:

Coefficient

  A coefficient which affects the size and sign of the orbital. Acceptable valies are -1. to +1.

Rotation

  The rotation relative to the vertical. This option is, of course, not available for s-type orbitals.

Type

  The type of the new orbital.

To modify an existing orbital, right click on it or on the corresponding atomic symbol, select the orbital in the popup menu, and choose Properties .

This pops up the following window with the same options as in the toolbox:

#### Orbital properties dialog

Screenshot of the orbital properties dialog.

### To Add or Modify a Bond

To add or modify an atom, you can activate one of the following tools:

#### Bond tool

##### Bond Tool

Screenshot of the Bond Tool button.

This tool allows to draw new bonds and to change the multiplicity of an existing bond. The changes become permanent only when the mouse button is released.

To add a new bond, click on an existing atom or fragment or on the background (an atom will be defined at the position of the click) with the left button.

On clicking, the new bond appears in the default direction. This direction depends on the number of preexisting bonds:

- No bond or more than two: horizontal, to the right.

- One bond: the new bond will form with the first bond an angle equal to the current setting in the tool options, to the right if the caps lock is on, to the left otherwise.

- Two bonds: the direction will be the external bisector of the angle of the two bonds.

If the default direction is not what you want, drag the mouse in the direction of the bond and release the mouse when the green line is where you want the bond lie. Current orientation is indicated in the status bar. If you drag to an existing atom, and if the Merge with existing atoms button in the tool options is checked, the bond will end on that atom and if you return the mouse to the original position, no bond will be added (the green line disappears). Release the button to draw the bond. &app; creates new atoms of the current element.

When the new bond does not end at a preexisting atom, the bond length is fixed and the bond angle from horizontal is a multiple of 5. Pressing the Shift key removes the fixed length restriction and pressing the Control removes the restriction about the angle.

To change a bond multiplicity, click on the bond with the left button. If you change your mind, drag the mouse away from the bond before releasing the button. A single bond will become a double bond, a double will become a triple and a triple bond will revert to a single bond. If the bond was a stereo bond, it becomes a normal single bond.

#### Stereo bond tools

##### Stereo Bond Tools

Screenshot of the Stereo Bonds Tools buttons.

These tools allow to draw single stereo bonds. If you click on an existing bond when this tool is active, the bond becomes a stereo bond. If it is already that sort of bond, extremities are exchanged, except for squiggle bonds for which it has no effect. Otherwise these tools work as the normal bond tool.

Convention for the wedge hashes start and end widths in &app; puts the largest end at start, because it is the nearest from the viewer perspective. This is contrary to the usual convention. To use the usual convention, check the appropriate box in the Preferences dialog.

The current convention is reflected by the icon displayed in the tool button. The bottom left end represents the start bond position and top right the end bond position. When the usual convention is used, the tool button will look like:

##### Inverted convention.

Screenshot of the Down bond tool when the invert wedge hashes option is selected.

#### Bond tools options

##### &app; toolbox when a bond tool is selected

Screenshot of the &app; toolbox when a bond tool is selected.

The available options are:

Bond length

  The default length of a new bond.

Bond angle

  The default angle between two consecutive bonds in a chain.

Merge with existing atoms

  If checked, exiting atoms will be used when present at the end of the new bond. Otherwise, a new atom will be created even if it results to two atoms at the same position.

### To Add a Chain

To add a chain, activate the chain tool.

#### Fixed Size Cycle Tools buttons

Screenshot of the Fixed Size Cycle Tools buttons.

This tool allows to add a new chain at once. The changes become permanent only when the mouse button is released.

To add a new chain, click on an existing atom or fragment or on the background (an atom will be defined at the position of the click) with the left button.

On clicking, the new chain appears in the default direction. The direction of the chain is not that of its first bond, but the direction from the start of the chain to the end of the second bond. This direction depends on the number of preexisting bonds:

- No bond or more than two: horizontal, to the right. The second bond will turn to the left if the caps lock is on, to the right otherwise.

- One bond: the fisrt bond of the new chain will form with the first bond an angle equal to the current setting in the tool options, to the right if the caps lock is on, to the left otherwise.

- Two bonds: the direction of the first bond will be the external bisector of the angle of the two bonds. The direction of the second bond depends on the status of the caps lock as before.

If the default direction is not what you want, drag the mouse in the direction of the bond and release the mouse when the green chain is where you want the chain lie. Current orientation is indicated in the status bar. If you drag to an existing atom, and if the Merge with existing atoms button in the tool options is checked, the bond will end on that atom and if you return the mouse to the original position, no bond will be added (the green chain disappears). Release the button to draw the chain. &app; creates new atoms of the current element.

When the new chain does not end at a preexisting atom, the bond length is fixed and the chain angle from horizontal is a multiple of 5. Pressing the Control key removes the restriction about the angle.

The chain length is either set in the options or calculated according to the mouse position. A new chain has at least two bonds.

Pressing the Shift key removes the constraint about the bond lengths, but fixes the bonds number.

When the chain tool is active, the toolbox looks like:

#### &app; toolbox when the chain tool is selected

Screenshot of the &app; toolbox when the chain tool is selected.

The available options are:

Bond length

  The default length of a new bond.

Bond angle

  The default angle between two consecutive bonds in a chain.

Bond number

  The number of bonds to add in the new chain. If the Auto is checked, the bond length is determined from the mouse position while dragging, otherwise, the number in the entry is used, which is quite useful when adding a chain with just one click.

Merge with existing atoms

  If checked, exiting atoms will be used when present at the end of a new bond. Otherwise, a new atom will be created even if it results to two atoms at the same position.

### To Add a Cycle

To add a cycle, you can activate one of the following tools:

#### Fixed size cycle tools

##### Fixed Size Cycle Tool

Screenshot of the Fixed Size Cycle Tools buttons.

These tools allow to draw a whole cycle at once. If the click occurs on an atom or on the background, dragging the mouse will change the orientation of the cycle. When the click occurs on a preexisting atom, the default orientation is chosen relatively to preexisting bonds. Shift and Control keys have the same effect than with the bonds tools.

If the click occurs on a bond, the new cycle will contain this bond. The new cycle appears by default on the less hindered size of the bond. Drag the mouse on the other size before releasing the button if you want to draw the cycle on the other side. Pressing the Shift key and moving the mouse to an adjacent bond will include this bond in the new cycle if the size of the new cycle is large enough (at least two new bonds will be created).

When one of the cycle tools is active, the toolbox looks like:

##### &app; toolbox when a cycle tool is selected

Screenshot of the &app; toolbox when a cycle tool is selected.

The available options are:

Bond length

  The default length of a new bond.

Merge with existing atoms

  If checked, exiting atoms will be used when present at the end of the new bond. Otherwise, a new atom will be created even if it results to two atoms at the same position.

#### Variable size cycle tool

##### Variable Size Cycle Tool

Screenshot of the Variable Size Cycle Tool button.

This tool works the same as the other cycle tools. The size or the new cycles can be changed in the property box associated with this tool. The default size is nine and the largest possible size is one hundred.

When the variable size cycle tool is active, the toolbox looks like:

##### &app; toolbox when the variable size cycle tool is selected

Screenshot of the &app; toolbox when the variable size cycle tool is selected.

The available options are:

Bond length

  The default length of a new bond.

Cycle Size

  The size of the new cycles.

Merge with existing atoms

  If checked, exiting atoms will be used when present at the end of the new bond. Otherwise, a new atom will be created even if it results to two atoms at the same position.

### To Add a Newman Projection

To add a Newman projection, use the following tool:

#### Newman Projection Tool

Screenshot of the Newman Projection Tool button.

This tool allows to add a Newman projection. The changes become permanent only when the mouse button is released.

To add a Newman projection, click on the background. Contrarily to other tools existing atoms are never used by this tool. It creates new atoms of the current element.

When the Neman projection tool is active, the toolbox looks like:

#### &app; toolbox when the Newman projection tool is selected

Screenshot of the &app; toolbox when the Newman projection tool is selected.

The available options are:

For the main bond:

Bond length

  The default length of the new projected bond. This has no influence ion the drawing, but might be important when exporting to a 3d model.

Bond order

  The bond order.

And for each atom:

Bonds number

  Number of other bonds for the atom.

First bond angle

  The direction of the first bond. Angles are measured counter clockwise from horizontal right.

Angle between bonds

  The angle between two consecutive bonds.

This version of &app; does not correctly support Newman projections with eclipsed bonds.

### To Edit a Polymer Molecule

To edit a polymer molecule, use the brackets tool:

#### Brackets Tool

Screenshot of the Brackets Tool button.

Drag the mouse so as to select the polymer unit and release the mouse button. You can then add a stoichiometric coefficient using the contextual menu for the brackets.

When the brackets tool is active, the toolbox looks like:

#### &app; toolbox when the brackets tool is selected

Screenshot of the &app; toolbox when the brackets tool is selected.

The available options are:

Brackets type

  Choose between curved, square and curly brackets using the dropdown list.

Used brackets

  Choose whether to use opening, closing, or both brackets. For polymers both should be used.

### To Modify a Molecule using the Lasso Tool

#### Lasso Tool

Screenshot of the Lasso Tool button.

It is possible to select only part of a molecule using the lasso tool. You just need to click and drag the mouse around the objects you want to select. Selected objects will be highlighted. Actually, it is possible to select any objects collection using this tool. In some cases, the result of transforming a complex selection might have unwanted effects.

When a collection of objects has been selected, you can translate the selection by clicking on one of the selectged objects and dragging with the mouse. When the objects are in an appropriate position, release the mouse.

It is also possible to use one of the buttons in the toolbox:

#### &app; toolbox when the lasso tool is selected

Screenshot of the &app; toolbox when the lasso tool is selected.

The property page of this tools contains three buttons:

Horizontal flip button

  Use this button to flip horizontally the current selection.

Vertical flip button

  Use this button to flip vertically the current selection.

Rotate button

  When this toggle button is active, dragging the mouse over the selecton will rotate it instead of moving it to a new position. The rotation center is the position of the object at the click position. For a bond, it is actually the bond center.

### To Merge two Molecules

To merge two molecules, you can add a bond betwwen two atoms, one from each molecule. The drawback is that this method will not align properly the two parts of your new molecule.

Another and much better method is to use the Merge button:

#### Merge Button

Screenshot of the Merge Tool button.

Suppose you want to draw a naphtalene molecule starting from two benzene molecules:

Two benzene molecules.

Move one of the molecules so that at least one atom from each molecule lies at the same place. These atoms must be identical (same element). In the examples, two atoms and a bond conincide:

The two molecules after alignment.

Then, select the two molecules. The Merge button becomes sensitive. If you click on it, you obtain:

The resulting naphtalene molecule.

If one of the molecule has two or more atoms at the same position than an atom of the second molecule, the result is not easily preditable.

### Using the Molecules contextual menu.

#### Molecules contextual menu

Screenshot of the Molecule contextual menu.

The available commands are:

Open 3D model in

  This is a submenu containig items for opening the model in one of Avogadro, Ghemical, or GChem3D. The actually present items correspond to the installed applications. If none is available, the menu will be hidden. When all are present, this gives:

  #### Export to 3D menu.

  Screenshot of the export to 3D menu.

  The model is converted to 3D using OpenBabel. This might fail with some polycyclic molecules because of a bug in OpenBabel.

  With the cyclohexane molecule, you get in Ghemical:

  #### Cyclohexane ghemical view.

  Screenshot of the initial cyclohexane ghemical view.

Find in databases

  This is another submenu containing a list of databases where the molecule might be searched for. This list can be extended by the user adding an entry to `$HOME/.gchemutils/databases.xml`. This file needs to have a `databases` root node, and each entry should look like the one for ChemSpider in the predefined databases:

  `<database><name>ChemSpider</name><uri>http://www.chemspider.com/InChIKey=%K</uri><class>molecule</class></database>`

  "`%K`" will be replaced by the InChiKey when querying. Other available codes are "`%I`" to use the InChI, and "`%S`" to use the canonical SMILES as generated by OpenBabel.

Generate InChI

  Generates the InChI for the molecule and displays it in a popup window.

Generate InChIKey

  Generates the InChIKey for the molecule and displays it in a popup window.

Generate SMILES

  Generates the canonical SMILES for the molecule and displays it in a popup window.

Open in Calculator

  Opens the chemical calculator GChemCalc with a copy of the molecule formula and performs the available calculations

Select alignment item

  If clicked, the object which was at the position of the mouse cursor when the right button was clicked becomes the element taken into account for horizontal alignment. If it is an atom, its baseline will be aligned with the other objects baselines, and if it is a bond, the center of the bond will be used.

## Other objects.

### To Add an Arrow

To add an arrow, activate the appropriate tool.

#### Arrow Tools buttons

Screenshot of the Arrow Tools buttons.

Select the appropriate tool according to the type of arrow you want to add.

When you click, a new horizontal arrow appears. You can move the mouse pointer to change it's orientation by steps of 5°. You can remove this restriction by pressing the Shift key. The length of the new bond is given by the value displayed in the toolbox, unless you press the Control key, in which case, the position of the mouse will be the end of the arrow.

If you drag the mouse cursor to it's original position before releasing the button, the green arrow disappears and if you release the button without moving the mouse anymore, no arrow is added to the document.

When an arrow tool (except the reversible rraction arrow tool) is selected, the tolbox looks like:

#### &app; toolbox when an arrow tool is selected

Screenshot of the &app; toolbox when an arrow tool is selected.

Only one option is available:

Arrow length

  The default length of a new arrow.

For reversible reaction arrows, the heads used are by default half-heads. It is possible to change the heads to full heads in the property box of the tool and even make your choice the default.

The toolbox will look like:

#### &app; toolbox when the reversible reaction arrow tool is selected

Screenshot of the &app; toolbox when the reversible reaction arrow tool is selected.

### To Attach an Object to a Reaction Arrow

Objects such as text and molecules can be attached to reaction arrows to give more information about the reaction. In the current version of &app;, only one object can be attached to a given reaction arrow. Attaching the object to the arrow ensures that the object will be correctly aligned, and the arrow length is large enough.

To attach an object to a reaction arrow, fiorst select the object.

#### Object selection.

Screenshot of the object selection step.

Then right click on the reaction arrow to show the contextual menu, and choose Attach selection to arrow...

#### Contextual menu.

Screenshot of the arrow contextual menu.

A dialog box pops up where you can select a role for the object.

#### Dialog box.

Screenshot of the attached object dialog box.

And things are done.

#### Attached object.

Screenshot of the attached object.

### To Add or Edit a Curved Arrow

To add a curved arrow, activate the appropriate tool.

#### Arrow Tools buttons

Screenshot of the Curved Arrow Tools buttons.

Curved arrows are used to depict electrons position changes in reaction mechanisms. If the arrow head is a full head, the arrow symbolize the move of an electrons pair, while half-headed arrows represent single electron moves. Select the appropriate tool according to the type of a curved arrow you want to add.

To add a curved arrow, go where you want the arrow to start, the mouse cursor should change to a drawing pencil. If not, then the framework does not allow an arrow at this position. The object owning the electron or electron pair should be highlighted. Then click and, if the new arrow does not end where you want or if no new arrow is displayed, drag the mouse to the target of the electron deplacement. When you see an arrow at the wanted position, release the mouse button.

When possible, the arrow initial orientation is choosen according to the mouse cursor position relative to the source of the electrons.

When the full headed curve arrow tool is selected, the toolbox looks like:

#### Toolbox when the full headed curved arrow tool is selected

Screenshot of the Full Headed Curved Arrow Tool.

Only one option is present:

End arrow at center of new bond

  When a new bond is created during a mechanism step, you can end the curved arrow either at the other atom position, or at the center of the future bond. The result of the two possibilities are displayed in the following figure:

  #### Alternative positions.

  Alternative positions of a curved arrow end.

Default

  Clicking the Default button will make the current option the default.

Half-headed arrows will always end near the center of the future bond, because a second electron should come from the other side.

Curved arrows can be edited to some extents. Only the intermediate control points can be moved. In order to do that, select the appropriate tool, click on the arrow that you wish to edit, the control points will be displayed, drag the mouse until it reaches one of the control points. When you are there, the control point will follow any further mouse move. When done, release the mouse button.

Curved arrows can be created inside a reaction or a mesomery. It is also possible to add the curved arrow to the molecule before creating the reaction or the mesomery. If you add a curved arrow between two molecules, and then create a reaction, the two molecules will be considered as only one reactant and no + sign will be added between them, and the molecules will not be realigned.

### To Add or Edit a Reaction

To create a reaction, you must first draw the molecules and an arrow.

Two tools are present to add an arrow (go to the section "To Add an Arrow" for more information):

#### Reaction Arrows Tools

Screenshot of the Reaction Arrows Tools buttons.

Use these tools to add the corresponding graphical objects where appropriate to represent a reaction.

When you have the molecules and the arrow, you can create a reaction. As an example, if you want to represent the benzene hydrogenation reaction, you must first obtain something as:

The molecules and arrow before grouping.

You must now select the molecules and click with the mouse right button. A popup menu appears which contains the appropriate item:

Creating the reaction.

Select the Create a new reaction item, you obtain:

The reaction.

After the reaction has been created, you can add a stoichiometry coefficient. Click with the mouse right button on the appropriate reagent or product and choose Add a stoichiometry coefficient in the popup menu.

Adding a stoichiometry coefficient.

Now, edit the stoichiometry coefficient. In the current version, &app; does not check what you type, but future versions might analyze and reject incorrect texts.

Editing a stoichiometry coefficient.

When inside a reaction, molecules and arrows cannot be selected indidually, except for operations available in the contextual menu.

You can destroy the reaction by selecting the Destroy the reaction in the popup menu. The "+" signs and the stoichiometry coefficients will be deleted, and the molecules and arrows will be ungrouped.

Reactions cannot be flipped or rotated.

&app; also supports reactions with several steps and unsing any string to symbolize a molecule like the following samples:

A linear reaction scheme.

A multiple steps reaction scheme.

A cyclic reaction scheme.

A cyclic multiple steps reaction scheme.

### To Add or Edit a Mesomery Relationship

Mesomery is indicated by a double headed arrow. The appropriate tool to add this type of arrow is (go to the section "To Add an Arrow" for more information):

#### Mesomery Arrow Tool

Screenshot of the Mesomery Arrow Tool button.

Use this tool to draw a double headed arrow between two mesomeric stuctures. This version of &app; has an incomplete support for mesomery. The validity of what you draw is not checked.

To build a mesomery relationship, first create all useful molecules and arrows.

#### Creation of the molecules and arrows.

Create the molecules and arrows.

Then, select the appropriate objects, right click, and select Create a new mesomery relationship

#### Selection of the popup menu entry.

Select the menu.

If &app; is unable to build a mesomery relationship from the selected objects, an error message is displayed.

The mesomery is created with a default object alignment. You can change how mesomers are aligned by selecting a bond or an atom with the Select alignment item menu entry as explained in the section To Group and/or Align Objects. With this version of &app;, you must repeat the operation for each mesomer.

#### Built mesomery relationship.

The mesomery relationship is built.

You can destroy the mesomery relationship path by selecting the Destroy the mesomery relationship in the popup menu. The molecules and arrows will be ungrouped.

Mesomery relationships cannot be flipped or rotated.

### To Add or Edit a Retrosynthesis Pathway

The appropriate tool to add a retrosynthesis arrow is (go to the section "To Add an Arrow" for more information):

#### Retrosynthesis Arrow Tool

Screenshot of the Retrosynthesis Arrow Tool button.

Use this tool to draw a retrosynthesis arrow between two steps of the pathway.

To build a path, first create all useful molecules and arrows.

#### Creation of the molecules and arrows.

Create the molecules and arrows.

Then, select the appropriate objects, right click, and select Create a new retrosynthesis path

#### Selection of the popup menu entry.

Select the menu.

If &app; is unable to build a retrosynthesis path from the selected objects, an error message is displayed.

There are some limitations to what is supported currently :

- You cannot have more than one target molecule.

- Cyclic paths are not allowed.

- If a step leads to several precursors, you must use one arrow for each.

The path is created with a default object alignment. You can change how molecules are aligned by selecting a bond or an atom with the Select alignment item menu entry as explained in the section To Group and/or Align Objects

#### Built retrosynthesis path.

The retrosynthesis path is built.

In the sample, one of the vertical bonds of the cycle has been selected.

#### Custom aligned retrosynthesis path.

The retrosynthesis path after alignment.

You can destroy the retrosynthesis path by selecting the Destroy the retrosynthesis path in the popup menu. The molecules and arrows will be ungrouped.

Retrosynthesis paths cannot be flipped or rotated.

### To Add or Edit some Text

To add or edit text, use the text tool:

#### Text tool

Screenshot of the text tool button.

When this tool is selected, you can select an existing text and edit it or add a new text by clicking on the background.

The text tool property page looks like:

#### Toolbox when the templates tool is selected

Screenshot of the &app; toolbox when the text tool is selected.

You can decorate the text by changing the selection in the various widgets.

&app; also recognize some keyboard shortcuts specific to text edition. Some of these shortcuts are:

Ctrl+b

  Toggles between bold and normal text if current font family exists for both weights.

Ctrl+i

  Toggles between italic and normal text if current font family exists for both styles.

Ctrl+k

  Toggles between strikethrough and normal.

Ctrl+u

  Toggles between single underscore and normal.

Ctrl+^ or Ctrl++

  Toggles between superscript and normal. The size of the font will be reduced to two thirds of the original value and the position raised to the new font size.

Ctrl+_ or Ctrl+=

  Toggles between subscript and normal.

  Toggles between superscript and normal. The size of the font will be reduced to two thirds of the original value and the position lowered to the half of the new font size.

Ctrl+Space

  Restores default values according to the theme associated to the active document.

### To Add Brackets around an Object

To add brackets around an object, use this tool:

#### Brackets Tool

Screenshot of the Brackets Tool button.

To add brackets around an object, choose the appropriate brackets using the toolbox, click and drag the mouse so as to select the whole object. When the mouse button is released the brackets appear around the object.

The brackets don't modify the nature of the embedded object which can be used with the same logic as withiout the brackets. A bracketted molecule can be inserted inside a reaction, a retrosynthesis, or a mesomery relationship

#### &app; toolbox when the brackets tool is selected

Screenshot of the &app; toolbox when the brackets tool is selected.

The available options are:

Brackets type

  Choose between curved, square and curly brackets using the dropdown list.

Used brackets

  Choose whether to use opening, closing, or both brackets. For polymers both should be used.

### To Add or Edit a Mathematical Expression

To add or edit a mathematical expression, use this tool:

#### Equation Tool

Screenshot of the Equation button.

To add a methematical equation, just click where you want to get it. A dialog box pops up where you can type the equation using ITeX commands.

#### Equation dialog box

Screenshot of the maths editor.

The equation will show up while you type the equation.

#### Equation sample

Screenshot of the maths inside &app;.

## Support.

### To Ask a Question

If you choose Help Ask a question, your mail agent should pop up with a new message to the GChemPaint mailing list.

Another way to get some help is to connect on the #gchemutils channel at irc.gimp.net and ask your question there (if you are not alone on the channel).

### To Find the Gnome Chemistry Utils on the Web.

If you choose Help Gnome Chemistry Utils on the web, the default web browser should pop up and display the main page for the Gnome Chemsitry Utils.

The main page is http://gchempaint.nongnu.org and the project page at savannah http://savannah.nongnu.org/projects/gchempaint.

### To Report a Bug

To report a bug, you must use the bug page for the Gnome Chemistry Utils at Savannah. You can access it by choosing Help Report Bugs (hopefully you'll have only one at once to report).

You can also type the bug report page address directly in the browser. The bug repository is at https://savannah.nongnu.org/bugs/?group=gchempaint

## License

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

A copy of the GNU General Public License is included as an appendix to the GNOME Users Guide. You may also obtain a copy of the GNU General Public License from the Free Software Foundation by visiting their Web site or by writing to

        Free Software Foundation, Inc.
        51 Franklin St - Fifth Floor
        Boston, MA 02111-1307
        USA