VYM

–
View Your Mind
Version 1.10.0

Uwe
c Drechsel

September 5, 2007
Contents
1 Introduction 6
1.1 What is a vym map? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
1.2 Why should I use maps? Time, Space and your Brain. . . . . . . . . . . . 6
1.3 Where could I use a map? . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
1.4 What you shouldn’t do with a map... . . . . . . . . . . . . . . . . . . . . . 8
1.5 Internet Ressources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8

2 The Concept of the vym application 8

2.1 The Mainwindow and its satellites . . . . . . . . . . . . . . . . . . . . . . . 8
2.2 Menus and Context menus . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
2.3 Toolbars . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
2.4 Maps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10

3 Mapeditor 10
3.1 Start a new map . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
3.2 Navigate through a map . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
3.3 Modify and move branches . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
3.4 Colours and Images - Using the right side of your brain . . . . . . . . . . . 13
3.5 Design of map background and connecting links . . . . . . . . . . . . . . . 15
3.6 Links to other documents and webpages . . . . . . . . . . . . . . . . . . . 16
3.7 Multiple maps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17

4 Noteeditor 17
4.1 States . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
4.2 Import and export notes . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
4.3 Edit and print note . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
4.4 RichText: Colours, paragraphs and formatted text . . . . . . . . . . . . . . 18
4.5 Fonts and how to switch them quickly . . . . . . . . . . . . . . . . . . . . 18
4.6 Find text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
4.7 Paste text into note editor . . . . . . . . . . . . . . . . . . . . . . . . . . . 19

5 Hello world 19
5.1 Import . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
5.2 Export . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
6 Advanced Editing 22
6.1 Properties of an object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
6.2 Changing the history: Undo and Redo . . . . . . . . . . . . . . . . . . . . 23
6.3 Macros . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
6.4 Bookmarks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
6.5 Associating images with a branch . . . . . . . . . . . . . . . . . . . . . . . 25
6.6 Modifier Modes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
6.7 Hide links of unselected objects . . . . . . . . . . . . . . . . . . . . . . . . 26
6.8 XLinks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
6.9 Adding and removing branches . . . . . . . . . . . . . . . . . . . . . . . . 27
6.10 Adding a whole map or a part of a map . . . . . . . . . . . . . . . . . . . 27

7 vym on Mac OS X 27
7.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
7.2 Contextmenu and special keys . . . . . . . . . . . . . . . . . . . . . . . . . 28
7.3 Viewing external links . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28

A vym initialisation process and configuration 29

A.1 Settings menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
A.2 Configuration file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
A.3 Path to ressources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
A.4 Command line options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30

B Scripts 31
B.1 Example scripts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
B.1.1 Export a set of maps . . . . . . . . . . . . . . . . . . . . . . . . . . 31

C Contributing to vym 31
C.1 Getting help . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
C.2 How to report bugs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
C.3 Compiling from the sources . . . . . . . . . . . . . . . . . . . . . . . . . . 32
C.3.1 Getting the sources . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
C.3.2 The Qt toolkit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
C.3.3 Compiling vym . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
C.4 vym file format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
C.5 New features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
C.6 New languages support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
C.7 New export/import filters . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
Credits
Many people have sent me their feedback and ideas, and all of that has helped a lot to
make vym better. Thanks to all of you!
For this manual I would like to send some special thanks to

• Peter Adamson for lots of feedback and proofreading of my far from perfect english

• The team of AClibre (Academia y Conocimiento Libre) in Colombia for their trans-
lation of the manual to spanish:

Encargado Actividad

– Vanessa Carolina Gutiérrez – Traducciónl

Sanchez – Revisión y correcciones
– Erika Tatiana Luque Melo varias
– Jeffrey Steve Borbón Sanabria – Estructuración y exporte
– John Edisson Ortiz Román – Revisión y correcciones
varias
1 Introduction

1.1 What is a vym map?

A vym map (abbreviated below as map) is a tree like structure:

Such maps can be drawn by hand on a sheet of paper or flip chart and help to structure
your thoughts. While a tree like structure like the illustration above can be drawn man-
ually vym offers much more features to work with such maps. vym is not just another
drawing software application, but a tool to store and modify information in an intuitive
way. For example you can reorder parts of the map by pressing a key or add various
pieces of information like a complete email by a simple mouse click.
Once you have finished collecting and organising your ideas, you can easily generate a
variety of outputs including for example a presentation in Open Office based on a map.

Hint: You find the map shown above and others by clicking

Help −→Open vym examples !

in the menu bar.

1.2 Why should I use maps? Time, Space and your Brain.

Space

A map can concentrate very complex content in a small space such as a piece of paper.
It helps to use both sides of your brain: the logical side and also your creative side (e.g.
by using pictures, colours and keywords in a map, often called anchors). It is a technique
to help organize the way you think and stimulate your creativity: It can help you by
developing, sorting and helping to memorise your ideas.
Time

Because you just use keywords and drawings, it is much faster than good old fashioned
’notes’. Your brain memorizes things by associating them with other things – a map
makes use of those connections and stimulates new asccociations.

Your Brain

In 1960 Prof. Roger Sperry discovered that both hemispheres of the human brain
undertake different tasks (of course both of them basically can do the same):

Left side Right side

• verbal speech and writ- • body language

ing
• visual thinking, day
• numbers dreams

• logical thinking • intuition and emotion

• analysing and details • overview of things

• science • creativity

• linear thinking • art, music, dancing

• concept of time • non-linear thinking, con-

necting things

• spatial awareness

In our science oriented western society we have learned to mainly rely on our left side of
the brain, the ”rational” one. In other cultures, such as the native americans and other
”old” cultures, the right side is much more important. Map are just one way to stimulate
the other side and make use of additional resources we all have.

