12. Configuration and customization

12. Configuration and customization
Prev		Next

12.1. Colors
12.2. Other options affecting tree appearence
12.3. GUI options
12.4. Fonts
12.5. Printing options
12.6. I/O related options
12.7. Miscelaneous options
12.8. Debugging options

The configuration and customization of TrEd is possible through modifying its configuration file. At the start of a session, TrEd searches for its configuration file on several places and uses the first configuraton file found:

First TrEd looks for a file given with a command-line parameter -c (see Section 13, “Command-line options” for details).
If the HOME system variable is set (on UNIX/Linux this variable points to user's home directory) TrEd searches for .tredrc (mind the dot here) file in that directory. On Windows, TrEd uses the Application Data folder in user's profile.
If the TREDHOME system variable is set TrEd searches for tredrc file in that directory.
TrEd looks for a tredrc file in the directory where the program file of TrEd itself is located.
TrEd looks for a tredrc file in directories ../lib/tred, ../lib/tredlib and ./tredlib/tredrc respectively, relative to the directory of the program file of TrEd.
TrEd looks for a tredrc file in the /usr/share/config/ directory.

If none of these files is found, default values for configuration options are used.

TrEd's configuration file is a plain text file with a very simple structure. It can be edited either in an external text editor (like vi, Emacs or Notepad) or directly from TrEd in a built-in editor (File->Edit Config). In both cases there is a way to update the options used by a running session of TrEd:

Use File->Reload Config menu command to make TrEd re-read the configuration file from disk.
In the TrEd's built-in configuration editor use the Save and Apply button to apply changes and save them or Apply button to apply changes withought saving them. In the latter case, all changes only apply for the current session and the configuration file is untouched. As the built-in editor re-reads the configuration file every time, all such changes are lost when the editor is closed (although they still apply). The first command also quits the configuration editor.

Note

Some configuration options only take effect after restarting TrEd.

Each line in the configuration file has the following simple form:

option_name = value

There may be any amount of white-space between the option name and value but they must be both on the same line. Any characters folowing a semi-colon (;) to the end of line are treated as a comment and hence ignored. It is possible to quote any value using either quotes or double-quotes, so that white-space and semi-colons are preserved correctly. All option names are case-insensitive.

Available configuration options may be divided into several categories:

12.1. Colors

BackgroundColor: Background color of the tree-view canvas.
BackgroundImage: This option allows specifying a background image for the canvas on which trees are displayed. At present, only GIF, XBM, XPM, BMP, JPEG, PNG and PPM/PGM files are supported.
BackgroundImageX: Horizontal offset of the background image.
BackgroundImageY: Vertical offset of the background image.
HighlightWindowColor: Color of the frame drawn around the focused view.
CurrentNodeColor: Color to draw the active node. Default is red.
NearestNodeColor: Color to highlight the nearest node to indicate the destination of a possible drop when dragging a node.
BWPrintNodeColor: Color used to fill nodes when printing in black-and-white. Defaults to white, which results in nodes with only black outline. If set to black, nodes are printed as all-black objects without a visible outline.
TextColor: Color used to display text of normal tree attributes.
TextColorShadow: Color used to display text of shadowed tree attributes.
TextColorHilite: Color used to display text of highlighted tree attributes.
TextColorXHilite: Color used to display text of extra-highlighted tree attributes. See FS-format description to learn about how to specify which attributes are shadowed, highlighted and extra-highlighted.
CustomColorname: Defines a custom color named name, which may be refered to in a stylesheet pattern with #{customname} or queried in a macro with CustomColor("name"). For more information see Section 9, “Customizing Tree Appearance: Stylesheets”. See also the AllowCustomColors option which can be used to enable or disable the actual use of the custom colors.
ActiveTextColor: Color used to flash the text of an attribute under the mouse-pointer.
BoxColor: Background color of a border drawn around the text of labels if the View->Draw boxes around edges item is checked.
CurrentBoxColor: Background color of a border drawn around the text of the active node's labels if the View->Draw boxes around labels item is checked.
HiddenBoxColor: Background color of a border drawn around the text of a hidden node's labels if the View->Draw boxes around labels and View->Show Hidden items are checked.
EdgeBoxColor: Background color of a border drawn around the text of edge labels if the View->Draw boxes around edge labels item is checked.
EdgeCurrentBoxColor: Background color of a border drawn around the text of the edge label of the active node ( if the View->Draw boxes around edge labels item is checked.
EdgeHiddenBoxColor: Background color of a border drawn around the text of a hidden node's edge labels if the View->Draw boxes around edge labels and View->Show Hidden items are checked.
LineColor: Color used to draw the lines connecting dependent nodes in a tree. Default is black.
HiddenLineColor: Color used to draw the lines connecting hidden nodes with their parents. Default is gray.
dashHiddenLines: Controls is lines connecting hidden nodes with their parents are dashed or solid. Allowed values are 0 (solid) or 1 (dashed). Default is 0.
LineArrow: One of the values “first”, “both”, “last”, may be used to make arrows to be drawn by default on one or both sides of the edge connecting the given node with its parent.
NodeColor: Color used to fill an ordinary node of the tree. Default is yellow.
NodeOutlineColor: Color used to draw the outline of an ordinary node. Default is black.
HiddenNodeColor: Color used to draw nodes marked as hidden, if shown. Default is black.

12.2. Other options affecting tree appearence

BalanceTree

If this option is set to 1, the tree will be auto-balanced, disregarding a node-ordering attribute.

SkipHiddenLevels

If the get_nodelist_hook provides an incomplete list of nodes of the tree, there may be nodes whose parent-node is not on the list. If this option is set to 1, any such a orphan node “skip levels” and appears as if it was child-node of its nearest ancestor-node that belongs to the list. This option implies SkipHiddenParents. (Note that this only affects the way a tree is drawn, it does not relate in any way to tree-navigation and tree-traversal functions). Default is 0.

SkipHiddenParents

If the get_nodelist_hook provides an incomplete list of nodes of the tree, there may be nodes whose parent-node is not on the list. If this option is set to 1, then any lines that would connect such an orphan node with its parent are instead connected to the nearest ancestor of the node that belongs to the list. The orphan node however remains on it's level in the tree (see also SkipHiddenLevels). (Note that this only affects the way a tree is drawn, it does not relate in any way to tree-navigation and tree-traversal functions). Default is 0.

HighlightWindowWidth

Width of the frame drawn around the focused view.

LineWidth

Width of the lines connecting dependent nodes in a tree.

NodeWidth

The horizontal diameter of the elipsis representing a node in a tree.

NodeHeight

The vertical diameter of the elipsis representing a node in a tree.

CurrentNodeWidth

The horizontal diameter of the elipsis representing the active node in a tree.

CurrentNodeHeight

The vertical diameter of the elipsis representing the active node in a tree.

NodeXSkip

The minimal horizontal distance between two nodes in a tree.

NodeYSkip

The minimal vertical distance between two nodes in a tree.

XMargin

Horizontal amount of space left around borders of the box surrounding the text of displayed attributes of a node.

YMargin

Horizontal amount of space left around borders of the box surrounding the text of displayed attributes of a node.

BaseXPos

The horizontal distance of the tree root (zero's node) from the right of the tree view.

BaseYPos

The vertical distance of the tree root (zero's node) from the top of the tree view.

DrawBoxes

If this option is set, TrEd starts with the View->DrawBoxes menu item checked.

DrawEdgeBoxes

If this option is set, TrEd starts with the View->Draw boxes around edge labels menu item checked.

EdgeLabelSkipAbove

Extra space left above every edge label.

EdgeLabelSkipBelow

Extra space left below every edge label.

UseAdditionalEdgeLabelSkip

This options controls whether the algorighm computing the tree-layout in TrEd should try to add a reasonable horizontal skip for the edge labels, to avoid their overlapping. Note that even with this option on, the algorithm cannot reliably ensure that. Defaults to 1.

HighlightAttributes

If this option is set, TrEd starts with the View->Highlight Attributes menu item checked.

ClearTextBackground

Choose if invisible rectangles should be drawn beneath text labels to clear the background for the text. Possible values are 0 and 1.

AllowCustomColors

This option takes one of the values 0 and 1. If set to 0, all references to custom colors in attribute patterns are ignored. It is also the default value.

ShowHidden

If this option is set, TrEd starts with the View->Show Hidden Nodes menu item checked.

HintWait

This option controls time interval that mouse pointer needs to linger over a node before the hint for the node is displayed. The value is to be given in milliseconds. See Section 9, “Customizing Tree Appearance: Stylesheets” for more information about defining the content of the hints.

ToolbarHintWait

This option controls time interval that mouse pointer needs to linger over a TrEd toolbar button (or other widget with a tool-tip) before a tool-tip is displayed. The value is to be given in milliseconds. See Section 9, “Customizing Tree Appearance: Stylesheets” for more information about defining the content of the hints.

SearchMethod

This option lets you define the default method used when searching with the Node->Find command. The default value is Exhaustive regular expression but user may use any of the following values (actually only the first letter suffices):

Regular Expression

Wildcards

Literal

Exhaustive regular expression

MacroListOrder

This option defines the default ordering of macros when View->List of available macros... menu command is used. Possible values are letters M (sort by macro menu label) and K (sort by keyboard shortcuts assigned to macros). Default value is M.

MaxDisplayedValues

This option may be used to tell TrEd how many fields should fit in one screen of a list when a dialog displaying possible (or already assigned) values for a certain attribute is displayed. (The greater the number is, the taller the dialog grows).

MaxDisplayedAttributes

This option may be used to tell TrEd how many fields should fit in one screen of the Edit Node ... and Find Node by Attributes dialog windows. (The greater the number, the taller the dialogs).

12.3. GUI options

AppName: The window title for the TrEd's main window.
AppIcon: TrEd's desktop and window icon (in XPM format).
StippleInactiveWindows: If set to 1, inactive views are covered with a semi-transparent stipple pattern. This may improve orientation if working with more than one view, but also slightly reduces the clarity of trees displayed in the inactive views. This option can also be controlled in run-time using View->Stipple Inactive Views.
VLineHeight: Initial height for the value line in lines. Default value is 2.
VLineAlign: Specifies alignment for value line. Possible values are left, center, and right.
VLineWrap: Specifies value line wrapping. Possible values are node (no wrapping), char (allow wrapping on any character boundary), and word (allow wrapping on word boundary).
VLineReverseLines: Draw wrapped value lines in reverse order (bottom-up).
VLineForeground: Foreground color of the value line.
VLineBackground: Background color of the value line.
VLineFocusForeground: Foreground color of the highlighted value corresponding to the active node.
VLineFocusBackground: Background color of the highlighted value corresponding to the active node.
HintBackground: Background color of the hints shown when mouse lingers over a node.
HintForeground: Text color of the hints shown when mouse lingers over a node.
ToolbarHintBackground: Background color of the tool-tips shown when mouse lingers over a tool-bar button or one of several other widgets.
ToolbarHintForeground: Text color of the tool-tips shown when mouse lingers over a tool-bar button or one of several other widgets.
ButtonsRelief: Style of the relief of the GUI buttons. Possible values for this option are: raised, sunken, flat, ridge, solid, and groove. Default is 'raised'.
ButtonsBorder: Width of the borders of GUI buttons. Default is 2.
MenubarRelief: Style of the relief of the GUI menu-bar. Same values as for ButtonsRelief option are possible. Default is 'raised'.
MaxMenuLines: Maximal number of User-menu lines. If more lines in the menu should appear, a submenu is created as a last item, in which the menu continues.
SortAttributes: If 1, all lists where attribute names or values are displayed are sorted alphabetically. Otherwise the order given in the FS-file header is preserved. Default value for this option is 1.
CreateMacroMenu: If this option is 1, TrEd creates a special menu Key-macros where all defined macros which are assigned a key are presented also as menu functions.
StrictMotif: If this option is 1, strict motifish look and feel is used in TrEd's GUI.
IconPath: Colon-separated (on Windows comma-separated) list of paths for tred to look for icons. Only XPM and PNG icons are supported (it is not recommended to use PNG icons on X11 with present versions of Tk804, due to a severe bug causing occasional crashes). Relative paths relate to libDir/icons directory.
LastAction: This option, automatically updated on exit, contains an URL and position of a last action on a tree.
Geometry: TrEd's main window geometry (HxW[+-]x[+-]y, where H is window's height, W is window's width, x is window's horizontal position from the left if positive and from the right if negative, and y is window's vertical position from the top of the screen if positive and from the bottom of the screen if negative). This option is automatically updated every time TrEd's main window is closed.

12.4. Fonts

Font

Font used to display the text of attributes and also in several other places of GUI where the text of attributes is displayed or edited. There are two possible formats of values for this option:

Standard X font-spec, with possible wildcards, e.g.: -*-helvetica-medium-r-normal-*-12-*-*-*-*-*-iso8859-2
Font attribute-oriented format, which is a comma-separated list of pairs of the form font-attribute:value. The attributes are: family, size, weight, slant, underline, overstrike. Family is a font-family name like Arial, Helvetica or Times New Roman. Size is a number providing the font-size in points (i.e. not pixels!). Possible values for bold are normal and bold, possible values for slant are roman and italics. The underline and overstrike attributes take just boolean values of 1 and 0. If a font, that would match the specified attributes exactly, is not found, the most similar font is used.
Example
Font = family:Arial,size:10,weight:bold

On XFT enabled Tk/X11, it is also possible to use font patterns as specified by the fontconfig library. These font patterns take the form:

<families>-<point sizes>:<name1>=<values1>:<name2>=<values2>...

Where names and values refer to the folowing table:

Name of a property	Value type	Description
`family`	String	Font family name
`style`	String	Font style. Overrides weight and slant
`slant`	Int	Italic, oblique or roman
`weight`	Int	Light, medium, demibold, bold or black
`size`	Double	Point size
`aspect`	Double	Stretches glyphs horizontally before hinting
`pixelsize`	Double	Pixel size
`spacing`	Int	Proportional, monospace or charcell
`foundry`	String	Font foundry name
`antialias`	Bool	Whether glyphs can be antialiased
`hinting`	Bool	Whether the rasterizer should use hinting
`verticallayout`	Bool	Use vertical layout
`autohint`	Bool	Use autohinter instead of normal hinter
`globaladvance`	Bool	Use font global advance data
`file`	String	The filename holding the font
`index`	Int	The index of the font within the file
`ftface`	FT_Face	Use the specified FreeType face object
`rasterizer`	String	Which rasterizer is in use
`outline`	Bool	Whether the glyphs are outlines
`scalable`	Bool	Whether glyphs can be scaled
`scale`	Double	Scale factor for point->pixel conversions
`dpi`	Double	Target dots per inch
`rgba`	Int	unknown, rgb, bgr, vrgb, vbgr, none - subpixel geometry
`minspace`	Bool	Eliminate leading from line spacing
`charset`	CharSet	Unicode chars encoded by the font
`lang`	String	List of RFC-3066-style languages this font supports

Example

Font = Times-12:bold:slant=italic:antialias=0

VLineFont

Font used for displaying the text in the value line above tree. The same formats as for Font are allowed for this option. If not specified, Font is used.

12.5. Printing options

DefaultPrintCommand: Command used to pass the resulting PostScript to the print spool. Default value is lpr in UNIX systems and prfile32.exe /- on Windows (prfile32.exe is a freeware Windows printing utility available at http://www.lerup.com/printfile/).
TTFont: Name of the TrueType font to be used when printing into Portable Document Format (PDF). Defaults to Arial.
TTFontPath: A comma-separated list of directories to look into for TrueType fonts. If this option is not explicitly specified, TrEd uses directories listed in fontconfig library configuration file /etc/fonts/fonts.conf on Unix and Windows system font directory on Windows.
PsFontFile: A pfa-file with a Type1 PostScript font to be used for PostScript or EPS generation.
PsFontAFMFile: An afm-file containing the Type1 font metrics to be used for PostScript or EPS generation. It is not necessary to specify this option if the metrics file name can be derived from the PsFontFile by substitution the extension for .afm.
PrintColors: If 0, TrEd prints in black and white. If 1, TrEd uses the same colors for printing as it does for displaying the tree on the screen. This option may be overriden by the Use Colors check-box in the Print dialog.
PsFontSize: Size of the Postscript font to be substituted by the font given in PsFontFile in the final PosctScript.
PrtFmtWidth: Width of the paper used for printing. Append one of the characters i,c,m to the number to destinguish the dimension (inches, centimeters, milimeters respectively). This option only applies if PSMedia is set to User (see below).
PrtFmtHeight: Width of the paper used for printing. Same format as PrtFmtWidth. This option only applies if PSMedia is set to User (see below).
PSMedia: A PostScript or PDF document media-type used to calculate page width and height. The default value is A4. If this option is set to BBox, then the generated page has the dimensions of a minimal bounding box around the tree. If this options set to User, then the values of PrtFmtHeight and PrtFmtWidth described above are used. The supported media types beside User and BBox are: Letter, LetterSmall, Legal, Statement, Tabloid, Ledger, Folio, Quarto, 7x9, 9x11, 9x12, 10x13, 10x14, Executive, A0, A1, A2, A3, A4, A4Small, A5, A6, A7, A8, A9, A10, B0, B1, B2, B3, B4, B5, B6, B7, B8, B9, B10, ISOB0, ISOB1, ISOB2, ISOB3, ISOB4, ISOB5, ISOB6, ISOB7, ISOB8, ISOB9, ISOB10, C0, C1, C2, C3, C4, C5, C6, C7.
PSFile: The default name of the output file when printed to file. This name may be modified in the Print dialog.
MaximizePrintSize: If this option is on (i.e. 1), TrEd tryes to draw the tree as big as to fill the whole paper. Default is 0 here.
PrtHMargin: Specifies the default horizontal print margin. Default is 2c (c = centimeters).
PrtVMargin: Specifies the default vertical print margin. Default is 3c (c = centimeters).
ImageMagickConvert: Path to ImageMagick's convert command which is used to convert resulting EPS to various image formats. The default value is convert which means TrEd expects the command to be installed in some directory in PATH.

12.6. I/O related options

IOBackends: This option can be used to provide additional (user-defined) I/O backends (see Section 15, “I/O backends”). It consists of a comma separated list of Perl module names implementing the backends. TrEd will try to open a file using the backends defined here before trying any of default I/O backends.
ResourcePath: This option can contain a (colon-separated on UNIX, comma-separated on Windows) list of directories where TrEd, it's I/O backends and macros should look for additional resources they might need (such as DTDs, XML/PML schemata, XSLT stylesheets, etc.).
AutoSave: Time interval in minutes in which TrEd creates auto-save file. AutoSave=0 disables auto-saving. Defaults to 5.
LockFiles: When a file is open, TrEd creates a lock file to prevent other TrEd instances accessing the same file. If set to 0, this option disables this behaviour.
ReloadPreservesPatterns: This option may be set to 0 to force the Reload function to use the file's attribute pattern setting rather than preserving the current one.
defaultFileEncoding: The encoding used for files opened in TrEd. If TrEd runs on Perl 5.8 or higher with Tk804 or higher with Unicode support, arbitrary encoding supported by Perl can be used. In all other cases, only 8-bit encodings are supported and it is necessary to setup the display font for correct displaying.
defaultDisplayEncoding: This option may be used in TrEd running on non-unicode aware Perl and Tk (see above) if the file encoding differs from the encoding used by the display font. In such case, TrEd supports conversions between iso-8859-2 and windows-1250 for Eastern European languages and iso-8859-6 and windows-1256 for Arabic.
OpenFileNameCommand: This option may be used to provide a custom command for displaying Open File dialogs. In the command specification, %t is replaced with the dialog title, %m with a list of file-types (patterns), %t with the initial filename (only for save dialogs, see the SaveFileNameCommand option below), and %d with the initial directory. For example, setting this option to kdialog --title %t --getopenfilename %d %m in a KDE 3.3.x environment makes TrEd use the default KDE Open File dialog. This option is unused by default.
SaveFileNameCommand: This option may be used to provide a custom command for displaying Save File dialogs. See the SaveFileNameCommand option above for more detail. For example, setting this option to kdialog --title %t --getopenfilename %d%f %m in a KDE 3.3.x environment makes TrEd use the default KDE Open File dialog. This option is unused by default.
sgmls: This option may be used to point TrEd to the nsgmls SGML parser.
SgmlsOpts: This option may be used to provide additional parameters to the SGML parser declared in Sgmls option. By default, this option is set to -i preserve.gen.entities. These parameters forces James Clark's nsgmls parser to include a part of CSTS DTD where all global entities are re-declared in such a way that they expand to themselves literally and thus are preserved (as if no expansion was done).
CstsParserCommand: This option may be used to customize the command used by CSTS backend to invoke SGML parser. The default value is %s %o %d %f. In this string, the %s substring is replaced with the value of Sgmls option, %o is replaced with the value of SgmlsOpts option, %d is replaced with the value of CSTSDoctype option, and %f is replaced with the filename. The only requirement is that this command returns a valid representation of the CSTS file in ESIS format on standard output.
CstsParserZCommand: This option may be used to customize the command used by CSTS backend to invoke SGML parser for files compressed with GNU GZip. The default value is %z < %f | %s %o %d -. In this string, the %z substring is replaced with the value of zcat option. See CstsParserCommand for more.
CSTSDoctype: This option should point to a file containing CSTS doctype declaration combining both the SGML subset declaration as well as the CSTS DTD. This file is included in the distribution of TrEd and is by default stored in TrEd's library directory as csts.doctype. Setting this option overrides this default.
gzip: This option may be used to point TrEd to a GNU gzip command, which is used for transparent saving files commpressed by GNU gzip. The default value is /bin/gzip -c if /bin/gzip exists and is executable. Otherwise the value is undefined and TrEd does not support transparent saving GNU-zipped files.
gzipopts: This option may provide additional command-line arguments for the gzip command.
zcat: This option may be used to point TrEd to a GNU zcat command, which is used for transparent opening files commpressed by GNU gzip. (These files are recognized by the .gz suffix.) The default value is /bin/zcat if /bin/zcat exists and is executable. Otherwise the value of gzip option is used.
zcatopts: This option may provide additional command-line arguments for the zcat command.
ssh: This option can be used to point TrEd to ssh command, which (depending on setup) may be used for transparent secure remote file-transfer.
sshopts: This option may provide additional command-line arguments for the ssh command.
curl: This option can be used to point TrEd to the program curl, which (depending on setup) may be used for transparent file-transfer over ftp and http.
curlopts: This option may provide additional command-line arguments for the curl command.
kioclient: This option can be used to point TrEd to the program kioclient (part of recent KDE distribution) which (depending on setup) may be used for transparent file-transfer over ftp://, http://, fish:// (ssh), and various other protocols.
kioclientopts: This option may provide additional command-line arguments for the kioclient command.
NoLockProtocols: This option may provide regular expression matching protocols for which lock-files should never be created. By default, it's value is set to ^(https?|zip|tar)$.
RejectProtocols: This option may provide regular expression matching protocols from which TrEd should never attempted to fetch files. .

12.7. Miscelaneous options

LibDir: This option forces TrEd to search for its library files in the specified directory.
PerlLib: This option may contain a colon-separated (on Windows comma-separated) list of additional directories where Perl modules are located (this has similar effect as setting the environment variable PERLLIB).
MacroFile: Path to a file with macros for TrEd.
DefaultMacroFile: Path to a file with the default set of macros for TrEd.
MaxUndo: Maximum number of operations stored by Undo/Redo functions.
NoConvertWarning: When a ImageMagick printing extension is used on Windows or with a black-listed version of ImageMagick, a warning dialog pops-up. This option can be set to 1 to disable this behaviour.
ReverseNodeOrder: Draw nodes (and value line values) in reverse order.
UseLocales: If 1 is set here, TrEd uses locales. This is especially useful in macros e.g. for sorting. LC_CTYPE locale settings may also affect keyboard input and other charset-related stuff in the GUI.
UseCzechLocales: If 1 is set here, TrEd uses Czech (cs_CZ) locales. This option is present for rather historical reasons.
displayNonAsciiLeftToRight: This option adds a poor-man's bidi-support. It reverses all non ASCII-strings before displaying. This option is not intended for Arabic, since TrEd already contains better arab-remixing algorigthms contributed by Ota Smrz.
defaultMacroEncoding: The default encoding used when parsing TrEd macros. This option only takes effect for Perl 5.8 or higher. Default macro encoding can be overriden in the macro itself as described in Section 14.3, “Using various character encodings”. Defaults to UTF-8.
displayStatusLine: Turn on/off displaying status line. Default is on. Currently, status line content can only be controlled from macros, via get_status_line_hook.

12.8. Debugging options

backenddebug: Print debugging information for I/O backends.
hookdebug: Print debugging information when hooks are called.
keyboarddebug: Print debugging on keyboard events.
macrodebug: Print debugging when macros are invoked.
treddebug: Print various debugging information not covered by the debugging options listed above.

Prev		Next
11. Using File-Lists	Home \| ToC	13. Command-line options