TikZiT Manual

- -

NOTE: This manual is currently written for the OS X version of TikZiT. However, we try to make the Linux and Windows ports as similar to the Mac version as possible, so much of the info here should still apply.

- -

TikZiT is a tool for editing graphs written in PGF/TikZ. PGF/TikZ is a -big macro package for embedding all kinds of diagrams in LaTeX. It's included -in most TeX distributions, so if you use TeX, you probably already have it. -Lots of info and examples can be found on texample.net, and the (very extensive) -manual can be found here.

- -

TikZiT uses *.tikz files, which are text files written in a subset of TikZ. Virtually everything TikZiT uses comes from the \node command and the \draw command. Users can edit a graph by using the GUI or editing the TikZ file from within TikZiT and parsing changes.

- -

Basic Graph Editing

- -

TikZiT has four basic tools: Select, Add Vertex, Add Edge, and Crop (Fig. 1). The Select tool is for selecting and moving vertices and edges. For vertices, this works pretty much as you would expect. Edges can be selected by clicking on them directly, which makes their control points become visible in blue (Fig. 2). Click and drag a control point to set the bend property of and edge. The radius of the circles indicates the looseness.

- -

Fig.1: The Tool Palette

- -

Fig.2: Setting the Bend

- -

Fig.3: Bezier Mode

- -

Double-click and edge to go to Bezier Mode (Fig. 3). The control points in Bezier Mode can be moved independently, and rather than setting bend, it sets the in and out properties of an edge. It is often useful to use the Shift key to select multiple edges, making their control points visible. Editing any of those edges' control points will not deselect the edges. Hold down the ⌘Command key to move both control points at once. This is particularly useful for self-loops.

- -

The Add Vertex tool adds a new vertex to the graph where you click. It is given the style that is selected in the Style Palette. If no style is selected, an Unstyled Vertex is added. Unstyled vertices are represented as dotted lines around a point, and are invisible. They are useful for making complex paths (Fig. 4) and edges that are not otherwise connected to vertices.

- -

Fig.4: Unstyled Vertices/Compound Path

- -

Fig.5: Adding an Edge

- -

Fig.6: Setting the Bounding Box

- -

The Add Edge tool adds new edges. With the tool selected, click and drag from the source vertex to the target vertex to create an edge (Fig. 5). Although TikZiT doesn't show the direction of the edge, it could still be relevant (e.g. for arrow heads), depending on the style of the edge. Click on a vertex to add a self-loop.

- -

Though TikZ computes bounding boxes automatically, if you wish to set one manually, you can do so using the Crop tool. Click and drag a box to set the bounding box. Click anywhere to remove it. The bounding box itself is implemented using a rectangular path with the use as bounding box property set.

- -

Editing Properties and Styles

- -

All graph, node, and edge properties can be edited using the Property Inspector. This inspector is divided into three parts: one for each type of property. These can be expanded or collapsed using the triangles in the upper left corner of each section. TikZiT handles two kinds of properties: normal properties and atoms. Normal properties are key/value pairs stored with the graph/node/edge. Atoms are just keys, leaving the value of the property itself implicit. Examples are baseline or <-. To add a new property, click the "+" button in the relevant section. To add a new atom, click the "+_a" button. Use the "-" button to remove a property or atom.

- -

You can also use the Property Inspector to edit the labels on nodes. After editing a label, you may need to hit Return to apply your changes. Always do this before deselecting the node.

- -

Fig.7: Property Inspector

- -

Fig.8: Style Inspector

- -

With the Property Inspector you can add a node to an edge by selecting it and clicking the checkbox next to Child Node. This node will be placed in the middle of the edge by default, but you can change this by editing it's properties. Often the atom auto is applied to an edge node to position its label a little off the edge. Again, when labelling an edge node, be sure to hit Return to apply your changes.

- -

