TreeLine

Version 1.2.1 (stable)

Other Programs

Contact Info

Home / News Features Screenshots Requirements Downloads Installation How to Use

How to Use TreeLine

Contents

Getting Started

Introduction

TreeLine is a more complex program than it appears at first glance. Reading much of this documentation is highly recommended in order to learn to use it effectively.

The Basics section describes views and selections. To learn how to move around and change the tree, refer to the Tree Navigation and Tree Editing sections. Next, its time to go beyond using TreeLine with only simple text for each node. To learn about setting up custom data for each node, refer to the Formatting and Node Types and the Field Types sections.

Templates

When starting a new file, the templates dialog gives a choice of nodes with a single line of text or with long text. The single line template only has a node title, while the long text options have a title and a multiple line text field in each node. For long text, you can also choose between plain text, which preserves line breaks, and HTML text, which allows more complex formatting.

There are a few more specific options, including canned setups for personal contact information a book list and a to-do list.

Example Files

Various TreeLine sample files can be opened by using the "File->Open Sample" command. They include (roughly in order of increasing complexity):

Basics

Left Pane Views

The default view in the left pane is the "Tree View". Parent nodes can be opened and closed to display or hide their indented descendant nodes.

The other tab in the left pane is the "Flat View". It displays all of the descendants of the nodes that are selected in the "Tree View" in a flat list. It also shows the results of filtering operations (see the Filtering section).

Right Pane Views

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 (see Figure 1). The "Data Editor" view shows a text edit box for each data field within a node (see Figure 2). The "Title List" view shows a list of node titles that can be modified using typical text editor methods.

When a parent node is selected in the tree, the the right view will default to showing information about the selected node in an upper pane and information about the selected node's children in the lower pane. The "View->Show Child Pane" command will toggle the display of the child nodes. If the selected node has no children, the view will show a single pane with information about the selected node only.

When multiple nodes are selected in the tree, the right view will not display any child node information. It will instead show information about every selected node.

When the "View->Show Output Descendants" command is toggled, the "Data Output" tab will show an indented list with information about every descendant of a single selected node.

The initial state of the views can be controlled by changing the startup conditions in "Tools->General Options".

By default, the number of nodes displayed simultaneously in the "Data Editor" view is limited. Buttons in a heading allow the next or previous set of nodes to be displayed. This provides a convenient way to page through the node information without slowing the program by trying to display too many fields. The number of pages to display can be set in "Tools->General Options".

Figure 1: Output Pane

Figure 2: Edit Pane

Commands

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.

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.

Tree Navigation

Keyboard Shortcuts

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 and SHIFT keys with "J" or "K" 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. The CTRL and SHIFT keys can be held with the "Page Up" and "Page Down" keys to move the tree view even when a different pane is focused.

All of these keys and the keyboard shortcuts for pull-down menu commands can be customized by using the "Tools->Set Keyboard Shortcuts" command. The shortcut editor has tabs for menu and non-menu based commands. Simply type the new key sequence with the appropriate field selected.

Another way to move through the tree is to type the first letter of a visible node title. Hitting the letter again moves to the next possibility.

Selection

Multiple nodes can be selected by holding down the CTRL or the SHIFT keys when changing the active node. Individual nodes are added or removed from the selection when the CTRL key is held. The selection of all nodes between the old and new active nodes are toggled when SHIFT is held. The active node can be changed by using the mouse or by using any of the keyboard navigation methods.

The "View->Previous Selection" and "View->Next Selection" commands can be used to toggle through a history of selections, allowing faster navigation through the tree.

By default, the selection sequence doesn't matter. However, if the general option for multiple selection is changed to "Selection Order", nodes selected with CTRL key held are output in the order selected.

Searching

There are two ways to search for nodes. These methods can find nodes that are 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 matching text will highlight in the "Data Output" pane.

The next method is an incremental search, started by typing CTRL + "/". Then type the search string, which shows up in the lower status bar area. 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".

Tree Editing

Edit Menu

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 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 nodes as the last child of the selected node. If more than one node is selected, additional copies are added under each selected node.

The "Edit->Paste Node Text" command renames the selection based on either the text in the clipboard or the title of the top node in the clipboard.

Shortcuts

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".

Right Pane Views

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) for this to be effective.

An external editor can also be invoked from a "Data Editor" box context menu. After the text editor saves changes and is closed, the changed text will be in the text box. The EDITOR environment variable can be used to specify the editor to start, or, if the variable doesn't exist, TreeLine will prompt for an executable to set as the default.

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.

Spell Check

