----------------------------------------------------------------------
Preferences

Last update: 24 July 1998

Confluent Technical Notes
Copyright (c) 1995-98 Confluent, Inc.  All rights reserved.
Suggestions or questions to 415-764-1000 or vthought@confluent.com.
----------------------------------------------------------------------

This technical note describes Visual Thought preferences.  Preferences
are settings that affect Visual Thought behavior, and that are
persistent across Visual Thought invocations.


Preference Summary
------------------
Visual Thought supports the following preferences:

  Preference Name      Description
  ---------------      -------------------------------------------------
  AutoConnect          Connection ends attach to objects
  BorderSize           Window border size in pixels
  ColorPSImages        Color PostScript commands are used for image output
  CreateConnect        Dragged palette shapes are connected to selected objects
  CreateNewDocument    A new document is created during startup
  DebugDefinitions     Alert notices are displayed during shape def parsing
  DeleteConnect        Connections to a shape are joined when shape is deleted
  DropSplit            Dragged palette shapes split an underlying connection
  EncodingLatin1       Support 8-bit multinational ISO-8859-1 characters
  ExportHandles        Selection handles are included when exporting images
  FontSize             Font size used to display text in dialogs
  NoIconTitles         Titles are not drawn in window icons
  InformTranslators    Messages generated for unavailable translator commands
  LimitToScreen        Windows resized and moved to display entirely on-screen
  LineFeedTermination  Lines in output text files terminated with line feeds
  Monochrome           Display only black and white on monochrome monitors
  Openwindows          Use border sizes for Sun Openwindows look-and-feel
  Personality          The "personality" customizing the startup interface
  PrintCommand         The command used to print on UNIX
  RaiseOnDrop          A View is focused when palette objects are dropped on it
  SaveAsDirectory      Documents are saved as directories instead of files
  ScreenHeight         Artificially set the root window height
  ScreenWidth          Artificially set the root window width
  ShortSuffixes        3-character suffixes are used for saving documents
  NoSoundAlert         Disable alert for unavailable audio control device
  TitleHeight          Window title bar height in pixels
  WMFCurveApprox       Curves are approximated with polygons in WMF output
  WMFCurveResolution   The level of approximation when using WMFCurveApprox
  NoXColormap          Disable creation of color palettes from system colormap

The following preferences can only be specified on the command line:

  Command Line         Description
  ------------         -------------------------------------------------
  background           Background color used to draw dialogs
  font                 Font family used to display text in dialogs
  foreground           Foreground color used to draw dialogs
  laf                  Look-and-feel used for interface appearance and behavior

The available preferences are described in more detail in the section
"Preference Descriptions" below.

Each preference has a form that must be used on the command line.
Preferences can be either booleans (YES or NO), integers, decimal
numbers, or strings.  Numeric preferences must fall between the
allowed minimum and maximum values.  Most preferences have default
values.  This information is presented in the table below.

  Preference Name      Command line        DS  Type     Default  Min/Max
  ---------------      ------------        --  ----     -------  -------
  AutoConnect          autoconnect         D   bool     YES
  BorderSize           bordersize              int      -1       -1/100
  ColorPSImages        colorpsimages       D   bool     NO
  CreateConnect        createconnect       D   bool     NO
  CreateNewDocument    createnewdocument   DS  bool     YES
  DebugDefinitions     debugdefinitions    D   bool     NO
  DeleteConnect        deleteconnect       D   bool     NO
  DropSplit            dropsplit           D   bool     NO
  EncodingLatin1       encodinglatin1      D   bool     NO
  ExportHandles        exporthandles        S  bool     NO
  FontSize             fontsize             S  decimal  12,11    5.9/24
  NoIconTitles         noicontitles            bool     NO
  InformTranslators    informtranslators   D   bool     NO
  LimitToScreen        limittoscreen       D   bool     YES
  LineFeedTermination  lflineterm          D   bool     NO
  Monochrome           monochrome           S  bool     NO
  Openwindows          openwindows             bool     NO
  Personality          personality         DS  string
  PrintCommand         printcmd            D   string   lpr
  RaiseOnDrop          raiseondrop         D   bool     NO
  SaveAsDirectory      saveasdirectory     D   bool     NO
  ScreenHeight         screenheight            int      99       99/9999
  ScreenWidth          screenwidth             int      99       99/9999
  ShortSuffixes        shortsuffixes       D   bool     NO
  NoSoundAlert         nosoundalert        DS  bool     NO
  TitleHeight          titleheight             int      -1       -1/100
  WMFCurveApprox       wmfcurveapprox      D   bool     NO
  WMFCurveResolution   wmfcurveresolution  D   int      0        0/100
  NoXColormap          noxcolormap             bool     NO
                       background           S  string   gray80
                       font                 S  string   family:helvetica
                       foreground           S  string   black
                       laf                  S  string   motif,windows,win95

  D => available in the Preferences dialog
  S => only effective at startup