1.3 Where could I use a map?

Here are some examples, how you can use those maps

• to prepare articles, papers, books, talks, . . .

• to sort complex data

• to memorize facts, peoples names, vocabulary, . . .

• to sort emails, files and bookmarks on your computer

• to moderate conferences

• to brainstorm solutions to problems

• to record the tasks when planning a project

1.4 What you shouldn’t do with a map...

A map drawn by somebody shows the way that the author thinks. There is no question
of right or wrong in the way it is drawn, so there is no way to criticise it. ”It is, what
it is” (F. Lehmann).The tool will be of considerable use to the author and only very
limited use to anyone else.
However, when groups share in creating a map all of the group will benefit from its use.
An example of such use is when a Tutor develops a map with a group of students during
instruction. Another group use is when a Project leader gathers a group of specialists to
help map the tasks that will be required to deliver a project.

1.5 Internet Ressources

A good starting point to learn more about Mindmaps in general is Wikipedia:

• English: http://en.wikipedia.org/wiki/Mind map

• German: http://de.wikipedia.org/wiki/Mindmap

2 The Concept of the vym application

2.1 The Mainwindow and its satellites

vym comes with several windows, the central one being the mapeditor. More windows,
each having a special purpose, can be opened and arranged around the mainwindow1 .
The image below shows the mapeditor together with the often used noteeditor:
1
The advantage of having separate window instead of integrating them in a combined workspace is
flexibility in arranging the windows. For example I usually have the noteeditor ”behind” the mapeditor.
On Linux my windowmanager (KDE) allows me to enter text into a small visible corner of the noteeditor
withour clicking the mouse button in it. I just push the mouse around to set the window focus, a concept
which is useful also working with http://www.gimp.org.
Most of the time you will work in the mapeditor by just adding new branches, moving
around and reordering them. The various ways to do this will be explained in 3. You can
store additional information e.g. the content of a email easily in a branch: Just type or
copy&paste it into the noteeditor. Working with notes is explained in 4
Here is a list of the available satellite windows:

• Noteeditor (see 4)

• Historywindow (see 6.2)

• Branch Property Window (see 6.1)

2.2 Menus and Context menus

At the top of each window you will find the menubar. The options provided there are
similar to those you are probably used to from other applications. Note that many (and
even more) options are availabe via context menus. Those are available if you right-click
onto an object in a map (on Mac OS X Command-Click).

2.3 Toolbars

The toolbars in the mainwindows give quick access to many functions and also display
the state of selected objects in the map. For example a branch may show certain flags,
the corresponding flags are also set in the toolbar.
 Hint: You can reposition all toolbars by simply grabbing and dragging
them with the toolbar handle to a new position. For example you
can move the flags-toolbar from its original horizontal position on
top of the mapeditor to a vertical position on the right side. Or
!
just insert it again at its original position. Also hiding some of the
toolbars is possible by right-clicking on the toolbar handle.

2.4 Maps

The map itself has always a mapcenter. The mapcenter has branches radiating out from
the centre just like the trunk of a tree. Each branch in turn may have branches again.

We will call a branch directly connected to the mapcenter a mainbranch, because it

determines the position of all its child branches.
The mapcenter and the branches all have a heading. This is the text you see in the
mapeditor. Usually it should just be one or a few key words, so that one can easily keep
track of the whole map.
In the toolbar above the mapeditor you see various symbols.

These are called flags and can be used to mark branches in the map, e.g. if something is
important or questionable. There are also more flags set by vym automatically to show
additional information, e.g. when a note is attached to a particular branch.
By default some of these flags are set exclusively e.g. when the ”thumb-up” flag is set,
then the ”thumb down” is reset and vice versa. You can change this default behaviour in
the settings menu (see ??).

3 Mapeditor

3.1 Start a new map

After vym is started two windows will open: the mapeditor and the noteditor. Usually
you will work in both windows, but at the moment we will just need the mapeditor.
Select the mapcenter ”New map” in the middle of the mapeditor by left-clicking with the
mouse. It will be highlighted yellow to show that is selected. There are several ways to
add a new branch to the center:

• Using the mouse: Open the context menu by clicking with the right mouse button
(CTRL-Click on Mac) onto the mapcenter and choose Add −→Add branch as child
 • Press [Ins] or [A]

A new branch will appear and you will be able to type the heading of the branch. Finish
adding the new branch by pressing [Enter]. Sometimes it comes in handy to be able to
add a new branch above or below the current one.

• Use [Shift-A] to add a branch above the selected one or...

• [Ctrl-A] to add one below.

It is also possible to add a branch in such a way, that the current selection becomes the
child of the new branch, which is like inserting it before the selection. This can be done
using the context menu.

Hint: To delete a branch press [CTRL-X]. If enabled in the Settings menu

(see ??), you can also use the [Del] key.
!
3.2 Navigate through a map

Select branches

To select branches you can use the left button of your mouse or also the arrow keys. De-
pending on the orientation of a branch tap [←−] or [−→] to move nearer to the mapcenter
or deeper down into the branches. Within a set of branches, let’s call them a subtree, you
can use [↑] and [↓] to go up and down. You can also use [Home] and [End] to select the
first and last branch.

Panning the view of a map

While adding more and more branches the size of the map may become larger than the
mapeditor window. You can use the scrollbars on the right and the bottom of your
mapeditor window to scroll the view up or down or left or right. It is easier to just scroll
using the left mouse button: Click anywhere on the canvas itself. Choose an empty space
somewhere between the branches. The mouse pointer will change from an arrow to a
hand, now move or drag the visible map to show the desired part.
If you select branches using the arrow keys, the map will scroll to ensure that the selected
branch is always visible.

