Userguide
Kontext is a tool for creating and manipulating graphs representing associative sets. It was written to be a general tool, and not with a very specific application in mind.
Kontext allows you to create networks of nodes – representing anything from ideas to computers – that are connected to each other. Connections do not follow any specific rules, and you can connect as many nodes with each other as you like.
The main purpose of kontext is to serve as a starting point for a project, a paper, a todo-list or whatever comes to your mind that you like to sort out and structure before you start working on it.
Kontext comes with its own installation program that should make it fairly easy to install the application. Before you try to install kontext, make sure that you have a Java Runtime Environment installed.
-
Download and install the Java Runtime Environment from Sun. Go to http://java.sun.com/j2se/downloads.html and select the Java version you want to download (usually, it’s the latest, which is at the top of the list). Then, select your Operating System. If you plan to only use software written in Java, downloading the JRE is enough. If you want to develop Java programs, you should choose the JDK (Java Development Kit).
-
Download the file kontext-install.jar
-
Start the installer
- On GNU/Linux
-
Open a terminal (for example, Konsole) and switch to the directory you downloaded the file kontext-install.jar into, e.g. cd ~/tmp/
Start the installer by typing java -jar kontext-install.jar . If you receive an error message, the JRE was not correctly installed.
- On OS X
-
Just click on kontext-install.jar .
- On Microsoft Windows
-
Depending on your Windows version or setup, you might have a shortcut to JAR-files set. Try double-clicking kontext-install.jar . If nothing happens (or a “Open file with” – dialog appears), open a command prompt, switch to the directory you downloaded the installer into, and start it with java -jar kontext-install.jar . If you receive an error message, the JRE was not correctly installed.
If you downloaded the file kontext-install.zip, there is a small batch-file that does that for you. Unzip the file, and double-click on the file named install.bat (or install, if you enabled the pesky “hide file extensions” option in the explorer). The icon of the file is a strange-looking text that somehow resembles the word “MS-DOS”.
-
Follow the instructions. Remember the path you installed kontext into.
-
Once the installer finished, you are ready to start kontext and create a desktop shortcut to the application. Since the creation of Desktop Shortcuts is not unified in any way, Java programs cannot easily install shortcuts on your system.
- On GNU/Linux
-
Select “Create shortcut to application” or similar (depending on your desktop manager), switch to the directory you installed kontext into, go into the bin directory, and select kontext.sh . This will start kontext.
- On OS X
-
Use the finder to go into the directory you installed kontext into. Create a shortcut on the file kontext.jar to start it.
- On Microsoft Windows
-
Right-click on the desktop, select “New Shortcut” and browse to the directory you installed kontext into. There, go to the bin directory, and select kontext.bat . This will start kontext.
If you have followed the steps above, you should have a working kontext installation on your computer.
When you first start kontext, you will see a screen that looks roughly like this:
The window is divided into two main areas: The graph view on the right, and the detail view on the left.
The graph view displays the currently opened file, and in the detail view, you see the details of an entry if you select it.
To create a new node, simply double-click anywhere in the main view (on the right side of the screen). This will place a new, unnamed node in the graph. To change its name, double-click on it, and enter your text. Please note that multi-line texts are not supported. Confirm your changes by pressing ENTER or RETURN.
You now have created a new, shiny node. You can move that node to any position on the display by simply dragging it there (move your mousepointer over the node, click the left mousebutton without releasing it, and move the mouse to the new position of the node, releasing the mousebutton there).
To connect nodes, move your mousepointer over one node, until it changes its shape from an arrow to a hand. Click with the left mousebutton and move away from the entry without releasing the mousebutton. You will see a connection following your moves. Move your mouse over the node you want as the end point of the connection, and release the mousebutton.
Of course, nodes can be changed after they have been created. Every aspect of the node can be modified.
To change the title of a node, double-click it. You cannot change the title of the node in the detail view.
To add text to a node, select it, and type your text on the left side in the text window. You do not need to confirm any changes. Simply saving the file or selecting a different node will write back your changes to the node.
Changing connections is just as easy as changing nodes.
To change the start or end node of a connection, select the connection by left-clicking it. Then, move your mousepointer to the beginning or the end of the connection, and drag it to the new target node.
Kontext helps you to get a view of what is most important in your domain by weighting the nodes of your graph. For this weighting, multiple algorithms can be selected.
Basic Weighting is the most simple Weighting algorithm. The more direct children a node has, the brighter it gets. Indirect children (ancestors of second grade or more) are not counted.The maximum number of connections equals the number of nodes minus 1 (since nodes are not connected to themselves). A node with this many connections will reach the end color. All other nodes will be darker, even if they are the nodes with the most connections.
Basic Weightings are useful for small graphs. The figure shows a graph where one node has the maximum number of connections, a case where basic weighting is most efficient. Examples for other weightings will show more complex graphs in which basic weighting will not work as well.
Subtree weighting computes the weight of a node respective to the size of the subtree that starts at this very node.Note that every node is the parent of a subtree (a part of the whole graph), even if it is the only member of that tree.
Declining subtree weighting is a derivative of subtree weighting. It works by the same principle, but the impact of children declines over the size of the tree. The farther away a child is, the less influence it has on the color of a parent.
Null weighting is just that: It does not weight. Every node is painted as if it had the maximum weight.
There is no fixed rule about what weighting works best or gives the best results. This depends first on the type of your document, and second on what exactly you are trying to illustrate. Declining Subtree Weighting has the potential of being the most generally useful weighting algorithm, because it shows the relative importance of nodes, and also accomodates the fact that long inheritance lines are not as important as short ones. Basic Weighting in my opinion is only usable in very special cases.
Weighting is implemented in a way that makes it easy for every developer to contribute her own weighting algorithms. Custom weighting algorithms need to implement the interface Weighting and must be added to the classpath and to the configuration file. See the JavaDoc and the kontext source for more details.
To change the weighting of a graph, select “Options – Preferences” from the menu bar to open the preferences dialog. Then, switch to “Graph Display” and select the weighting system your prefer.
Important
Please note that the weighting is connected to the kontext application itself, and not to a document file. It is not possible to store a preferred weighting algorithm inside the document. I am thinking about adding this information to the document.
Note
As of version 0.1, the changed weighting is not reflected immediately in the graph. You need to modify the structure (read: add/remove an entry or a connection, or change a connections start and end entries) of the graph before the change is visible.
The motivation to write kontext came from the observation that you often have to deal with topics, problems or tasks of which you do not have a very clear picture. Especially when the thing in question consists of multiple subsets of taks/problems/actions that are in some way connected to each other, but it is not quite clear how.
Work usually starts that way: Get a feeling of what needs to be done, and how these single things interconnect with each other. This is a highly associative, hence a highly unstructured process. All software tools I found, and all mental techniques I read about cannot cope with this lack of structure. Mind Maps, for example, require that you actually need a very good understanding of how things fit together, otherwise you will not be able to draw them correctly. These techniques (flow charts, mind maps, etc.) are great companions throughout a project, but they are very poor guides at the start.
Kontext tries to be of help here. It allows you to freely associate and just create new nodes by double-clicking and entering a text. Once you feel that two nodes are connected to each other, you simply drag a connection between them. The highlighting helps you determine what is most important inside your current work.
If you think that this sounds like a very unstructured process: you’re right. But that is exactly the purpose of kontext.
In order to give you an idea about what can be done with kontext, I’ve put together a small collection of possible applications of kontext. This list is by no means exhaustive, and if you found a great way to use kontext, please tell me.
This application was the first thing that came to my mind when I was looking for a program that allows me to easily draw interconnected nodes. I was working on a paper, and I wanted a way to sort my thoughts.
I started out by writing down what came to my mind, and created a node for each word. Then, I connected and re-connected nodes that somehow where related together. This helps you find the most important aspects of what you where thinking about, and gives you a basic structure you can use for further writing.
Before the start of a project or during the realisation, you might want to know what exactly you are up to, or where you are standing. Kontext provides a nice way of creating graphs that represent the work that has to be done to finish the project.
If you’re interested in how your friends are connected to each other, and who has which position inside a social structure, you can create a simple map of these structures by creating a node for each person, and connecting these nodes according to the connection of people in real life. Of course, what makes up a “connection” between two people is up to you, but should be fairly easy to figure out. I’ve seen some nice maps of this kind made with kontext, especially if they combine persons and projects.
Most sitemaps (and programs that allow the creation of sitemaps) are very static, and follow a very hierarchical scheme. Often, this is not the best way to sketch out how a website could or should work. You can create nodes that can but not necessarily have to represent actual pages (they could be a subset of pages, or even actions a user can take). By combining the nodes with each other, you get the first impression of how a useful navigation on the page could look like. Additionally, the weighting tells you what the most important parts of your website probably are, giving you a better start for designing the interface.
Besides the very specific applications listed above, kontext can be used for just about everything that can be supported by a quick map. So far, I’ve used kontext for drawing quick network diagrams, database relations and other technical stuff that can be explained easier by a small picture than with words.
Kontext was built with flexibility in mind. Most aspects of the program can be changed easily through the user interface.
To change the program preferences, select “Options – Preferences” from the menu bar. This will open the preferences dialog, where you can modify most aspects of kontext.
You can specify your firstname, lastname, eMail address and honorific title (if you have one. If you don’t, I suggest you make one up that sounds cool. Actually, even if you have one, I still suggest you make one up.). These settings will be used as default values for new documents (see below for information stored inside documents).
On the appearance tab, you can change fonts, and colors of kontext.
Most of the settings speak for themselves (for example, the fonts settings). The cell color controls let you adjust the way the weight of an entry is visualized. The color on the left (the start color) is used for entries that have a weight of 0, the smallest possible weight. On the other hand, the color on the right (end color) is used for entries with a weight of 1, the maximum weight. Between these two colors, a gradient is drawn. This gradient represents the colors for entries which have a weight between 0 and 1.
The Line Ends control allows you to use different decorations of the beginning and the end of connections. Please note that regardless of how the connections look like, they always have the orientation you set when you created them, from the first node you selected, to the second one. Even if you revert the display (setting an arrow end for the line start, and no decoration for the line end), this will not revert the true orientation of the connection.
Kontext stores a view things inside each data file. Most notably, information about the author, a title, a description, the date on which the document was created, and the date it was last saved. Author information, title, description and a version information can be modified. Date information and the revision of the file (which actually is the number of times the file was saved) cannot.
Author information is copied from the Configuration of the kontext installation the document was created on. To enter information about the document you are currently editing, click on the button on the right of the toolbar. The File Information dialog will pop up.
All the information entered here will be visible if you export the file to PNG (see below). The author information can be edited.
[1]
Kontext uses its own – very simple – data file format for saving documents. This data files are XML-documents, which means that they can be used by lots of other applications and are to some extend human-readable as well.
Kontext data files (kdx extension) are very simple XML-files. Actually, there is not much structure or information that these files need to hold, so there is no need for a big file-structure at all.
A kontext data file contains a header and the entry and connection data. The header looks like this:
The description ... ... ... ... Kontext 0.1
Then the actual data entries come.
...
And last, the connections between the entries. Note that the file format has fields for labeling connections, but the application itself does not support them. Maybe in a later release …
Currently, kontext supports only one file format except its own: Portable Network Graphic, short PNG. PNG is a very capable picture format, invented to replace the older (and patent-handicapped) GIF format. To export a graph to PNG, simply choose File –> Export as PNG.
These files can easily be modified with any common image manipulation program and can be imported in most (if not all) word processors, spreadsheet programs or presentation applications.
If you think that kontext should support other file formats as well, please drop me a line. At the moment, I am thinking about adding support for SVG and the file format the JGraphPad application uses.
This version of kontext is 0.1, meaning that it is in a very early stage of development. To the best of my knowledge, it is stable, but it has some issues. Most of them are cosmetic, but some are more serious.
- No undo
-
Kontext 0.1 does not support undo/redo actions.
- No confirmation on exit
-
If you edit a document and close the application (or load a different file, or start a new document), kontext will not warn you that you are about to close a modified document. You will just be presented with the new document, the modifications on the old file will happily go down the drain.
- Weighting and changing connections
-
If you change connections by deleting them or attaching them to different entries, the weighting of the graph will be recomputed, but the changed weighting will not be reflected until you further modify the graph by changing a connection or an entry again.
- Multiple saves without modifications
-
Kontext does not track modifications to the current document, and cannot determine if a file has been modified and differs from the file on the harddisk, making it possible to save a document multiple times without any modifications (this screws up the revision tag).
Since kontext is still in its early stages, there is a lot of room for improvement. Of course, the issues mentioned above will be addressed first. Also, I’d like to speed up especially the loading of data files.
Another big thing will be adding layout support to the graph. At the moment, relative importance of single entries are only marked by their colors. It would be nice to change the layout of the graph, too (for example, by putting the most important ones on the top of the page, and the other ones below).
Additionally, I’m thinking about modularizing the data model to allow different types of entries either co-exist in one graph, or to allow for easy modification of kontext for different purposes (for example, a better todo-list that allows the addition of priorities and status). But this is rather further away in the future and will highly depend on demand.
Speaking of demand, when it comes to new features, I’d rather implement features that users actually need instead of making some up on my own. So if there is something kontext should be able to do in order to be more useful for you, please contact me.
At the moment, few people use kontext, and this hardly justifies the creation of an online forum or a users mailinglist. If you need help with kontext, you can contact me directly (send a mail to rick@subnet.at). If you are interested in the future of kontext, you can contact me too, and I will keep you up-to-date. If enough people show up, I’ll create a mailing list and/or online forum faster than my cats can put some hair one a black shirt.
Kontext is Open Source Software, published under the terms of the subnet Software License. It is free for use, and can be modified and distributed as long as you adhere to the terms of the license.
KontextMarqueeHandler is a derivative from the class MarqueeHandler written by Gaudenz Alder, which is available from the JGraph website (see below). This derivative is published under the terms of the subnet Software License with the permission of the original author. See the source file for details.
KontextVertexRenderer and KontextVertexView are inspired by the “Labeled Vertex Demo” contributed to the JGraph project by Douglas B. Caulkins. This demo is available at the Source Forge project page of JGraph (http://sourceforge.net/projects/jgraph/), at http://sourceforge.net/tracker/index.php?func=detail&aid=829163&group_id=43118&atid=537692.
If this URL changes, you should be able to access it by selecting “Contributions” from the main project site.
Everything else is Copyright 2003-2004 Peter Riegersperger.
Kontext is Open Source Software published under the terms of the subnet Software License. This license is available in this distribution, or online at the kontext homepage http://homex.subnet.at/peter/kontext or at the subnet website http://www.subnet.at/about/verein/subnet_software_license.html.
Kontext uses the JGraph, a java graph drawing library. It is published under the terms of a BSD-style license which is included in the distribution (doc/jgraph_LICENSE.txt). For more information about JGraph, please visit their website at http://www.jgraph.com. JGraph is Copyright 2001 – 2004 Gaudenz Alder.
Kontext uses Software developed by the Apache Software Foundation (http://www.apache.org): Xerces, a XML-parser (http://xml.apache.org) and log4j, a logging library (http://jakarta.apache.org/log4j). These libraries are published under the terms of the Apache Software License, which is included in this distribution (doc/apache_software_license.txt).
Kontext is open source. That means that you can use and redistribute it free of charge. You also get access to the source code, which allows you to modify it to fit your needs. I encourage you to do so. If you are planning to modify kontext, please take the time and read the subnet Software License; it’s a fun read, thrilling and very short. If you think your modifications can be useful for other people as well, consider publishing your version, or even better, send me your modifications so I can include them into the program.
To visit kontexts homepage, go to http://homex.subnet.at/peter/kontext/. You can also send me an eMail: rick@subnet.at.
[1] Actually, it can be changed. The data files are stored in a simple XML structure and are therefore editable with any common text editor.