Preferences marked with a "D" above are available in the Preferences
dialog.

Preferences marked with an "S" can take effect only when Visual
Thought starts up.  For example, after changing these preferences in
the Preferences dialog, you need to restart Visual Thought for the
preferences to take effect.


How to Specify Preferences
--------------------------
Preferences can be specified in any of the following three ways:

 1. Use the Preferences dialog, opened with the
    Options->Preferences... menu item

 2. Edit the Preferences files

 3. Specify on the command line

The easiest way to set preferences is with the Preferences dialog, but
systems administrators and advanced users may occasionally want to
edit Preferences files or specify preferences on the command line.

Each method is described in more detail below.


Specifying Preferences with the Preferences Dialog
--------------------------------------------------
To change preferences with the Preferences dialog, run Visual Thought
and select the Options->Preferences... menu item.  The resulting
dialog that is displayed contains most of the preferences defined in
Visual Thought.

To set boolean preferences, just click on the appropriate checkboxes.
To set numeric or string preferences, type into the appropriate fields
and then press Tab (important!) to tell Visual Thought to accept your
entry.

Visual Thought's Preferences dialog is different from those of most
other applications in two significant ways.

First, preference changes take effect immediately.  For example, when
you click a checkbox, the preference is activated (or deactivated)
immediately and the setting is saved in the user Preferences file.
This means you don't have to press any OK or Apply buttons.

Second, the Preference dialog itself is non-modal.  That is, you can
perform other work in other Visual Thought windows while keeping the
Preference dialog displayed.

These differences make it quite a bit faster for you to work with
Preferences.  For example, sometimes in the same drawing you want
connections to attach to shapes (when you draw diagrams) and sometimes
you don't (when you want to draw freehand lines).  You can switch
between the two modes very quickly by keeping the Preference dialog
displayed, and turning the AutoConnect preference on and off as you
work.


Specifying Preferences by Editing the Preferences Files
-------------------------------------------------------
Visual Thought uses two Preferences files, both aptly named
"Preferences."  Most available preferences may be specified in the
Preferences files.

On startup, Visual Thought reads preferences from both the user and
system Preferences files.  User preferences, if specified, take
precedence over system preferences.  While there is only one system
Preferences file for an entire installation, each user may have a user
Preferences file.

The system Preferences file is read from the following location
(assuming Visual Thought has been installed in the default location):

  UNIX:

    /usr/local/confluent/vt-1.4/<system>/config

  Windows:

    C:\Program Files\Confluent\Visual Thought 1.4\config

<system> is one of the following, depending on your system:

  system          <system>
  ------          --------
  HP-UX 9.x/10.x  hpux-9
  Solaris 2.x     solaris-2
  SunOS 4.1.x     sunos-4.1

The user Preferences file is read from the following location:

  UNIX:

    ~/.vthought

  Windows:

    The first of the following directories that is available:

      %HOME%\.vthought
      %HOMEDRIVE%%HOMEPATH%\.vthought
      C:\Program Files\Confluent\Visual Thought 1.4\.vthought

Visual Thought's use of the system and user Preferences files makes it
easy for a systems administrator to set preferences for an entire
site, yet similarly easy for a user to override these settings for
personal tastes.

A preference may be specified in a Preference file by writing its name
and its value on a single line, separated by white space.  For
example, to set the Personality and RaiseOnDrop preferences, you can
write something like:

  Personality  Accident
  RaiseOnDrop  YES