Zooming the view of a map

Working with huge maps, the zoom-function comes in handy: You can use

• from the menu: View −→Zoom in, View −→Zoom out, View −→reset Zoom.

• the toolbar buttons

Clicking the crossed magnifying lens icon will reset the zoomed view to its original size.
Find Function

With huge maps there is the need to have a find function. Choose Edit −→Find to open
the Find Window:

The find function will search for, the text you enter here, in all the branch headings and
also in the associated notes. Everytime you press the ”Find”-button it will look for the
next occurence, which will then be selected automatically. If the search fails, a short
message ”Nothing found” will appear for a few seconds in the statusbar on the bottom of
the mapeditor.

Keep the overview – scroll a part of the map

A very big subtree of a map e.g. a branch with hundreds of child branches would make
it very hard to keep an overview over the whole map. You can hide all the children of a
branch by scrolling it – this function is often called folding. Think of the whole subtree
as painted onto a broadsheet newspaper. You can scroll or fold the paper to a small roll,
leaving just the headline visible.
To scroll or unscroll a branch and its children,

• press either the [Scroll Lock] key or the [S]

• press the middle-mouse button or

• choose the scroll icon from the toolbar.

If you select parts of a scrolled branch e.g. using the find function or by using the arrow-
keys, it will unscroll temporary. This is shown as a scroll with a little hour glass. If the
temporary unscrolled part is no longer needed, it will be hidden again automatically. It
is also possible to unscroll all branches using ”Edit−→Unscroll all scrolled branches”.
You can also hide parts of the map while exporting it e.g. to a webpage or a presentation,
see 5.2 for details.

3.3 Modify and move branches

Modify the heading

You can edit the heading by selecting the branch and then

• pressing [Enter]
 • pressing [F2]

• double-clicking with left mouse.

Just type the new heading (or edit the old one) and press [Enter].

Move a branch

The easiest way to move a branch is to select it with left-mouse and drag it to the
destination while keeping the mouse button pressed. Depending on the branch it will be

• moved to the destination or

• linked to a new parent (mapcenter or branch)

If you drag the branch over another one or over the mapcenter, you will notice that the
link connecting it to the old parent will be changed to lead to the new parent which is
now under your mousepointer. If you release the button now, the branch will be relinked.
If you release the button in the middle of nowhere, the result will depend on the type of
branch you are releasing:

• A mainbranch is directly connected to the mapcenter. It will stay on its new posi-
tion.

• An ordinary branch will ”jump” back to its original position.

Thus you can easily rearrange the layout of the mainbranches to avoid overlapping of
their subtrees. There is another convenient way to move branches, especially if you want
to reorder a subtree: You can move a branch up or down in a subtree by

• pressing [↑] and [↓]

• selecting Edit −→Move branch

• clicking on the toolbar buttons:

There is yet another way to move branches: If you press [Shift] or [Ctrl] while moving
with the mouse, the branch will be added above or below the one the mouse pointer is
over. This can also be used to reorder branches in a map.

3.4 Colours and Images - Using the right side of your brain

Change colour of a heading

You can also use colours to add more information to a map, e.g. use red, green and more
colours to prioritize tasks. Again you can

• use the menu and choose e.g Format −→Set Color

 • use the toolbar

The first button (black in the graphic above) shows the current colour. Clicking on it
let’s you choose another colour. You can also ”pick” another colour by selecting a branch
with the desired colour and using the ”pick colour” button. Both of the icons showing
a palette actually apply the current colour to the selected branch. While the first one
just colours the heading of the selection, the last one also colours all the children of the
selected branch.
A very useful function is the ”copy colour” using the mouse: Select the branch which
should get the new colour, then press [Ctrl] and simultanously click with left-mouse on
another branch to copy its colour to the first one. Here the children of the selection also
will get the new colour, if you just want to colour the selection itself, additionally press
[Shift].

Use flags

vym provides various flags. They are usually displayed in the toolbar on top of the
mapeditor window. (Note: Like all toolbars you can also move them to the left or the
right side of the window or even detach them. Just grab the very left ”dotted” part of
the toolbar with your left-mouse button.)

If you have a branch selected, you can set any number of flags by clicking them in the
toolbar. The toolbar buttons change their state and always reflect the flags set in the
selected branch. So, to remove a flag from a branch, select the branch and then click the
highlighted flag on the toolbar.
At present vym uses two kinds of flags: System Flags and Standard Flags. The standard
flags are those shown in the toolbar. System flags are set by vym to indicate e.g. that
there is additional information in a note (more on this in 4). Later versions of vym may
have another kind of flags, which may be edited by the user.

Images

The easiest way to add an image to a branch is by dragging it e.g. from a webbrowser to
the mapeditor while a branch is selected there.
You can also add an image to a branch by opening the context menu of the branch. Right
click the selected branch, choose ”Add Image”. A dialog window enables you choose the
image to load. 2 While an image is selected in the dialog, a preview of the image is
displayed. It is also possible to select multiple images.
You can position the image anywhere you want, just drag it with left mouse. To relink it
to another branch, press [Shift] while moving it. To delete it, press [Del].
If you right-click onto an image, a context menu will open which let’s you first choose one
of several image formats. Then a file dialog opens to save the image.
2
Supported image types are: PNG, BMP, XBM, XPM and PNM. It may also support JPEG, MNG
and GIF, if specially configured during compilation (as done when vym is part of SUSE LINUX).
Hint: This is used to ”export” the image, it will be saved anyway in the map itself! You
can also cut and copy images, but it is not possible to add objects to an image3
The option ‘Use for export ’controls the output of exports e.g. to HTML: If set to no,
the image won’t appear in the text part of the output. This is useful for large images or
if images are used as a kind of frame e.g. the famous cloud symbol around a part of the
map. Those shouldn’t appear in the middle of the text.
At the moment image support is preliminary: Images will be saved together with all the
other data of a map in the .vym-file. Later versions will include more functionality like
resizing the images, changing its z-value (put it into background) etc.

