# Copyright (c) 2025-2026 Gigasoft, Inc. All rights reserved.
=== ProEssentials Annotations (knowledge rev 4.7) (Line, Axis, Table, Polar) ===

ProEssentials supports annotation types: line annotations (reference
lines), graph annotations (text/markers at data coordinates), axis
annotations (labels on axis regions), and table annotations.

GRAPH ANNOTATIONS: See pe-graph-annotations knowledge file for full
  details on graph annotations (Pego, Pesgo, Pepso, Pe3do). Covers:
  text prefix codes, angled text, composite patterns, bitmaps, dodging,
  per-annotation formatting, TextBoundingBox, multi-axis targeting.

LINE ANNOTATIONS (horizontal/vertical reference lines):
  Horizontal lines: PeAnnotation.Line.YAxis[i] = yValue
  Vertical lines: PeAnnotation.Line.XAxis[i] = xValue
  Per-annotation properties (all indexed arrays):
    YAxisType / XAxisType -- LineAnnotationType enum
    YAxisText / XAxisText -- text string with optional prefix codes
    YAxisColor / XAxisColor -- Color per annotation
    YAxisInFront / XAxisInFront -- AnnotationInFront enum per annotation
    YAxisAxis -- multi-axis targeting (horizontal only, see below)
    YAxisZoomWindow / XAxisZoomWindow -- AnnotationZoomWindow enum
  Use case: threshold lines, target values, reference markers, custom grids.

LINE ANNOTATION TYPE ENUM (LineAnnotationType):
  ThinSolid(0), Dash(1), Dot(2), DashDot(3), DashDotDot(4),
  MediumSolid(5), ThickSolid(6), GridTick(7), GridLine(8),
  MediumThinSolid(9), MediumThickSolid(10), ExtraThickSolid(11),
  ExtraThinSolid(12), ExtraExtraThinSolid(13),
  GridTickColoredText(14), GridLineColoredText(15).
  Types 16+ (MediumThinDash through ExtraThickDashDotDot, values 16--35)
  require RenderEngine Hybrid or GdiPlus.

  +1000 RIGHT Y-AXIS OFFSET: Adding 1000 to any LineAnnotationType
  integer value makes the annotation's Y value interpreted against the
  RIGHT Y-axis scale instead of the left Y-axis. The line still draws
  at the correct visual position but uses the RY scale for its value.
    PeAnnotation.Line.YAxisType[i] = LineAnnotationType.ThickSolid + 1000;
  This works with both single-axis (RYAxisComparisonSubsets) and
  multi-axis layouts. See Example 101.

LINE ANNOTATION TEXT JUSTIFICATION CODES:
  Both YAxisText and XAxisText support two-character prefix codes.
  First character is the pipe symbol "|". Second character controls
  placement. Each annotation type has a default placement when no
  prefix is used.

  HORIZONTAL LINE ANNOTATION TEXT (YAxisText) -- 13 CODES:
  Default (no prefix) = left inside edge.
    |l -- Left inside edge of graph (same as default)
    |L -- Left OUTSIDE edge (needs LeftMargin)
    |M -- Left OUTSIDE edge with opaque BackColor (needs LeftMargin)
    |r -- Right inside edge of graph
    |R -- Right OUTSIDE edge (needs RightMargin)
    |S -- Right OUTSIDE edge with opaque BackColor (needs RightMargin)
    |c -- Centered inside graph grid
    |t -- Top inside edge (text placed at top of graph area)
    |T -- Top OUTSIDE edge, vertical text orientation (needs TopMargin)
    |H -- Top OUTSIDE edge, horizontal text orientation
    |b -- Bottom inside edge (text placed at bottom of graph area)
    |B -- Bottom OUTSIDE edge, vertical text orientation (needs BottomMargin)
    |h -- Bottom OUTSIDE edge, horizontal text orientation

  VERTICAL LINE ANNOTATION TEXT (XAxisText) -- 10 CODES:
  Default (no prefix) = bottom inside edge.
    |b -- Bottom inside edge of graph (same as default)
    |B -- Bottom OUTSIDE edge, vertical text (needs BottomMargin)
    |h -- Bottom OUTSIDE edge, horizontal text
    |t -- Top inside edge of graph
    |T -- Top OUTSIDE edge, vertical text (needs TopMargin)
    |H -- Top OUTSIDE edge, horizontal text
    |c -- Centered inside graph grid
    |l -- Left inside edge (text placed at left of graph area)
    |L -- Left OUTSIDE edge (needs LeftMargin)
    |r -- Right inside edge (text placed at right of graph area)

  MULTILINE TEXT: Use newline character within text strings:
    YAxisText[i] = "|RTest" + '\n' + "String";

  BackColor CODES (|M and |S): These draw an opaque background
  rectangle behind the text to prevent overlap with grid numbers.
  Color set via: PeAnnotation.Line.LineAnnotBackColor = Color.xxx;
  Only applies to horizontal line annotations. See Example 005.

