# Using &ktikz;

## Editing

The source code of a TikZ picture (this is the code between \begin{tikzpicture} and \end{tikzpicture} that would normally be included in a LaTeX file) is edited in the editor.

### Example content of the editor

    \begin{tikzpicture}[x=4cm,y=4cm]
      %\tikzstyle{every node}=[font=\small]
      \def\xx{0.3} \def\xy{0.7}

      \draw[color=black,fill=black!30]
        (0,0) node[below left] {$[0,0]$} --
        (1,1) node[right] {$[1,1]$} --
        (0,1) node[left] {$[0,1]$};
      \draw[-latex] (0,0) -- (1.125,0) node[right=3,below] {$x_1$};
      \draw[-latex] (0,0) -- (0,1.125) node[right=-1] {$x_2$};

      \fill[fill=black] (\xx,\xy) circle (.2em)
        node[right=20,above] {$x = [x_1,x_2]$};
      \draw[dashed] (\xx,0) node[below] {$x_1$}
        -- (\xx,\xy)
        -- (0,\xy) node[left] {$x_2$};
    \end{tikzpicture}

While editing, a preview of the TikZ picture is generated on the fly in the Preview panel. If an error occurs, the error messages are displayed in the Messages panel. If the error messages are not clear, the complete LaTeX log file can be displayed in the Messages panel by clicking the View Log button.

When the TikZ picture contains function plots which are created externally using `gnuplot`, the Shell Escape option should be enabled in the toolbar or in the Process menu.

Note that enabling the Shell Escape option is dangerous, since this can cause malicious software to be run on your computer! So you should check the TikZ code and the LaTeX code in the template file to see which commands are executed.

## Templates

&ktikz; features a template mechanism. A template file is a skeleton LaTeX file in which all necessary packages and definitions are loaded and in which the style (fonts, ...) is determined. A template file does (usually) not contain any real contents, instead it contains a replacement string (which is <> by default) which is replaced by the TikZ code in the editor when the preview is generated.

When the preview is generated, &ktikz; internally replaces the replacement string in the template file by the TikZ code in the editor and compiles the resulting LaTeX file. The resulting PDF file is then displayed in the Preview panel. If any errors occur during compilation (both errors in the TikZ code and in the template file), they are displayed in the Messages panel.

The user can create template files and specify the full path in the Template text field. If the Template text field is empty while generating the preview, an internal template file is used, so the user is not forced to create a template file.

For example, a template file named `ktikz_template.pgs` could contain the following:

### An example template file

    \documentclass{article}
    \usepackage{mathptmx}
    \usepackage{tikz}
    \usepackage{color}
    \DeclareSymbolFont{symbolsb}{OMS}{cmsy}{m}{n}
    \SetSymbolFont{symbolsb}{bold}{OMS}{cmsy}{b}{n}
    \DeclareSymbolFontAlphabet{\mathcal}{symbolsb}
    \usepackage[active,pdftex,tightpage]{preview}
    \PreviewEnvironment[]{tikzpicture}
    \PreviewEnvironment[]{pgfpicture}
    \begin{document}
    <>
    \end{document}

### Another example template file

    \documentclass[compress]{beamer}
    \usetheme{Frankfurt}
    \usepackage{amsmath}
    \usepackage{booktabs}
    \usepackage{tikz}
    %\usepackage{color}
    \usepackage[active,pdftex,tightpage]{preview}
    \PreviewEnvironment[]{tikzpicture}
    \input{hulpjes.tex}
    \begin{document}
    <>
    \end{document}

## Tips

The following are a number of tips to enhance the experience of using &ktikz;.

### Allow to insert UTF8 characters in the TikZ code

When writing TikZ code with Russian or Greek text (or other languages with a non-Latin script), it would be nice to be able to insert those characters directly in the editor and have &ktikz; compile this code correctly. This can be achieved by using a template in which the necessary LaTeX packages are loaded. The following example (by Alexander Kudrevatykh) shows a template file which can be used for this purpose.

