0.2
Copyright © 2010, 2011 Glad Deschrijver
Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.2 or any later version published by the Free Software Foundation; with no Invariant Sections, with no Front-Cover Texts, and with no Back-Cover Texts. A copy of the license is included in the section entitled "GNU Free Documentation License".
Abstract
QtikZ is program for Qt for creating TikZ (from the LaTeX pgf package) diagrams.
Table of Contents
List of Examples
QtikZ is a TikZ/PGF code editor for Qt which allows to preview the code real-time while editing. The editor features syntax highlighting of the TikZ/PGF code, the TikZ/PGF commands can be inserted from a menu or a dock widget, the style of the preview can be changed by setting a template.
Please report any problems or feature requests to the QtikZ author via the bug report dialog. This is accessible from the → menu of the application.
Table of Contents
The QtikZ main window consists of a (1) menu bar, (2) toolbar, (3) template selector, (4) text editor, (5) preview panel, (6) messages panel and (7) status bar.
The Preview and Messages panels can be shown or hidden in → . The visible panels can then be dragged around the QtikZ window by clicking and dragging the panel title.
In the editor the source code of a TikZ picture (everything between “\begin{tikzpicture}” and “\end{tikzpicture}”) can be edited. While editing, a preview of the TikZ picture is generated on the fly in the Preview panel. The TikZ code is highlighted in different colors according to the syntax. Text-completion is provided for TikZ commands: when the user types the first letters of a TikZ command, the commands starting with those letters are listed and can be selected by the user using the arrow keys and pressing Enter. If a TikZ command is selected in this way or if it is selected from the Insert menu, the syntax of the command is shown in the status bar. In the inserted text the options or arguments that must be filled in are marked with •. The first of these symbols is automatically selected and can be overwritten by just typing. You can select the next or previous • by pressing Tab or Shift+Tab.
If the user triggers the Find or Replace action, a “Find & Replace” panel appears at the bottom of the editor. In the Find text field, the text to be searched is entered. In the Replace with text field the text to replace with can be entered. Pressing the Find button will only search for the text, while pressing the Replace button will show a “Replace” bar with the following options: Replace the first occurrence, Replace All occurrences, Don't Replace the current occurrence, or Cancel the replace operation. Checking the Whole words option will cause the find to match only complete words, checking the Case sensitive option will cause the find to match only those occurrences which have exactly the same case (otherwise the find works case insensitive). Two arrow buttons are available which allow the user to specify the direction in which the search should be done (move backwards or forward in the text). Finally there is a Cancel button which causes the panel to be closed.
If the user triggers the Go to Line action, a “Go to Line” panel appears at the bottom of the editor. In the Go to line spin box, the line number to which the cursor should be moved is entered. Pressing Enter or the Go button closes the panel and moves the cursor in the editor to the specified line. Finally there is a Cancel button which causes the panel to be closed without moving the cursor.
If the user triggers the Indent action, an “Indent” panel appears at the bottom of the editor. The indentation character (space or tab) can be selected and the number of times that character is inserted at the start of each to be indented line can be chosen in the corresponding spin box. Pressing Enter or the Indent button closes the panel and indents the selected lines (or the current line if no line is selected) in the editor. Finally there is a Cancel button which causes the panel to be closed without indenting.
In the Preview panel an image which is the result of compiling the current TikZ code in the editor is shown. If there are errors in the TikZ code, an error message is shown instead. The preview can be enlarged or made smaller by pressing the Zoom In and Zoom out buttons or by changing the zoom percentage. The zoom percentage can also be changed by rolling the mouse wheel while pressing the Ctrl button.
If the TikZ code contains several pictures (enclosed by “\begin{tikzpicture}” and “\end{tikzpicture}”), then the preview will only show one picture. The other images can be shown by pressing the Previous Image and Next Image buttons which become available in this case.
If there are errors in the TikZ code, an error message is shown in the Messages panel. If the error message is not clear enough, then the user can press the View Log button and the complete LaTeX log file will be shown in the Messages panel.
The template selector consists of a text field in which the path to a template file is given, a button which opens a file selector dialog in which the template file can be selected, a reload button which can be pressed to regenerate the preview when the template file is edited in an external editor, and an Edit button which opens the template file in an external editor.
See the section on templates for more details on how to use templates in QtikZ.
Table of Contents
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 3.1. 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.
QtikZ 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, QtikZ 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:
Example 3.2. 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}
Example 3.3. 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}
The following are a number of tips to enhance the experience of using QtikZ.
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 QtikZ 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 3.4. 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}
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 QtikZ by default. However, using an appropriate template it is possible to use these commands and QtikZ 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 3.5. 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}
QtikZ 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 QtikZ 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 → PS → PDF compilation, so you will also have to apply the next tip.
Example 3.6. 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 3.7. 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}
Since QtikZ 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).
Example 3.8. LaTeX → PS → 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 QtikZ 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 QtikZ, go to Settings -> Configure QtikZ..., 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 3.9. Example template file for LaTeX → PS → 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 ( → ), 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 → PS → PDF compilation).
Many of the shortcuts are configurable by way of the Settings menu. By default QtikZ 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 | |
Shift+F1 | |
F3 | |
Shift+F3 | |
Ctrl+A | |
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 | |
Ctrl+Shift+D | |
Ctrl+F | |
Ctrl+G | |
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++ | |
Ctrl+- |
This starts a new document in a new and independent editor window.
Displays a standard Qt Open File dialog. Use the file view to select the file you want to open, and click on to open it. You can find more information about the Qt Open File dialog in the Qt User Guide.
This is a shortcut to open recently saved documents. Clicking on this item opens a list to the side of the menu with several of the most recently saved files. Clicking on a specific file will open it in QtikZ - if the file still resides at the same location.
This saves the current document. If there has already been a save of the document then this will overwrite the previously saved file without asking for the user's consent. If it is the first save of a new document the save as dialog (described below) will be invoked.
This allows a document to be saved with a new file name. This is done by means of the file dialog box described above in the Open section of this help file.
Exports the current document to different formats, so that the document can be viewed as an image. Currently the document can be exported as Encapsulated PostScript (EPS), Portable Document Format (PDF), Portable Network Graphics (PNG), Joint Photographic Experts Group Format (JPEG), Tagged Image File Format (TIFF) and Windows Bitmap (BMP).
Reload the current document from disk. If you have made unsaved changes, you will be prompted to save the file before QtikZ reloads it.
Opens a simple print dialog allowing the user to specify what, where, and how to print.
Close the active file with this command. If you have made unsaved changes, you will be prompted to save the file before QtikZ closes it.
This will close the editor window, if you have more than one instance of QtikZ running, through the or menu items, those instances will not be closed.
This is used to eliminate or reverse the most recent user action or operation.
This will reverse the most recent change (if any) made using Undo.
This command deletes the current selection and places it on the clipboard. The clipboard is a feature of Qt that works invisibly to provide a way to transfer data between applications.
This copies the currently selected text to the clipboard so that it may be pasted elsewhere. The clipboard is a feature of Qt that works invisibly to provide a way to transfer data between applications.
This will insert the contents of the clipboard at the cursor position. The clipboard is feature of Qt that works invisibly to provide a way to transfer data between applications.
This will select the entire document. This could be very useful for copying the entire file to another application.
This increases the paragraph's indentation by one step. The size of the step can be selected in the dialog that appears when triggering this action.
This adds the LaTeX comment character “%” and one space to the beginning of the line where the text cursor is located or to the beginning of any selected lines.
This removes the LaTeX comment character “%” and one space (if any exist) from the beginning of the line where the text cursor is located or from the beginning of any selected lines.
This opens the search bar at the bottom of the editor window. On the left side of the bar is an icon to close the bar, followed by a small text box for entering the search pattern.
You have to enter the characters of your search pattern and press the
button. If there is a match in the text, this is highlighted. Continue to press the button to find the next matches. If the search pattern does not match any string in the subsequent text anymore, a dialog asking to start searching from the beginning is shown.Use the
or button to direct the search to proceed in an upwardly or downwardly direction.You can modify the search behavior by selecting different Options: Checking Whole Words Only prevents the search from stopping on words that contain the searched for pattern. Selecting Case Sensitive will limit finds to entries that match the case (upper or lower) of each of the characters in the search pattern.
This repeats the last find operation, if any, otherwise starts a new find operation.
This repeats the last find operation, if any, searching backwards instead of forwards through the document.
This opens the search and replace bar at the bottom of the editor window. On the left side of the bar is an icon to close the bar, followed by a small text box for entering the search pattern.
Use the
or button to direct the search to proceed in an upwardly or downwardly direction.You can modify the search behavior by selecting different Options: Checking Whole Words Only prevents the search from stopping on words that contain the searched for pattern. Selecting Case Sensitive will limit finds to entries that match the case (upper or lower) of each of the characters in the search pattern.
Enter the text to be replaced in the text box labeled Find and the text to replace with in the text box labeled Replace, then click the button. The replace bar is replaced by a set of buttons. If there is a match in the text, this is highlighted. Press to replace the currently highlighted text. Continue to press the button to find and replace the next matches. If the search pattern does not match any string in the subsequent text anymore, a dialog asking to start searching from the beginning is shown. Press the button to replace the search text in the whole document. Press the button to skip the currently highlighted text and find the next match. Press the button to cancel the replacing.
The
menu allows you to manage settings specific to the preview.Increase the magnification of the document view.
Decrease the magnification of the document view.
Show the preview of the previous TikZ picture in the code. This item is only shown when there are multiple TikZ pictures in the code (delimited by “\begin{tikzpicture}” and “\end{tikzpicture}”).
Show the preview of the next TikZ picture in the code. This item is only shown when there are multiple TikZ pictures in the code (delimited by “\begin{tikzpicture}” and “\end{tikzpicture}”).
This opens the goto line bar at the bottom of the window which is used to have the cursor jump to a particular line (specified by number) in the document. The line number may be entered directly into the text box or graphically by clicking on the up or down arrow spin controls at the side of the text box. The little up arrow will increase the line number and the down arrow decrease it. Close the bar with a click on the icon on the left side of the bar.
Abort the execution of the currently running process.
Show the LaTeX log file in the Messages panel.
Enable LaTeX to run shell commands, this is needed when you want to plot functions using gnuplot within TikZ.
Enabling this may cause malicious software to be run on your computer! Check the LaTeX code to see which commands are executed.
This menu contains a (currently non-exhaustive) list of TikZ commands. By selecting them, you can insert them in the text at the cursor's current position.
This menu contains the list of user-defined TikZ commands. By selecting them, you can insert them in the text at the cursor's current position. The entries of this menu can be edited by selecting
.This submenu lists the available toolbars, each item toggles the display of the associated toolbar. When checked, each item displays a movable toolbar containing buttons used to initiate frequently used commands. When unchecked the toolbar is hidden.
This submenu lists the available sidebars, each item toggles the display of the associated sidebar.
This menu item opens a dialog whereby several different settings may be adjusted.
QtikZ has a standard Qt as described below, with one addition:
Opens the TikZ Manual. This is the full TikZ Manual bundled with the LaTeX PGF package, it contains a tutorial on how to use TikZ and a reference guide of all PGF and TikZ commands.
The standard Qt
entries are:Invokes the Qt Help system starting at the QtikZ help pages. (this document).
Changes the mouse cursor to a combination arrow and question mark. Clicking on items within QtikZ will open a help window (if one exists for the particular item) explaining the item's function.
This will display version and author information.
This displays the Qt version and other basic information.
Table of Contents
In order to configure QtikZ the user needs to access the QtikZ Configuration dialog. This can be accessed via the menu bar, by selecting → .
The QtikZ Configuration dialog consists of three sections; General, Editor and Highlighting. Clicking one of these sections in the vertical list on the left side of the dialog will make those options available accordingly. The options available are displayed to the right of the dialog.
By means of buttons along the bottom of the box the user can control the configuration process. You may invoke the Help system, accept the current settings and close the dialog by means of the button, or the process.
The categories General, Editor and Highlighting are detailed in the following sections.
This section of the dialog lets you configure the interface and set the paths to the necessary executables and the documentation.
If this option is checked, a dock widget is available with a list of TikZ commands which you can insert in your code by clicking on them. If this option is not checked, the TikZ commands will be available in a menu instead. You have to restart QtikZ for this change to take effect.
Specify whether the preview should be generated automatically or manually.
If this option is checked, the TikZ code in the editor is compiled while editing.
If this option is checked, a Build button is available and the TikZ code is only compiled when you press that button.
If this option is checked, the coordinates of the mouse cursor in the preview are shown.
If this option is checked, the mouse coordinates are shown with enough precision but without redundant decimals.
If this option is checked, the mouse coordinates are shown with the specified number of decimals.
Enter the path of the PDFLaTeX executable here. This executable is used to typeset a LaTeX file containing the TikZ code in order to generate the preview.
Enter the path to the pdftops executable (part of poppler) here. This executable is used to export the image to EPS (Encapsulated PostScript).
Enter the path to the file containing the TikZ documentation here. An URL to online documentation may also be given.
Press this button to search the file containing the TikZ documentation in the TeX directory structure using kpsewhich.
This section of the dialog lets you configure the look and feel of the text editor.
Select the font of the unhighlighted main text.
Show white spaces in the text by replacing them with special symbols. These symbols will not be saved on disk.
Select the color in which the spaces will be shown.
Show tabulators in the text by replacing them with special symbols. These symbols will not be saved on disk.
Select the color in which the tabulators will be shown.
If the cursor is on a bracket ({[]}), then the corresponding opening/closing bracket will be highlighted.
Select the color in which the highlighted brackets will be shown.
When the first letters of a TikZ command are typed in the text, a list of possible completions will be shown.
This section of the dialog lets you configure the fonts and colors for the highlighted code in the text editor.
When this option is checked, the default fonts and colors are used in the output.
When this option is checked, the fonts and colors defined below will be used in the output instead of the default ones.
Select in the table the structure appearing in the TikZ code for which you want to change the fonts and colors.
Select the font in which the structure that you selected in the table above should be displayed.
Select the text color in which the structure that you selected in the table above should be displayed.
QtikZ
Program copyright 2007-2011 Florian Hackenberger <florian@hackenberger.at>
Program copyright 2007-2011 Glad Deschrijver <glad.deschrijver@gmail.com>
Documentation copyright 2010, 2011 Glad Deschrijver <glad.deschrijver@gmail.com>
This documentation is licensed under the terms of the GNU Free Documentation License.
This program is licensed under the terms of the GNU General Public License.
Table of Contents
QtikZ can be found at the official homepage. QtikZ is also available at http://www.kde-apps.org.
In order to successfully use QtikZ you need to at least to have Qt 4.4 and poppler 0.6 installed.
In order to compile QtikZ it is necessary to install the development packages for Qt 4.4, poppler 0.6 and gcc.
For detailed information on how to compile and install QtikZ, see the INSTALL file that is provided with the source.
Since Qt uses qmake you should have no trouble compiling QtikZ. Should you run into problems please report them via email to the developers.