MARGIN PROPERTIES (space allocation for outside-edge text):
  When text is justified OUTSIDE the graph grid (|L, |R, |T, |B, |H,
  |h, |M, |S), you must allocate space so text is not clipped.
  Set the margin to the longest annotation string at that edge:
    PeAnnotation.Line.LeftMargin = "Longest Left Text ";
    PeAnnotation.Line.RightMargin = "Longest Right Text ";
    PeAnnotation.Line.TopMargin = "Longest Top Text ";
    PeAnnotation.Line.BottomMargin = "Longest Bottom Text ";

  SHOWMARGINS ENUM controls when margins are applied:
    PeAnnotation.Line.ShowMargins = ShowMargins.ShowAnnotations; (default)
      -- margins only applied when PeAnnotation.Show = true
    ShowMargins.Always -- margins always applied regardless of Show state
    ShowMargins.Never -- margins never applied

LINE ANNOTATION MULTI-AXIS TARGETING:
  Horizontal line annotations can target specific axis regions:
    PeAnnotation.Line.YAxisAxis[i] = axisIndex; // 0--15
  The Y value is interpreted in that axis's Y-scale and the line renders
  in that axis's vertical strip. Without setting YAxisAxis, annotations
  default to axis 0.
  Vertical line annotations have NO axis targeting -- they span ALL axes
  from top to bottom of the chart. There is no XAxisAxis property.
  See Example 101 for both single and multi-axis line annotations.

LINE ANNOTATION PER-ANNOTATION Z-ORDER:
  Each annotation can individually control its draw order:
    PeAnnotation.Line.YAxisInFront[i] = AnnotationInFront.InFront;
    PeAnnotation.Line.XAxisInFront[i] = AnnotationInFront.Behind;
  AnnotationInFront enum: Default(0), Behind(1), InFront(2), Hide(3).
  Default follows PeAnnotation.InFront global setting. Hide suppresses
  the individual annotation without removing it from the array.

LINE ANNOTATION VISIBILITY HIERARCHY:
  Three levels of visibility control:
  1. PeAnnotation.Show = true -- GLOBAL master switch for ALL annotations
  2. PeAnnotation.Line.YAxisShow = true -- always show horizontal lines
     (if false, horizontal lines only show when Show = true)
     PeAnnotation.Line.XAxisShow = true -- same for vertical lines
  3. Per-annotation: YAxisInFront[i] = AnnotationInFront.Hide

LINE ANNOTATION TEXT PROPERTIES:
  PeAnnotation.Line.TextSize -- int, range 20--100 (100 = largest)
  PeAnnotation.Line.LineAnnotBackColor -- Color for |M and |S codes