For more information about preference formats, see any of the
Preferences files.


Specifying Preferences on the Command Line
------------------------------------------
Preferences may be set on the command line by adding arguments of the
form:

  Command Line Argument   Effect
  ---------------------   ------
  -<name> <value>         Give the preference <name> the value <value>
  -<name>                 Turn the boolean preference <name> on
  +<name>                 Turn the boolean preference <name> off

As an example, to use a 14 pt font for dialog interface controls,
start Visual Thought with the following command line arguments:

  -fontsize 14

Note that the name of a preference (e.g., "FontSize") is different
from the form that must be typed on the command line (e.g.,
"fontsize").  For the command line forms, consult the table in the
section "Preference Summary" above.

Consult the section "Preference Descriptions" below for descriptions
of each preference.


Preference Descriptions
-----------------------
Following is a more detailed description of each preference.

D => available in the Preferences dialog
S => only effective at startup

For preferences available in the Preferences dialog, the following
descriptions contain the dialog tab and text associated with the
preference.

  Preference Name      Command line        DS  Type     Default  Min/Max
------------------------------------------------------------------------
* AutoConnect          autoconnect         D   bool     YES

  Tab:  Drawing
  Text: A connection end is attached to an object when the end is
        dragged and released over the object.

  Turning this preference on is useful for creating diagrams (drawings
  containing shapes with rubberbanding connections).  Turning this
  preference off is useful for drawing freehand lines.

* BorderSize           bordersize              int      -1       -1/100

  Sets the border size of windows.  This is used at startup in
  calculating the separation between windows such as the Inspector and
  the main Application window.

* ColorPSImages        colorpsimages       D   bool     NO

  Tab:  Print/EPS
  Text: Color PostScript commands are used for printed and EPS output
        of color raster images.

  When off, printed output (on UNIX) and Encapsulated PostScript
  output is generated using standard Level 1 PostScript.  Color raster
  images (e.g., GIF images) are output using gray scales.  This output
  is compatible with Level 1 PostScript printers.

  When on, printed and Encapsulated PostScript output is generated
  using Level 1 PostScript with color extensions (i.e., the colorimage
  operator).  Color raster images (e.g., GIF images) are output in
  color.  This output is compatible with Level 2 PostScript printers and
  color Level 1 PostScript printers with color extensions.  This
  preference should be used for the output of documents containing color
  raster images.

  This preference is not useful for printed output on Windows.

* CreateConnect        createconnect       D   bool     NO

  Tab:  Drawing
  Text: A dragged palette shape is connected to shapes selected in the
        View where the shape is dropped.

  When on, this preference can be useful for creating hierarchies of
  objects extremely quickly.  For example, select a row of objects in a
  View and drop another shape centered above that row into the View to
  connect all selected shapes to the dropped shape.

* CreateNewDocument    createnewdocument   DS  bool     YES

  Tab:  Startup
  Text: A new document is created during startup.

  A new document named Untitled-1 is created during startup only if
  this preference is on.

  It is sometimes useful to turn this preference off when activating a
  Personality (via the Personality preference), where the Personality
  provides a custom configuration of Visual Thought documents during
  startup.

* DebugDefinitions     debugdefinitions    D   bool     NO

  Tab:  Debug
  Text: Alert notices with debugging information are displayed during
        parsing of shape definitions.

  This preference is useful for debugging new shape definitions.  See
  the file note_shapedefs.txt for more information on creating shape
  definitions.

* DeleteConnect        deleteconnect       D   bool     NO

  Tab:  Drawing
  Text: Two connections are joined when the shape to which they are
        connected is deleted.

  This preference is useful for flowcharting or dataflow applications,
  in which objects are frequently added to or deleted from linear flows
  consisting of connections between shapes.

* DropSplit            dropsplit           D   bool     NO

  Tab:  Drawing
  Text: A connection is split and the new endpoints are attached to a
        dragged palette shape dropped over the connection.

  This preference is useful for flowcharting or dataflow applications,
  in which objects are frequently added to or deleted from linear flows
  consisting of connections between shapes.

