Development: Difference between revisions

From FreeMind
Jump to navigationJump to search
No edit summary
No edit summary
 
(100 intermediate revisions by 12 users not shown)
Line 1: Line 1:
<table><tr>
<table><tr>
<td valign=top>
{{Navigation_bar}}
<td>&nbsp;
<td width=600>
<td width=600>


The development of FreeMind is coordinated using FreeMind's [http://sourceforge.net/projects/freemind/ project page] at SourceForge, and also using this wiki. At wiki, we have '''[[requests for enhancements]]''' page; there is also [http://sourceforge.net/tracker/?group_id=7118&atid=357118 requests for enhancements] (RFEs) page at SourceForge (not preferred). You can [http://freemind.cvs.sourceforge.net/freemind/ browse CVS repository].
The development of FreeMind is coordinated using FreeMind's [http://sourceforge.net/projects/freemind/ project page] at SourceForge, and also using this wiki. At wiki, we have '''[[requests for enhancements]]''' page; there is also [http://sourceforge.net/tracker/?group_id=7118&atid=357118 requests for enhancements] (RFEs) page at SourceForge (not preferred). You can [http://freemind.git.sourceforge.net/git/gitweb.cgi?p=freemind/freemind;a=summary browse] our new [[GIT]] repository.


We also use SourceForge for [http://sourceforge.net/tracker/?group_id=7118&atid=107118 bugs],  and [http://sourceforge.net/forum/forum.php?forum_id=22101 open discussion forum]. We do not use the documentation part there as we use this wiki instead.
We also use SourceForge for [http://sourceforge.net/tracker/?group_id=7118&atid=107118 bugs],  and [http://sourceforge.net/forum/forum.php?forum_id=22101 open discussion forum]. We do not use the documentation part there as we use this wiki instead.


== Getting started as a developer or tester ==
==Contributing to FreeMind==


=== To get the latest beta version of FreeMind ===
See [[Contributing]].


You can get the beta version from the CVS. Look under branches. Observe, that these versions are not official releases
==Getting started as a developer==
and may admit serious errors. Please, use them only if you urgently need a feature included in such a version
or to give us feedback to our development which is highly appreciated.


=== To compile FreeMind on your own ===
See [[Getting started as a developer]].


If you are a developer, just download the sources, unpack them,
==Getting started as a tester==
find the folder with the file build.xml, and execute the command
<code>ant</code> in that folder. For more detail description
see the [http://freemind.sourceforge.net/docs/compile/windows/Quick%20guide%20to%20compiling%20Freemind%20on%20an%20XP%20system.html Quick guide to compiling Freemind on an XP system using Eclipse] prepared for you by Bob Alexander.


Broken down into simple steps, a simple way for a developer of compiling FreeMind is perhaps the following.
See [[Getting started as a tester]].


# install [http://java.sun.com/javase/downloads/index.html Java SDK] &mdash; standard development kit
==Reporting bugs==
# install [http://ant.apache.org/ Ant] &mdash; a tool for building code using complicated make files)
# download FreeMind's [http://sourceforge.net/project/showfiles.php?group_id=7118 source code]  as published in the Files section
# unpack the source code package with the extension <code>tar.gz</code>
# change directory to the one where <code>built.xml</code> file resides &mdash; the build file for Ant, similar to make files for the C language
# type <code>ant</code> in the command shell


=== To set up a FreeMind project under Eclipse ===
See [[Reporting bugs]].


You download FreeMind to ~/src/freemind say.
==Organization of FreeMind development==
Then, you have to compile FreeMind on command line using "ant dist".
After that you open a new project with working directory ~/src you should find the following settings:


* The binaries are stored into ~/src/bin/classes.
Initially, every active developer of the core team works on his own GIT branch. Our intermediate results are
* You have two source folders.
published as our "alpha versions". We use forum [http://sourceforge.net/forum/forum.php?forum_id=22101 Open Discussion] to communicate them.
* All jars you find in ~/src/freemind are added to the project.
 
Then finish the project settings and there should be no errors in the project. You can run FreeMind starting the class <code java>freemind.main.FreeMind</code>.
 
=== Further development wiki pages ===
 
Further reading (still under construction):
 
* [[FreeMind Actions]]
* [[Plugins]]
* [[Undoable Actions]] (first version available)
 
===Working with CVS===
 
See [[CVS]].
 
=== Contributing to FreeMind ===
 
There are different possible ways of taking part in the FreeMind development: the project needs people for developing, testing and documenting of the program, and translating its interface and documentation in foreign languages.
 
New developer starts by sending his contributions for example as patches. Later on, he may get access to [[CVS]] repository. The process is approximately as follows.
 
* Create a user account at SourceForge. 
* Discuss your contribution (the change, feature, bug fix, documentation or test plan) in our [http://sourceforge.net/forum/forum.php?forum_id=22101 open discussion forum].
* If the topic is accepted, start to change the actual CVS code. Be careful to use the right CVS branch. Currently we use the branch with a strange name "fm_060405_integration".
* For later merging of the code it could be better if you start from code state already labeled by a tag, e.g. "fm_0_9_0_beta9".
* If you have any questions during the implementing feel free to ask them in the "Open Discussion" forum. It is read by the other developers who possible can help you.
* Post your contribution in the patch section of SourceForge or send it by email to the current project manager. We do not respond immediately, as FreeMind team consists of volunteers.
* After having successfully developed and integrated some items, you get access to FreeMind's CVS repository at SourceForge.
 
=== Development resources ===
 
* [http://freemind.sourceforge.net/javadoc/index.html API documentation] (javadoc)
* [http://freemind.sourceforge.net/Freemind-development.html Obsolete development mind map]
* [http://freemind.sourceforge.net/Freemind-development.mm Obsolete development mind map for download]
* [http://freemind.sourceforge.net/Freemind-development-exported.html Obsolete development mind map exported to HTML with folding]
 
== Organization of FreeMind development ==
 
Initially every active developer works on his own branch. Our intermediate results are
published as our "alpha versions". We use forum [http://sourceforge.net/forum/forum.php?forum_id=22101 Open Discussion] and section [[Experimental_versions]] on this wiki page to communicate them.


Further details about the FreeMind release process are described on the FreeMind [[Release process]] page.
Further details about the FreeMind release process are described on the FreeMind [[Release process]] page.


=== Experimental versions ===
==Experimental versions==
 
Currently, there are the following experimental versions available. They are not meant for productive use; use at your own risk!
 
==== FreeMind 0.9.0 beta 9 with  Node Attributes, Map Filters  and WYSIWYG rich text node editor====
Attaching of named attributes to every node, filtering of the displayed map content based on node text, node icons and node attributes, HTML based rich text formatting for nodes and notes, fit for Java6, a script editor is included in the script plugin
* [https://sourceforge.net/forum/message.php?msg_id=4190697 Discussion forum thread]
* [https://sourceforge.net/project/showfiles.php?group_id=7118&package_id=188772&release_id=488111 Downloads]
 
 
 
== Conceptual remarks ==
 
=== Modular model - view design ===
 
The architecture of FreeMind makes it possible that FreeMind becomes general tool for editing tree-structured data, that is mind maps, XML/HTML documents, folder trees etc. in future.
 
All these kinds of data would be presented to the user as a mind map. Model-View-Controller design makes it possible for you only to write so called model of the data structure, without caring for the visual representation. Currently, mind map mode and file mode are implemented.
 
=== Original vision of Joerg Mueller ===
 
Joerg Muller is the original author of FreeMind, developing it up to the version 0.4.0. Here follows what he's got to say on his original vision:
 
: What I had in mind when I began to write FreeMind, was creating a collaborative mind where people can intuitively share their ideas, knowledge and thoughts with each other. Of course FreeMind is only a first step into this direction, but I did this first step. Now a Mode must be implemented that makes collaboration over the Internet possible, maybe using the Topic-Map standard. I think linear text is a very poor way of representing knowledge, and by using trees and networks, visual representation, internet collaboration and open source we should be able to create some kind of a collaborative mind.
 
: FreeMind now has evolved from a specific Mind Map Editor to a generic editor for tree structured data. I want FreeMind to become for tree structured data what emacs is for linear data (ie. text).
 
One may think of extending FreeMind to work with networks as opposed to trees only, an example of this being Topic Maps (ISO).
 
Daniel Polansky: Joerg's vision of FreeMind becoming Emacs for tree data is intriguing, but rather far fetched at the time. You would need to provide scripting facility and at least many basic operations, like upcase, downcase, replace and many others. It is even not evident that this goal valuable compared to other goals - there many quite obvious and still missing features.
 
=== Why not use OPML for storage instead of FreeMind's native XML format ===
 
The current version of [http://www.opml.org/ OPML] is not suited for our purposes. It should be easy to create conversion XSLT between FreeMind and OPML. First, if we decided to use OPML, we would have to wait until the owner of OPML changes his standard to fit our needs. Thus, we would be dependent, not being able to act dynamically. Second, already the current version of OPML is insufficient. It does not contain most of what FreeMind already uses: colors, fonts, folded tag, edges and icons. It is not a superset of FreeMind's XML format, even not in a vague sense. Even if I renamed the elements names properly, OPML would still be a subset and not superset of FreeMind's XML. As a result, we have no benefit from using OPML right now.
 
''Summary:'' 1) we would run into dependence, and 2) OPML is insufficient, loosely speaking it is a subset.
 
=== Why may FreeMind be more relevant than some other open source applications ===
 
There are many efforts to create new text editors, text processor and the like. While this activity is not without value, it does not fill that big value gap as mind mapping application.
 
Take, for instance, text editors like JEdit. There are already well estabilished text editors like Emacs or Vim, and there are many others. It's not that these editors would be perfect, far from that, but they're still pretty useful and with some training users can become very efficient with them.
 
With text processors, the thing is that most users in companies have already Microsoft Office for free. What does that mean? That means that the individual users do not have to pay for the MS Office, and they cannot effectively decide to use other Office platform either because of the value of easy sharing. Furthermore, there are competing free Office platforms like KOffice, OpenOffice or AbiWord.
 
In mind mapping, the situation is quite different. You do not get commercial alternative granted in companies, unlike office applications. The point here is that most of MS Windows users, the mainstream, do not have a mind mapping application yet. For them, starting to use FreeMind is not a switch from Microsoft product to alternative product. It is a switch from scattered documents in incomparable and hard-to-overview formats to one document with unprecedented order and transparency - FreeMind's mind map.
 
Therefore, I am expecting a growth of interest of free developers in developing and using this application.
 
Furthermore, even though Java is quite slow and memory hungry, it solves the neverending quarrel between religious die-hard fans of different computing platforms, which I have first experienced with Atari 800 XL versus Commodore 64 battle, later IBM compatible versus Commodore Amiga battle, and nowadays Windows versus Linux battles.
 
== Misc ==
 
=== To create a new release ===
 
To succesfully complete a new release, do the following
 
* upload the release files into /incoming at ftp:upload.sourceforge.net , use the user anonymous and your e-mail address as a password
* create new release. The files you have uploaded with ftp will be offered to you. Releases have names like "0.6.1", "0.6.5".
* update the home page so that it points to the new version of installation files
* post news, listing the most important changes of the new version
* repost the news to the Announce forum, with basically the same text
* repost the news the mailing list freemind-users@lists.sourceforge.net
 
Notice that the news cannot be monitored unlike forum, and forum has no RSS
feed unlike news.
 
=== To create proper copyright notice ===
 
A source file may be viewed as a sum ''b'' + ''d<sub>1</sub>'' + ''d<sub>2</sub>'' + ... + ''d<sub>k</sub>'', where ''b'' is the basis, ''d<sub>i</sub>'' are deltas (or patches), and the plus operator is the operator of applying a patch. The basis and each delta have their own copyright holder and the year of copyright.
 
If there is only one autor and one year, then the copyright notice is simple.
 
If there is only one autor and more years, then the copyright notice may look like
 
<blockquote>
Copyright © 2003-2005 Big Author
</blockquote>
 
which is to be understood as
 
<blockquote>
Some parts of the sum are copyrighted in 2003, some perhaps in 2004, and some certainly in 2005.
</blockquote>
 
If there are more authors, then the copyright notice consists of more lines, like
 
<blockquote>
Copyright © 2003-2005 Big Author, <br>
Copyright © 2005 Captain,
</blockquote>
 
Not all changes are eligible for copyright. If a change is small, then it does not make sense to add a line to the copyright notice for it.
 
Copyright notice is not required for copyright to hold. It makes claiming your right at court easier.
 
The correctness of these instructions is not granted. They are subject to improvement as we see fit.
 
--[[User:Danielpolansky|Danielpolansky]] 11:29, 3 Jun 2005 (PDT)
 
=== All on keyboard mappings ===
 
Currently, each function has at most one key assigned. But, it should be the other way around;
the keys should have functions assigned, rather than functions key. For instance, it would be
valuable to have both ''insert'' and ''tab'' assigned to ''new node'' function. (Actually on MS Windows it is right now not possible at all to bind anything to ''tab''.)
 
=== To translate FreeMind into your language ===
 
See [[Translation]].
 
=== To translate the wiki pages ===
 
See [http://meta.wikimedia.org/wiki/Meta:Interlanguage_links] for a description of how to do that. We don't have such a page yet, so, please, be careful.
 
=== FreeMind's xml data format (.mm) ===
 
FreeMind stores his data in own XML flavor. Up to FreeMind 0.6.5, the xml format has been unchanged. The list of elements and their attributes as of FreeMind 0.7.1 follows.
 
* '''map''' (root element)
** version (0.7.1)
* '''node''' (parent element: node, map)
** id  (0.7.1)
** text
** link
** folded
** color
** position (left or right, only for children of the root) (0.7.1)
* '''edge''' (parent element: node)
** style
** color
** width
* '''font''' (parent element: node)
** name
** size
** bold
** italic
* '''icon''' (parent element: node) (0.6.7)
** builtin
* '''cloud''' (parent element: node) (0.7.1)
** color
* '''arrowlink''' (parent element: node) (0.7.1)
** color
** destination (id of the target node)
** startarrow (arrow style)
** endarrow (arrow style)
 
The actual W3C schema can be found under
[[http://cvs.sourceforge.net/viewcvs.py/freemind/freemind/Attic/freemind.xsd?rev=1.1.2.1&only_with_tag=fm_041017_base_integration&view=log]].
 
=== Libraries and tools used in FreeMind ===
 
* [http://nanoxml.cyberelf.be/ NanoXML]
 
=== Sources of free icons ===


FreeMind uses (a) tool icons used in the toolbars, and (b) icons used in nodes. Especially for the icons used in nodes, a good comprehensive source of free icons is needed. FreeMind uses PNG icons, in the size of 16 x 16. Nowadays many icons are drawn in SVG vector format first, and converted to 16 x 16 bitmap images afterwards.  
Currently, there are no experimental versions available. The latest release candidate can be downloaded from [http://sourceforge.net/project/showfiles.php?group_id=7118 Files section].


Ideally, it would not be the task of FreeMind team to draw icons; this task should be outsourced instead. Whether this is a realistic assumption remains to be seen.
==Obtaining focus for selected node in reliable manner==
 
Some links on the sources of free icons follow.
 
* [http://www.kde-look.org/index.php?xcontentmode=22x27 Icons at kde-look]
* [http://www.gnome-look.org/index.php?xcontentmode=120 Icons at gnome-look]
* [http://www.everaldo.com/crystal.html Crystal icons] &mdash; an icon set often used in KDE desktop environment
* [http://tango-project.org/Tango_Desktop_Project Tango Desktop Project] &mdash; an icon library for KDE and Gnome, licenced under Creative Commons Attribution Sharealike
* [http://www.famfamfam.com/lab/icons/silk/ Silk icons] &mdash; 1000 icons licenced under Creative Commons attribution license
* [http://www.openclipart.org/ Open Clip Art Library] &mdash; a library used for some Mediawiki icons, mostly not suitable as a source of icons but rather as of clipart
* [http://commons.wikimedia.org/wiki/Category:PD_OpenClipart Open Clipart at Wikimedia commons]
 
 
More relevant links
 
* [http://jimmac.musichall.cz/icons.php Icons by Jimmac]
 
== Implementation ==
 
 
 
=== To implement embedded images ===
 
To implement embedded images, one would store binary data in a node, like &lt;node TYPE="image" BINARY="x4543edvc...45ert"/&gt;
Upon opening the node for viewing, temporary file would be created and HTML viewer would point to that file. Upon editing,
external image editor would be opened to edit the temporary file, like Gimp.
 
 
 
 
 
=== To obtain focus for selected node in reliable manner ===


Requesting focus for NodeView using requestFocus() method is unreliable. A reliable way of doing that has been implemented in the method <code>obtainFocusForSelected()</code> of Controller. A typical call in ControllerAdaper.java is  
Requesting focus for NodeView using requestFocus() method is unreliable. A reliable way of doing that has been implemented in the method <code>obtainFocusForSelected()</code> of Controller. A typical call in ControllerAdaper.java is  
Line 284: Line 44:


where <code>newSelected</code> is a NodeView is unreliable, though most often works.
where <code>newSelected</code> is a NodeView is unreliable, though most often works.
=== To set the class load path in manifest.mf in jar ===
In the source folder tree of FreeMind, there's a file MANIFEST.MF. This file tells what
should happen with the freemind.jar when java tries to run the jar archive. The file
may look like
Manifest-Version: 1.0
Main-Class: freemind.main.FreeMind
Class-Path:                  silk.jar nanoxml.jar ekit.jar kafenio.jar
            kafenio-config.jar kafenio-icons.jar gnu-regexp-1.1.4.jar
Created-By: Joerg Mueller
A tricky thing about the file is that the length of the lines can be
at most 72 characters. That creates difficulties when specifying Class-Path.
In the exaple above, the first line of Class-Path is set in such a way
that it has 70 chacters. That has been achieved by putting spaces before
the actual list of classes. In the freemind.jar, the file can be found in the
folder META-INF. Here you can check if the manifest has been created correctly.
=== Deleting nodes and branches in FreeMind ===
Since version 0.8.0, it is possible to delete a whole branch of nodes by pressing DELETE. When a user accidentally presses DELETE and does not notice that, they may loose considerable amount of data. For users using FreeMind as a knowledge base or a semi-structured database, being able to delete whole branch at one keystroke is problematic and unusual; in filesystem browsers, users are asked for confirmation before the file is deleted by the system.
However, some users use FreeMind as a mind mapper and are glad to be able to delete nodes just by pressing DELETE.
There are several solutions to this problem.
* Add user option to enable or disable confirmation before deleting of nodes and branches (depending on model type)
* Store all deleted nodes and branches in a kind of trashcan associated with every mind map
* Ask for confirmation only for nodes with children
* Ask for confirmation only for nodes with more than ''p'' children
The confirmation would be requested both for keystrokes DELETE and CONTROL + X, that is the actions Delete and Cut.


== More development pages ==
== More development pages ==

Latest revision as of 19:04, 28 May 2011

The development of FreeMind is coordinated using FreeMind's project page at SourceForge, and also using this wiki. At wiki, we have requests for enhancements page; there is also requests for enhancements (RFEs) page at SourceForge (not preferred). You can browse our new GIT repository.

We also use SourceForge for bugs, and open discussion forum. We do not use the documentation part there as we use this wiki instead.

Contributing to FreeMind

See Contributing.

Getting started as a developer

See Getting started as a developer.

Getting started as a tester

See Getting started as a tester.

Reporting bugs

See Reporting bugs.

Organization of FreeMind development

Initially, every active developer of the core team works on his own GIT branch. Our intermediate results are published as our "alpha versions". We use forum Open Discussion to communicate them.

Further details about the FreeMind release process are described on the FreeMind Release process page.

Experimental versions

Currently, there are no experimental versions available. The latest release candidate can be downloaded from Files section.

Obtaining focus for selected node in reliable manner

Requesting focus for NodeView using requestFocus() method is unreliable. A reliable way of doing that has been implemented in the method obtainFocusForSelected() of Controller. A typical call in ControllerAdaper.java is

 getController().obtainFocusForSelected();

Requesting focus using

 newSelected.requestFocus();

where newSelected is a NodeView is unreliable, though most often works.

More development pages

To see all development pages, have a look at the category Development, by clicking on the link at the bottom of this page.