LINE ANNOTATION ZOOM WINDOW:
  Annotations can optionally appear in the zoom overview strip:
    PeAnnotation.Line.YAxisZoomWindow[i] = AnnotationZoomWindow.GraphAndZoomWindow;
    PeAnnotation.Line.XAxisZoomWindow[i] = AnnotationZoomWindow.ZoomWindowOnly;
  AnnotationZoomWindow enum: GraphOnly(0), GraphAndZoomWindow(1), ZoomWindowOnly(2).
  Default (empty array) = annotations do not show in zoom window.

CUSTOM Y-AXIS RECIPE (using line annotations to replace numeric grid):
  1. PeGrid.Option.ShowYAxis = ShowAxis.Empty -- hides default numbers
  2. PeGrid.Configure.ManualScaleControlY = ManualScaleControl.MinMax
  3. PeGrid.Configure.ManualMinY / ManualMaxY -- set explicit range
  4. Create GridLine annotations at labeled positions:
       PeAnnotation.Line.YAxis[i] = value;
       PeAnnotation.Line.YAxisType[i] = LineAnnotationType.GridLine;
       PeAnnotation.Line.YAxisText[i] = "|LLabel Text";
  5. Create GridTick annotations at unlabeled intermediate positions:
       PeAnnotation.Line.YAxisType[i] = LineAnnotationType.GridTick;
       PeAnnotation.Line.YAxisText[i] = "";
  6. PeAnnotation.Line.LeftMargin = "longest label ";
  7. PeAnnotation.Show = true;
  8. PeAnnotation.Line.TextSize = 100;
  9. PeGrid.InFront = true -- draws grid over filled area data
  See Example 005 for complete implementation.

POLAR ANNOTATIONS (Pepso):
  In Pepso polar mode, Y-axis line annotations render as CONCENTRIC CIRCLES
  instead of horizontal lines. This is the primary way to add colored
  reference circles to a polar chart.
    PeAnnotation.Line.YAxis[i] = radialValue;
    PeAnnotation.Line.YAxisColor[i] = Color.FromArgb(255, r, g, b);
    PeAnnotation.Show = true;
  YAxisType defaults work fine -- no need to set explicitly.

  REPLACING DEFAULT GRID CIRCLES WITH ANNOTATION CIRCLES:
    PeGrid.LineControl = GridLineControl.YAxis;
    This suppresses default concentric grid circles (shows only radial/degree
    grid lines), letting colored annotation circles serve as radial references.
    GridLineControl enum: Both=0, YAxis=1, XAxis=2, None=3.

  TIP: PeUserInterface.Menu.AnnotationControl = true enables the annotation
  menu when popups are active -- good practice whenever annotations are used.
  See Example 206 for complete implementation.

HOTSPOT ENABLING:
  Line annotations:
    PeUserInterface.HotSpot.YAxisLineAnnotations[i] = AnnotationHotSpot.All
    PeUserInterface.HotSpot.XAxisLineAnnotations[i] = AnnotationHotSpot.All
  Graph annotations: see pe-graph-annotations knowledge file.
  Menu control:
    PeUserInterface.Menu.AnnotationControl = true
    PeUserInterface.Menu.ShowAnnotationText = MenuControl.Show
  Hotspot arrays are under PeUserInterface, NOT under PeAnnotation.

AXIS ANNOTATIONS (colored regions along an axis):
  Collection under PeAnnotation.Axis.
  Paint colored/labeled bands on X or Y axis regions.
  Useful for: shift indicators, good/bad zones, time-of-day bands.

TABLE ANNOTATIONS (see pe-table-annotations knowledge file for full details):
  Independent positioned table elements (up to 20 instances via Working 0-19).
  NOT the same as PeTable (built-in data table). Full location system with
  anchored positions, axis-aligned, table-spaced, and pixel-positioned modes.
  Support cell types (text/symbols), styling, stacking, interactivity,
  real-time update via DrawTable(), and moveable/hotspot capabilities.

KEY: Always query exact paths before coding:
  pe_query.py search "annotation"
  pe_query.py enum "LineAnnotationType"