Frames

A frame can be added to a branch in the property window (see 6.1). Alternatively, you
can use use images as frames. Have a look at the demo map todo.vym as an example,
where the mapcenter is a cloud. You can use an external drawing program like gimp to
create an image, preferable with an transparency channel, so that you can design frames
which don’t use a rectangular borderline, just like that cloud.

3.5 Design of map background and connecting links

The design of the background of a map and also of the links connecting various parts of
the map can be changed by

• Selecting Format from the menu

• Right clicking on the canvas, which will open a context menu

Background

The colour is set (and also displayed) as ”Set background colour”. Alternatevily you can
set an background image, though this is not recommended in general. Working on the
map becomes slow and the image currently cannot be positioned freely.

Link colour

Links connecting branches can be coloured in one of two ways:

• use the same colour for the heading and for the branch link line.

• use one colour for all links and choose different colours for the branch headings text.
The default colour for branch link lines is blue.

The latter can be set with ”Set link colour”. Check or uncheck the ”Use colour of heading
for link” option to toggle between the two designs for your map.
3
Images are regarded as ”extra feature”. It would make working with the map much more complex
if e.g. images could be linked to images.
Link style

vym offers four different styles for the appearences of links:

• Line

• Parabel

• Thick Line

• Thick Parabel

The ”thick” styles only apply to links starting at the mapcenter, link lines for the rest of
the map are always painted ”thin”.

3.6 Links to other documents and webpages

vym supports two kind of external links:

• Document, which will be opened in an external webbrowser

• vym map, which will be opened in vym itself

In addition to the external links there also internal ones, leading from one branch in a
map to another one. Those are called XLinks and are explained in section 6.8.

Webbrowser

Modern Webbrowsers like konqueror and Firefox are able to display various types of
files, both local or on the internet. To enter the URL of any document, press [U] or right-
click onto a branch to open the contextmenu then choose ”References−→Edit URL”. If
you want to use a file dialog to conveniently choose a local file you can use [SHIFT-U].
After an URL was entered, a little globe will appear in the branch. By clicking on the
globe in the toolbar or the context menu an external browser4 will be launched.

For more information on working with bookmarks and webbrowsers see section 6.4.
In the context menu there is also an option to open all URLs found in the selected subtree
of the map. That’s useful to simultanously open a collection of URLs in the webbrowser,
especially if the browser can open them in tabs (like Konqueror).

vym map

To link to to another map right click on a branch and choose ”Edit vym link”. A file
dialog opens where you can choose the map. A branch with a link is marked with

4
The browser can be changed in the Settings Menu (see ??).
Clicking this flag beside the branch heading, in the toolbar or in the context menu of a
branch will open the map in another tab (see 3.7 for working with multiple maps). To
delete an existing link, just right click the branch and select ”Delete vym link”.
In the context menu there is also an option to open all vymlinks found in the selected
subtree of the map. That’s useful to simultanously open a collection of related maps.
Technical note: Internally vym uses absolute paths, to avoid opening several tabs con-
taining the same map. When a map is saved, this path is converted to a relative one (e.g.
/home/user/vym.map might become ./vym.map. This makes it fairly easy to use multiple
maps on different computers or export them to HTML in future.

3.7 Multiple maps

You can work on multiple maps at the same time. Each new map is opened in another
tab. The available tabs are shown just above the mapeditor. You can use the normal
cut/copy/paste functions to copy data from one map to another.

4 Noteeditor
If you want to attach more text to a branch e.g. a complete email, a cooking recipe, or
the whole source code of a software project, you can use the noteeditor.

This editor displays text associated with a branch selected in the mapeditor. The noteed-
itor shows different background colours depending on whether text is associated with a
selected branch.

4.1 States

Before you can type or paste text into it, you have to select a branch in the mapeditor.
Note that the background colour of the noteeditor indicates its state:

• grey: no text entered yet

• white: some text has been entered

In the mapeditor itself, to signal that there is a note with more information for a particular
branch, a little ”note” flag will appear next to the heading of the branch. This is illustrated
in the lower branch on the right hand side:

4.2 Import and export notes

The note is always saved automatically within the vym map itself. Nevertheless some-
times it is nice to import a note from an external file or write it. In the Note Editor use
”File−→ Import” and ”File−→ Export” to do so.

4.3 Edit and print note

Editing works like in any simple texteditor, including undo and redo functions. You can
delete the complete note by clicking the trashcan. Only the note itself is printed by
clicking the printer icon.

4.4 RichText: Colours, paragraphs and formatted text

vym supports formatted text (QT Rich Text) in the noteeditor since version 1.4.7. Colours
and text attributes (e.g. italic, bold) can be set with the buttons above the text. The text
itself is divided into paragraphs. For each paragraph the format can be set (e.g. centered,
right). A paragraph is ended when a [Return] is entered. If you just want to begin a new
line, press [CTRL-Return].

4.5 Fonts and how to switch them quickly

The noteeditor is designed to be used for simple notes, not really as a full featured word
processor. Because of many requests vym supports formatted text in the noteeditor5
Two default fonts are supported which can be set in the Settings menu (see ??). One is a
fixed width font, the other has variable width. The fixed font is usually used for emails,
source code etc. while the variable font is used for simple notes, where one doesn’t need
fixed character widths. Both fonts can easily switched using the following symbol from
the toolbar:

In the Settings menu both fonts can be set. The default font can also be toggled between
the fixed and variable font by selecting or deselecting the ”fixed font is default” menu
item.
5
vym uses the QRichtText format, which is basically a subset of the formatting provided in HTML.
Additionally to the default fonts any font installed on your system can be used. Please
note, that the chosen font also will be used for HTML exports, so if youy VYM mind
map could ever be exported to a web or intranet page you should only use fonts which
are available generally.

4.6 Find text

The noteeditor itself has no Find function, use Find in the mapeditor, which will also
search all notes (see 3.2).

4.7 Paste text into note editor

Often you will paste text into the editor from another application e.g. an email. Normally
vym will generate a new paragraph for each new line. This usually is not what you want,
so you can choose from the menu

5 Hello world
This section is about how vym can interact with other applications. Many applications
can now read and write their data using XML, the eXtensible Markup Language. vym
also uses XML to save its maps, see C.4 for a more detailed description.
So if you make use of another application that understands XML, chances are good that
someone could write import/export filters for vym . Volunteers are always welcome ;-)