#### Example template file which allows to insert UTF8 characters

    \documentclass[12pt]{article}
    \usepackage[T2A]{fontenc}
    \usepackage[utf8]{inputenc}
    \usepackage{tikz}
    \usepackage[active,tightpage]{preview}
    \PreviewEnvironment[]{pgfpicture}
    \PreviewEnvironment[]{tikzpicture}
    \begin{document}
    <>
    \end{document}

### Using the beamer commands \uncover and \only in PGF pictures

When creating tikzpictures which will be included in slides created with the LaTeX beamer package, one may need the commands \uncover or \only or similar in the tikzpicture itself. Support for these commands is not included in &ktikz; by default. However, using an appropriate template it is possible to use these commands and &ktikz; will generate several images in the preview which can be browsed using the Previous Image and Next Image buttons. The following example shows a template file which can be used for this purpose.

#### Example template file which allows to use the beamer commands \uncover and \only

    \documentclass[compress]{beamer}
    \usetheme{Berlin}
    \setbeamercovered{transparent}
    \usepackage{tikz}
    \begin{document}
    \begin{frame}{}
    <>
    \end{frame}
    \end{document}

### Using &ktikz; for picture packages other than PGF

&ktikz; is designed to be used for TikZ or PGF pictures (pictures created using the LaTeX PGF package). But by using the template mechanism in a smart way it is possible to use &ktikz; also for other picture packages available in LaTeX. For example, the following template file could be used to be able to draw pspictures (with the pstricks package). Note however that pstricks only supports LaTeX &to; PS &to; PDF compilation, so you will also have to apply the next tip.

#### Example template file for pstricks

    \documentclass{article}
    \usepackage{mathptmx}
    \usepackage{pstricks}
    \DeclareSymbolFont{symbolsb}{OMS}{cmsy}{m}{n}
    \SetSymbolFont{symbolsb}{bold}{OMS}{cmsy}{b}{n}
    \DeclareSymbolFontAlphabet{\mathcal}{symbolsb}
    \usepackage[active,dvips,tightpage]{preview}
    \PreviewEnvironment[]{pspicture}
    \begin{document}
    <>
    \end{document}

#### Example content of the editor

    \psset{unit=.45pt}
    \begin{pspicture}*(420, 420)
      \psset{linewidth=.4pt}
      % Frame
      \pspolygon(0, 0)(420, 0)(420, 420)(0, 420)
      % Circumscribed circle and inscribed circle
      \pscircle(206, 222){166.18}
      \pscircle(250, 197){75.42}
      % Adjacent circles
      \pscircle[linestyle=dashed](476, 135){157.68}
      \pscircle[linestyle=dashed](-32, -22){266.53}
      \pscircle[linestyle=dashed](132, 579){315.92}
      % triangle
      \psset{linewidth=1pt}
      \pspolygon(43, 253)(361, 283)(287, 77)
      % nine-points circle (Feuerbach)
      \pscircle[linestyle=dotted](242, 195){83.09}
    \end{pspicture}

### Using LaTeX &to; PS &to; PDF compilation

Since &ktikz; is designed to be used for TikZ and PGF pictures, the compilation done behind the scenes is done with `pdflatex`. Using the following shell script (only for Unices) and an appropriate template file, it is however possible to generate the preview by using the `latex`, `dvips`, `ps2pdf` sequence (i.e. first compile to PS and then convert the PS to PDF).

