# Copyright (c) 2025-2026 Gigasoft, Inc. All rights reserved.
=== ProEssentials PointLabelsII (knowledge rev 4.1) (Multi-Row X-Axis Labels) ===

Pego-only feature (v10+). Creates a 2D table of hierarchical labels
below the x-axis, replacing the simple 1D PointLabels array.

WHEN CUSTOMERS ASK FOR THIS:
  "multi-level x-axis labels", "hierarchical categories",
  "nested x-axis grouping" (Year/Quarter/Month), "grouped axis labels",
  "two rows of labels under chart", "parent-child categories on x-axis",
  "drill-down style axis labels", "multi-tier x-axis".

CORE PROPERTY:
  PeString.PointLabelsII[row, column] -- 2D string array.
  Columns = PeData.Points count. Rows = 1--50.
  Row 0 is nearest the chart (finest granularity).
  Higher rows go further below (coarser grouping).

AUTO-MERGE BEHAVIOR (critical concept):
  Adjacent identical strings in the same row merge into one wider box
  with a single centered label. Merge is SEQUENTIAL ONLY -- identical
  labels separated by a different label do NOT merge.
  Example: "A","A","A","B","B","A","A" --> box(A,3), box(B,2), box(A,2)
  This is how hierarchical grouping works: coarser rows repeat values
  across wider spans, producing wider merged boxes.

REPLACES PointLabels:
  When PointLabelsII has data, PointLabels is completely ignored.
  To revert: PeString.PointLabelsII.Clear() empties the 2D array,
  causing PointLabels to display again.

COMPANION PROPERTIES (almost always used together):

  PeString.PointLabelsIIBoxed = true;
    Draws horizontal lines between rows of the label table.

  PeString.PointLabelsIISeparators = true;
    Draws vertical lines between columns of the label table.

  PeString.GridLineSeparators = true;
    Shifts chart area vertical grid lines to midpoints between data
    points instead of on top of them. Aligns chart grid with the
    label table separators. Also useful independently for histograms,
    bin charts, or any chart where grid lines on data look wrong.

  PeGrid.Configure.AltFreqThreshold = <value greater than Points>;
    ALWAYS SET THIS when using PointLabelsII. Forces all labels to
    display, preventing the chart from thinning labels at high point
    counts. Without this, merged groupings may display incorrectly.
    Example: if Points=48, set AltFreqThreshold=50 or higher.

CODE PATTERN (Example 036 -- 4 subsets, 48 points, 3-row hierarchy):
  // Row 0: finest labels -- one per point, repeating pattern
  for (int c = 0; c < 46; c += 3)
  {
      Pego1.PeString.PointLabelsII[0, c]     = "3.55";
      Pego1.PeString.PointLabelsII[0, c + 1] = "3.8";
      Pego1.PeString.PointLabelsII[0, c + 2] = "4";
  }
  // Row 1: mid-level -- groups of 3 merge into wider boxes
  for (int c = 0; c < 37; c += 9)
  {
      Pego1.PeString.PointLabelsII[1, c]     = "-20";
      Pego1.PeString.PointLabelsII[1, c + 1] = "-20";
      Pego1.PeString.PointLabelsII[1, c + 2] = "-20";
      Pego1.PeString.PointLabelsII[1, c + 3] = "25";
      // ... identical values across 3 columns each merge
  }
  // Row 2: coarsest -- groups of 9 merge into widest boxes
  for (int c = 0; c < 9; c++)
  {
      Pego1.PeString.PointLabelsII[2, c]      = "5.15";
      Pego1.PeString.PointLabelsII[2, c + 9]  = "5.5";
      Pego1.PeString.PointLabelsII[2, c + 18] = "5.9";
  }

  // Required companion settings
  Pego1.PeGrid.Configure.AltFreqThreshold = 50; // > Points (48)
  Pego1.PeString.GridLineSeparators = true;
  Pego1.PeString.PointLabelsIISeparators = true;
  Pego1.PeString.PointLabelsIIBoxed = true;

ZOOMWINDOW INTERACTION:
  ZoomWindow can render PointLabelsII on its x-axis. Setting
  PePlot.ZoomWindow.ShowXAxis = false hides it to avoid redundancy,
  though some users may prefer seeing labels in the zoom window.

HOTSPOTS:
  PeUserInterface.HotSpot.Point = true works with PointLabelsII.
  Hot spot data includes the multi-row label context.

METHODS on PeString.PointLabelsII:
  Length(), GetLength(dimension), Clear(), Clear(newSize),
  Copy() --> string[,], CopyFrom(string[,] source).

NOT AVAILABLE ON: Pesgo, Pe3do, Pepso, Pepco -- Pego only.