<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE language SYSTEM "klayout_doc.dtd">

<doc>

  <title>The Marker Browser</title>
  <keyword name="Marker browser"/>

  <p>
  KLayout offers a generic concept of storing error markers or related information.
  This concept is called the "Report database" (RDB). An arbitrary number of report databases
  can be associated with a layout view. Usually, each database refers to a certain layout 
  but that is not a strict requirement. 
  </p>

  <p>
  A report database primarily is a generic collection of "values", which can be strings or other
  items. Usually, a value is a collection of geometrical objects which somehow flag
  some position or drawn geometry. Multiple of such values comprise a "marker item". 
  The report database associates these marker items with
  additional information:</p>

  <ul>
    <li><b>Tags:</b> Flags that indicate certain conditions. The marker browser uses
      a couple of predefined tags like "important", "waived" and "visited" which can be
      set or reset by the user indicating whether a marker item is considered important or
      an error has been waived.
    </li>
    <li><b>Image:</b> A marker can be assigned a screenshot image which serves for
      documentation purposes.
    </li>
  </ul>

  <p>
  Marker items are organized into categories. Each marker item must be associated with a 
  category. Categories themselves can be organized hierarchically, i.e. categories can be split 
  into sub-categories. This offers a way of improving the organisation of such categories.
  </p>

  <p>
  Marker items are usually associated with a cell, i.e. where a error was detected. By default,
  a marker item is simply associated with the top cell.
  </p>

  <p>
  The report database uses a proprietary format based on XML which is capable of storing the 
  annotations provided by the database. It is possible however to 
  import Calibre DRC ASCII format files.
  </p>

  <p>
  The marker browser is a tool to browse a report database associated with a view.
  The marker browser can be started using the "Marker Browser" function in the "Tools" menu.
  The marker browser tracks whether a marker has already been visited similar to the 
  "read" flag in a mail client. This allows tracking of a review session. The "visited" state is 
  reflected in the database file.
  </p>

  <p>
  In the marker browser, use the "Open" button to load a XML database file or import files from
  other formats. Choose "Reload" to reload a file and "Save As" to write a database in XML
  format.
  </p>

  <p>
  The marker browser offers three panels:
  </p>

  <ul>
    <li><b>Directory:</b> This panel lists the categories and cells of the database. 
      Categories or cells with unvisited markers will be shown in bold font. Such with
      no markers at all are shown in green color. It is possible to suppress these 
      categories or cells by deselecting "Show All" in the directory's context menu.
      To have the lists sorted by marker count, click at the header of the count 
      column.<br/>
      Multiple categories or cells can be selected. In that case, the markers panel
      will show the markers of all selected cells or categories.
    </li>
    <li><b>Markers:</b> This panel lists the markers in the selected category and/or cell.
      A length of the list is limited and can be changed on the configuration page 
      ("Configure" button on the marker browser or in the setup dialog).
      Various tags are shown in this panel as well. The list can be sorted 
      in various ways by clicking at the respective header.<br/>
      When a marker is selected in this list, it will be highlighted in the layout, provided
      a suitable layout is associated. The way a marker is highlighted and how the
      view is adjusted can be specified on the configuration page.
    </li>
    <li><b>Info:</b> This panel summarizes the information for the selected marker.
      If a screenshot was associated with the marker it is shown here. Click on the thumbnail
      image to show it in a separate window in the original size.
    </li>
  </ul>    

  <p>
  Similar to the shape and instance browsers, the marker browser offers navigation
  buttons to select the next marker, category or cell.
  </p>

  <p>
  The marker browser supports "tagged values": each marker can be associated with a value
  that has a name. Such values can be imported from RVE files where they are called 
  properties. Tagged values are generated by certain generators and can represent 
  measurement values or similar. When tagged values are present, they will be shown 
  in the markers list. The markers can be sorted by these values by clicking on the 
  appropriate header.
  </p>

</doc>

