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

<doc>

  <title>Ruler Properties</title>
  <keyword name="Rulers"/>
  <keyword name="Ruler properties"/>

  <p> 
  These are the properties that can be configured for rulers:
  </p>
  <ul>
    <li><b>Labels:</b> depending on the outline of the ruler, up to three labels an be present.
      Each label can be configure individually to either show a text or the measurement 
      values. The main label is always present, X and Y labels are only present, if the ruler
      has an explicit vertical or horizontal component (all outline styles except "diagonal").
      For the main label the position of the label can be specified ("P" setting): the label
      can be made to appear on the first or the second point or in the middle of the ruler.
      The Alignment of the labels can be specified too: whether the appear left or right-aligned
      or centered.
    </li>
    <li><b>Style:</b> the style determines how the ruler or its components are drawn. This can be
      "ruler-like" (with ticks), arrow style, a plain line or with cross markers at the end.
    </li>
    <li><b>Outline:</b> the outline determines how the two points forming the ruler are connected
      to render the ruler shape. This is either just one line ("diagonal"), a horizontal and a vertical line
      (in some outline styles combined with the diagonal line) or a box given by the two points of the 
      ruler. A special outline is the ellipse which draws an ellipse inside the box defined by the
      ruler.
    </li>
    <li><b>Angle constraint:</b> the orientation of the ruler can be restricted in several ways, i.e. 
      just being horizontal. By default, the ruler uses the global setting. It can however be configured 
      to provide its own constraint.
    </li>
    <li><b>Mode:</b> in normal mode, two clicks are required to define a ruler: to set the first
      point and to set the second one. In "Single click" mode, a single click will set both 
      points to the same. In "Auto measure" mode, the points will be determined by looking
      for edges in the vicinity of the click point and adjusting the points accordingly.
    </li>
    <li><b>Never snap to objects:</b> if this option is on, the ruler never snaps to drawing
      objects, even if that global option is enabled.
    </li>
  </ul>

  <p>
  The "Label format" is an arbitrary text with embedded expressions that may represent a measurement
  value. Each such expression starts with a dollar sign, followed by the expression string. The expression 
  syntax supports the basic operations ("*", "/", "+", "-" ..), bitwise operations ("|", "&amp;", ..), 
  the conditional operator ("x:y?z") as well as some functions, i.e. "abs", "sqrt", "exp". It includes a "sprintf" 
  function. These are some examples:
  </p>

  <ul>
    <li><b>$X</b>: The value of the X variable (the horizontal distance, see below for a complete list of variables).</li>
    <li><b>$(sprintf('%.2f',X))</b>: The value of the 'X' variable formatted as two digit fixed precision value.
      The "sprintf" function follows the conventions of the same standard C function.</li>
    <li><b>$(abs(X)+abs(Y))</b>: The Manhattan distance of the ruler.</li>
    <li><b>$min(X,Y)</b>: The minimum of X and Y.</li>
    <li><b>$(X) ($Y)</b>: the value of the X variable, followed by the value of the Y variables in brackets. 
      This will give a string like "2.5 (-0.5)". Note 
      that you cannot simply write "$X ($Y)" because the expression evaluation reads that as an attempt to call a 
      function named "X".</li>
  </ul>

  <p>
  A description of the expression syntax and the functions available can be found in <link href="/about/expressions.xml"/>.
  </p>

  <p>
  This is a list of all variables available:
  </p>

  <ul>
    <li><b>D:</b> The length of the ruler in micron units.</li>
    <li><b>L:</b> The Manhattan length of the ruler in micron units.</li>
    <li><b>U:</b> The x-position of the ruler's first point in micron units.</li>
    <li><b>V:</b> The y-position of the ruler's first point in micron units.</li>
    <li><b>P:</b> The x-position of the ruler's second point in micron units.</li>
    <li><b>Q:</b> The y-position of the ruler's second point in micron units.</li>
    <li><b>X:</b> The horizontal extension of the ruler in micron units.</li>
    <li><b>Y:</b> The vertical extension of the ruler in micron units.</li>
    <li><b>A:</b> The area enclosed by the ruler (if it was a box) in square millimeters.</li>
    <li><b>G:</b> The angle enclosed by the first and last segment of the ruler (used for angle measurement rulers).</li>
  </ul>

  <p>
  For multi-rulers additional variables are provided for "incremental" values.
  These are the sums of the respective values up to the given part:
  </p>

  <ul>
    <li><b>DD:</b> The sum of all lengths up to the labelled segment.</li>
    <li><b>LL:</b> The sum of all Manhattan up to the labelled segment.</li>
    <li><b>XX:</b> The horizontal distance between first and current point.</li>
    <li><b>YY:</b> The vertical distance between first and current point.</li>
  </ul>

</doc>