* EncodingLatin1       encodinglatin1      D   bool     NO

  Tab:  Print/EPS
  Text: Printed and EPS output supports 8-bit multinational characters
        in the ISO-8859-1 character set.

  When on, characters in the ISO-8859-1 character set with codes
  greater than 127 are printed correctly.  This is accomplished by
  modifying the PostScript output to change font encoding vectors from
  StandardEncoding to an encoding vector for the ISO-8859-1 character
  set.  This preference is typically used to enable Visual Thought to
  correctly print 8-bit multinational characters from European
  languages.

  This preference should only be used if it is necessary to print
  ISO-8859-1 characters with character codes greater than 127.  It may
  affect printing performance and could potentially fail on some
  printers.

  This preference is only useful on UNIX.

* ExportHandles        exporthandles        S  bool     NO

  When on, show the selection handles of any selected objects when
  exporting documents or images from the Export dialog or when printing.

* FontSize             fontsize             S  decimal  12,11    5.9/24

  The font size used to display text in Visual Thought dialogs.  It is
  recommended that the font size match a font size available from the X
  server or the system.  Font sizes much greater than 12 can make Visual
  Thought dialogs difficult to use.

  The allowed values depend on the fonts available from the X server
  or the system.  Typical sizes are 8, 10, 12, 14, 18, and 24.

  The default font size is 12 on UNIX and 11 on Windows.

  On UNIX, the available fonts can be determined with xlsfonts.  For
  example, the following will list the available medium Helvetica fonts:

    xlsfonts '*helvetica-medium-r-normal*'

* NoIconTitles         noicontitles            bool     NO

  When on, titles are not drawn in window icons.

* InformTranslators    informtranslators   D   bool     NO

  Tab:  Debug
  Text: Informational messages are generated when format translator
        commands specified in the Translators file are not available.

  Turning informational messages on is helpful for debugging purposes
  when modifying the Translators file to add, change, or delete file
  export translators available to Visual Thought.

* LimitToScreen        limittoscreen       D   bool     YES

  Tab:  Startup
  Text: Windows are resized and repositioned, if necessary, so they
        are displayed entirely on-screen when they are opened.

  This preference should be specified when Visual Thought is being
  displayed on a monitor with a small screen.

* LineFeedTermination  lflineterm          D   bool     NO

  Tab:  Files
  Text: Lines in output text files are terminated with line feed
        characters (the default for UNIX systems).

  By default, the termination characters depend on the system being
  used to run Visual Thought.  This preference should be specified when
  Visual Thought output text files must be formatted identically on all
  systems.

  This preference is only useful on Windows.

* Monochrome           monochrome           S  bool     NO

  When on, all dialogs are drawn using only black and white, with
  dithering used to represent gray scales in some cases.  This
  preference should be specified when Visual Thought is being displayed
  on a monochrome monitor.

* Openwindows          openwindows             bool     NO

  When on, customized window border sizes for the Sun Openwindows
  look-and-feel are used.

* Personality          personality         DS  string

  Tab:  Startup
  Text: The startup personality: the name of a subdirectory of the
        definitions and startup directories from which documents are
        read at startup.

  This preference makes it easy to create customized "desktops" for
  turnkey or vertical applications.  See the file note_personality.txt
  for more information.

* PrintCommand         printcmd            D   string   lpr

  Tab:  Print/EPS
  Text: The command used to print on UNIX.

  This preference specifies the print command used to print documents
  to a PostScript printer.  Printing is accomplished by executing the
  print command after setting the LPDEST and PRINTER environment
  variables to the printer specified in the Print dialog.

  This preference is only useful on UNIX.

* RaiseOnDrop          raiseondrop         D   bool     NO

  Tab:  Drawing
  Text: A View window is raised and focused when a dragged palette
        shape is dropped in the View.

* SaveAsDirectory      saveasdirectory     D   bool     NO

  Tab:  Files
  Text: Documents are saved as directories instead of files.

  Saving documents as directories allows document descriptions to be
  saved as text (vthought.txt files), and images and sounds in documents
  to be saved in native formats (GIF and AU).  These formats are
  convenient for programmatic manipulation.

  If programmatic manipulation is not desired, documents should be
  saved as files instead to allow easier manipulation by the file
  system.