5.1 Import

KDE Bookmarks

The integrated bookmark editor in KDE (Konqueror etc.) is somewhat limited, so why
not use vym to maintain the bookmark mess? To create a new map containing your
current KDE bookmarks just choose

• File −→Import−→KDE Bookmarks

Mind Manager

vym has currently a very basic import filter to convert maps created by Mind Manager6
into vym maps. Notes and pictures are not converted at the moment. You can import
files with

• File −→Import−→Mind Manager

6
Mind Manager is a commercial i.e. non free, software application by Mindjet for Windows and the
Mac. Both names are registered trademarks by Mindjet. For more information see their website at
http://mindjet.com
Directory structure

vym can read a directory structure. This is mainly for testing vym e.g. to easily create
huge maps used for benchmarks (yes, there is still room to optimize vym ;-)

5.2 Export

Often you may not want to export the whole map, but just parts of it. For example
you may have additional info you want to talk about in a presentation, while those parts
should not be visible to the audience. To achieve this you can ”hide” parts of the map
during exports by setting the ”hide in export” flag.

You can toggle this flag in the toolbar or by pressing [H]. Note that there is a global
option in the settings menu ( ??) to toggle the use of this flag. By default the flag is
enabled.

Open Office

Open Office beginning with version 2 uses the so called ”Open Document Format”, which
can be written by vym . The options are currently limited, but it possible to export
presentations which can be opened in Open Office Impress. By selecting

• File −→Export−→Open Office

you get a file dialogue where you can choose the output file and the file type:

The file types represent various templates, which can be created with some manual work
from an existing Open Office document. The structure of vym map is then inserted into
a template. There are some limitations at the moment:
 • vym can’t take care of page lengths, so you have to check and probably reedit in
Open Office to avoid text running over the end of a page

• Images and flags are not used at the moment

• Notes are just written as plain text, without RichText

• The full range of templates are not available in all distributions.

Some of the templates make use of sections i.e sections insert the headings of mainbranches
as chapters for sections into the presentation.

Image

vym supports all image formats which are natively supported by the QT toolkit: BMP,
JPEG, PBM, PGM, PNG, PPN, XPM, and XBM. For use in websites and for sending
images by email PNG is a good recommodation regarding quality and size of the image.
vym uses QTs default options for compressing the images.

ASCII

Exporting an image as text is somewhat experimental at the moment. Later this will
probably be done using stylesheets. So the output may change in future versions of vym
.

LATEX

vym can generate an input file for LATEX. Currently this is considered as experimental,
there are no options (yet). By selecting

• File −→Export−→LATEX

you will be asked in a file dialog for the name of the output file. This file may then be
included in a LATEXdocument using command:

\include{inputfile.tex}

KDE Bookmarks

vym will overwrite the KDE bookmarks file and then try to notify running Konquerors
via DCOP of the changed file. vym does not create a backup!

• File −→Export −→KDE Bookmarks

XHTML (Webpages)

This is the format to use if you wish to create a webpage. To see an example visit the
vym homepage: www.InSilmaril.de/vym
Some explanation on how this works: Before a map is exported as XHTML, it will be
first written as XML into a directory (see 5.2). Then the external program xsltproc7
will be called to process the XML file and generate HTML code. A dialog allows the user
to set various options:

• Include image: If set, vym will creat an image map at the top of the HTML
output. Clicking on a branch in the map will jump to the corresponding section in
the output.

• Colored headings: If set to yes, vym will colour the headings in the text part
with the same colours used in the vym map.

• Show Warnings: If set to yes, vym will ask before overwriting data.

• Show output: This is useful mainly for debugging. It will show how the processing
of the XML file works by calling the external xsltproc.

Additionally the paths to the CSS and XSL stylesheets can be set. By default on
SUSE Linux they will be in /usr/share/vym/styles.

XML

The map is written into a directory both as an image and as an XML file. The directory
is set in a file dialog. If the directory is not empty, you will be warned and offered choices
if you are at risk of overwriting existing contents.
It is possible to export different maps into the same directory. Each file generated will have
the map’s name as prefix, e.g. todo.vym becomes todo.xml, todo.png, todo-image-1.png
and so on. This is useful if, for example, a website comprises several combined maps that
have to be stored in the same directory.

Export a part of a map

Select a branch you want to export together with its children, then open the context
menu and choose Save Selection. This will create a file with the suffix .vyp, which is an
abbreviation for ‘vym part’.