#### LaTeX &to; PS &to; PDF compilation shell script

    #!/bin/sh

    # This shell script compiles a LaTeX file to PDF using the latex, dvips,
    # ps2pdf sequence and is supposed to be used in &ktikz; only, as a replacement
    # for pdflatex.
    # Therefore the following assumptions are made in the code of this script:
    # - the only options with a value are -output-directory and -interaction
    # - the name of the tex file passed to this script always ends on .tex
    # - the name of the tex file is the only thing which is not an option or
    #   the value of one of the above mentioned options

    # Usage:
    # - open &ktikz;, go to Settings -> Configure &ktikz;..., in the "General" tab
    #   change the value of PDFLaTeX command to /path/to/ktikzlatex2ps2pdf.sh
    # - in the "Template" box change the value to /path/to/ktikzlatex2ps2pdf_template.pgs

    options=""
    texfile=""

    while test x"$1" != x
    do
    	case $1 in
    		-output-directory|-interaction) # add their values to the list of options
    			options="$options $1"
    			shift
    			options="$options $1"
    			shift;;
    		-*)
    			options="$options $1"
    			shift;;
    		*)
    			texfile=$1
    			shift;;
    	esac
    done

    texfilebasename=`echo $texfile | sed -e "s/\.tex$//"`

    latex $options $texfilebasename.tex
    # return when latex fails (otherwise ps2pdf below runs without errors)
    latexreturn=$?
    if test $latexreturn -ne 0
    then
    	exit 1
    fi

    export DVIPSHEADERS=$DVIPSHEADERS:$TEXINPUTS # if a dvips header file is located in the same directory as the template file, then this will make dvips find it
    dvips -Ppdf -G0 -o $texfilebasename.ps $texfilebasename.dvi

    ps2pdf14 $texfilebasename.ps $texfilebasename.pdf

#### Example template file for LaTeX &to; PS &to; PDF compilation

    \documentclass{article}
    \usepackage{mathptmx}
    \usepackage{tikz}
    \usepackage{color}
    \DeclareSymbolFont{symbolsb}{OMS}{cmsy}{m}{n}
    \SetSymbolFont{symbolsb}{bold}{OMS}{cmsy}{b}{n}
    \DeclareSymbolFontAlphabet{\mathcal}{symbolsb}
    \usepackage[active,dvips,tightpage]{preview}
    \PreviewEnvironment[]{tikzpicture}
    \PreviewEnvironment[]{pgfpicture}
    \begin{document}
    <>
    \end{document}

In the configuration dialog (Settings Configure &ktikz;...), the PDFLaTeX command should be replaced by the full path to the above shell script (or simply the shell script name if the script is in the PATH). In the main window, the Template should be replaced by the above template (or another template file that is compatible with LaTeX &to; PS &to; PDF compilation).

## Shortcuts

Many of the shortcuts are configurable by way of the Settings menu. By default &kappname; honors the following shortcuts:

Left Arrow | Move the cursor one character to the left.
Right Arrow | Move the cursor one character to the right.
Up Arrow | Move the cursor up one line.
Down Arrow | Move the cursor down one line.
Page Up | Move the cursor up one page.
Page Down | Move the cursor down one page.
Backspace | Delete the character to the left of the cursor.
Home | Move the cursor to the beginning of the line.
End | Move the cursor to the end of the line.
Delete | Delete the character to the right of the cursor (or any selected text).
&Shift;Left Arrow | Mark text one character to the left.
&Shift;Right Arrow | Mark text one character to the right.
F1 | Help
&Shift;F1 | What's this?
F3 | Find Next
&Shift;F3 | Find Previous
&Ctrl;A | Select All
&Ctrl;B | Set or unset a bookmark for the current line in the text editor.
&Alt;Up | Go to the previous bookmark.
&Alt;Down | Go to the next bookmark.
&Ctrl;C | Copy the marked text to the clipboard.
&Ctrl;D | Comment
&Ctrl;&Shift;D | Uncomment
&Ctrl;F | Find
&Ctrl;G | Go to line...
&Ctrl;I | Indent selection.
&Ctrl;N | New document.
&Ctrl;O | Open a document.
&Ctrl;P | Invokes the Print command.
&Ctrl;Q | Quit - close active copy of editor.
&Ctrl;R | Invokes the Replace command.
&Ctrl;S | Invokes the Save command.
&Ctrl;V | Paste the clipboard text into line edit.
&Ctrl;W | Invokes the Close command.
&Ctrl;X | Delete the marked text and copy it to the clipboard.
&Ctrl;Z | Invokes the Undo command.
&Ctrl;&Shift;Z | Invokes the Redo command.
&Ctrl;+ | Zoom In
&Ctrl;- | Zoom Out