There is a spell check command in the "Tools" menu. Use of this command requires an external program to be installed (either aspell or ispell - 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, the spell check will use dictionaries for the current operating system language. If using aspell, there is an option under "Tools->File Options" to specify an alternate two-letter language code for the current TreeLine file. Note that the appropriate aspell dictionary files must be installed and that this option does not work with ispell.

Formatting and Node Types

Setting Nodes to a Type

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.

Type List

The "Type List" is the first tab of the "Data->Configure Types Dialog". The list of data types can be modified by the buttons on the right. New types can be added, and existing types can be copied, renamed or deleted.

Type Config

"Type Config" is the second tab of the "Data->Configure Types Dialog". It contains a selection for the default child type. If set, this will be the initial type used for new children with this type of parent. If set to "[None]", children will default to either the type of their siblings or their parent.

The "Change Icon" button allows the selection of a custom tree icon for this data type. The "Clear Select" button on the icon dialog can be used to set the icon to "None", so that no icon will be displayed for this type. To avoid showing any tree icons, the "Show icons in the tree view" general option can be unset.

Field List

The "Field List" is the third tab of the "Data->Configure Types Dialog". The list of fields within a data type can be modified by using the buttons on the right. New fields can be added, and existing fields can be moved up and down in the list, renamed or deleted.

Field Config

"Field Config" is the fourth tab of the "Data->Configure Types Dialog" (see Figure 3). The field type and its output format string can be set (see the Field Types section for details). Extra prefix and suffix text to be output with the field can also be set, and a default field value for new nodes can be entered. There is a choice between plain text, which preserves line breaks, and HTML text, which allows various formatting options. Finally, the number of lines displayed in the editor for the field can be specified.

Figure 3: Field Config Tab

Output

"Output" is the last tab of the "Data->Configure Types Dialog" (see Figure 4). The left half of the dialog shows the fields. The right half 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*}". The field that is selected in the list can be added to a format at the cursor position with the ">>" keys. The format field reference at the cursor can be removed with the "<<" keys.

Figure 4: Output Tab

Title Formatting

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 the 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.

Skipped Output Lines

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.

HTML Tags

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. For an example of tag use, see the "sample_color_items" file (by using the "File->Open Sample" command).

A line break is automatically output after each formatting line, unless the "Add line breaks after each line" file option is unset. In addition, 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.

Formatting Examples

Here is an example of output formatting for a book list:

<hr/>"{*Title*}"
(c) {*Copyright*}, Rating: {*Rating*}
{*PlotDescription*}

Sample files with various kinds of formatting are included in the program distribution. They can be opened by using the "File->Open Sample" command. They are also listed in the Example Files section.

Other Field References

References to fields that are not contained within the node can be added to the output. Pushing the "Show Advanced" button on the "Output" tab of the configure dialog makes a reference level selection become visible.

If the reference level is changed to "File Info Reference", fields containing file meta-data can be added to the output. These include the file name, path, size, and modified time. These are shown as "{*!field_name*}" in the title and output format editors.

There are field references to various ancestor nodes (parents, grandparents, etc.). These require the data type of the reference to be specified. This selection determines the field names that are available, but the data from any type with a matching field name will be shown in the output. 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.

References to child nodes can also be added. These also require that the child data type be specified. The child data becomes embedded in the parent output. The child data is delimited with a separator string defined as a file option. The separator defaults to a comma and a space, but can be set to <br> or anything else.

