<chapter id="chapter.gui.preferences">
  <title>Navigating the Preferences Window</title>
  <para>
    The preferences window allows the user to adjust the view of some of the GUI elements for the purpose of more easily 
    analyzing coverage information for a specific user. <xref linkend="figure.gui.pref.main"/> shows the preferences 
    window that is created when the user selects the <emphasis role="bold"><code>View > Preferences...</code></emphasis> menu option 
    from the main window.
  </para>
  <para>
    <figure id="figure.gui.pref.main">
      <title>Main Preferences Window</title>
      <mediaobject><imageobject><imagedata fileref="img/pref_main.gif" format="GIF"/></imageobject></mediaobject>
    </figure>
  </para>
  
  <sect1 id="section.gui.pref.categories">
    <title>Option Categories</title>
    <para>
      On the left side of the preferences window is a list of option categories that can be modified. Selecting any one 
      of the items in the listbox will display the modifiable options to the frame to the right of the listbox. The 
      following option categories exist:
    </para>
    <para>
      <itemizedlist>
        <listitem><para><xref linkend="section.gui.pref.general"/></para></listitem>
        <listitem><para><xref linkend="section.gui.pref.color"/></para></listitem>
        <listitem><para><xref linkend="section.gui.pref.goals"/></para></listitem>
        <listitem><para><xref linkend="section.gui.pref.syntax"/></para></listitem>
        <listitem><para><xref linkend="section.gui.pref.exclude"/></para></listitem>
        <listitem><para><xref linkend="section.gui.pref.merging"/></para></listitem>
      </itemizedlist>
    </para>
  </sect1>
  
  <sect1 id="section.gui.pref.buttons">
    <title>Preference Buttons</title>
    
    <sect2 id="section.gui.pref.buttons.apply">
      <title>Apply Button</title>
      <para>
        Clicking on the <emphasis role="bold">Apply</emphasis> button will cause the currently selected preference 
        options to be immediately updated in Covered but will not update the preference option values in the .coveredrc 
        file.  This has the effect of changing the preferences for the current application only. Clicking on this button 
        will not close the Preferences window.
      </para>
    </sect2>
    
    <sect2 id="section.gui.pref.buttons.ok">
      <title>OK Button</title>
      <para>
        Clicking on the <emphasis role="bold">OK</emphasis> button will cause the currently selected preference options 
        to be immediately updated in Covered and will update the .coveredrc file with the new values. This also causes 
        the Preferences window to close.
      </para>
    </sect2>
    
    <sect2 id="section.gui.pref.buttons.cancel">
      <title>Cancel Button</title>
      <para>
        Clicking on the <emphasis role="bold">Cancel</emphasis> button will cause the the Preferences window to close 
        without updating Covered with the currently selected values and without updating the .coveredrc file.
      </para>
    </sect2>
    
    <sect2 id="section.gui.pref.buttons.help">
      <title>Help (?) Button</title>
      <para>
        Clicking on the help (?) button will cause the help page for the currently selected'Option Category' to be
        displayed.
      </para>
    </sect2>
  </sect1>
  
  <sect1 id="section.gui.pref.configfile">
    <title>Preferences Configuration File</title>
    <para>
      User preferences are loaded from the ".coveredrc" file that is searched for in the following order:
    </para>
    <para>
      <orderedlist>
        <listitem><para>Current directory that the 'covered report -view' command was executed from.</para></listitem>
        <listitem><para>The user's home directory.</para></listitem>
        <listitem><para>The installation directory (by default this is /usr/local/share/covered).</para></listitem>
      </orderedlist>
    </para>
    <para>
      If user preferences are changed in this window and the <emphasis role="bold">OK</emphasis> button is pressed, the 
      settings are immediately saved back to a configuration file and the GUI is immediately updated to reflect the new 
      user changes.  If the <emphasis role="bold">Cancel</emphasis> button is pressed, all changes are thrown away and 
      the configuration file remains unchanged. The location of the stored configuration file depends on which 
      configuration file location was initially loaded. The following table describes this correlation.
    </para>
    <para>
      <table id="table.gui.pref.coveredrc">
        <title>Location of Written .coveredrc File According to the Location of Read .coveredrc File</title>
        <tgroup cols='2'>
          <thead>
            <row>
              <entry>Loaded config file location</entry>
              <entry>Stored config file location</entry>
            </row>
          </thead>
          <tbody>
            <row>
              <entry>Current directory</entry>
              <entry>Current directory</entry>
            </row>
            <row>
              <entry>Home directory</entry>
              <entry>Home directory</entry>
            </row>
            <row>
              <entry>Install directory</entry>
              <entry>Current directory</entry>
            </row>
            <row>
              <entry>None found</entry>
              <entry>Current directory</entry>
            </row>
          </tbody>
        </tgroup>
      </table>
    </para>
  </sect1>
  
  <sect1 id="section.gui.pref.general">
    <title>Preferences General Pane</title>
    <para>
      The general preferences pane allows the user to control Covered's settings that are not specific to an individual
      task.  The following subsections describe the controls available within this pane.
    </para>
    
    <sect2 id="section.gui.pref.general.wizard">
      <title>Show wizard window on startup</title>
      <para>
        This checkbutton selects if Covered's <link linkend="chapter.gui.wizard">wizard</link> popup window will be displayed upon
        starting Covered.  Simply check this button if you would like to see the wizard at the beginning of each startup
        or uncheck it to cause the wizard window to not be displayed on startup. On the wizard window itself, there is
        an option to change this behavior as well.
      </para>
      <para>
        Note that you can always display the wizard window by selecting its menu option in the 
        <link linkend="section.gui.main.viewmenu">view</link> menu.
      </para>
    </sect2>

    <sect2 id="section.gui.pref.general.state">
     <title>Save state of GUI when exiting the application</title>
     <para>
       This checkbutton determines if certain GUI element (i.e., window placement/sizing, module/instance listbox 
       column arrangement/width/state, etc.) information is saved when the GUI exits.  If this checkbutton is selected,
       the state is saved to the configuration file on application exit and will be used when the application is started.
       If the checkbutton is deselected, the state will not be saved and the default GUI element behaviors will be used.
     </para>
     <para>
       This setting allows the user to setup the various GUI elements to their liking and retains this information whenever
       the application is restarted, saving the user the hassle of getting the environment setup again.
     </para>
     <note>
       While the application is being used, any GUI state information will be remembered for the duration of the application
       run, regardless of the setting of this preference item.
     </note>
    </sect2>
    
    <sect2 id="section.gui.pref.general.tooltips">
      <title>Show tooltips</title>
      <para>
        This checkbutton specifies if GUI widget tooltips should be displayed if the user hovers the cursor over a GUI element
        that has a tooltip associated with it.  To disable tooltips from being used, uncheck this option and click either the
        <emphasis role="bold">Apply</emphasis> or <emphasis role="bold">OK</emphasis> buttons.
      </para>
    </sect2>
  </sect1>
  
  <sect1 id="section.gui.pref.color">
    <title>Preferences Color Pane</title>
    <para>
      The color preference pane allows the user to adjust the foreground and background colors for all code that is 
      considered covered, uncovered, or in a race condition state.
    </para>
    
    <sect2 id="section.gui.pref.color.set">
      <title>Set Highlight Color</title>
      <para>
        This frame contains six buttons that affect the foreground and background colors used to highlight code in the 
        <link linkend="section.gui.main.viewer">file viewer</link> portion of the main window. The currently selected foreground/background 
        colors are displayed to the left of the corresponding buttons to allow the user to see the selections prior to 
        committing to them by clicking the <emphasis role="bold">Apply</emphasis> or <emphasis role="bold">OK</emphasis> 
        buttons at the bottom of the Preferences window.
      </para>
      <para>
        The "F" button controls the foreground color while the "B" button controls the background color.  Clicking one
        of these buttons will bring up a color selection window that you can use to modify the current color to one of
        your choosing.
      </para>
    </sect2>
  </sect1>
  
  <sect1 id="section.gui.pref.goals">
    <title>Preference Coverage Goals Pane</title>
    <para>
      The coverage goals preference pane allows the user to change the acceptable coverage goals for each coverage metric.
    </para>
    <para>
      <figure id="figure.gui.pref.goals">
        <title>Coverage Goals Window</title>
        <mediaobject><imageobject><imagedata fileref="img/pref_goals.gif" format="GIF"/></imageobject></mediaobject>
      </figure>
    </para>
    
    <sect2 id="section.gui.pref.goals.acceptable">
      <title>Set Acceptable Coverage Goals Frame</title>
      <para>
        This frame contains four spinner boxes that contains values between 0 and 100. These values correspond to a 
        coverage percentage for each coverage metric that the user deems to be "good enough". These values are used by 
        the <link linkend="section.gui.main.listbox">listbox</link> to help visually identify modules/instances that are meeting or 
        exceeding these goals and which modules are not meeting these goals. If a coverage percentage for a 
        module/instance is less than this value, the module is colored red. If the coverage percentage is greater than or 
        equal to this value, the module/instance is colored yellow (or green which indicates that the module/instance 
        reached 100% coverage for a given metric).
      </para>
      <para>
        To increase the specified percentage value, simply click on the "Up" button to the right of the percentage until 
        the desired value is displayed. To decrease the specified percentage value, simply click on the "down" button to 
        the right of the percentage until the desired value is displayed.
      </para>
      <para>
        <itemizedlist>
          <listitem>
            <para><emphasis role="bold">Line Coverage %</emphasis></para>
            <para>
              Sets the coverage goal of line coverage to the specified percentage to the right. If line coverage for a 
              given module/instance meets or exceeds this percentage value, it will be displayed yellow in the 
              Module/Instance listbox on the Main window.
            </para>
          </listitem>
          <listitem>
            <para><emphasis role="bold">Toggle Coverage %</emphasis></para>
            <para>
              Sets the coverage goal of toggle coverage to the specified percentage to the right. If toggle coverage for 
              a given module/instance meets or exceeds this percentage value, it will be displayed yellow in the 
              Module/Instance listbox on the Main window.
            </para>
          </listitem>
          <listitem>
            <para><emphasis role="bold">Memory Coverage %</emphasis></para>
            <para>
              Sets the coverage goal of memory coverage to the specified percentage to the right. If memory coverage for 
              a given module/instance meets or exceeds this percentage value, it will be displayed yellow in the 
              Module/Instance listbox on the Main window.
            </para>
          </listitem>
          <listitem>
            <para><emphasis role="bold">Combinational Logic Coverage %</emphasis></para>
            <para>
              Sets the coverage goal of combinational coverage to the specified percentage to the right. If combinational 
              logic coverage for a given module/instance meets or exceeds this percentage value, it will be displayed 
              yellow in the Module/Instance listbox on the Main window.
            </para>
          </listitem>
          <listitem>
            <para><emphasis role="bold">FSM State/Arc Coverage %</emphasis></para>
            <para>
              Sets the coverage goal of FSM state/arc coverage to the specified percentage to the right. If FSM state/arc 
              coverage for a given module/instance meets or exceeds this percentage value, it will be displayed yellow in 
              the Module/Instance listbox on the Main window.
            </para>
          </listitem>
          <listitem>
            <para><emphasis role="bold">Assertion Coverage %</emphasis></para>
            <para>
              Sets the coverage goal of assertion coverage to the specified percentage to the right. If assertion 
              coverage for a given module/instance meets or exceeds this percentage value, it will be displayed yellow in 
              the Module/Instance listbox on the Main window.
            </para>
          </listitem>
        </itemizedlist>
      </para>
    </sect2>
  </sect1>
  
  <sect1 id="section.gui.pref.syntax">
    <title>Preferences Syntax Highlighting Pane</title>
    <para>
      The syntax highlighting preferences pane allows the user to adjust the syntax highlighting mode and colors for any 
      displayed Verilog source code.
    </para>
    <para>
      <figure id="figure.gui.pref.syntax">
        <title>Syntax Highlighting Preferences Pane</title>
        <mediaobject><imageobject><imagedata fileref="img/pref_syntax.gif" format="GIF"/></imageobject></mediaobject>
      </figure>
    </para>
    <sect2 id="section.gui.pref.syntax.highlighting">
      <title>Set Syntax Highlighting Options</title>
      <para>
        This frame allows the user to specify if syntax highlighting should be performed in all Verilog source viewers or 
        not. When the square to the left of the <emphasis role="bold">Turn on syntax highlighting mode</emphasis> is 
        selected, syntax highlighting will occur; otherwise, it will not perform syntax highlighting. The various colored 
        buttons below the selection mode allow the user to select the foreground color of the text associated with its 
        specified syntax type (Comments, Preprocessor Keywords, Verilog Keywords, Strings, Constant Values, and Operation 
        Symbols). Simply click on one of the buttons to change its color. Doing so will cause a color selection window 
        (see <xref linkend="figure.gui.pref.syntax"/> above) to be displayed.
      </para>
      <para>
        If the syntax highlighting mode is disabled by the user, the color selection buttons will be disabled.
      </para>
    </sect2>
  </sect1>
  
  <sect1 id="section.gui.pref.exclude">
    <title>Preferences Exclusion Pane</title>
    <para>
      The exclude preferences pane allows the user to control whether or not the coverage exclusion reason window
      automatically pops up when a coverage point is excluded, and it allows the user to create some general purpose
      exclusion reasons.  The reasons created in this pane can be selected in the exclusion reason window's drop-down
      table and can help to expedite the exclusion process when many coverage points are being excluded for the same
      reason.  <xref linkend="figure.gui.pref.exclude"/> shows the layout of this preference pane.
    </para>
    <para>
      <figure id="figure.gui.pref.exclude">
        <title>Exclusion Preferences Pane</title>
        <mediaobject><imageobject><imagedata fileref="img/pref_exclude.gif" format="GIF"/></imageobject></mediaobject>
      </figure>
    </para>
    <sect2 id="section.gui.pref.exclude.enable">
      <title>Enable exclusion reason support when items are excluded</title>
      <para>
        If this option is enabled, whenever the user clicks on a coverage point to cause it to be excluded from
        coverage, a popup window will be displayed, allowing for an exclusion message to be associated with the
        excluded coverage point.
      </para>
      <para>
        If this option is not enabled, the coverage point will still be excluded but no exclusion message will
        be associated with it.
      </para>
      <note>
        If a coverage point was excluded and is selected to be included and the coverage point had an exclusion
        message associated with it, the exclusion message will be forgotten/deleted.
      </note>
    </sect2>
    <sect2 id="section.gui.pref.exclude.genreasons">
      <title>Create General Exclusion Reasons</title>
      <para>
        This frame allows the user to add/delete general purpose exclusion reasons that can be selected from within
        the <link linkend="chapter.gui.exclude">exclusion reason popup window's</link> drop-down table.  Having these 
        reasons specified can help to speed up coverage point exclusion when multiple coverage points need to be 
        excluded for the same reason.
      </para>
      <para>
        To add a new general purpose exclusion reason, simply type in the general purpose exclusion reason in the
        bottom textbox (note that any formatting characters such as newlines, tabs, extra spaces will be removed
        from the exclusion message) and click the "+" button.  You will see the exclusion reason get added to the
        table when this occurs.  Note that the "+" button will only be enabled when you have entered at least one
        character in the textbox.
      </para>
      <para>
        To remove a general purpose exclusion reason from the table, simply click on the reason in the table and
        click the "-" button.  Note that the "-" button will only be enabled once an entry has been selected in
        the table.
      </para>
      <para>
        To help find an exclusion reason more easily within the exclusion reason popup window, you may also rearrange
        the order of the exclusions within the table by simply clicking on an entry and dragging it to the desired
        location.  The order of the exclusion reasons specified in this table will be the initial order of the
        exclusion reasons in the popup window.
      </para>
    </sect2>
  </sect1>
  
  <sect1 id="section.gui.pref.merging">
    <title>Preference Merging Pane</title>
    <para>
      The merging pane is needed to specify to Covered how to resolve conflicts that are found when merging CDD
      files.  Although coverage points and exclusions are simply merged (ORed) together, things such as exclusion
      reasons can exist for the same coverage point but contain different information.  When two exclusion reasons
      are given for the same coverage point, Covered must decide how to resolve this information and this preference
      pane allows the user to set what this behavior will be.
    </para>
    <para>
      <figure id="figure.gui.pref.merging">
        <title>Merging Preferences Pane</title>
        <mediaobject><imageobject><imagedata fileref="img/pref_merge.gif" format="GIF"/></imageobject></mediaobject>
      </figure>
    </para>
    <sect2 id="section.gui.pref.merging.er">
      <title>Exclusion Reason Conflict Resolution Frame</title>
      <para>
        This frame allows the user to specify the way in which exclusion reason conflicts should be resolved.  The
        following options are provided:
      </para>
      <para>
        <itemizedlist>
          <listitem>
            <para><emphasis role="bold">Use the first reason</emphasis></para>
            <para>
              Specifies if two or more exclusion reasons are found for the same coverage point, Covered should use
              the exclusion reason found in the first CDD file merged.  The rest of the exclusion reasons are thrown away.
            </para>
          </listitem>
          <listitem>
            <para><emphasis role="bold">Use the last reason</emphasis></para>
            <para>
              Specifies if two or more exclusion reasons are found for the same coverage point, Covered should use
              the exclusion reason found in the last CDD file merged.  The rest of the exclusion reasons are thrown away.
            </para>
          </listitem>
          <listitem>
            <para><emphasis role="bold">Use the newest reason</emphasis></para>
            <para>
              Specifies if two or more exclusion reasons are found for the same coverage point, Covered should use
              the newest exclusion reason (when an exclusion is created, a timestamp is saved along with the
              coverage reason).  The rest of the exclusion reasons are thrown away.
            </para>
          </listitem>
          <listitem>
            <para><emphasis role="bold">Use the oldest reason</emphasis></para>
            <para>
              Specifies if two or more exclusion reasons are found for the same coverage point, Covered should use
              the oldest exclusion reason.  The rest of the exclusion reasons are thrown away.
            </para>
          </listitem>
          <listitem>
            <para><emphasis role="bold">Merge all reasons</emphasis></para>
            <para>
              Specifies if two or more exclusion reasons are found for the same coverage point, Covered should
              merge all of them.  No information is lost in this case.
            </para>
          </listitem>
        </itemizedlist>
      </para>
    </sect2>
  </sect1>
  
</chapter>
