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

Table annotations are independent positioned table elements (up to 20
instances, Working index 0-19). They are NOT rows in the built-in PeTable.
They can appear inside axis regions, at chart edges, aligned with data
points, inside the PeTable area, or at arbitrary pixel coordinates.
Applies to: Pego, Pesgo, Pe3do, Pepso.

CORE WORKFLOW (every table annotation):
  1. PeAnnotation.Table.Working = N;          // select table 0-19
  2. PeAnnotation.Table.Rows = R;             // set dimensions FIRST
  3. PeAnnotation.Table.Columns = C;
  4. PeAnnotation.Table.Text[row, col] = "x"; // populate cells
  5. PeAnnotation.Table.Location = GraphTALocation.xxx;
  6. PeAnnotation.Table.Show = true;           // per-table visibility
  Always set Rows and Columns BEFORE accessing Text/Color/Type arrays.

VISIBILITY HIERARCHY (both must be true to see a table):
  PeAnnotation.Table.Show = true;             // per-table, set per Working
  PeAnnotation.ShowAllTableAnnotations = true; // global master (default true)
  Optional menu: PeUserInterface.Menu.ShowTableAnnotations = MenuControl.Show;
  lets users toggle all table annotations via right-click menu.

LOCATION SYSTEM -- GraphTALocation enum:
  ANCHORED POSITIONS (automatic placement, no coordinates needed):
    Outside chart: TopCenter(0), TopLeft(1), LeftCenter(2), BottomLeft(3),
      BottomCenter(4), BottomRight(5), RightCenter(6), TopRight(7)
    Inside chart: InsideTopCenter(8)..InsideTopRight(15) -- same 8 positions
      but within the graph plotting area.

  AXIS-ALIGNED (inside specific multi-axis regions):
    InsideAxis0(100)..InsideAxis5(105) -- places table inside axis N region.
    OutsideAxis0(200)..OutsideAxis5(205) -- outside axis N region.
    OverlapInsideAxis0(400)..OverlapInsideAxis5(405) -- overlapping axis N.
    When using InsideAxisN, set AxisLocation for sub-positioning (see below).

  TABLE-SPACED (columns auto-align with chart data points):
    Use InsideAxisN or InsideTable with AxisLocation set to
    TopTableSpaced(8) or BottomTableSpaced(9).
    Column count should match point count -- PE automatically spaces each
    column center to align with the corresponding X-axis data point.
    InsideTable(300) places the annotation within the PeTable region,
    used for adding custom labeled rows to the built-in data table.

  PIXEL-POSITIONED (free placement, optionally draggable):
    InsidePixelUnits(16) -- uses Table.X and Table.Y for pixel coordinates.
    Coordinate (0,0) is top-left of chart control.
    Combine with Moveable = TAMoveable.Full for user-draggable tables.
    Use GetRectGraph() after ReinitializeResetImage() to position relative
    to graph bounds (see Example 034).

AXIS LOCATION -- GraphTAAxisLocation enum (sub-position within axis):
  TopFullWidth(0), TopLeft(1), TopCenter(2), TopRight(3),
  BottomFullWidth(4), BottomLeft(5), BottomCenter(6), BottomRight(7),
  TopTableSpaced(8), BottomTableSpaced(9), NewRow(100).

STACKING TABLES (NewRow pattern -- not in main docs, only in examples):
  Multiple tables can stack vertically inside the same axis region by
  adding NewRow multiples to the AxisLocation value:
    Table 0: AxisLocation = GraphTAAxisLocation.TopLeft;           // row 0
    Table 1: AxisLocation = TopLeft + Convert.ToInt32(NewRow);     // row 1
    Table 2: AxisLocation = TopLeft + Convert.ToInt32(NewRow) * 2; // row 2
  NewRow=100, so TopLeft(1)+100=101 for row 1, +200=201 for row 2.
  All stacked tables must share the same InsideAxisN Location.
  Use case: hierarchical column headers (Example 027 -- Category/SubCat).