* ScreenHeight         screenheight            int      99       99/9999

  Sets the height of the root window used by Visual Thought in window
  placement and size calculations.  Useful for debugging purposes.

* ScreenWidth          screenwidth             int      99       99/9999

  Sets the width of the root window used by Visual Thought in window
  placement and size calculations.  Useful for debugging purposes.

* ShortSuffixes        shortsuffixes       D   bool     NO

  Tab:  Files
  Text: Three-character file extensions (instead of long extensions)
         are used for saving documents and palettes.

  Normal extensions for Visual Thought documents are long, such as
  .vthought, .vpalette, and .vtdef.  This preference should be turned on
  when three-character extensions (.vtt, .vtp, .vtd) are required.

* NoSoundAlert         nosoundalert        DS  bool     NO

  Tab:  Startup
  Text: Alert notices on failure to open the audio control device are
        disabled during UNIX startup.

  When on, no alert notice is displayed at startup if the audio
  control device (/dev/audioctl) cannot be opened.  Turn this preference
  on is useful to avoid alert notices on startup if the host machine is
  intended to not have an audio control device, or access to the audio
  control device is to be restricted.

  This preference is only useful on UNIX.

* TitleHeight          titleheight             int      -1       -1/100

  Sets the height of title bars of windows.  This is used at startup
  in calculating the separation between windows such as the Inspector
  and the main Application window.

* WMFCurveApprox       wmfcurveapprox      D   bool     NO

  Tab:  Files
  Text: Curves are approximated with polygons in Windows Metafile
        output.

  Visual Thought by default exports curves in the WMF format as Bezier
  curves, which should allow import or paste with full resolution into
  applications supporting WMF import.  While WMF is a standard vector
  graphics exchange format, many applications (such as Word and
  PowerPoint) do not handle the format in standard ways.

  If pasting or importing a Visual Thought WMF image containing curves
  into an application results in no image appearing, try turning this
  preference on.  Visual Thought will render curves as many short line
  segments, usually allowing the application to display the WMF image
  while sacrificing some resolution.

  Consult the FAQ file (FAQ.txt or FAQ.html) for more information
  about WMF limitations.

* WMFCurveResolution   wmfcurveresolution  D   int      0        0/100

  Tab:  Files
  Text: The level of approximation in pixels between curves and their
        polygon approximations in Windows Metafile output.

  The fineness of the approximation is greatest when the curve
  resolution parameter is 0, coarsest when the parameter is 100.

  This preference is effective only if WMFCurveApprox is turned on.

* NoXColormap          noxcolormap             bool     NO

  When on, disable use of the system colormap to create color palettes
  for images.

*                      background           S  string   gray80

  The background color used to draw dialogs.  The color can be
  specified in any format recognized by the X server or the system
  (e.g., "#ff0000", "red").

  The allowed values depend on the colors available from the X server
  or the system.  Typical values are red, green, blue, #ff0000, #00ff00,
  and #0000ff.

  This preference can only be specified on the command line.

*                      font                 S  string   family:helvetica

  The font family used to display text in Visual Thought dialogs.

  This preference is specified in the form "-font family:<name>",
  where <name> is the font family name.

  The allowed values depend on the fonts available from the X server
  or the system.  Typical names are avantgarde, bembo, bookman, charter,
  clean, courier, fixed, gill, helvetica, lucida, menu, new century
  schoolbook, palatino, rockwell, terminal, and times.

  On UNIX, the available fonts can be determined with xlsfonts.  For
  example, the following will list the available medium Helvetica fonts:

    xlsfonts '*helvetica-medium-r-normal*'

  This preference can only be specified on the command line.

*                      foreground           S  string   black

  The foreground color used to draw dialogs.  The color can be
  specified in any format recognized by the X server or the system
  (e.g., "#ff0000", "red").

  The allowed values depend on the colors available from the X server
  or the system.  Typical values are red, green, blue, #ff0000, #00ff00,
  and #0000ff.

  This preference can only be specified on the command line.

*                      laf                  S  string   motif,windows,win95

  The look-and-feel used for the Visual Thought interface appearance
  and behavior.

  The allowed values are motif, openlook, windows, win95, and cua.

  This preference can only be specified on the command line.