6 Advanced Editing

6.1 Properties of an object

For any branch you can open a satellite window (see 2.1): the property window:
7
On SUSE Linux and some other distributions xsltproc is installed by default.
 • Frame

• Link (see ??)

• Layout (see 6.5)

6.2 Changing the history: Undo and Redo

vym keeps track of all changes done in a map. The default number of changes which can
be undone is 75. The complete history can be seen in the historywindow:

A single step back be undone or redone with [CTRL-Z] or [CTRL-Y], or by using the
buttons in the toolbar or the historywindow. Inside the historywindow, you can click on
a line to unwind all actions done until that point in time – or redo all changes by clicking
on the last line.

Hint: You can ”paste from the past”: Go back in time by e.g. with
[CTRL-Z], then copy to clipboard by pressing [CTRL-C].
Now do all actions again, e.g. by [CTRL-Y] or clicking on the last
!
action in historywindow. Now paste from the past with [CTRL-V].
6.3 Macros

Macros have been added to vym in version 1.9.0. So far they have a preliminary character,
maybe they are going to be replaced by full-featured scripting functionality later (though
the commands will be more or less the same).
Each function key [F1] to [F12] holds a macro, which is executed on the current selection
if the key is pressed. The default macros change the colour of a subtree or set the frame
of a branch:

Each macro is a vym script, which is executed when the associated key is pressed. The
default location of the scripts can be changed in the Settings menu. More information on
using scripts in vym is found in [??) appendix B.

6.4 Bookmarks

Open new tabs instead of new windows

If you use konqueror as your browser, vym will remember the konqueror session which
was opened first by vym . You can also press [Ctrl] and click to open the link in a new
tab.
vym can also open a new tab in Mozilla or Firefox using the remote command8 of these
browsers.

Drag and Drop

If you want to keep bookmarks in a map, select a branch where you want to add the
bookmark, then simply drag the URL from your browser to the map. Also you could
use an existing heading as URL: Right click onto the branch and select ”Use heading for
URL”.

Directly access bookmark lists of a browser

Please see the sections 5.1 and 5.2 about Import and Export filters.
8
http://www.mozilla.org/unix/remote.html
Special URLs

vym can turn an existing heading of a branch into an URL. Currently this works for
Bugentries in the Novell Bugtracking system: Open the context menu of a branch (usually
by right-clicking it) and select

• Create URL to Bugzilla

The URL will be build from the number in the heading.

6.5 Associating images with a branch

The default setting for an image is for it to float ”freely”. Images can be positioned
anywhere on the canvas, but may end up in the same place as other parts of the map
obscuring that part of the map.
The solution is to insert or include them ”into” a branch. This can be done via the
property window (see 6.1):

• Include images horizontally

• Include images vertically

The image is still positioned relative to its parent branch, but the heading and border of
the branch frame adapt to the floating image, see below:

6.6 Modifier Modes

Modifiers are for example the [Shift]- the [Ctrl]- ot the [Alt]-keys. When pressed while
applying mouse actions, they will cause vym to use a ”modified” version of the action
which usually would be done.
Without a modifier key pressed, the first mouse click on a branch just selects it. For
the behaviour of the [Ctrl] modifier there are several options, which can be set from the
modifier toolbar:
The default mode is to copy the colour from the clicked branch to the already selected
branch. The figure above shows the toolbar with the default modifier selected. The second
modifier let’s you easily copy a whole branch with a single click. The third modifier lets
you create links between branches called xLinks. They will be explained in the next
section 6.8.

6.7 Hide links of unselected objects

Sometimes it would be useful to position a branch freely, just like a mainbranch or an

image. This is possible for all branches, you can use a mainbranch and hide its connecting
link to the mapcenter or hide the link between a child branch and its parent. This can
be used e.g. for legends or a collection of vymLinks pointing to other maps:

To hide the link between a branch and its parent open the 6.1 and check ”Hide link if
object is not selected” on ”Link” tab.

6.8 XLinks

So far all the data in the vym map has been treelike. Using xLinks you can link one
branch to any other, just like attaching a rope between two branches in a real tree. This
is especially useful in complex maps, where you want to have crossreferences which can
not be displayed on the same visible area of the mapeditor window. The following example
map still fits on one screen, but shows how data can be crosslinked. In the graphics there
is a link from a task (prepare a presentation) to general information:

Note that a xLink which points to a branch that is not visible (because it is scrolled),
is just shown as a little horizontal arrow. In the screenshot above have a look at the
‘Tuesday’ branch.
Create a xLink

Choose the link mode from the modifier toolbar (by clicking the toolbar icon or pressing
[L]). Select the branch, where the xLink should start. Press the modifier key [Ctrl] and
then click on the selected branch where the link should start and drag the mouse pointer
to the branch where the link is to end. (The link is drawn to follow the mouse pointer).
When you release the mouse over a branch the xLink becomes permanent.

Modify or delete a xLink

First select a branch at either end of the xLink. Then open the context menu and select
‘Edit xLink’. A submenu contains all the xLinks of the branch (if there are any). They
are named like the branches, where they end. Choose one and the xLink dialogue opens,
where you can set colour, width and also delete the xLink.

Follow a xLink

In a complex vym map it sometimes comes in handy to be able to jump to the other end
of a xLink. You can do this by opening the context menu of the branch and clicking on
‘Goto xLink’and selecting the xLink you want to follow.

6.9 Adding and removing branches

The context menu of a branch shows some more ways to add and delete data e.g. you
can delete a branch while keeping its children. The children become linked to the parent
of the previously removed branch. Similar branches can be inserted into existing maps.
For keyboard shortcuts also have a look at the context menu.