CELL CONTENT:
  Text[row, col] = "string";    // text content
  Color[row, col] = Color;      // foreground/text color per cell
  Type[row, col] = LegendAnnotationType.xxx; // symbol cells instead of text
    Symbol types: SquareSolid, LargeSquareSolid, DotSolid, etc.
    Symbols render as colored shapes -- used for custom legend indicators.
  Justification[row, col] = TAJustification.Left/Center/Right;
  Fonts[row, col] = "fontname"; // per-cell font override

COLUMN AND ROW STRUCTURE:
  ColumnWidth[col] = N;         // width in character count units
    Default: auto-sized to content. Manual width useful for alignment.
  HeaderRows = N;               // first N rows styled as headers
  HeaderColumn = true;          // first column styled as header
    Headers are visually separated from the grid body.
  TextSize = 85;                // font size, range ~50-200, default 100

STYLING:
  BackColor = Color.FromArgb(a, r, g, b); // table background
  ForeColor = Color.FromArgb(a, r, g, b); // default text color
  Border = TABorder.xxx;        // DropShadow(0), SingleLine(1),
                                   NoBorder(2), Inset(3), ThickLine(4)
  GradientStyle = PlotGradientStyle.xxx; // background gradient
  GradientColor = Color.xxx;    // gradient start color
  BevelStyle = BevelStyle.xxx;  // 3D bevel effect

  TRANSPARENT/INHERIT COLOR: To make BackColor or ForeColor match the
  chart's GraphBackColor/GraphForeColor, use the full 32-bit zero value:
    Color.FromArgb(0, 1, 0, 0)  // treated as "empty" -- inherits from chart
  The underlying DLL uses raw 32-bit color values (not .NET Color.Empty).

TEXTMODE (paragraph tables):
  When TextMode=true with Rows=1 and Columns=1, the table becomes a
  word-wrapping paragraph block. Set Width for wrap width in pixels.
  Height auto-sizes to fit content. Use Char(10) for line breaks:
    str = "First paragraph." + ((Char)10).ToString() + "Second paragraph.";
  Combine with InsidePixelUnits + Moveable.Full for floating text blocks.

INTERACTIVITY:
  Moveable = TAMoveable.None(0) / NoHotSpots(1) / Full(2);
    Full enables drag-to-move and resize. Position stored in Table.X/Y.
  HotSpot[row, col] = true;     // makes cell clickable
    Click triggers PeTableAnnotation event. Use GetHotSpotData() to read:
      hsd.Type == HotSpotType.TableAnnotation0..TableAnnotation19
      hsd.Data1 = row, hsd.Data2 = column of clicked cell.
  Events: PeTableAnnotation (click), PeTAMoved (drag), PeTASizedLeft/Right.

REAL-TIME UPDATE (DrawTable):
  PeFunction.DrawTable(tableIndex) repaints a single table without full
  chart reinitialize. Use in MouseMove events for live data display:
    1. Track mouse via PeUserInterface.Cursor.LastMouseMove
    2. Convert pixel to data via PeFunction.ConvPixelToGraph(...)
    3. Interpolate Y values from PeData.Y arrays
    4. Update Table.Text cells (set Working first)
    5. Call DrawTable(0), DrawTable(1), etc.
  See Example 028 for complete implementation.

RELATED FEATURE -- SubsetsToShow:
  PeData.SubsetsToShow[i] = 0..9;  // 0=hide, 1-9=show (weight=draw order)
  Newer/preferred over RandomSubsetsToGraph. Easier: set 0 to hide, any
  nonzero to show. Weight controls draw order (9 drawn first/behind).
  Combined with table HotSpots, enables interactive subset toggle UIs.

KEY EXAMPLES:
  026 -- Basic workflow, two tables at anchored positions, HeaderRows/Column
  027 -- Stacked tables with NewRow, ColumnWidth, per-cell Color
  028 -- Symbol cells (Type), real-time DrawTable, multi-axis legend tables
  029 -- TableSpaced alignment, InsideTable, transparent colors, mixed methods
  034 -- Pixel positioning, Moveable, TextMode paragraphs, HotSpot + events