The Style Inspector lets you add, remove, and edit styles. You can edit a style's name, shape, foreground colour, background colour, and scale. Note that these properties change how nodes of this style will appear in TikZiT, but not necessarily in the final, built LaTeX. TikZiT styles are meant more as a visual cue for the sake of editing graphs than to produce a nice end result. Use Apply to apply the selected style to the selected nodes and Clear to clear the style.

- -

Editing the TikZ Code Directly

- -

TikZiT supports a small subset of the TikZ language. At any point, you can edit the TikZ code manually in the bottom half of the window. Editing the code will cause the main graph display to ghost, and it prevents editing with the GUI until the graph is re-parsed using ⌘T. If the parse was successful, the main graph will un-ghost, and a message saying success will be displayed along the bottom of the window. If the parse was unsuccessful, parse error will be displayed.

- -

As a reference, here is the complete syntax supported by TikZiT:

- -

- <tikzpicture> ::= "\begin{tikzpicture}" <properties>?
- <expression>*
- - "\end{tikzpicture}"
-
- <expression> ::= <ignore> | <node> | <edge> | <bounding box>
- -
- <ignore> ::= "\begin{pgfonlayer}" DELIMITED_STRING |
- "\end{pgfonlayer}"
- -
- <properties> ::= "[" <property> ("," <property>)* "]"
- -
- <property> ::= <symbol>* "=" <value> | <symbol>*
- -
- <symbol> ::= WORD | NUMBER
-
- <value> ::= <symbol>* | QUOTED_STRING
- -
- <node> ::= "\node" <properties>? <node name>
- "at" <coords> DELIMITED_STRING ";"
- -
- <node name> ::= "(" (NATURAL_NUMBER | WORD) (".center")? ")"
- -
- <coords> ::= "(" NUMBER "," NUMBER ")"
-
- - <edge> ::= "\draw" <properties>? <node name>
- "to" <edge node>? (<node name> | "()") ";"
- -
- <edge node> ::= "node" <properties>? DELIMITED_STRING
-
- <bounding box> ::= "\path" "[use as bounding box]" <coords>
- - "rectangle" <coords> ";" -

- -

Note that DELIMITED_STRING means a string delimited by braces ( { , } ). This string can contain any character, including other braces, provided they are nested correctly. A WORD may contain letters, greater-than ( > ), less-than ( < ), dash ( - ), and prime ( ' ). Question mark ( ? ) denotes optional productions, and star ( * ) denotes repeated ones.

- -

Preambles and LaTeX Preview

- -

Use ⌘R to preview the current graph using LaTex. The preview will be shown in a new window. In the event of an error, the LaTeX output is displayed.

- -

Fig.8: LaTeX Preview

- -

The Preamble Editor is used to set up the preamble that the LaTeX preview uses. The default preamble will include minimal style definitions, but you will most likely want to use a default preamble. A good strategy is to define all of the TikZ styles in a single LaTeX file, then \input that file both in your paper and in the TikZiT preamble.

- -

Fig.9: Preamble Editor

- -

Use the "+" and "-" buttons to add or remove custom preambles. Double-click a preamble's name to change it. Click Insert Styles to paste in the styles from the default preamble at the current cursor location.

- - -

Custom Shapes

- -

Custom shapes are implemented in TikZiT. To add a custom shape, navigate to the TikZiT support directory: ~/Library/Application Support/TikZiT. If it doesn't already exist, create a directory called shapes. Now, you can add *.tikz files to this directory, and they will be included as shapes in TikZiT.

- -

Not all graphs will made nice looking shapes. TikZiT builds a shape from a graph by extracting all of the paths in the TikZ graph, and drawing them as (filled) bezier curves.

- -

Fig.10: A Custom Shape

- -

The best graphs for defining shapes are single cycles, consisting of unstyled nodes. You can draw a shape as big or small as you like. When the shape is displayed in TikZiT with scale = 1, the shape will fit inside a 4x4 square on the grid. If you make a change to the custom shapes with TikZiT open, click Refresh Shapes in the TikZ menu to refresh the shapes.

- - - - -