Finally, a "Child Count" reference can be added. This field will show the number of children ("Level1" field) or grandchildren ("Level2" field) of a node. These are shown as {*#Level1*} in the format editors.

For examples of these fields, see the "sample_other_fields" file (by using the "File->Open Sample" command).

Sibling Prefix and Suffix

Pushing the "Show Advanced" button on the "Type Config" tab of the configure dialog makes a sibling text section become visible, with 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>

Also see the "sample_table_booklist" example file (by using the "File->Open Sample" command).

Siblings should generally be of the same type, or at least have the same prefix and suffix tags.

Link Reference Field

One of the fields for each type is designated as the link reference field. By default, it is the first field in the list. Pushing the "Show Advanced" button on the "Type Config" tab of the configure dialog shows the selector for this field.

The link reference field is used for internal link references and for the arrange and flatten by reference commands. The contents of this field should generally be unique if usage of these functions is planned.

Generic and Derived Types

Data types can be set to derive their field settings from a generic type. This allows types with different output formatting to always use the same set of fields. Any changes to the generic's list of fields and field types are automatically reflected in the fields of all derived types. This does not apply to a field's output formatting, which can still be set independently.

There are two methods for creating derived types. First, a derived option can be selected when copying a type on the "Type List" tab of the "Data->Configure Types Dialog". Alternately, a generic type can be specified from the derived type's "Type Config" tab of the dialog if the advanced functions are shown.

Conditional Types

Conditional expressions can be used to automatically assign a data type based on each node's content. Conditions can be assigned only to a generic type and its associated derived types. This allows the automatic assignment of different output formatting or different icons depending on each node's field data.

The conditional dialog box is accessed from a button on the "Type Config" tab of the "Data->Configure Types Dialog" if the advanced functions are shown. Each line of the condition includes a field, an operator and a comparison value (see Figure 5). The operators include equality, greater than, less than, starts with, ends with, and contains. There are also True and False operators that will toggle the type of all nodes simultaneously.

For special field types such as dates, times, and booleans, the comparison value should be entered in the same format that is used in the Data Editor window. In general, the starts with, ends with, and contains operators should not be used for these special fields, since the comparison is done using an internal data representation. Dates and times also support a special comparison value of "now", which is always interpreted as the current date and time.

The "Add New Rule" button is used to add additional condition lines. The lines can be joined with "and" or "or" operators. The "Remove Rule" button deletes the last condition line. If only a single line is present, the "Remove Rule" button completely removes the condition.

Conditions do not have to be set for all types in a family. If no conditions are true for a node, the program will select a blank condition over a false one.

For an example, see the "sample_conditional_todo" file (by using the "File->Open Sample" command).

Figure 5: Conditional Dialog

Copying Formats

Another method for changing data type formatting is to copy the formats from another TreeLine file. This is done with the "Data->Copy Types from File" command. All types from the chosen file are copied. Any types in the current file with matching names are overwritten, but types with unique names are retained.

Field Types

Field Options

The field type and options are set in the "Field Config" tab of the "Data->Configure Types Dialog" (see Figure 3). The field type may be set to text, number, choice, combination, auto choice, date, time, boolean, URL, path, internal link, executable link, unique ID, 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. For an example of rich text use, see the "sample_char_format" file (by using the "File->Open Sample" command).

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 "#####".

Text Type

The default field type is a text field. These fields are edited using edit boxes in the data editor view. The edit box height expands when redisplayed after adding several lines of text. The edit box height can also be set explicitly in the "Field Config" tab.

Choice, Combination and Boolean Types

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".

There is also an AutoChoice field type. Like Choice, it provides pull-down selection items, but it does not have a formatting string. The pull-down is automatically populated with all previously used entries.

Number Type

In the number type, special characters in the format define the display of the numbers. The format uses a string of "#" (optional digit) and "0" (required digit) characters to define the output formatting. For example, pi formatted with "#.#" 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. But use care to show enough decimal places (either optional or required) to avoid problems with round-off error.

The radix character can be specified as either "." or "," to handle internationalization. For use as a thousands separator, use "\," or "\.". For example, a large number may be formatted as "#\,###\,###.##" or as "#\.###\.###,##". Press the "Format Help" button from the field format dialog for more formatting details.

Unlike most other formats, the number type also uses the output format for display in the Data Editor. Of course, any new entry with a reasonable format is correctly interpreted (but the correct radix character must be used).

Date and Time Types

In the date, and time field types, special characters in the formats are replaced by elements of the data, similar to number fields. Press the "Format Help" button from the field format dialog for formatting details.

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, but dates must use the correct day-month-year sequence. Also note that the date editor format does not support days of the week. Entries which cannot be interpreted will cause the field name to show in bold.

A default initial field value of "Now" can be used to get a time-stamp of node creation.

Linking Types

The URL, path, and email field types are used to create 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.

There is also an internal link field type. It creates a clickable link in the Data Output window that selects the next node with matching text in its reference field. If link or reference fields contain multiple lines, each line is treated as a separate link or reference, respectively. If desired, the same field can be used as both the link and reference fields, so that clicking on a keyword in one node's field selects the next node that also has that keyword. If exported to HTML, the internal links function as links to page anchors, but, in cases with duplicate references, they only find the uppermost reference on the page instead of the next one. For an example, see the "sample_intern_links" file (by using the "File->Open Sample" command).

The ExecuteLink field type runs an external program when its link is clicked. The command to run is given by the text of the field. Or the field's prefix may contain the program name, so that the field's text is used for arguments or file names. A general option can disable these links when security is a concern.

The picture field type will show a referenced picture in the output. Enter the path to a local image file in the data editor. Supported image types include JPEG and PNG. GIF is support is optional - it may be supported depending on build options in the Qt library. Of course, when exporting HTML, the picture will show as long as the browser supports the format.

Unique ID Type

A Unique ID field type is automatically loaded with unique numbers. This is often useful for ensuring that the link reference field is always unique.

Initially, the field's format string is set to the desired first number in the series, with optional leading zeros and optional leading or trailing characters. The initial number and the extra characters are useful to avoid duplication of numbers in different files. All nodes of the data type will get an automatically assigned ID. The field format string will always show the next available number, which will be given to the next new node of that type.

Advanced Options

The "Show Advanced" button in the "Field Config" tab of the "Data->Configure Types Dialog" brings up additional settings.

Link fields can display alternate text in place of the target URL. This is done by specifying an alternate text field.

There is also a setting to flag fields as required to be filled in. Those fields will be marked with an asterisk in the data edit view.

Fields can also be set as hidden, to prevent them from showing in the data edit view.

Tree Data Manipulation

Category-based Commands

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.

Reference-based Commands

The "Arrange by Reference" and "Flatten by Reference" commands arrange data nodes by using pointers to the value of their parent's reference data field. These commands rely on nodes having unique values in the reference 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.

Sorting

The "Data->Sort" command brings up the sort dialog. It contains options for sorting the entire tree, the selected branches, the selection's children or the selection's siblings. The sorting can be based on specific fields within specified types or on titles only.

Sorting by types allows the selection of several fields to be used as the first key, second key, etc. Multiple types can be selected in the list on the left. The fields that the selected types have in common are listed on the right. The fields to be used as keys are selected in order with the left mouse button and the direction is changed with the right mouse button.

Filtering

The "Data->Conditional Filter" command limits the display of nodes in the flat view based on user-defined rules. First, the type to be filtered is selected. Next, logical rules may be entered based on any of the type's fields (similar to Figure 5). Multiple rules can be linked by the "and" and "or" operators (press the "Add Rule" button). The "True" rule can be used to show all of the nodes of a given type. Only descendant nodes that match the rules will be shown in the "Flat View" pane. The filtering stays in effect for the "Flat View" pane until it is cleared using the "Data->Clear Filtering" command (see Figure 6).

The "Data->Text Filter" command works similarly, except it only prompts for a text search string. Only the nodes that have a match for that string somewhere in their field data are displayed in the "Flat View". Again, the filtering stays in effect for the "Flat View" pane until it is cleared using the "Data->Clear Filtering" command.

Figure 6: Filter Results

Numbering

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.

Change Selections

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. To erase field values, enter a character then delete it - this will indicate that a blank field is desired.

Printing

Print Options

The "File->Print Options dialog's first tab is "General Options". On the left, printing of the entire tree, the selected branches (all descendants) or the selected nodes can be selected. The first two options print all of the descendants with the children indented.

On the right are options for drawing tree structure lines, including the root node, including only open children and keeping the first child with its parent. 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.

By default, TreeLine will avoid breaking pages between a parent and its first child. This behavior can be disabled by disabling the "Keep first child with parent" option.

Page Setup

The second tab of the "Print Options" dialog box is "Page Setup". On the left are settings for page size, orientation and units. On the right are settings for columns, indent offsets, and margins.

Printer Font

The third tab of the "Print Options" dialog box is "Font Selection". The printout will use the same font as the "Data Output" pane if the upper check box is checked. If it is unchecked, a font can be selected specifically for printing.

Header and Footer

The third tab on the "Print Options" dialog is used to set the print header and footer. There are file info fields on the left and six header/footer edit boxes (left, center and right justified) on the right. These fields can be added and combined with other text in the edit boxes, just like in the "Output" tab of the "Data->Configure Data Types" dialog. The header and footer settings are saved with the TreeLine file.

Print Preview

The print preview window can be shown by using the "File->Print Preview" menu or with the button on the "Print Options" dialog. Buttons on the window are used to navigate between pages, open the "Print Options" dialog, or open the print dialog. The print preview will show more detail if its window is made larger.

Printing Problems

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.

File Handling

File Compression

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.

File Encryption

There is a file encryption option to password protect TreeLine files. Individual files can be set to encrypted mode from either "Tools->File Options" or from the save-as dialog. There is also a general option to set the default for new files. The encryption uses the SHA hash function as a stream cipher - it should be fairly secure.

Auto-Save

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.

Saved Tree States

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

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.

File Import

General Information

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.

Delimited Text

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.

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 subsequent row becomes a node.

Plain Text

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.

Treepad Files

There is also a filter to import files from the Treepad shareware program. Only Treepad text nodes are supported.

Bookmark Files

TreeLine will import bookmark files in both the Mozilla HTML format (Mozilla, Firefox and Netscape browsers) and the XBEL format (Konqueror, Galeon and Elinks browsers). Each bookmark becomes a node with a name and a link field. Some information in the files, such as visited dates and icon references, is not imported. For an example, see the "sample_bookmarks" file (by using the "File->Open Sample" command).

Generic XML

TreeLine will import and export generic XML files. These routines do not have much intelligence - each XML element becomes a node and each XML attribute becomes a field. XML text content become fields named "Element_Data". This lets TreeLine function as a crude XML editor.

ODF Text Document

TreeLine will import Open Document Format (ODF) text documents, from applications such as OpenOffice.org and KWord. The node structure is formed based on the heading styles assigned in the document. Any text under each heading is assigned to that heading's node. The import filter is intended for simple text outlines only. No formatting is maintained, and objects such as tables and pictures are not imported.

File Export

General Information

Files are exported using the "File->Export" command. This will show a dialog box of available export types and options.

HTML

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 reference 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.

Delimited Text

Data can be exported to tabbed title text 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.

Bookmark Files

TreeLine will export bookmark files in both the Mozilla HTML format (Mozilla, Firefox and Netscape browsers) and the XBEL format (Konqueror, Galeon and Elinks browsers).

Generic XML

TreeLine will import and export generic XML files. These routines do not have much intelligence - each node becomes an XML element and each field becomes an XML attribute, except for fields named "Element_Data" that become the element's text. This lets TreeLine function as a crude XML editor.

XSLT

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. Recent versions of most browsers are XSLT compliant. Note that complex field type formatting will be ignored by the XSLT.

When exporting to XSLT, a link to the XSL file is added to the TreeLine file. Note that the TreeLine file must then be saved. In general, the TreeLine file should have a .xml extension 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. Also, the reference to the XSLT file in the TreeLine file may be removed with the "Tools->Remove XSLT Reference" command.

ODF Text Document

TreeLine will export an outline to an Open Document Format (ODF) text document, compatible with OpenOffice.org and KWord. The title of each node is assigned a heading style at the appropriate level. Any other text in the output of each node becomes normal text under the heading. The export filter is intended for simple text outlines only. Any HTML formatting is stripped, and objects such as tables and pictures are not supported.

Customizations

Options

TreeLine's behavior can be modified with several settings available in "Tools->General Options". Most of these options are covered elsewhere in this document.

Fonts

Fonts used in the tree views, the output view and the editor views can be set in the "Tools->Set Fonts" menu.

Keyboard Shortcuts

Keyboard shortcuts can be customized by using the "Tools->Set Keyboard Shortcuts" command. The shortcut editor has tabs for menu and non-menu based commands. Simply type the new key sequence with the appropriate field selected.

Toolbars

An editor to customize the toolbars is available from "Tools->Customize Toolbars". The number of toolbars can be set and the buttons on each can be defined.

Colors

User interface colors can be set using the last three items in the "Tools menu. If the "Use Default System Colors" command is enabled, the user background and text color settings are overridden.

Tree Icons

There is an icons directory in the user configuration directory ("~/.treeline-1.x/icons" on Linux, "Documents and Settings\<user>\Application Data\bellz\treeline-1.x\icons" on Windows). Image files (PNG or BMP) placed into this directory are available for use as tree icons.

Plugins

Description

TreeLine has an interface to plugin extension modules. This allows extensions to be written by various coders that provide functionality needed by a few users without adding bloat to the main application. The plugins can add new menu items, access the TreeLine data and read and write TreeLine Files.

Currently available plugins are listed on the "Downloads" page of the TreeLine web site.

Installation

The plugins are installed by copying their Python file (*.py) to a plugins directory. This can be a directory in the TreeLine installation ("<prefix>/lib/treeline/plugins/" on Linux or "TreeLine\lib\plugins\" on Windows) or in the user configuration directory ("~/.treeline-1.x/plugins/" on Linux, "Documents and Settings\<user>\Application Data\bellz\treeline-1.x\plugins\" on Windows). A list of loaded plugins can be found using the "Help->About Plugins" command.

Interface

Information about writing new plugins can be found in the "plugininterface.py" file in the TreeLine source code.

Common Problems

Closed Panes

If one of the view panes is not visible when it should contain data, it has probably been collapsed to a size of zero. This can apply to the left pane and to the upper and lower right panes. To fix this, look for a thin stripe along one of the view borders that can be dragged back into its proper position.

XML Error

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.

Printing

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.