# Copyright (c) 2025-2026 Gigasoft, Inc. All rights reserved.
=== ProEssentials Axis Formatting (knowledge rev 4.1), Inversion & Grid Density ===

Covers: AxisFormat strings, InvertedAxis, SpecialScaling, grid density control.
ALWAYS query pe_query.py for exact paths -- this file provides concepts only.

--- AXIS FORMAT STRINGS ---

  Custom formatting of grid line numbers via pipe-delimited format string:
    PeGrid.Option.AxisFormatY = "{PRE}|{.}{,}{0000}|{POST}";

  SYNTAX: Three sections separated by two pipe | characters (pipes required):
    PRE  -- text prepended to each number (e.g. "$")
    MID  -- formatting controls: . = decimal point, , = thousands commas,
           0/00/000 = zero-padding / forced decimal places
    POST -- text appended to each number (e.g. "sec", " units", "%")

  EXAMPLES (value 1000):
    "$|,|"           --> "$1,000"          prefix + commas
    "$|,.00|"        --> "$1,000.00"       prefix + commas + 2 decimals
    "|.0|sec"        --> "1000.0sec"       1 decimal + suffix
    "$||"            --> "$1000"           prefix only, no format change
    "||%"            --> "1000%"           suffix only

  Available for all axes (each is WorkingAxis-dependent for multi-axis):
    PeGrid.Option.AxisFormatY   -- Y axis (Pego, Pesgo, Pe3do)
    PeGrid.Option.AxisFormatRY  -- Right Y axis (Pego, Pesgo)
    PeGrid.Option.AxisFormatX   -- X axis (Pesgo, Pe3do)
    PeGrid.Option.AxisFormatTX  -- Top X axis (Pesgo only)
    PeGrid.Option.AxisFormatZ   -- Z axis (Pe3do only)

  Related: PeConfigure.Decimal and PeConfigure.Thousands override OS
  locale symbols for decimal separator and thousands separator.

  CANNOT be combined with SpecialScaling on the same axis.
  See Example 109.

--- INVERTED AXIS ---

  Flips label polarity so negative data values display as positive numbers.
  Used for "depth" charts (drilling, underwater, underground) where data
  increases downward but labels should show positive depth values.

  ALWAYS USE TOGETHER:
    1. Negate the data: PeData.Y[s,p] = -1 * actualValue;
    2. Enable inversion: PeGrid.Option.InvertedYAxis = true;

  The property ONLY changes label display -- it does NOT transform data.
  All front-facing UX (axis labels, tooltips, cursor prompts) shows
  positive values. Developer must negate data to match.

  Available variants (all bool, all WorkingAxis-dependent):
    PeGrid.Option.InvertedYAxis   -- Pego, Pesgo, Pe3do
    PeGrid.Option.InvertedRYAxis  -- Pego, Pesgo
    PeGrid.Option.InvertedXAxis   -- Pesgo, Pe3do, Pepso
    PeGrid.Option.InvertedTXAxis  -- Pesgo only

  When using InvertedYAxis, also set NullDataValue to a sentinel
  (e.g. -999) so legitimate zeros are not treated as null.
  See Example 108.

--- SPECIAL SCALING (FINANCIAL FRACTIONS) ---

  Converts decimal Y-axis labels to fractional notation (e.g. 20 1/2).
  Used for financial/stock tick pricing.

    PeGrid.Option.SpecialScalingY = SpecialScaling.Financial;

  Enum SpecialScaling: None(0), Financial(1).
  Also: PeGrid.Option.SpecialScalingRY for right Y axis.

  Fraction precision adapts automatically:
    -- Shows halves (1/2), quarters (1/4), eighths (1/8), sixteenths (1/16),
      up to sixty-fourths (1/64) depending on data range and zoom level.
    -- Reverts to decimal display when zoomed beyond 1/64 precision.
  No property to manually control denominator -- it's automatic.

  CANNOT be combined with AxisFormat strings on the same axis.
  Supports WorkingAxis for multi-axis charts.
  See Example 111.

--- GRID LINE DENSITY CONTROL ---

  Manually control spacing of major grid lines and minor tick marks:

    PeGrid.Configure.ManualYAxisTicknLine = true;  // enable manual control
    PeGrid.Configure.ManualYAxisLine = 250;         // grid line every 250 units
    PeGrid.Configure.ManualYAxisTick = 25;           // tick mark every 25 units

  Best practice: ManualYAxisLine should be evenly divisible by ManualYAxisTick.

  Available for all axes (all WorkingAxis-dependent):
    ManualYAxisTicknLine / ManualYAxisLine / ManualYAxisTick    -- Y axis
    ManualRYAxisTicknLine / ManualRYAxisLine / ManualRYAxisTick -- RY axis
    ManualXAxisTicknLine / ManualXAxisLine / ManualXAxisTick    -- X axis
    ManualTXAxisTicknLine / ManualTXAxisLine / ManualTXAxisTick -- TX axis
    ManualZAxisTicknLine / ManualZAxisTick                      -- Z axis (Pe3do)

  Related properties:
    PeGrid.Option.YAxisLongTicks = true -- extends minor ticks across chart
    PeGrid.LineControl = GridLineControl.Both -- controls which axes show gridlines
      Enum GridLineControl: Both(0), YAxis(1), XAxis(2), None(3)

  TROUBLESHOOTING: If auto-scaling forces multiples of 2/5/10 and your
  desired spacing conflicts, set:
    PeGrid.Configure.GridLineMultiples = true;
  This DISABLES the 2/5/10 constraint (despite the positive name -- the
  DLL constant is PEP_bNOGRIDLINEMULTIPLES). Rarely needed.
  See Examples 113, 134.