6.10 Adding a whole map or a part of a map

Select a branch where you want to add a previously saved map (.vym)or a part of a map
(.vyp) , then open the context menu and choose Add −→Add Map (Insert). For the
import you can choose between Add Map (Insert) and Add Map (Replace): The imported
data will be added after the selected branch.

7 vym on Mac OS X

7.1 Overview

Basically there are two ways to run vym on Macs:

Qt Mac Edition:

vym here provides the well known Mac look and feel. vym is available as Mac OS X
application package in contained in a disk image (vym.dmg. It has been compiled and
tested in Mac OS 10.4. This package includes runtime libraries of Qt by Trolltech.
X11 version

vym can also be run using the Linux version, but then menus and handling will also be
those of the Linux version e.g. The menu bar will look different.

7.2 Contextmenu and special keys

Most Macs unfortunatly just have a single mouse button. In order to show the context
menu which usually would be opened with the right mouse button, you can click while
pressing the [command]-key.
Especially on Laptops some of the keys usually used on PC keyboards seem to be missing.
The QT-Mac Edition of vym has its own keyboard shortcuts. To find the shortcuts just
have a look at all the menu entries, the shortcut is visible next to an entry. Toolbar
buttons also may have shortcuts, just position the mouse pointer over a button and wait
for the little help window to appear.

7.3 Viewing external links

vym on Mac uses the system call /usr/bin/open to view links. Mac OS determines
automatically if the link is a pdf or www page and opens the right browser.
A vym initialisation process and configuration

A.1 Settings menu

The Settings menu allows to configure vym to your needs:

Set application to open PDF files

Choose a PDF viewer like acrobat or konqueror which is installed on your system.

Set application to open external links

Choose your favourite webbrowser here.

Set path for macros

Set the default search path for macros, which will be executed when you press one of the
function keys. Each key corresponds to a file (macro-1.vys..macro12.vys) in the search
path.

Set number of undo levels

Sets the number of undo/redo levels. The default setting is 75 levels.

Autosave and autosave time

Automatic saving of modified maps can be toggled on or off. The autosave time is entered
in seconds.

Edit branch after adding it

If set, the heading of a new branch will be edited immediatly after adding the branch.

Select branch after adding it

If set, a new branch will be selected immediatly after adding it. When you ”brainstorm”
on a given keyword, you don’t want to go deeper and deeper into details, but keep the
focus on the keyword. So the default setting here is to not select the freshly added branch.

Select existing heading

If set and you begin to edit the heading of a branch, the heading text in the dialog will
be selected. Usefully to copy&paste to other applications.
Delete key

If set, the [Delete] is enabled to, well, delete objects. This can be switched off to avoid
confusing with the nearby [Insert]-key on PC keyboards.

Exclusive flags

If set, some of the standard flags can only be used exclusively, e.g. the smileys.

Use hide flags

If set, every branch which also has the hide flag set (see 5.2) will be hidden in exports.

A.2 Configuration file

On startup vym will look for a configuration for user specific settings like window posi-
tions, toolbars etc. If this file does not already exist, it will be created. The file is located
in the users home directory. The exact position depends on the platform:

Platform Configuration file

Linux ∼/.config/InSilmaril/vym.conf
Mac OS X /Users/NAME/Library/Preferences/com.insilmaril.vym.plist

The file can be edited manually, or on Mac OS X with Property List Editor (installed
with xtools).

A.3 Path to ressources

vym will try to find its ressources (images, stylesheets, filters, etc.) in the following places:

1. Path given by the environment variable VYMHOME.

2. If called with the local option (see A.4 below), vym will look for its data in the
current directory.

3. /usr/share/vym

4. /usr/local/share/vym

A.4 Command line options

vym has the following options:

 Option Comment Argument Description
v version Show version and codename of vym
l local Use local paths to stylesheets, translations,
icons, etc. instead of system paths. Useful
for testing
h help Show help
r run filename Load and run script
q quit Quit immediatly after startup. Useful for
benchmarks.

You can also give several filenames at the commandline to let vym open several maps at
once.

B Scripts
TODO: This section of the vym manual is not complete yet, sorry.

B.1 Example scripts

B.1.1 Export a set of maps

# Simple vym script to export images of various maps simultanously

exportImage ();

The script above can be used to export all maps in a directory automatically. If the script
is named export-image.vys, call vym with

$ vym --quit --run export-image.vys *.vym

C Contributing to vym
So far I’d say I have written 98% of the code on my own. No surprise, that vym exactly
fits my own needs. Nevertheless I would like to encourage all users of vym to contribute.
Maybe not only with feature requests, but also with code, new import/export filters,
translations etc. In this appendix I’ll try to show how easy it is to expand the things you
can do already with vym . I really look forward to hear from you!

C.1 Getting help

Frequently asked questions

Please refer to the FAQ available on the vym website:

http://www.InSilmaril.de/vym/faq.html
Mailinglists

There are two mailinglists: vym-forum is the vym users forum to discuss various questions,
while vym-devel is intended for people interested in contributing to vym . You can view
the archives and subscribe at

https://sourceforge.net/mail/?group id=127802

Contacting the author

Especially for support questions please try the mailinglists first. If everything else fails
you can contact the author Uwe Drechsel at

[email protected]

C.2 How to report bugs

Though Sourceforge has its own bugreporting system, I’d rather prefer if you contact me
directly (see C.1) or even better: You can file a bugreport in Bugzilla, the bugtracking
system of openSUSE:

http://en.opensuse.org/Submit a bug

I build vym regulary for openSUSE, so you may report it against a recent version there,
even if you use another Operating System. Please don’t forget to tell me what you are
using:

• the exact steps needed to reproduce the bug

• the version and build date of vym (see the Help −→About vym )

• hardware and Operating System

C.3 Compiling from the sources

C.3.1 Getting the sources

You find the latest version of vym at the project site:

https://sourceforge.net/projects/vym/

There you can check them out of the source repository (CVS):

cvs -d:pserver:[email protected]:/cvsroot/vym checkout code

C.3.2 The Qt toolkit

Qt is C++ toolkit for multiplatform GUI and application development. It provides single-
source portability across MS Windows, Mac OS X, Linux and all major commercial Unix
variants. Qt is also available for embedded devices. Qt is a Trolltech product. For more
information see

www.trolltech.com/qt

C.3.3 Compiling vym

Make sure you have installed your Qt environment properly, see the Qt documentation
for details. You need to have the Qt command qmake in your PATH-environment, then run

$ qmake
$ make
$ make install

The last command make install needs root-permissions. Of course it may be omitted,
if you just want to test vym .

C.4 vym file format

vym maps usually have the suffix ”.vym” and represent a compressed archive of data. If
you want to have a closer look into the data structure map called ”mapname.vym”, just
uncompress the map manually using

$ unzip mapname.vym

This will create directories named images and flags in your current directory and also
the map itself, usually named mapname.xml. The XML structure of vym is pretty self
explaining, just have a look at mapname.xml.
This XML file can be loaded directly into vym , it does not have to be compressed. If
you want to compress all the data yourself, use

$ zip -r mapname.vym .

to compress all data in your current directory.

C.5 New features

There are lots of features which might find their way into vym . Together with vym you
should have received a directory with several example maps. You find them by clicking
Help −→Open vym example maps. There you will find the map vym-projectplan.vym.
It lists quite a lot of things to be done in future. If you have more ideas, contact the
development team at [email protected].
C.6 New languages support

In order to add a new language to vym you need the sources (see C.3.1) and an installation
of Trolltechs QT. A part of QT are the development tools, from those tools especially the
translation tool ”Linguist” is needed.
In some Linux distributions the development tools are in an extra package, e.g. on SUSE
LINUX you should have installed:

libqt4-devel.rpm
libqt4-devel-doc.rpm
libqt4-devel-tools.rpm

If you don’t have QT in your system, you can get it from http://www.trolltech.com
Once you are able to compile vym yourself, you can translate the text in vym itself by
performing the following steps:

• Let’s assume now your encoding is ”NEW” instead of for example ”de” for german
or ”en” for english

• Copy the file lang/vym en.ts to lang/vym NEW.ts (The code itself contains the
english version.)

• Add lang/vym NEW.ts to the TRANSLATIONS section of vym.pro

• Run Linguist on vym NEW.ts and do the translation

• Run lrelease to create vym NEW.qm

• Do a make install to install the new vym and check your translation

If you feel brave, you can also translate the manual. It is written in LaTeX, you just have
to change the file tex/vym.tex. (Linguist and QT are not needed, but it is useful to know
how to work with LaTeX and esp. pdflatex to create the PDF.)
Please mail me every translation you have done. I can also give you a developer access to
the project, if you want to provide translations regulary.

C.7 New export/import filters

vym supports various kinds of filters. Data can be written directly, inserted into templates
or it can be written as XML data and then processed by XSL transformations.
Most of the import/export functionality is available in the classes ImportBase and Ex-
portBase and subclasses. All of them can be found in imports.h and exports.h.

Direct import/export

An example for a direct export is the XML export. This method touches the implemen-
tation of nearly every object of vym , so whenever possible you should better use a XSL
transformation instead.
If you still want to know how it is done, start looking at MapEditor::saveToDir in
mapeditor.cpp.
Templates

Templates have been introduced to export to opendoc format used e.g. by Open Office.
While I read the spec (> 500 pages) about the format9 I had the feeling that I did not
want to write the export from scratch. It would be too complex to adapt the styles to
your own wishes, e.g. the layout.
Instead I analyzed existing Open Office documents. I found out that there are lots of
redundant bits of information in a standard presentation, for example each list item is
contained in its own list. In the end I came up with the default presentation style, which
still could be simplified, just in case you have free time. . .
The existing templates are still work in progress, before you spend too much time devel-
oping your own style, please contact me. Basically the following steps are needed to build
your own style:

1. Create an example in Open Office. Use a title, authors name, page heading etc.
which you can easily grep for in the output file.

2. Unzip the Open Office document into a directory.

3. The main file is called content.xml. All data is in one single line. You can split the
XML tags using the script scripts/niceXML, which is part of the vym distribution.

4. Copy the output of niceXML to content-template.xml.

5. Looking closer you will find lots of unused definitions, for example of styles. You
can delete or simply ignore them.

6. Try to find your title, authors name. vym will replace the following strings while
exporting:

<!-- INSERT TITLE --> title of map

<!-- INSERT AUTHOR--> author
<!-- INSERT COMMENT --> comment
<!-- INSERT PAGES--> content of map

The content itself is generated in a similar way by inserting lists into page-template.
Here the following substitutions are made:

<!-- INSERT PAGE HEADING--> heading of a page (mainbranch or child

of mainbranch, depending on the use of
sections)
<!-- INSERT LIST --> all childs of the branch above

Currently images are exported and notes just will appear as text without formatting and
colours.

XSL Transformation

vym uses XSL transformations while exporting (e.g. XHTML) and importing data (e.g.
KDE bookmarks). There is a little code needed to provide the GUI, the rest is done using
the .xsl stylesheet and calling the xsltproc processor, which is part of libxslt, the XSLT
C library for GNOME.
9
http://www.oasis-open.org/