1 \documentclass[12pt,a4paper]{article}
2 \usepackage[utf8]{inputenc}
7 %https://de.overleaf.com/learn/latex/Code_listing
9 \lstdefinestyle{mystyle}{
10 backgroundcolor=\color{backcolour},
11 commentstyle=\color{codegreen},
12 keywordstyle=\color{magenta},
13 numberstyle=\tiny\color{codegray},
14 stringstyle=\color{codepurple},
15 basicstyle=\ttfamily\tiny,
16 breakatwhitespace=false,
23 showstringspaces=false,
28 \setlength{\headheight}{0cm}
29 \setlength{\headsep}{0cm}
30 \setlength{\topskip}{0cm}
31 \setlength{\topmargin}{-0.5cm}
33 \setlength{\parskip}{1.5ex}
34 \setlength{\parindent}{0cm}
35 \setlength{\oddsidemargin}{0cm}
36 \setlength{\textwidth}{16cm}
37 \setlength{\textheight}{25cm}
39 \newlength{\maximgwidth}
40 \setlength{\maximgwidth}{14cm}
41 \newcommand{\maximage}[1]{
43 \includegraphics[width=\maximgwidth]{#1}
46 \newcommand{\hint}[1]{
48 \begin{tabular}{|rp{12cm}|} \hline
49 {\bf Hint}:& #1\\ \hline
55 \newcommand{\vym}{{\sc vym }}
56 \newcommand{\ra}{$\longrightarrow$}
57 \newcommand{\la}{$\longleftarrow$}
58 \newcommand{\ua}{$\uparrow$}
59 \newcommand{\da}{$\downarrow$}
60 \newcommand{\key}[1]{[#1]}
62 \newenvironment{code}[1] { \verbatim #1}{\endverbatim }
65 \pagenumbering{arabic}
67 \hypersetup{bookmarks, bookmarksopen,
68 pdftitle={VYM - a tool for visual thinking },
69 pdfauthor={Uwe Drechsel},
71 pdfkeywords={map, tool},
72 pdfpagemode={UseOutlines},
73 bookmarksopenlevel={1},
83 \includegraphics[width=8cm]{images/vym-logo-new.png} \\
84 VYM -- View Your Mind \\
85 {\small Version 2.9.0} \\
87 \author{\textcopyright Uwe Drechsel }
100 Many people have sent me their feedback and ideas, and all of that has
101 helped a lot to make \vym better. Thanks to all of you!
103 For this manual I would like to send some special thanks to
106 \item {\em Peter Adamson} for lots of feedback and proofreading of my
107 far from perfect english
108 \item The team of {\em AClibre (Academia y Conocimiento Libre)}
109 in Colombia for their initial translation of
110 the manual to spanish:
112 \begin{tabular}{|p{7cm}|p{5.5cm}|} \hline
113 Encargado & Actividad \\ \hline
115 \item Vanessa Carolina Guti\'errez Sanchez
116 \item Erika Tatiana Luque Melo
117 \item Jeffrey Steve Borb\'on Sanabria
118 \item John Edisson Ortiz Rom\'an
122 \item Revisi\'on y correcciones varias
123 \item Estructuraci\'on y exporte
124 \item Revisi\'on y correcciones varias
125 \end{itemize} \\ \hline
132 \section{Introduction}
133 \subsection{What is a \vym map?}
134 A \vym map (abbreviated below as {\em map}) is a tree-like structure:
135 \maximage{images/example1.png}
136 Such maps can be drawn by hand on a sheet of paper or flip chart and
137 help to structure your thoughts. While a tree like structure like the
138 illustration above can be drawn manually \vym offers much more features
139 to work with such maps. \vym is not just another drawing software
140 application, but a tool to store and modify information in an intuitive
141 way. For example you can reorder parts of the map by pressing a key or
142 add various pieces of information like a complete email by a simple
145 Once you have finished collecting and organising your ideas, you can
146 easily generate a variety of outputs including for example a
147 presentation in Open~Office based on a {\em map}.
149 \hint{You find the map shown above and others by clicking
150 \begin{center}Help \ra Open vym examples\end{center} in the menu bar.}
152 \subsection{Why should I use {\em maps}? Time, Space and your Brain.}
153 \subsubsection*{Space}
154 A {\em map} can concentrate very complex content in a small space such
155 as a piece of paper. It helps to use both sides of your brain: the
156 logical side and also your creative side (e.g. by using pictures,
157 colours and keywords in a map, often called {\em anchors}). It is a
158 technique to help organize the way you think and stimulate your
159 creativity: It can help you by developing, sorting and helping to
162 \subsubsection*{Time}
163 Because you just use keywords and drawings, it is much faster than good
164 old fashioned 'notes'. Your brain memorizes things by associating them
165 with other things -- a {\em map} makes use of those connections and
166 stimulates new associations.
169 \subsubsection*{Your Brain}
170 In 1960 Prof. {\sc Roger Sperry} discovered that both hemispheres
171 of the human brain undertake different tasks (of course both of them
172 basically {\em can} do the same):
174 \begin{tabular}{|p{5.5cm}|p{5.5cm}|} \hline
175 Left side & Right side \\ \hline
177 \item verbal speech and writing
179 \item logical thinking
180 \item analysing and details
182 \item linear thinking
183 \item concept of time
187 \item visual thinking, day dreams
188 \item intuition and emotion
189 \item overview of things
191 \item art, music, dancing
192 \item non-linear thinking, connecting things
193 \item spatial awareness
194 \end{itemize} \\ \hline
197 In our science oriented western society we have learned to mainly rely
198 on our left side of the brain, the "rational" one. In other cultures,
199 such as the native americans and other "old" cultures, the right side is
200 much more important. {\em Map} are just one way to stimulate the other
201 side and make use of additional resources we all have.
204 \subsection{Where could I use a {\em map}?}
205 Here are some examples, how you can use those {\em maps}
207 \item to prepare articles, papers, books, talks, \ldots
208 \item to sort complex data
209 \item to memorize facts, peoples names, vocabulary, \ldots
210 \item to sort emails, files and bookmarks on your computer
211 \item to moderate conferences
212 \item to brainstorm solutions to problems
213 \item to record the tasks when planning a project
216 \subsection{What you shouldn't do with a {\em map}...}
217 A {\em map} drawn by somebody shows the way that the author thinks.
218 There is no question of right or wrong in the way it is drawn, so there
219 is no way to criticise it. "It is, what it is" ({\sc F.~Lehmann}).The
220 tool will be of considerable use to the author and only very limited use
223 However, when groups share in creating a {\em map} all of the group will
224 benefit from its use. An example of such use is when a Tutor develops a
225 {\em map} with a group of students during instruction. Another group use
226 is when a Project leader gathers a group of specialists to help {\em
227 map} the tasks that will be required to deliver a project.
232 \subsection{Internet Ressources}
233 There are a few tutorial vides on youtube:
236 \href{https://www.youtube.com/c/ViewYourMind}{https://www.youtube.com/c/ViewYourMind}
238 A good starting point to learn more about Mindmaps in general is Wikipedia:
241 \href{http://en.wikipedia.org/wiki/Mind_map}{http://en.wikipedia.org/wiki/Mind\_map}
243 \href{http://de.wikipedia.org/wiki/Mindmap}{http://de.wikipedia.org/wiki/Mindmap}
251 \section{The Concept of the \vym application}
252 %FIXME-3 maybe add a general introduction here...
253 \subsection{The Mainwindow and its satellites} \label{satellite}
254 \vym comes with several windows, the central one is called {\em
255 mainwindow}. It contains one or more
256 tabs, each of these tabs has a {\em mapeditor} and optionally a {\em
257 tree editor}, representing a different view of the same data:
258 \maximage{images/mainwindow.png}
259 The (currently visible) main areas of the mainwindow are the {\em tree
260 editor} to the left and the {\em mapeditor} to the right. Note that both
261 editors represent the same data and share their selection: Both show the
262 {\em heading} "Get valentine surprise".
264 More windows, each having a special purpose, can be opened and arranged
265 around or even in the mainwindow. These extra windows are called
266 called {\em satellites}\footnote{
267 The advantage of having separate window instead of integrating them
268 in a combined workspace is flexibility in arranging the windows. For
269 example I usually have the {\em noteeditor} "behind" the {\em
270 mapeditor}. On Linux my windowmanager (KDE) allows me to enter text
271 into a small visible corner of the {\em noteeditor} without clicking
272 the mouse button to move focus to the window, so that it receives
273 input from keyboard. I just push the mouse around to set the
274 window focus, a concept which is useful also working with
275 \href{http://www.gimp.org}{http://www.gimp.org}.
277 The next image below shows the {\em mainwindow}
278 together with the {\em history window}. The mainwindow itself currently
279 has three parts: {\em treeeditor}, {\em mapeditor} and at the bottom
281 \maximage{images/windows.png}
282 Most of the time you will work in the {\em mapeditor} by just adding new
283 branches, moving around and reordering them. The various ways to do this
284 will be explained in \ref{mapeditor}. You can store additional
285 information e.g. the content of a email easily in a {\em branch}: Just
286 type or copy\&paste it into the {\em noteeditor}. Working with notes is
287 explained in \ref{noteeditor}
289 Here is a list of the available satellite windows, the {\em dockable}
290 feature is explained in next section \ref{dockable}:
292 \item Branch Property Window (see section \ref{propwindow})
293 \item \includegraphics[width=0.5cm]{../icons/find.png}
294 Find window to search for text (dockable)
295 \item \includegraphics[width=0.5cm]{../icons/headingeditor.png}
296 Heading editor (dockable, features are the same as in the
297 noteeditor, see section \ref {noteeditor})
298 \item \includegraphics[width=0.5cm]{../icons/history.png}
299 Historywindow (see section \ref{historywindow})
300 \item \includegraphics[width=0.5cm]{images/flags/system/note.png}
301 Noteeditor (dockable, see section \ref {noteeditor})
302 \item \includegraphics[width=0.5cm]{../icons/scripteditor.png}
303 Scripteditor (dockable, see section \ref {scripteditor})
304 \item \includegraphics[width=0.5cm]{../icons/slideeditor.png}
305 Slideeditor (dockable, see section \ref {slideeditor})
306 \item \includegraphics[width=0.5cm]{../icons/taskeditor.png}
307 Taskeditor (dockable, see section \ref {taskeditor})
310 \subsection{Dockable windows} \label{dockable}
311 Beginning with \vym 1.13.0 some of the windows may be docked and become
312 a part of an existing window. Or the other way round: Parts of a window
313 may be "undocked" and become their own independent windows or can be
314 placed in a different position within the mainwindow. Example: Toolbar
315 above the map with flags can be placed below or besides of the map, or
316 even float independantly.
318 \subsection{Toolbars}
319 The toolbars in the mainwindows give quick access to many functions and
320 also display the state of selected objects in the map. For example a
321 branch may show certain {\em flags}, the corresponding flags are also
324 \hint {Toolbars are {\em dockable} (see also section \ref{dockable}):
325 You can reposition all toolbars by simply grabbing and dragging them
326 with the toolbar handle to a new position. For example you can move the
327 flags-toolbar from its original horizontal position on top of the
328 mapeditor to a vertical position on the right side. Or just insert it
329 again at its original position. Also hiding some of the toolbars is
330 possible by right-clicking on the toolbar handle.}
332 \subsection{Menus and Context menus}
333 At the top of each window you will find the menubar. The options
334 provided there are similar to those you are probably used to from other
335 applications. Note that many (and even more) options are available via
336 {\em context menus}. Those are available if you right-click onto an
337 object in a map (on Mac~OS~X Command-Click).
340 The {\em map} has one or more {\em mapcenters}. Each mapcenter has
341 {\em branches} radiating out from the centre just like the trunk of a
342 tree. Each branch in turn may have branches again.
343 \maximage{images/branches.png}
344 We will call a branch directly connected to the mapcenter a {\em
345 mainbranch}, because it determines the position of all its child
348 If you want to have more than one mapcenter, open the context menu by
349 right-clicking onto the background of a map and select "Add mapcenter".
350 Or just press \key{C}.
351 The mapcenter and the branches all have a {\em heading}. This is the
352 text you see in the mapeditor. Usually it should just be one or a few
353 key words, so that one can easily keep track of the whole map.
354 There are several ways to quickly edit the heading, see
358 In the toolbar above the mapeditor you see various symbols.
359 \maximage{images/default-flags.png}
360 These are called {\em flags} and can be used to mark branches in the
361 {\em map}, e.g. if something is important or questionable. There are
362 also more flags set by \vym automatically to show additional
363 information, e.g. when a note is attached to a particular branch.
365 By default some of these flags are set exclusively e.g. when the
366 "thumb-up" flag is set, then the "thumb down" is reset and vice
367 versa. You can change this default behaviour in the settings menu (see
370 \section{Mapeditor} \label {mapeditor}
371 \subsection{Start a new map}
372 After \vym is started you will see the {\em mainwindow} with two parts: the {\em mapeditor} and the
373 {\em tree editor}. Usually you will work in both windows, but at the
374 moment we will just need the mapeditor.
376 Select the mapcenter "New map" in the middle of the mapeditor by
377 left-clicking with the mouse. It will be highlighted yellow to show that
378 is selected. There are several ways to add a new branch to the center:
380 \item Using the mouse: Open the context menu by clicking with the
381 right mouse button (CTRL-Click on Mac) onto the
382 mapcenter and choose Add \ra Add branch as child
383 \item Press \key{Ins} or \key{A}
385 A new branch will appear and you will be able to type the heading of the
386 branch. Finish adding the new branch by pressing \key{Enter}.
388 Sometimes it comes in handy to be able to add a new branch above or
389 below the current one.
391 \item Use \key{Shift-A} to add a branch above the selected one or...
392 \item \key{Ctrl-A} to add one below.
394 It is also possible to add a branch in such a way, that the current
395 selection becomes the child of the new branch, which is like inserting
396 it {\em before} the selection. This can be done using the context menu.
398 \hint{To delete a branch press \key{CTRL-X}. If enabled in the Settings
399 menu (see \ref{settings}), you can also use the \key{Del} key.}
401 \subsection{Navigate through a map}
402 \subsubsection*{Select branches}
403 To select branches you can use the left button of your mouse or also the
404 arrow keys. Depending on the {\em orientation} of a branch tap \key{\la}
405 or \key{\ra} to move nearer to the mapcenter or deeper down into the
406 branches. Within a set of branches, let's call them a {\em subtree}, you
407 can use \key{PgUp} and \key{PgDn} to go up and down. You can also use
408 \key{Home} and \key{End} to select the first and last branch.
410 You can also select branches in the {\em tree editor}. Once this editor
411 is active, you can also use \key{\ua} and \key {\da}, which have a
412 slightly different meaning than in mapeditor: don't forget to click back
413 into mapeditor to continue working there.
415 There is also a {\em selection history:} Use \key{CTRL-I} and
416 \key{CTRL-O} to go back to previous or later selections.
418 \subsubsection*{Panning the view of a map}
419 While adding more and more branches the size of the map may become
420 larger than the mapeditor window. You can use the scrollbars on the
421 right and the bottom of your mapeditor window to scroll the view up or
422 down or left or right. It is easier to just scroll using the left mouse
423 button: Click anywhere on the {\em canvas} itself. Choose an empty space
424 somewhere between the branches. The mouse pointer will change from an
425 arrow to a hand, now move or drag the visible map to show the desired
428 If you select branches using the arrow keys, the map will scroll to
429 ensure that the selected branch is always visible.
431 \subsubsection*{Zooming the view of a map}
432 Working with huge maps, the {\em zoom}-function comes in handy: You can
435 \item from the menu: View \ra Zoom in, View \ra Zoom out, View \ra reset Zoom.
436 \item the toolbar buttons
438 \includegraphics[width=3cm]{images/zoom-buttons.png}
441 Clicking the crossed magnifying lens icon will reset the zoomed view to
442 its original size. The keyboard shortcuts for zooming are \key{+} and
443 \key{-}. \key{,} resets the zoom and \key{.} centers view on selection.
445 Alternatively you can {\em zoom using the mouse}: Press \key{CTRL} while
446 using the scrollwheel. With \key{CTRL} and middle-mouse you reset the
449 \subsubsection*{Find Function} \label{findwindow}
450 Choose Edit \ra Find or just press \key{CTRL+F} to open
451 the Findwidget. The image below shows the findwidget above the
452 noteeditor and the mapeditor:
454 \maximage{images/find-window.png}
456 The text you enter here will be searched in all the
457 branch headings and also in the associated notes. Just click on one of
458 the results shown to select the found heading or an occurance in a note.
459 In above example we searched for "opensuse", which had a number of
460 occurences in this map, e.g. in the note of "HowTo check into in
461 editors on Factory"\ branch.
463 Press \key{CTRL+F} again to hide the widget once it's no longer needed.
464 Or you could also undock it (see \ref{dockable}).
466 \subsubsection*{Keep the overview -- scroll a part of the map}
467 A very big subtree of a map e.g. a branch with hundreds of child
468 branches would make it very hard to keep an overview over the whole map.
469 You can hide all the children of a branch by {\em scrolling} it -- in
470 other software also called {\em folding}. Think of the whole subtree as
471 painted onto a broadsheet newspaper. You can scroll or fold the paper to
472 a small roll, leaving just the headline visible.
474 To scroll or unscroll a branch and its children,
476 \item press the \key{S}
477 \item press the middle-mouse button or
478 \item choose the scroll icon from the toolbar.
480 If you select parts of a scrolled branch e.g. using the find function or
481 by using the arrow-keys, it will unscroll temporary. This is shown as a
482 scroll with a little hour glass. If the temporary unscrolled part is no
483 longer needed, it will be hidden again automatically. It is also
484 possible to unscroll all branches using "Edit\ra Unscroll all scrolled
487 You can also hide parts of the map while exporting it e.g. to a webpage
488 or a presentation, see \ref{hideexport} for details.
490 \subsection{Modify and move branches}
491 \subsubsection*{Modify the heading} \label{editheading}
492 You can edit the heading by selecting the branch and then
494 \item pressing \key{Enter}
495 \item double-clicking with left mouse.
497 Just type the new heading (or edit the old one) and press \key{Enter}.
498 You can also open the {\em heading editor} by pressing \key{E} or
500 \maximage{images/headingeditor.png}
501 %FIXME-2 Maybe add own section on HE: TextEditors-> HE,NE
502 in the toolbar. The {\em heading editor} allows you to enter richtext, just
503 like the {\em note editor} does for notes (see section \ref{noteeditor}).
505 \subsubsection*{Move a branch}
506 The easiest way to move a branch is to select it with left-mouse and
507 drag it to the destination while keeping the mouse button pressed.
508 Depending on the branch it will be
510 \item moved to the destination or
511 \item {\em linked} to a new {\em parent} (mapcenter or branch)
513 If you drag the branch over another one or over the mapcenter, you will
514 notice that the link connecting it to the old parent will be changed to
515 lead to the new parent which is now under your mousepointer. If you
516 release the button now, the branch will be relinked.
518 If you release the button in the middle of nowhere, the result will
519 depend on the type of branch you are releasing:
521 \item A mainbranch is directly connected to the mapcenter.
522 It will stay on its new position.
523 \item An ordinary branch will "snap" back to its original position
524 \footnote{In newer versions of vym the "snap back" is animated.
525 Animation can be configured, see section \ref{settings}}.
527 Thus you can easily rearrange the layout of the mainbranches to avoid
528 overlapping of their subtrees. There is another convenient way to move
529 branches, especially if you want to {\em reorder} a subtree: You can
530 move a branch up or down in a subtree by
532 \item pressing \key{\ua} and \key {\da}
533 \item selecting Edit \ra Move branch
534 \item clicking on the toolbar buttons:
537 \includegraphics[width=1.5cm]{images/move-buttons.png}
540 There is yet another way to move branches: If you press \key{Shift} or
541 \key{Ctrl} while moving with the mouse, the branch will be added above
542 or below the one the mouse pointer is over. This can also be used to
543 reorder branches in a map.
545 Another special way to move or select branches are {\em targets}, see
546 \ref{targets}. Branches with targets use this flag:
548 \includegraphics[width=0.5cm]{images/flag-target.png}
553 \subsection{Colours and Images - Using the right side of your brain}
554 \subsubsection*{Change colour of a heading}
555 You can also use colours to add more information to a map, e.g. use
556 red, green and more colours to prioritize tasks. Again you can
558 \item use the menu and choose e.g Format \ra Set Color
559 \item use the toolbar
561 \includegraphics[width=3cm]{images/color-buttons.png}
564 The first button (black in the graphic above) shows the current colour.
565 Clicking on it let's you choose another colour. You can also "pick"
566 another colour by selecting a branch with the desired colour and using
567 the "pick colour" button. Both of the icons showing a palette actually
568 apply the current colour to the selected branch. While the first one
569 just colours the heading of the selection, the last one also colours all
570 the children of the selected branch.
573 A very useful function is the {\em pick color modifier} of the mouse:
574 Select the branch which should get the new colour, then press
575 \key{Shift} and simultanously click with left-mouse on another branch to
576 copy its colour to the currently selected subtree. If you only want to
577 color the branch, not the whole subtree, press \key{Shift}+\key{Ctrl}
580 \subsubsection*{Use flags}
581 \vym provides various flags. They are usually displayed in the toolbar
582 on top of the mapeditor window. (Note: Like all toolbars you can also
583 move them to the left or the right side of the window or even detach
584 them. Just grab the very left "dotted" part of the toolbar with your
586 \maximage{images/default-flags.png}
587 If you have a branch selected, you can set any number of flags by
588 clicking them in the toolbar. The toolbar buttons change their state and
589 always reflect the flags set in the selected branch. So, to remove a
590 flag from a branch, select the branch and then click the highlighted
593 \vym uses three kinds of flags:
595 \item {\em System Flags}
596 are set by \vym to indicate e.g. that there is additional
597 information in a note (more on this in \ref{noteeditor}) or
598 that there is a task associated (see the \ref{taskeditor})
599 \item {\em Standard Flags}
600 \item {\em User Flags}
602 Standard flags can be toggled by clicking in the toolbar
603 \maximage{images/default-flags.png}
604 User flags are similar, but can be added to their own toolbar when clicking the edit icon
606 \subsubsection*{Images}
607 The easiest way to add an image to a branch is by dragging it e.g. from a
608 webbrowser to the mapeditor while a branch is selected there.
610 You can also add an image to a branch by opening the context menu of the
611 branch. Right click the selected branch, choose "Add Image". A dialog
612 window enables you choose the image to load.
613 \footnote{Supported image types are: PNG, BMP, XBM, XPM and PNM. It may
614 also support JPEG, MNG and GIF, if specially configured during
615 compilation (as done when \vym is part of SUSE LINUX).}
616 While an image is selected in the dialog, a preview of the image is
617 displayed. It is also possible to select multiple images.
619 You can position the image anywhere you want, just drag it with left
620 mouse. To relink it to another branch, press \key{Shift} while moving
621 it. To delete it, press \key{Del}.
623 If you right-click onto an image, a context menu will open which let's
624 you first choose one of several image formats. Then a file dialog opens
627 \hint{ This is used to "export" the image as separate file. As part of
628 the map it always will be
629 saved anyway in the map itself! You can also cut and
631 Note that it is not possible to add objects to an image, which would
632 make working with the map much more complex if e.g. images could be
635 The option "{\bf Use for export}" controls the output of exports
636 e.g. to HTML: If set to no, the image won't appear in the {\em text}
637 part of the output. This is useful for large images or if images are
638 used as a kind of frame e.g. the famous cloud symbol around a part of
639 the map. Those shouldn't appear in the middle of the text.
641 Resizing images has been added to /vym in version 1.13.20. Later
642 versions will include more functionality like
643 changing its z-value (put it into background) etc.
645 \subsubsection*{Frames}
646 Various types of frame can be added to a branch in the {\em property window} (see
647 \ref{propwindow}), e.g. ellipses, rectangle and cloud. The frames can
648 optionally also include the children of the the framed branch, thus
649 allowing even to "put boxes of contents into other boxes".
650 Alternatively, you can use use images as frames:
651 \maximage{images/frames.png}
653 \subsection{Design of map background and connecting links }
654 The design of the background of a map and also of the links connecting
655 various parts of the map can be changed by
657 \item Selecting Format from the menu
658 \item Right clicking on the canvas, which will open a context menu
661 \subsubsection*{Background }
662 The colour is set (and also displayed) as "Set background colour".
663 Alternativily you can set a background image, though this is not
664 recommended in general. Working on the map becomes slow and the image
665 currently cannot be positioned freely.
667 \subsubsection*{Link colour}
668 Links connecting branches can be coloured in one of two ways:
670 \item use the same colour for the heading and for the branch link
672 \item use {\em one} colour for all links and choose different
673 colours for the branch headings text. The default colour for branch
676 The latter can be set with "Set link colour". Check or uncheck the "Use
677 colour of heading for link" option to toggle between the two designs for
680 \subsubsection*{Link style}
681 \vym offers four different styles for the appearences of links:
688 The "thick" styles only apply to links starting at the mapcenter, link
689 lines for the rest of the map are always painted "thin".
691 \subsection{Links to other documents and webpages}
692 \vym supports two kind of external links:
694 \item Documents, viewed with an external webbrowser.
695 Examples are {\tt .pdf} and {\tt .html} files. References
696 are called {\em URLs} and marked with the globe
699 \includegraphics[width=0.5cm]{images/flag-url.png}
702 \item \vym maps, viewed in \vym itself. References are called
703 a {\em vymlinks} and marked with the \vym flag:
705 \includegraphics[width=0.5cm]{images/flag-vymlink.png}
709 \subsubsection{How to create an URL}
710 Use one of the following:
712 \item{Drag and drop URL from a webbrowser}
713 \item{Use the "URLs and vymlinks toolbar:}
715 \includegraphics[width=0.5cm]{images/flag-urlnew.png}
717 \item{Keyboard shortcut:}
718 Press \key{U} or right-click onto a
719 branch to open the contextmenu then choose "References\ra Edit URL". If
720 you want to use a file dialog to conveniently choose a local file you
721 can use~\key{U}. Also drag and drop from a browser can be used to create
722 a new branch with an URL.
724 Right click onto branch,
725 in the context menu there is also an option to open all URLs found
726 in the selected subtree of the map. That's useful to simultanously open
727 a collection of URLs in the webbrowser, especially if the browser can
732 After an URL was entered, a little globe will appear in the branch. By
733 clicking on the globe in the toolbar or the context menu an external
735 The browser can be changed in the Settings Menu (see \ref{settings}).}
737 For more information on working with bookmarks and webbrowsers see
738 section \ref{bookmarks}.
740 If your \vym installation supports accessing external tools like JIRA or
741 Confluence, \vym might update the branch after retrieving information
742 from the tool, e.g. replacing the complete URL of a Confluence by its
744 \subsubsection{How to create a vymlink}
745 Creation is possible both from the "URLs and vymlinks" toolbar or from
746 the context menu of a branch:
748 \includegraphics[width=0.5cm]{images/flag-vymlinknew.png}
751 A file dialog opens where you can choose the map.
752 Clicking this flag beside the branch heading, in the toolbar or in the
753 context menu of a branch will open the map in another tab (see
754 \ref{tabs} for working with multiple maps). To delete an existing link,
755 just right click the branch and select "Delete \vym link".
757 \hint{Open a linked map in background by pressing \key{Ctrl} while
758 clicking on the icon in the map}
760 In the context menu there is also an option to open all vymlinks found
761 in the selected subtree of the map. That's useful to simultanously open
762 a collection of related maps\footnote{
763 Technical note: Internally \vym uses absolute paths, to avoid
764 opening several tabs containing the same map. When a map is saved,
765 this path is converted to a relative one
766 (e.g. {\tt /home/user/vym.map} might become {\tt ./vym.map}. This
767 makes it fairly easy to use multiple maps on different computers or
768 export them to HTML in future.}.
771 \subsection{Multiple maps} \label{tabs}
772 You can work on multiple maps at the same time. Each new map is opened
773 in another {\em tab}. The available tabs are shown just above the
774 mapeditor. You can use the normal cut/copy/paste functions to
775 copy data from one map to another.
777 \subsection{Brainstorming} \label{brainstorming}
778 When brainstorming you collect quickly a number of thoughts or ideas,
779 without sorting, discussing or otherwise spending any amount of time on
782 \vym helps you to quickly create mapcenter, either by pressing \key{C}
785 \includegraphics[width=0.5cm]{images/newmapcenter.png}
787 If you want to place the new mapcenter at a specific position, you
788 could also open the context menu by right-clicking on the background and
789 selecting "Add mapcenter".
791 Once you are done adding new items, you can start to sort them and
792 arrange them by moving and relinking them to create a new map.
794 \hint{If you have enabled "Automatic Layout"\ in the Settings menu,
795 the new parts will move around to avoid overlapping}
798 %\subsubsection{Menus}
799 %\subsubsection{Keyboard shortcuts}
804 % Working with tabs (multiple maps)
808 \section{Noteeditor} \label {noteeditor}
809 If you want to attach more text to a branch e.g. a complete email, a
810 cooking recipe, or the whole source code of a software project, you can
811 use the noteeditor. (The {\em Headingeditor} has the same features.)
812 \maximage{images/noteeditor.png}
813 This editor displays text associated with a branch selected in the
814 mapeditor. The noteeditor shows different background colours
815 depending on whether text is associated with a selected branch.
818 Before you can type or paste text into it, you have
819 to select a branch in the mapeditor.
820 In the mapeditor a little "notepad" flag will appear
821 next to the heading of the branch, once you have entered some text in
822 the noteeditor. This is illustrated in the lower
823 branch on the right hand side:
824 \maximage{images/branches-flags.png}
826 \subsection{Import and export notes}
827 The note is always saved automatically within the \vym map itself.
828 Nevertheless sometimes it is nice to import a note from an external file
829 or write it. In the Note Editor use "File\ra~Import" and
830 "File\ra~Export" to do so.
832 \subsection{Edit and print note}
833 Editing works like in any simple texteditor, including undo and redo
834 functions. You can delete the complete note by clicking the trashcan.
835 Only the note itself is printed by clicking the printer icon.
837 \subsection{RichText: Colours, paragraphs and formatted text}
838 Notes and also the headings of branches can either use a default font or
839 all text attributes availabe in RichText, like bold, italic, colors,
840 etc. To enable the latter, click the RichText button:
842 \includegraphics[width=0.5cm]{../icons/formatrichtext.png}
845 \subsection{Fonts and how to switch them quickly}
846 If you just want to do quick notes and don't need fully formatted
847 RichText as mentioned above, you still can select either a fixed font
848 width font or a variable width font by clicking
850 \includegraphics[width=0.5cm]{../icons/formatfixedfont.png}
854 The fixed font is usually used for emails, source code etc.\ while the
855 variable font is used for simple notes, where one doesn't need fixed
858 In the Settings menu both fonts can be set. The default font can also be
859 toggled between the fixed and variable font by selecting or deselecting
860 the "fixed font is default" menu item.
862 \hint{Additionally to the default fonts any font installed on your system can
863 be used. Please note, that the chosen font also will be used for HTML
864 exports, so if your VYM mind map should be exported to a web page
865 you should only use fonts which are available generally.}
867 \subsection{Find text}
868 The noteeditor itself has no Find function, use Find in the mapeditor,
869 which will also display occurences of text in notes (see
872 \subsection{Paste text into note editor}
873 Often you will paste text into the editor from another application e.g.
876 \section{Task editor} \label{taskeditor}
877 Tasks are used to easily create and maintain a "Todo-list".
878 The taskeditor is visible on the left side in the image below.
880 \includegraphics[width=13cm]{images/taskeditor.png}
883 The default columns in the taskeditor list are:
885 \item Delta: This value can be manually added to the priority to change the automated priorization
886 \item Status: Shows the state and if the task is currently sleeping
887 % \item Age total: Days, since the task has been created
888 % \item Age modified: Days, since the task has been changed
889 % \item Sleep: Days, which will pass until task will wake up
890 % \item Position of tasks branch in its subtree (higher priority if further up)
891 \item Flags: Lists flags, which affect the priority (see above)
892 \item The name of task (identical to heading of branch in the map)
894 Priorities can be adjusted manually in the taskeditor, either by entering a
895 delta value or by dragging the task to a new position (more on priorities below).
898 \subsection{Creating tasks}
899 To create a task press \key{Shift + W}. The branch will get an
900 additional flag and its name will be visible in the taskeditor.
902 A task can have different states:
904 \item New task or just awakened task \includegraphics[width=0.5cm]{images/flags/system/task-new.png}
905 \item Not started \includegraphics[width=0.5cm]{images/flags/system/task-not-started.png}
906 \item Work in progress \includegraphics[width=0.5cm]{images/flags/system/task-wip.png}
907 \item Finished \includegraphics[width=0.5cm]{images/flags/system/task-finished.png}
909 You can cycle these states by pressing \key{W}.
911 \subsection{Reminders - let a task sleep for a while}
912 A task may be set to "sleep", which can be used to get a reminder
913 after a certain amount of time. The flag will change to one of these:
915 \item Not started - sleeping
916 \includegraphics[width=0.5cm]{images/flags/system/task-new-sleeping.png}
917 \item Work in progress - sleeping
918 \includegraphics[width=0.5cm]{images/flags/system/task-wip-sleeping.png}
920 You can set the sleep time of a task should right clicking on the task flag in the
921 mapeditor or the task in the taskeditor. "Reset sleep" will wake up
922 a currently sleeping task.
924 Alternatively you can press \key{Shift-Q} and manually enter the sleep time, here are some examples:
927 \begin{tabular}{|c|p{11cm}|} \hline
928 {\bf Input } & {\bf Sleep} \\ \hline
929 1 & 1 day, postpone until tomorrow morning\\
934 18:00 & Postpone until 6pm \\
935 24.12.2024 & Postpone until Dec 24 in 2024 \\
936 2024-12-24 & Postpone until Dec 24 in 2024 \\
937 2038-12-24T21:34 & Postpone until December 24 in 2038, 9:34 pm (ISO format) \\ \hline
941 %These tasks will get a new flag and status
944 % \item Not started - morning %\includegraphics[width=0.5cm]{../flags/flag-task-new-morning.png}
945 % \item Work in progress - morning % \includegraphics[width=0.5cm]{../flags/flag-task-wip-morning.png}
946 % \item New tasks - only show new freshly "woken up" tasks
947 % \item Various filters for priorty flags
948 % \includegraphics[width=0.5cm]{../flags/flag-arrow-up.png}
949 % \includegraphics[width=0.5cm]{../flags/flag-2arrow-up.png}
950 % \includegraphics[width=0.5cm]{../flags/flag-no-arrow-up.png}
954 \subsection{Priority of tasks}
955 The tasks visible in the taskeditor are ordered by their {\em
956 priorities}, listed on the left side of the editor. The lower the
957 priority number, the more important is a task: The most important task always has priority~1.
959 There are several principles that influence the priority of a task:
962 Old tasks tend to bubble up, meaning theyget a higher priority over
963 time. Rationale: If you have a task named "water the flowers"\ and
964 you have postponed it now for 187 days, better delete the task. (And
965 create a new task to dump the remains of the flowers.)
968 Colors in the map: If you use the Function keys to assign the
969 colors red, amber, green, etc. the tasks will get a different
974 \includegraphics[width=0.5cm]{images/flags/stopsign.png}
975 will increase the priority. Use it for your shipstoppers\ldots
978 The arrow up flags also move tasks up in the list
982 Sleeping tasks and finished tasks will tend to fall to the bottom of
986 The freshly woken up "morning tasks"\ will tend to pop up right
987 at the top, so that they cannot be missed. Remove the "morning"\ state by pressing \key{W} once.
990 \subsection{Filter tasks - keeping the overview}
991 The taskeditor has filters: %FIXME add flag icons
993 \begin{tabular}{|c|p{11cm}|} \hline
994 {\bf Icon} & {\bf Filter } \\ \hline
995 \includegraphics[width=0.4cm]{../icons/taskfilter-currentmap.png} &
996 Current map only, hide tasks from other maps \\
997 \includegraphics[width=0.4cm]{../icons/taskfilter-activetask.png} &
998 Active tasks only, hide finished nor sleeping \\
999 \includegraphics[width=0.5cm]{../icons/taskfilter-newtask.png} &
1001 \includegraphics[width=0.4cm]{images/flags/arrow-up.png}
1002 \includegraphics[width=0.4cm]{images/flags/arrow2-up.png} &
1003 Tasks with "arrow up" flags only \\
1004 \includegraphics[width=0.4cm]{../flags/system/no-arrow-up.png} &
1005 Only tasks without "arrow up" flags \\ \hline
1010 \section{Slideeditor - presentations}\label{slideeditor}
1011 \vym can be used to do animated presentations using the slideeditor as
1012 seen on the right side of the image below:
1014 \includegraphics[width=13cm]{images/slideeditor.png}
1016 The slideeditor can be opened by pressing \key{S} or from the {\em View}
1017 menu. The (currently) available action are:
1020 \includegraphics[width=0.5cm]{../icons/slideprevious.png}
1021 Select previous slide
1024 \includegraphics[width=0.5cm]{../icons/slidenext.png}
1028 \includegraphics[width=0.5cm]{../icons/slide-camera.png}
1029 Create a new slide by snapshotting the current selection. The exact
1030 set of actions performed when selecting the new snapshot defined in
1031 a script called {\tt slideeditor-snapshot.vys}. The script is one of
1032 the \vym macros, see \ref{macros}.
1035 \includegraphics[width=0.5cm]{../icons/scripteditor.png}
1036 Open the scripteditor to manually edit the current slide \\
1037 (More on scripting in appendix \ref{scripts}).
1040 \includegraphics[width=0.5cm]{../icons/edittrash.png}
1041 Delete the current slide
1044 \includegraphics[width=0.5cm]{../icons/up.png}
1045 Move current slide up in slidedeck
1048 \includegraphics[width=0.5cm]{../icons/down.png}
1049 Move current slide down in slidedeck
1051 In the {\em View-menu} or it's toolbar you can also toggle the
1052 presentation mode to hide most of the toolbars and buttons
1055 \section{Hello world - vym and other applications}
1056 This section is about how \vym can interact with other applications.
1057 Many applications can now read and write their data using XML, the
1058 eXtensible Markup Language. \vym also uses XML to save its maps, see
1059 \ref{fileformat} for a more detailed description.
1061 So if you make use of another application that understands XML, chances
1062 are good that someone could write import/export filters for \vym.
1063 Volunteers are always welcome ;-)
1065 \subsection{Import} \label{import}
1067 \subsubsection{Mozilla Firefox bookmarks}
1068 Currently \vym supports an experimental import of Firefox bookmarks:
1069 Firefox can backup bookmkarks in a file in JSON format. This file can be
1070 imported into an existing \vym map.
1072 Future \vym versions might be able to export this bookmark map again to JSON, so
1073 that it could be restored in Firefox.
1075 \subsubsection{Freemind and Freeplane}
1076 Freemind is no longer actively developed, the project is continued in
1077 the Freeplane project, see also
1078 \href{https://www.freeplane.org/}{https://www.freeplane.org/}.
1080 \vym supports reading the general structure of a Freeplane map and some
1081 of its flags. Also notes are read.
1083 \subsubsection{Mind Manager}
1084 \vym has currently a very basic import filter to convert maps created by
1085 {\em Mind Manager}\footnote{Mind Manager is a commercial i.e. non free,
1086 software application by Mindjet for Windows and the Mac. Both names are
1087 registered trademarks by Mindjet. For more information see their website
1088 at \href{http://mindjet.com}{http://mindjet.com}} into \vym maps. Notes
1089 and pictures are not converted at the moment. You can import files with
1091 \item File \ra Import\ra Mind Manager
1095 \subsubsection{Directory structure}
1096 \vym can read a directory structure. This is mainly for
1097 testing \vym e.g. to easily create huge maps used for benchmarks (yes,
1098 there is still room to optimize \vym ;-)
1100 \subsection{Export} \label{export}
1102 Often you may not want to export the whole map, but just parts of it.
1103 For example you may have additional info you want to talk about in a
1104 presentation, while those parts should not be visible to the audience.
1105 To achieve this you can "hide" parts of the map during exports by
1106 setting the "hide in export" flag.
1108 \includegraphics[width=0.5cm]{images/flag-hideexport.png}
1110 You can toggle this flag in the toolbar or by pressing \key{H}. Note
1111 that there is a global option in the settings menu ( \ref{settings}) to
1112 toggle the use of this flag. By default the flag is enabled.
1114 \subsubsection{Last used format}
1115 Repeats the last export action without further dialogs like asking for
1116 directories. The associated export type and filepaths are stored within
1117 the map and thus map specific. Note: Not all export types support this
1120 \subsubsection{Image}
1121 \vym supports all image formats which are natively supported by the
1123 BMP, JPEG, PBM, PGM, PNG, PPN, XPM, and XBM.
1124 For use in websites and for sending images by email PNG is a good
1125 recommodation regarding quality and size of the image. \vym uses QTs
1126 default options for compressing the images.
1129 Exports to Portable Document Format.
1132 Exports to Scalable Vector Graphics.
1134 \subsubsection{Open Office}
1135 Open Office beginning with version~2 uses the so called "Open Document
1136 Format", which can be written by \vym. The options are currently
1137 limited, but it possible to export presentations which can be opened in
1138 Open Office Impress. By selecting
1140 \item File \ra Export\ra Open Office
1142 you get a file dialogue where you can choose the output file and the
1144 \maximage{images/export-oo.png}
1145 The file types represent various templates, which can be created with
1146 some manual work from an existing Open Office document. The structure of
1147 \vym map is then inserted into a template. There are some limitations
1150 \item \vym can't take care of page lengths, so you have to check and
1151 probably reedit in Open Office to avoid text running over the end of
1153 \item Images and flags are not used at the moment
1154 \item Notes are just written as plain text, without RichText
1155 \item The full range of templates are not available in all
1158 Some of the templates make use of {\em sections} i.e sections insert the
1159 headings of mainbranches as chapters for sections into the presentation.
1161 \subsubsection{HTML (Webpages)}
1162 This is the format to use if you wish to create a webpage. To see an example
1163 visit the \vym homepage:
1164 \href{http://www.InSilmaril.de/vym}{www.InSilmaril.de/vym}
1165 A dialog allows the user to set various options:
1167 \item {\bf Include image:} If set, \vym will create an image map at
1168 the top of the HTML output. Clicking on a branch in the map will
1169 jump to the corresponding section in the output.
1171 \item {\bf Colored headings:}
1172 If set to yes, \vym will colour the headings in the text part with the
1173 same colours used in the \vym map.
1174 \item {\bf Save settings:}
1175 If set to yes, \vym will save above settings in the map.
1178 \subsubsection{A \& O -- Achievements and Objectives}
1179 A specialized form of ASCII export (see next section), which is used for
1180 workreports. Currently it is considered experimental.
1183 \subsubsection{ASCII}
1184 Exporting a map as text is somewhat experimental at the moment. Later
1185 this will probably be done using stylesheets. So the output may change
1186 in future versions of \vym.
1189 Exports map into a Comma Separated Value file, which can be used to
1190 import into all kinds spreadsheet software.
1192 \subsubsection{Taskjuggler}
1193 Used to export to Taskjuggler project management software. Currently
1194 considered experimental.
1196 \subsubsection{\LaTeX}
1197 \vym can generate an input file for \LaTeX. Currently this is considered
1198 as experimental, there are no options (yet).
1201 \item File \ra Export\ra \LaTeX
1203 you will be asked in a file dialog for the name of the output file. This
1204 file may then be included in a \LaTeX document using command:
1206 \include{inputfile.tex}
1208 New in version 2.2.0: You can configure the names of the sections in the
1209 vym config file, depending on your platform e.g. in
1211 $HOME/.config/InSilmaril/vym.conf
1213 Just add e.g. these entries>
1215 /export/latex/sectionName-0=chapter
1216 /export/latex/sectionName-1=section
1217 /export/latex/sectionName-2=subsection
1218 /export/latex/sectionName-3=subsubsection
1219 /export/latex/sectionName-4=paragraph
1222 \subsubsection{Markdown}
1223 Used to export to Markdown, see also
1224 \href{https://daringfireball.net/projects/markdown/}{https://daringfireball.net/projects/markdown/}
1225 Currently considered experimental.
1227 \subsubsection{OrgMode}
1228 Used to export to Emacs OrgMode, see also
1229 \href{https://orgmode.org/}{https://orgmode.org/}
1230 Currently considered experimental.
1233 \subsubsection{XML} \label{xmlexport}
1234 The map is written into a directory both as an image and as an XML file.
1235 The directory is set in a file dialog. If the directory is not empty,
1236 you will be warned and offered choices if you are at risk of overwriting
1239 It is possible to export different maps into the same directory. Each
1240 file generated will have the map's name as prefix, e.g. {\tt todo.vym}
1241 becomes {\tt todo.xml}, {\tt todo.png}, {\tt todo-image-1.png} and so
1242 on. This is useful if, for example, a website comprises several combined
1243 maps that have to be stored in the same directory.
1245 \subsubsection{Export a part of a map}
1246 Select a branch you want to export together with its children, then open
1247 the context menu and choose {\em Save Selection}. This will create a
1248 file with the suffix {\tt .vyp}, which is an abbreviation for "vym
1251 \subsection{Connect vym to the cloud} \label{cloud}
1252 Starting with \vym 2.8.16 some exchange with cloud applications is
1253 possible. So far this is limited to cloud applications from the company
1254 Atlassian\footnote{Atlassian, Confluence and JIRA are registered
1255 trademarks}. You find the related features and settings in the "Connect"
1256 settings in the menubar on top of the main window.
1257 \subsubsection{Confluence}
1260 \item Get Confluence user name and insert it into map. (This will
1261 create a link to the user profile during export to Confluence)
1262 \item Export a map to a Confluence page
1263 \item Get the name of a Confluence page and the space name and use
1264 it as heading when pasting an URL. (Happens automatically, if
1265 Confluence is configured)
1268 \subsubsection{JIRA}
1270 \item Get description of a JIRA ticket and use it as heading
1271 \item Get additional information, e.g. color branch if ticket is
1275 \subsection{Connect vym using DBUS}
1276 If you don't know what DBUS is, you probably want to skip this section,
1277 this is about remote controling \vym using the DBUS protocol on Linux.
1279 Currently this is used to
1281 \item Run the development tests, see also
1283 \href{https://github.com/insilmaril/vym/blob/develop/test/vym-test.rb}
1284 {https://github.com/insilmaril/vym/blob/develop/test/vym-test.rb}
1285 \item Add content from other applications, e.g. paste an email from
1286 the mutt client, see also
1288 \href{https://github.com/insilmaril/vym/blob/develop/scripts/vym-addmail.rb}
1289 {https://github.com/insilmaril/vym/blob/develop/scripts/vym-addmail.rb}
1291 For more details see also \ref{dbus}.
1293 \section{Advanced usage}
1295 \subsection{Quickly sorting branches or postponing actions} \label{targets}
1296 Sometimes it's very handy to have a small number of shortcuts to quickly
1297 select a certain branch or move something somewhere and proceed with
1298 next item. This can be used for quick sorting to a number of
1299 destination. For example if used in timeplanning, you could quickly move something
1300 to "next tuesday". The destinations are called {\em targets} and are
1303 \includegraphics[width=0.5cm]{images/flag-target.png}
1306 The target flag is toggled with \key{T}. If you want to "Goto" a target,
1307 press \key{G}. Similar if you want to "Move" a branch, press \key{M}.
1308 A context menu will open and lets you select the target.
1312 \subsection{Properties of an object}
1313 For any branch you can open a satellite window (see \ref{satellite}):
1314 the {\em property window}:
1316 \includegraphics[width=8cm]{images/propwindow.png}
1319 %FIXME create updated screenshot
1321 \subsubsection*{Frame}
1322 sets the appearance of the frame of a branch. Currently there are
1329 The "Include Children" checkmark is used to, well, include the children
1330 of the branch. "Padding" sets the distance between both neighbouring
1331 branches and frame and also the frame and branch itself. The "width"
1332 sets the thickness of the frame.
1334 Two colors can be assigned to background of the frame and frame itself.
1336 \subsubsection*{Layout}
1337 The images belonging to a branch can use different layouts, e.g.
1338 floating freely alongside or being included {\em within} the branch. For
1339 details and illustration see \ref{incimg}).
1341 \subsubsection*{Link}
1342 The advantage of hiding a link, which is the connection between a branch
1343 (or image) and its parent, is to make the branch itself appear a
1344 mapcenter of its own. Details are in \ref{hidelink}).
1346 \subsection{Changing the history: Undo and Redo}
1347 \vym keeps track of all changes done in a map. The default number of
1348 changes which can be undone is~75. The complete history can be seen in
1349 the {\em historywindow}:
1350 \maximage{images/historywindow.png}
1351 \label{historywindow}
1352 A single step back be undone or redone with \key{CTRL-Z} or \key{CTRL-Y},
1353 or by using the buttons in the toolbar or the {\em historywindow}.
1354 Inside the {\em historywindow}, you can click on a line to unwind all
1355 actions done until that point in time -- or redo all changes by clicking
1359 You can "paste from the past": Go back in time by e.g. with
1360 \key{CTRL-Z}, then copy to clipboard by pressing \key{CTRL-C}.
1362 Now do all actions again, e.g. by \key{CTRL-Y} or clicking on the
1363 last action in {\em historywindow}. Now paste from the past with
1367 \subsection{Macros} \label{macros}
1369 \key{F1} to \key{F12} holds a macro, which is executed on the current
1370 selection if the key is pressed. The default macros change the colour of
1371 a subtree or set the frame of a branch:
1373 \includegraphics[width=8cm]{images/macros.png}
1375 Each macro is a \vym script, which is executed when the associated key
1376 is pressed. The default location of the scripts can be changed in the
1377 Settings menu. More information on using scripts in \vym is found in
1378 appendix~\ref{scripts}.
1380 \subsection{Bookmarks} \label{bookmarks}
1381 \subsubsection*{Open new tabs instead of new windows}
1382 If you use konqueror as your browser, \vym will remember the konqueror session which
1383 was opened first by \vym. You can also press \key{Ctrl} and click to
1384 open the link in a new tab.
1386 \vym can also open a new tab in Mozilla or Firefox using the remote
1388 \href{http://www.mozilla.org/unix/remote.html}{http://www.mozilla.org/unix/remote.html}}
1391 \subsubsection*{Drag and Drop}
1392 If you want to keep bookmarks in a map, select a branch where you want
1393 to add the bookmark, then simply drag the URL from your browser to the
1394 map. Also you could use an existing heading as URL: Right click onto the
1395 branch and select "Use heading for URL".
1398 \subsubsection*{Directly access bookmark lists of a browser}
1399 Please see the sections \ref{import} and \ref{export} about
1400 Import and Export filters.
1402 \subsection{Associating images with a branch} \label{incimg}
1403 The default setting for an image is for it to float "freely". Images can
1404 be positioned anywhere on the canvas, but may end up in the same place
1405 as other parts of the map obscuring that part of the map.
1407 The solution is to insert or include them "into" a branch. This can be
1408 done via the property window (see \ref{propwindow}):
1410 \item Include images horizontally
1411 \item Include images vertically
1413 The image is still positioned relative to its parent branch, but the
1414 heading and border of the branch frame adapt to the floating image, see
1415 below: \maximage{images/includeImages.png}
1417 \subsection{Modifier Modes}
1418 The modifier mode can be selected in the toolbar
1420 \includegraphics[width=3cm]{images/modmodes.png}
1422 or also using the adjacent keys \key{L}, \key{K} and \key{L}.
1423 The selected mode influences mouse behaviour when the \key{Shift}-modifier is
1426 \item Multiple selection: Press Shift and click to select multiple objects
1427 \item Colorpicker: Pick from another branch and apply to currently
1429 \item XLink: Draw a connecting XLink between two branches. See also
1431 \item Move object: Move an object, but when releasing it over another one, do not relink.
1432 (Useful for positioning branches in other branches for presentations.)
1433 \item Move view: Only move view without selecting an object
1436 \subsection{Hide links of unselected objects} \label{hidelink}
1437 Sometimes it would be useful to position a branch freely, just like a
1438 mainbranch or an image. This is possible for all branches, you can use a
1439 mainbranch and hide its connecting link to the mapcenter or hide the
1440 link between a child branch and its parent. This can be used e.g. for
1441 legends or a collection of vymLinks pointing to other maps:
1443 \includegraphics[width=9cm]{images/hiddenlink.png}
1445 To hide the link between a branch and its parent open the
1446 \ref{propwindow} and check "Hide link if object is not selected" on
1450 \subsection{XLinks} \label{xlinks}
1451 So far all the data in the \vym map has been treelike. Using xLinks you
1452 can link one branch to any other, just like attaching a rope between two
1453 branches in a real tree. This is especially useful in complex maps,
1454 where you want to have crossreferences which can not be displayed on the
1455 same visible area of the {\em mapeditor} window. The following example
1456 map still fits on one screen, but shows how data can be crosslinked. In
1457 the graphics there is a link from a task (prepare a presentation) to
1458 general information:
1459 \maximage{images/xlink-control.png}
1460 Note that a xLink which points to a branch, that is not visible (because
1461 it is scrolled), is just shown as a little horizontal arrow. In the
1462 image above have a look at the "Screenshot"\ branch.
1464 \subsubsection*{Create a xLink}
1465 Choose the link mode from the modifier toolbar (by clicking the toolbar
1466 icon or pressing \key{L}). Select the branch, where the xLink should
1467 start. Press the modifier key \key{Shift}
1468 drag the mouse pointer to the branch where the link should end. (The
1469 link is drawn to follow the mouse pointer). When you release the mouse
1470 over a branch the xLink becomes permanent.
1472 \subsubsection*{Modify or delete a xLink}
1473 First select the link, either in the tree editor or by clicking the xLink
1474 itself in the mapeditor. A dialogue opens, where you can set colour,
1475 width and also delete the xLink.
1477 You can also move the control points of the link to change the curve and
1478 change the appearance of the xlink by right clicking on one of
1481 \includegraphics[width=6cm]{images/xlink-property.png}
1485 \subsubsection*{Follow a xLink}
1486 In a complex \vym map it sometimes comes in handy to be able to jump to
1487 the other end of a xLink. You can do this by opening the context menu of
1488 the branch and clicking on "Goto xLink" and selecting the xLink you
1489 want to follow. Even easier is to click on the lower right end of a
1490 branch -- a popup menu will show up with all xLinked branches. Click one
1491 of them to jump to it.
1494 \subsection{Adding and removing branches}
1495 The context menu of a branch shows some more ways to add and delete data
1496 e.g. you can delete a branch while keeping its children. The children
1497 become linked to the parent of the previously removed branch. Similar
1498 branches can be inserted into existing maps. For keyboard shortcuts also
1499 have a look at the context menu.
1501 \subsection{Adding a whole map or a part of a map}
1502 Select a branch where you want to add a previously saved map ({\tt
1503 .vym})or a part of a map ({\tt .vyp}) , then open the context menu and
1504 choose {\em Add \ra Add Map (Insert)}. For the import you can choose
1505 between {\em Add Map (Insert)} and {\em Add Map (Replace)}: The imported
1506 data will be added after the selected branch.
1508 \section{\vym on Mac OS X}
1509 %FIXME-3 Currently not yet supported on Mac OS X in 1.13.x
1511 %\subsection{Overview}
1512 %Sorry, currently (\vym 2.2.2) there is no Mac port available. Please
1513 %contact the author\footnote{
1514 % Email Uwe Drechsel: \href{mailto:vym@insilmaril.de}{vym@insilmaril.de}} if
1515 %you are interested in a Mac version.
1517 %Basically there are two ways to run \vym on Macs:
1518 %\subsubsection*{Qt Mac Edition:}
1519 % \vym here provides the well known Mac look and feel. \vym is
1520 % available as Mac OS X application package in contained in a disk
1521 % image ({\tt vym.dmg}). It has been compiled and tested in
1522 % Mac~OS~10.4. This package includes runtime libraries of Qt by
1525 %\subsubsection*{X11 version} \vym can also be run using the Linux
1526 %version, but then menus and handling will also be those of the Linux
1527 %version e.g. The menu bar will look different.
1529 \subsection {Contextmenu and special keys}
1530 Most Macs unfortunatly just have a single mouse button. In order to show
1531 the context menu which usually would be opened with the right mouse
1532 button, you can click while pressing the \key{kommand}-key.
1534 Especially on Laptops some of the keys usually used on PC keyboards seem
1535 to be missing. The Qt-Mac Edition of \vym has its own keyboard
1536 shortcuts. To find the shortcuts just have a look at all the menu
1537 entries, the shortcut is visible next to an entry. Toolbar buttons also
1538 may have shortcuts, just position the mouse pointer over a button and
1539 wait for the little help window to appear.
1541 \subsection {Viewing external links}
1542 \vym on Mac uses the system call {\tt /usr/bin/open} to view links.
1543 Mac~OS determines automatically if the link is a pdf or www page and
1544 opens the right browser.
1550 \section{\vym initialisation process and configuration}
1551 \subsection {Settings menu} \label{settings}
1552 The {\em Settings} menu allows to configure \vym to your needs:
1554 \subsubsection*{Set application to open PDF files} Choose a PDF
1555 viewer like {\tt acrobat} or {\tt konqueror} which is installed on
1558 \subsubsection*{Set application to open external links}
1559 Choose your favourite application, this usually depends on your
1562 \item Windows: {\tt explorer}
1563 \item Linux: {\tt xdg-open} or {\tt mimeopen}
1564 \item Mac: {\tt /usr/bin/open}
1566 Defaults should be set by \vym automatically.
1568 \subsubsection*{Set path for macros}
1569 Set the default search path for macros, which will be executed when
1570 you press one of the function keys. Each key corresponds to a file
1571 ({\tt macro-1.vys..macro12.vys}) in the search path.
1573 \subsubsection*{Set number of undo levels}
1574 Sets the number of undo/redo levels. The default setting is
1577 \subsubsection*{Autosave and autosave time}
1578 Automatic saving of modified maps can be toggled on or off. The
1579 autosave time is entered in seconds.
1581 \subsubsection*{Write backup on save}
1582 When saving a map called {\tt example.vym}, \vym will rename the
1583 existing file to {\tt example.vym\~{}} before writing the {\tt
1584 example.vym} itself.
1586 \subsubsection*{Edit branch after adding it}
1587 If set, the heading of a new branch will be edited immediatly after
1590 \subsubsection*{Select branch after adding it}
1591 If set, a new branch will be selected immediatly after adding it.
1592 When you "brainstorm" on a given keyword, you don't want to go
1593 deeper and deeper into details, but keep the focus on the keyword.
1594 So the default setting here is to {\em not} select the freshly added
1597 \subsubsection*{Select existing heading}
1598 If set and you begin to edit the heading of a branch, the heading
1599 text in the dialog will be selected. Usefully to copy\&paste to
1602 \subsubsection*{Delete key}
1603 If set, the \key{Delete} is enabled to, well, delete objects. This
1604 can be switched off to avoid confusing with the nearby
1605 \key{Insert}-key on PC keyboards.
1607 \subsubsection*{Exclusive flags}
1608 If set, some of the standard flags can only be used exclusively,
1611 \subsubsection*{Use hide flags}
1612 If set, every branch which also has the hide flag set (see
1613 \ref{hideexport}) will be hidden in exports.
1615 \subsubsection*{Note editor is dockable}
1616 If set (default), the note editor can be docked into the main
1617 widget. Changing this setting needs a restart of \vym. Details see
1620 \subsubsection*{Animation}
1621 If set (default), some animation will be used, e.g.\ for "snapping
1622 back" of released branches.
1624 \subsubsection*{Autolayout} %FIXME-3
1625 If set (not on default), \vym will try to autolayout mainbranches.
1626 Currently considered experimental and only working under certain
1629 \subsection{Configuration file}
1630 On startup \vym will look for a configuration for user specific settings
1631 like window positions, toolbars etc. If this file does not already
1632 exist, it will be created. The file is located in the users home
1633 directory. The exact position depends on the platform:
1636 {\bf Platform} & {\bf Configuration file} \\ \hline
1637 Linux & {\tt $\sim$/.config/InSilmaril/vym.conf } \\
1638 Mac OS X & {\tt /Users/NAME/Library/Preferences/com.insilmaril.vym.plist } \\
1639 Windows (registry) & {\tt HKEY\_Current\_User/Software/InSilmaril/vym } \\
1642 The file can be edited manually, or on Mac~OS~X with Property List
1643 Editor (installed with xtools). On windows you can use {\tt regedit.exe}.
1645 \subsection{Path to ressources}
1646 \vym will try to find its ressources (images, stylesheets, filters,
1647 etc.) in the following places:
1649 \item Path given by the environment variable {\tt VYMHOME}.
1650 \item If called with the local option (see \ref{options} below),
1651 \vym will look for its data in the current directory.
1652 \item {\tt /usr/share/vym}
1653 \item {\tt /usr/local/share/vym}
1656 \subsection{Command line options} \label{options}
1657 \lstinputlisting{help.tex}
1658 You can also give several filenames at the commandline to let \vym open
1659 several maps at once.
1662 \section{Scripts} \label{scripts}
1663 \subsection{Overview}
1664 Beginning with version 2.7.0 \vym is fully scriptable, though the
1665 scripting support is still considered a {\em technical preview}. Some
1666 parts still might change and improve in later versions.
1667 Scripts are internally used for
1670 \item Macros on function keys
1673 In addition to the internal scriptengine, which is using QScript,
1674 you can also use external ruby scripts, which communicate with \vym via
1675 DBUS. Please note that the latter is currently only possible on Linux.
1676 See also the examples in \ref{examplescripts}.
1678 The scripts within \vym are edited using the {\em script editor}:
1679 \begin{center} \label{scripteditor}
1680 \includegraphics[width=13cm]{images/scripteditor.png}
1682 Open the scripteditor by pressing \key{Alt + S} or from the {\em
1683 View}-menu. The output of of scripts cans be seen in the script output
1684 window with \key{Alt + Shift + S}
1686 \subsection{Example scripts} \label{examplescripts}
1687 A set of example scripts is installed together with \vym, see the
1688 installation directory and the subfolder {\tt demos/scripts/} and the
1689 macros in the macro tab of the script editor.
1690 \subsubsection{Macro to create a rounded rectangle frame}
1692 // Macro Shift + F1: Frame background light red
1693 function macro_shift_f1()
1695 map = vym.currentMap();
1696 status = "Background off";
1697 if (map.getFrameType() == "NoFrame") {
1698 status = "Background light red";
1700 toggle_frame ( map );
1701 map.setFrameBrushColor("#ffb3b4");
1702 statusMessage(status);
1706 \subsubsection{Batch script to export all maps as images}
1707 This script can be used to export all maps in a directory
1708 automatically. If the script is named {\tt export-image.vys}, call \vym
1711 \$ vym --quit --run export-image.vys *.vym
1714 \subsubsection{Full scripting using ruby and DBUS} \label{dbus}
1715 Nearly every action in \vym can be controlled via DBUS (on Linux
1716 machines). You can have several \vym instances running at the same time,
1717 e.g. for production and development. Before controlling one, you need to
1718 give it a name, here "test"\ is used:
1722 You can now access \vym via DBUS, if you have Qt installed, try {\tt
1723 qdbusviewer}. In the {\tt scripts} directory, which is part of \vym,
1724 you'll find the script {\tt vym-ruby.rb}. This rubyscript provides two
1725 classes to manage and control \vym instances. A short script to set the
1726 heading of a branch might be:
1730 require "#{ENV['PWD']}/scripts/vym-ruby"
1732 vym_mgr=VymManager.new
1733 vym=Vym.new(vym_mgr.find('test') )
1736 vym.setHeading "This is a new heading!"
1739 An full example how this is
1740 used is in the automated \vym testing:
1745 \subsection{Available commands}
1746 Start vym with the "command"\ option to get a listing of available
1749 vym --commands --quit
1751 The currently available commands are:
1753 \input{commands.tex}
1758 \section{Contributing to \vym}
1759 So far I'd say I have written 98\% of the code on my own. No surprise,
1760 that \vym exactly fits my own needs. Nevertheless I would like to
1761 encourage all users of \vym to contribute. Maybe not only with feature
1762 requests, but also with code, new import/export filters, translations
1763 etc. In this appendix I'll try to show how easy it is to expand the
1764 things you can do already with \vym. I really look forward to hear from
1767 \subsection{Getting help}
1769 \subsubsection*{Frequently asked questions}
1770 Please refer to the FAQ available on the \vym website:
1772 \href{http://www.InSilmaril.de/vym/faq.html}{http://www.InSilmaril.de/vym/faq.html}
1775 \subsubsection*{Mailinglists}
1776 There are several mailinglists: {\tt vym-forum} is the \vym users forum to
1777 discuss various questions, while {\tt vym-devel} is intended for people
1778 interested in contributing to \vym. The third list is {\tt vym-trans} to
1779 coordinate translations. You can view the archives and subscribe at
1781 \href{https://sourceforge.net/mail/?group_id=127802}{https://sourceforge.net/mail/?group\_id=127802}
1784 \subsubsection*{Contacting the author}\label{author}
1785 Especially for support questions please try the mailinglists first. If
1786 everything else fails you can contact the author Uwe Drechsel at
1788 \href{mailto:vym@InSilmaril.de}{vym@InSilmaril.de}
1793 \subsection{How to report bugs}
1794 Please file bugs and issues in github:
1796 \href{ https://github.com/insilmaril/vym/issues}{https://github.com/insilmaril/vym/issues}
1799 I build \vym regulary for openSUSE and Windows, so you may report it against a
1800 recent version there, even if you use another Operating System.
1801 Please don't forget to tell me what you are using:
1803 \item the exact steps needed to reproduce the bug
1804 \item the version and build date of \vym (see the Help \ra About
1806 \item hardware and Operating System
1809 \subsection{Compiling from the sources}
1810 \subsubsection{Getting the sources} \label{getsources}
1811 You find the latest code of \vym in the {\tt develop} branch on Github:
1813 \href{ https://github.com/insilmaril/vym}{https://github.com/insilmaril/vym}
1816 \subsubsection{The Qt toolkit}
1817 Qt is C++ toolkit for multiplatform GUI and application development. It
1818 provides single-source portability across MS~Windows, Mac~OS~X, Linux
1819 and many more. Qt is also available for
1820 embedded devices. Qt is a product of the Qt Company. For more information see
1822 \href{https://www.qt.io}{https://www.qt.io}
1827 \subsubsection{Compiling \vym }
1828 Make sure you have installed your Qt environment properly, see the Qt
1829 documentation for details. You need to have the Qt command {\tt qmake}
1830 in your {\tt PATH}-environment, then run
1836 The last command {\tt make install} needs root-permissions. Of course it
1837 may be omitted, if you just want to test \vym. For testing you should
1838 also use the "-l" (local) option on startup (see \ref{options}).
1840 %\subsubsection*{Compiling \vym on Macs}
1843 \subsection{\vym file format} \label{fileformat}
1844 \vym maps usually have the suffix "{\tt .vym}" and represent a
1845 compressed archive of data. Actually the widely used "zip" format
1846 is used\footnote{zip is meanwhile available on all major platforms,
1847 including Windows~10: either in the file explorer or on the command line
1848 e.g.~ as part of the "tar" command}.
1850 If you want to have a closer look into the
1851 data structure map called "mapname.vym", just edit the XML data
1852 by using the {\tt vivym} script or by uncompressing manually. In a shell
1853 on Linux or Mac OS you can do this by calling
1855 \$ unzip mapname.vym
1857 This will create directories named {\tt images} and {\tt flags} in your
1858 current directory and also the map itself, usually named {\tt
1859 mapname.xml}. The XML structure of \vym is pretty self explaining, just
1860 have a look at {\tt mapname.xml}.
1862 This XML file can be loaded directly into \vym, it does not have to be
1863 compressed. If you want to compress all the data yourself, use
1865 \$ zip -r mapname.vym .
1867 to compress all data in your current directory.
1869 \subsection{New features}
1870 There are lots of features which might find their way into \vym.
1871 Together with \vym you should have received a directory with several
1872 example maps. You find them by clicking Help \ra Open~vym~example~maps.
1873 %FIXME outdated example
1874 There you will find the map {\tt vym-projectplan.vym}. It lists quite a
1875 lot of things to be done in future. If you have more ideas, open
1878 \href{https://github.com/insilmaril/vym/issues}{https://github.com/insilmaril/vym/issues}
1881 \subsection{New languages support}
1882 In order to add a new language to \vym you need the sources (see
1883 \ref{getsources}) and an installation of Trolltechs QT. A part of QT are
1884 the development tools, from those tools especially the translation tool
1885 "Linguist" is needed.
1887 In some Linux distributions the development tools are in an extra
1888 package, e.g. on SUSE LINUX you should have installed:
1891 libqt5-devel-doc.rpm
1892 libqt5-devel-tools.rpm
1894 If you don't have Qt in your system, you can get it from
1895 \href{https://qt.io}{https://qt.nio}
1896 You can translate the text in vym
1897 itself by performing the following steps:
1899 \item Let's assume now your encoding is "NEW" instead of for example
1900 "de" for german or "en" for english
1902 \item Copy the file {\tt lang/vym\_en.ts} to l{\tt ang/vym\_NEW.ts}
1903 (The code itself contains the english version.)
1905 \item Add {\tt lang/vym\_NEW.ts} to the TRANSLATIONS section of
1908 \item Run Linguist on {\tt vym\_NEW.ts} and do the translation
1910 \item Run {\tt lrelease} to create {\tt vym\_NEW.qm}
1912 \item Do a make install to install the new vym and check your
1916 If you feel brave, you can also translate the manual. It is written in
1917 LaTeX, you just have to change the file tex/vym.tex. (Linguist and Qt
1918 are not needed, but it is useful to know how to work with LaTeX and esp.
1919 pdflatex to create the PDF.)
1921 Please mail me every translation you have done. I can also give you a
1922 developer access to the project, if you want to provide translations
1925 \subsection{New export/import filters}
1926 \vym supports various kinds of filters. Data can be written directly,
1927 inserted into templates or it can be written as XML data and then
1928 processed by XSL transformations.
1930 Most of the import/export functionality is available in the classes
1931 ImportBase and ExportBase and subclasses. All of them can be found in
1932 {\tt imports.h} and {\tt exports.h}.
1934 \subsubsection*{Direct import/export}
1935 An example for a direct export is the XML export. This method touches
1936 the implementation of nearly every object of \vym, so whenever possible
1937 you should better use a XSL transformation instead.
1939 If you still want to know how it is done, start looking at
1940 {\tt MapEditor::saveToDir} in {\tt mapeditor.cpp}.
1942 \subsubsection*{Templates}
1943 Templates have been introduced to export to opendoc format used e.g. by
1944 Open~Office. While I read the spec ($>$ 500 pages) about the format\footnote{
1945 \href{http://www.oasis-open.org/}{http://www.oasis-open.org/}}\
1946 I had the feeling that I did not want to write the export from scratch.
1947 It would be too complex to adapt the styles to your own wishes, e.g. the
1950 Instead I analyzed existing Open~Office documents. I found out that
1951 there are lots of redundant bits of information in a standard
1952 presentation, for example each list item is contained in its own list.
1953 In the end I came up with the default presentation style, which still
1954 could be simplified, just in case you have free time\ldots
1956 The existing templates are still work in progress, before you spend too
1957 much time developing your own style, please contact me. Basically the
1958 following steps are needed to build your own style:
1960 \item Create an example in Open Office. Use a title, authors name,
1961 page heading etc.\ which you can easily grep for in the output file.
1963 \item Unzip the Open Office document into a directory.
1965 \item The main file is called {\tt content.xml}. All data is in one
1966 single line. You can split the XML tags using the script {\tt
1967 scripts/niceXML}, which is part of the \vym distribution.
1969 \item Copy the output of {\tt niceXML} to {\tt
1970 content-template.xml}.
1972 \item Looking closer you will find lots of unused definitions, for
1973 example of styles. You can delete or simply ignore them.
1975 \item Try to find your title, authors name. \vym will replace the
1976 following strings while exporting:
1978 \begin{tabular}{lp{4cm}}
1979 {\tt <!-- INSERT TITLE -->} & title of map \\
1980 {\tt <!-- INSERT AUTHOR--> } & author \\
1981 {\tt <!-- INSERT COMMENT -->} & comment \\
1982 {\tt <!-- INSERT PAGES-->} & content of map \\
1985 The content itself is generated in a similar way by inserting lists
1986 into {\tt page-template}. Here the following substitutions are made:
1988 \begin{tabular}{lp{7cm}}
1989 {\tt <!-- INSERT PAGE HEADING-->} & heading of a page
1990 (mainbranch or child of mainbranch, depending on the use of
1992 {\tt <!-- INSERT LIST --> } & all children of the branch above \\
1996 Currently images are exported and notes just will appear as text
1997 without formatting and colours.
2004 %\subsubsection{Keyboard shortcuts}
2005 %Where does vym save its settings? -> ~/.qt/vymrc