Written by Doug Bell
Version 0.9.0
September 1, 2004
Do you have lots of sticky notes lying around with various useful information jotted down? Or many lists of books, movies, links, website logins, personal contacts, or things to do? Can you find them when you need them? Well, I often couldn't. So here's my answer.
Some would call TreeLine an Outliner, others would call it a PIM. Basically, it just stores almost any kind of information. A tree structure makes it easy to keep things organized. And each node in the tree can contain several fields, forming a mini-database. The output format for each node can be defined, and the output can be shown on the screen, printed, or exported to HTML.
Since I'm not in the software business, I'm making this program free for anyone to use, distribute and modify, as long as it is not incorporated into any proprietary programs. If you like the software, feel free to let others know about it. And let me know what you think - my e-mail address is doug101 AT bellz DOT org
TreeLine is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either Version 2 of the License, or (at your option) any later version.
This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY. See the LICENSE file provided with this program for more information.
As a special exception, the author gives permission to link and distribute this program with the Qt Non-Commercial Edition without including the source code for Qt.
TreeLine requires the following libraries and programs:
Using the files provided in the installer, TreeLine should run on any computer running Win 95, 98, NT, 2000, or XP.
If spell checking capability is desired, an external program is required. Either aspell (preferred) or ispell must be installed. See <http://aspell.net/win32/> or <http://www.luziusschneider.com/Speller/English/> to download one of the programs and its dictionaries for any desired languages.
Extract the source files from the treeline tar file, then change to the TreeLine directory in a terminal. For a basic installation, simply execute the following command as root: python install.py
To see all install options, use: python install.py -h
To install TreeLine with a different prefix (the default is /usr/local), use: python install.py -p /prefix/path
If installing as a normal user with a prefix under your home directory, the installer will warn that it cannot write to the sitecustomize.py file in your Python installation. This file is required for proper Unicode support. To correct this problem, simply copy the sitecustomize.py file from the source directory to the site-packages directory in your Python installation. If you already have a sitecustomize.py file, the lines in the new one may be appended to the existing file.
Any old ~/.treeline configuration files should be deleted or renamed if this is a major TreeLine upgrade (such as 0.8.x to 0.9.x) or if editing of new keyboard shortcuts is planned.
Simply execute the downloaded installation file (treeline-x.x.x-install.exe). It will install the program with its libraries and optionally create file associations and shortcuts.
If you already have a working installation of TreeLine version 0.7.0 or higher, you can use a smaller download. Simply install and execute treeline-x.x.x-upgrade.exe to upgrade the files from your previous installation.
To use TreeLine's spell checker, an external program (aspell or ispell) must be installed (see the System Requirements section).
Any old treeline.ini configuration files should be deleted or renamed if this is a major TreeLine upgrade (such as 0.8.x to 0.9.x) or if editing of new keyboard shortcuts is planned.
If you wish to modify the source code or write your own PyQt programs for Windows, do not use the above procedure. Instead, you need to install Python (see <www.python.org>), Qt (see <www.trolltech.com>), and PyQt (see <www.riverbankcomputing.co.uk>). Then extract the source code files from the Linux version (treeline tar file) to a directory of your choice, copy the sitecustomize.py file as noted in the Linux Section, and execute the treeline.py file.
TreeLine's window is divided into two panes. The view on the left shows the entire tree structure, while the view on the right shows various information about the tree node that is selected in the left pane.
The right pane is tabbed to show one of three different views of the data. The "Data Output" view shows the formatted text for each node and is read-only. The "Data Editor" view shows a text edit box for each data field within a node. The "Title List" view shows a list of node titles that can be modified using typical text editor methods.
By default, the right view will show information about the selected node in an upper pane and information about the selected node's children in the lower pane. Selecting "View->Show Selected Node" will show a single pane with information about the selected node only. When there are many children, the combined view may slow down, especially in the "Data Editor" view. In this case, it is quicker to view just the selected node. The initial state of the view can be controlled in "Tools->General Options".
Most of the menu and tool-bar commands apply to the items selected in the left view. In general, they perform an operation on the nodes themselves or on the descendants of the nodes. Multiple nodes can be selected by holding down the "Ctrl" and "Shift" buttons when clicking with the mouse. But some commands, such as "File->Export" and "File->Print", use data from only the current node, which is shown with a surrounding rectangle. The right hand view also references only the current node.
To add information to a new TreeLine document, use the "Edit->Add Child" command to create a new node. Then, combinations of the add and insert commands may be used for additional nodes. Alternatively, new node titles may be typed into the "Title List" view in the right pane.
There are several keyboard commands that can be used for tree navigation. The up and down arrow keys move the selection. The left and right arrows open and close the current node. Holding the CTRL key and the up and down arrows moves between siblings, skipping children. The CTRL key and "U" moves to an item's parent. The "Home", "End", "Page Up" and "Page Down" keys can be used to move quickly through the tree. Holding the SHIFT key with the "Page Up" and "Page Down" keys will scroll the right-hand child view.
All of these keys and the keyboard shortcuts for pull-down menu commands can be customized by editing the TreeLine configuration file ("~/.treeline" on Linux, "treeline.ini" on windows).
Another way to move through the tree is to type the first letter of a visible node title. A lowercase letter moves downward, an uppercase letter moves upward. Hitting the letter again moves to the next possibility.
There are two ways to search for nodes. These methods can find nodes that are deeply buried in the tree structure. The first is the "Tools->Find" command. Keywords can be entered in a modeless dialog box. A node is found if the keywords are matched in any of the node's fields. The next method is an incremental search. Type a "/" followed by a search string. The search will progress as the string is being typed. The incremental search only finds text in the node's titles. The previous search can be repeated with the "F3" key and backward with "Shift-F3".
By default, parent nodes will automatically open and close when found with the search methods, by typing the first letter, and with the "next sibling" keyboard command. This behavior can be disabled in "Tools->General Options".
The commands in the "Edit" menu (except for undo and redo) operate on the selected nodes in the left tree view. The cut, copy and paste commands can also be an exception to this, since they operate on the right view when something is selected there. And keep in mind that, in general, the descendants of the selected nodes are also affected.
Paste will add a copied node as the last child of the current node. Alternatively, the "Edit->Paste Node Text" command actually renames the selection based on the top node in the clipboard.
There are several shortcuts for use in tree editing. Drag and drop will move or copy nodes to become a children of the destination node. Clicking on a selected node will rename it. Pressing the enter key will insert a new node, and pressing the delete key will remove the selected nodes. If desired, these shortcuts can be disabled in "Tools->General Options".
In the right pane, the "Data Editor" view provides the most direct way to edit the data within a node. If the edited field is used in the title formatting, the node title in the tree will show the changes. The field editor will scroll, allowing multiple lines of text to be entered.
There are items in the "Data Editor" box context menus to add HTML font tags around selected text. These tags include bold, italics, underline, size and color. Note that the fields must be set to display HTML content (see the Field Types section, below) for this to be effective.
Also in the right pane, the "Title List" view is useful to quickly rename child titles or to add new child nodes. A text list of new nodes can even be pasted directly into this view.
There is a spell check command in the "Tools" menu. Use of this command requires an external program to be installed (see the System Requirements section). If there are any misspelled words in the selected branch, a dialog will allow the word to be ignored, added to the dictionary, replaced with a suggestion or edited. This will spell check the text in all data fields of each node.
By default, a new TreeLine document contains two node types: "ROOT" and "DEFAULT". The type is shown at the top of each node box in the "Data Editor" right-hand view. The creation of new types and the customization of types is described below. To set the selected nodes to a specific type, use the "Data->Set Item Type" menu. Alternately, to set a series of child and descendant nodes to a specific type, use the "Data->Set Descendant Types" command. The resulting dialog box allows the selected nodes, their children, all descendants, or descendants matching logical conditions to be set to the highlighted type. The dialog box can be left open while the tree selection is changed to set more nodes.
The data types are configured with the "Data->Configure Data Types" dialog. The type is selected at the top of the dialog box, and the "Modify List" button is used to add, delete and rename the available types. The left half of the configure dialog shows the fields. These are the data fields that will be in each node of this data type. There are buttons to add, delete and reorder the fields. A button to change the field type is covered later.
The right half of the Configure Data Types dialog box shows the formatting for the title (used for the node text in the tree view) and the node output. The formatting consists of text lines with embedded fields. The fields are shown as "{*field_name*}". They can be added or removed with the ">>" and "<<" keys.
References to fields from parent and grandparent nodes are shown as "{**field_name*}" and "{***field_name*}", respectively. There are also general ancestor references, shown as "{*?field_name*}", that take data from the closest ancestor with a matching field.
These references can be added with the "Other Fields" button in the field portion of the dialog. This will prompt for the parent level (any ancestor, parent, grandfather, etc.) and the ancestor's data type. Then, the ">>" keys will add the selected fields to the formatting.
The "Other Fields" dialog also contains file info references. These fields contain file meta-data, including the file name, path, size, and modified time. These are shown as "{*!field_name*}" in the title and output format editors.
When a node in the tree is renamed, the program attempts to match the title formatting pattern to set the appropriate fields. If the title formatting is too complex, it may not correctly guess your intent. Things like adjacent fields with no characters separating them should be avoided unless you do not wish to rename nodes from the tree.
If the text data used for a tree view title has multiple lines, only the first line will be used as the title.
If a line in the output formatting contains one or more fields and all of those fields for a given node are empty, the line is skipped. No blank line or embedded text will be output for that line. Note that this does not apply to a line without any fields (only embedded text). Also, when a line ending with a <br/> or an <hr/> tag is skipped, the ending tag is retained.
Simple HTML formatting tags can be used in node output formats. Commonly used tags include "<b>bold</b>", "<u>underline</u>", "line break<br/>", "<hr/>horizontal line", and various font tags. Complex block tags should generally be avoided. When the "Allow HTML rich text in formats" file option is disabled, formatting tags are treated as plain text.
A line break is automatically added after each formatting line. The "Add blank lines between nodes" file option determines whether there is also an automatic blank line between node outputs. A line break tag ("<br>") can be used at the end of the formatting to get the same effect, or a horizontal line tag ("<hr>") may be used instead to separate the nodes.
Here is an example of output formatting for a book list:
<hr/>"{*Title*}"Sample files with various kinds of formatting are included in the program distribution (see the "sample_*.trl" files in the "doc" directory).
(c) {*Copyright*}, Rating: {*Rating*}
{*PlotDescription*}
The "Configure Data Types" dialog also contains a setting for the default child type. If set, this is the initial data type that is used for new children of this type parent.
Finally, the dialog has settings for sibling prefix and suffix tags. These tags can often be left blank, but are useful for creating tables or bulleted lists. These tags will be placed before and after sibling groups of the proper type. For example, to create an output table, the sibling prefix tag could be set to "<table border="1">" and the suffix tag could be set to "</table>". Then, the output format could be set to:
<tr><td>"{*Title*}"</td><td>(c) {*Copyright*}</td></tr>Siblings should generally be of the same type, or at least have the same prefix and suffix tags.
In the "Configure Data Types" dialog, the "Field Type" button brings up a dialog for formating the selected field. The field type may be set to text, long text, choice, combination, boolean, number, date, time, URL, path, email, or picture. Prefix and suffix text can be entered and will show up whenever the data is not blank.
There are also settings for text content handling that can be set to allow HTML rich text in the field data or to preserve line breaks (ignoring HTML code). If HTML rich text is used, carriage returns are ignored and non-escaped "<", ">" and "&" symbols do not display. There is also a general option available that makes new fields default to HTML content.
Several of the field types use a formatting string to define their output. For a list of available formatting characters, use the "Format Help" button. Entries in the data editor which do not match the format will cause the field name label to show in bold, and the output for that field will be replaced by "#####".
The long text field is the same as a normal text field except that it uses a multi-line data editor field by default. The normal text field only uses a multi-line editor if there are already multiple lines in the data. The general option "Max lines in data edit box" can be used to change the default length.
The choice and combination field types allow for the selection of text items from a pull-down edit list. The formatting strings for these types list the items separated with the "/" character (use "//" to get a literal "/" in an item). Choice is used to select a single item and combination to select multiple items. The pull-down edit list for combination allows items to be added or removed. Also, the initial text of an item can be typed and auto-completed.
The boolean field type is similar to choice, but defaults to options such as "True/False", "yes/no" and "1/0".
In the number, date, and time field types, special characters in the formats are replaced by elements of the data. There are also formats for these types under "Tools->General Options->Data Editor Formats". These control how these fields are displayed in the Data Editor view. Generally, entries in the data editor with various formats will be correctly interpreted regardless of this setting. Entries which cannot be interpreted will cause the field name to show in bold.
The number field type uses a string of "#" (optional digit) and "0" (required digit) characters to define the output formatting. For example, pi formatted with "x.x" is "3.1" and formatted with "00.00" is "03.14". Regardless of the formatting, digits to the left of the decimal point are not truncated, since that would display an incorrect result.
The date and time field types are similar to the number field. See "Format Help" for formatting details. One exception is the "Data Editor Format" for dates, which does not support days of the week. Also, dates entered in the Data Editor must use the correct day-month-year sequence defined in the "Data Editor Format".
The URL, path, and email field types are used to create a links in the output. URL is for a standard web link (defaults to http:// unless otherwise specified), path is for a local file link (defaults to file:///), and email is for a mail link (defaults to mailto:). When clicked in the output window. these links open an external browser or email program. In exported HTML, they act as regular links. Simply enter the desired full path (such as "www.bellz.org/treeline/index.html") in the data editor. In Linux, setting the "BROWSER" environment variable to a string like "mozilla %s" will result in the desired browser being used.
The picture field type will show a referenced picture in the output. Enter the full path to a local image file in the data editor. For Qt2 (used on windows builds) the output window only supports GIF and PNG image formats. For Qt3, JPEG and other image types are supported. Of course, when exporting HTML, the picture will show as long as the browser supports the format.
The "Data" menu contains commands for arranging and flattening the data by category and by reference. These methods are used to automatically add and remove levels of nodes below the current node in the tree.
The "Add Category Level" command allows you to select one or more of the fields that the child nodes have in common. These fields are used to create new parent nodes for the children, grouping them by common categories. For example, in a list of books, picking the "author_first_name" and "author_last_name" fields will result in a tree with the books under new nodes for each unique author.
The "Flatten by Category" command is almost the opposite of "Add Category Level". It eliminates any descendant nodes with children, transferring their data fields to their children. It will rename fields instead of overwriting data with the same field names, but this command is most useful when the children and parents are different types with unique field names.
The "Arrange by Reference" and "Flatten by Reference" commands arrange data nodes by using pointers to the value of their parent's first data field. These commands rely on nodes having unique values in the first data field, such as an ID number. The "Flatten by Reference" command adds a field containing the parent's ID to each descendant node. It then places all of the nodes under the selected root node. The "Arrange by Reference" command does the opposite, placing each node under the parent with the referenced ID. If there are multiple nodes with the same ID, the nearest node above the child is chosen. Any nodes with lost parents are placed directly under the selected root node.
The "Update by Reference" command uses a separate file to update the values of missing fields. Unique values are matched in the first data field. Any fields in the reference nodes but not in the original node are added. Fields may be deleted in the original file to force the update, since the field must be missing (not just blank).
The "Data" menu also contains the "Sort Node Children", "Sort Type in Branch" and "Sort Branch by Title" commands. The first two allow the selection of several fields to be used as the first key, second key, etc. The keys are selected in order with the left mouse button and the direction is changed with the center mouse button. The "Sort Node Children" command sorts the children of the selection only, while the "Sort Type in Branch" command sorts all descendants of a given type. The "Sort Full Branch" command will sort all descendants, but sorts only by the node title text, not by particular keys.
The "Filter Data" command allows the removal of nodes based on user-defined rules. If there is more than one data type in the selection's descendants, the type to be filtered is selected. Next, logical rules may be entered based on any of the type's fields. Multiple rules can be linked by the "and" and "or" operators (press the "Add Rule" button). Rules with their operator set to "None" are ignored. Any descendant nodes of the given type that don't match the rules will be deleted (including their children). The current filename will have "_filter" added to avoid overwriting the full document. If the document was already modified, there will be a prompt allowing the unfiltered file to be saved. Once done, there is no way to undo the filtering.
The "Numbering" command is used to add number fields to descendant nodes. The number fields do not automatically update when the tree is modified - the "Numbering" command must be repeated. In the dialog, a new or existing field name is entered, and the root (selected) node may be included in the numbering if desired. One of three styles may be chosen: outline style restarts numbering for each group of children, section style appends the child's number onto the parent's number, and single level style numbers only the first level of children. The default formats can be used ("I, II..., A, B..., 1, 2..." for outlines; "1, 2..., 1.1, 1.2..." for sections), or custom formats may be specified for each level. The custom formats should contain one of the following characters: "1", "A", "a", "I", or "i". The series will continue from there (using numbers, letters or Roman numerals, respectively). The last occurrence of one of these characters in the format string is used - previous ones are assumed to be part of the format.
Finally, the "Change Selected Data" command allows the values of a data field to be changed simultaneously for all selected nodes. Simply select the desired field and enter the new value.
The "Data Output" right hand views show the formatted output text for the current node and its children. The formatted output can be printed. When printing, starting from the current node, the node's descendants are shown with the children indented. The root node can be included or excluded, and items with closed parents in the tree can be skipped. Also, the number of columns in the output can be specified.
There are also options in the "Print Options" dialog box for setting printer fonts, for setting margin sizes, and for adding tree structure lines. The tree structure lines are drawn to connect parent and child nodes. They can make parent/child relationships easier to visualize, especially across multiple pages. The lines may not display as desired when using some HTML formatting tags.
A preview will be shown before printing (but after hitting 'OK' on the normal print dialog box) by default. The print preview will show more detail if its window is made larger.
Some printing problems, especially problems with margins and word-wrapping, can be eliminated by changing the print font to a font that is better supported by the printer.
A TreeLine file is in an XML text format. There are also options to work with compressed files (gzip format) to save space. Individual files can be set to compressed mode from either "Tools->File Options" or from the save-as dialog. There is also a general option to set the default mode for new files.
An auto-save feature can store unsaved files with a "~" appended to the file name. The backup files are automatically removed when the file is saved or TreeLine exits cleanly. The auto-save time interval is set in the general options. Setting the interval to zero disables this feature.
When opening a recently used file, TreeLine will restore the states of open and selected nodes. This information is stored in the user's TreeLine configuration file. If desired, this feature can be disabled with a general option.
Command line options allow non-interactive file importing and exporting. This allows automated runs to be scheduled. For more details, run "treeline -h" from the command line. If using a windows binary, output is supressed, so it must be directed to a log file ("treeline -h > log.txt").
A TreeLine file is in an XML text format. Other types of text files can be imported simply by opening them. Opening a file that is not valid TreeLine XML will result in a prompt for the type of import desired.
TreeLine will open a text file with a tree structure represented by tabs before each line. In this case, only the node title is imported, without any extra fields. This method is used to open files from old versions of TreeLine.
A tab-delimited table can also be imported. It becomes a single level of children under the root node, with each node containing fields from each table column. The first row of the table is used as field names and each row thereafter becomes a node.
There are two types of plain text import. One creates a separate node for each line in the file. The other creates a node for each paragraph, assuming the paragraphs are separated by blank lines. In both cases, the resulting TreeLine file will have all of the text under a single parent, but it is a good starting point. Additional structure can be added later.
There is also a filter to import files from the Treepad shareware program. Only Treepad text nodes are supported.
Files are exported using the "File->Export" command. This will show a dialog box of available export types and options.
Single-file HTML output is similar to printing, with similar options. It can include the print header and footer in the HTML, and the number of columns can be set.
There is also a multiple-file HTML export that creates a directory structure. Directories are named for the content of the first data field, which must contain legal file names and not have duplicates under the same parent. Each HTML file is a table of data for a set of siblings, with links to the parent and child pages.
Data can be exported to tabbed title text (the old TreeLine text format) and tab-delimited tables. These formats are the same as the corresponding import formats. When exporting to a table, only the first level of children is used, so you may wish to flatten the data before exporting.
In addition to exporting data, the format for a file can be exported to an XSLT file. This can be used to display the XML data from a native TreeLine file in a compliant browser without exporting the data to HTML. Only the newest browsers are XSLT compliant (Mozilla, Galeon and IE 6.x should be okay; IE 5.x is not compliant unless the MSXML3 upgrade is installed in replace mode; Konqueror is not compliant). Note that complex field type formatting will be ignored by the XSLT. A link to the XSL file is added to the TreeLine file (assuming the file is saved), so that the TreeLine file can be opened directly in a compliant browser. After that, the XSL file does not need to be re-exported for data changes (only for formatting changes).
If HTML tags are used in data formats that will be exported to XSLT, they should use xHTML style (<br /> instead of <br>). When exporting, there is a prompt for the name of an optional style sheet (css). This name is stored in the TreeLine file as the default for future exports. The reference to the XSLT file in the TreeLine file may be removed with the "Tools->Remove XSLT Reference" command.
An error message, "Error loading XML Parser", typically means that TreeLine could not find a necessary XML library. Under Linux, Python uses external libraries for parsing. Installing either the expat library or the PyXML package should fix the problem. Under Windows, Python includes a parser, so this error should not be seen unless files are missing or corrupt.
There is a problem in which the tree and output text appears with squares between each character and truncated before the end. This is generally due to a unicode problem with a certain PyQt RPMs on Red Hat systems. The solution is to upgrade to an RPM for PyQt 3.7 or higher. A sip RPM of the same version must also be installed.
Some printing problems, especially problems with margins and word-wrapping, can be eliminated by changing the print font to a font that is better supported by the printer.
I can be contacted by email at: doug101 AT bellz DOT org
I
welcome any feedback, including reports of any bugs you find. Also,
you can periodically check back to <www.bellz.org> for
any updates.