pe-zoom-1200tokens.txt

# Copyright (c) 2025-2026 Gigasoft, Inc. All rights reserved.
=== ProEssentials Zoom (knowledge rev 4.2) & Scroll ===

Zooming and scrolling differ between Pego (categorical) and Pesgo (numeric).

*** IF THE APP ALSO DRAGS ANNOTATIONS, CURSORS OR DATA POINTS, READ
pe-events-interaction PATTERN H2 FIRST. *** The engine begins painting the XOR
zoom band during the button-down, BEFORE the managed MouseDown fires, so
disabling zoom in MouseDown is too late and strands a half-drawn rectangle.
Zooming must be armed/disarmed during HOVER instead. Worked implementation:
PE11\TestBeds\WinformNet80\SinusAmorti\.

PESGO AXIS CONTROL -- THREE INDEPENDENT LEVELS:
  A Pesgo axis can be controlled at three levels. Understanding this
  prevents confusion between "zooming" and "manual scaling":

  a) AUTO-SCALED (default) -- chart finds min/max from data
     ManualScaleControlY = ManualScaleControl.None;

  b) MANUALLY SCALED -- developer sets fixed range
     ManualScaleControlY = ManualScaleControl.MinMax;
     ManualMinY = 0; ManualMaxY = 100;

  c) ZOOM-CONTROLLED -- overlays manual scaling without changing it
     PeGrid.Zoom.MinY = 20; PeGrid.Zoom.MaxY = 80;
     PeGrid.Zoom.Mode = true;
     The axis now shows 20--80 while ManualMinY/MaxY stay 0/100.

  Zoom mode is useful when a developer wants to manually scale but
  also allow zooming (user-interactive or programmatic) without
  disturbing the manual scale values. Undo zoom restores the manual
  range. This is especially useful in real-time where ManualMinX/MaxX
  track the data window and zoom allows the user to focus on a region.

PESGO ZOOM (true numeric zoom):
  Enable: PeUserInterface.Allow.Zooming = AllowZooming enum value
  Options: HorzAndVert, HorzOnly, VertOnly, HorzAndVertMb, etc.
  User rubber-bands a region --> chart zooms to that data range.

  Programmatic zoom (Pesgo):
    PeGrid.Zoom.MinX = startValue;
    PeGrid.Zoom.MaxX = endValue;
    PeGrid.Zoom.MinY = bottomValue;
    PeGrid.Zoom.MaxY = topValue;
    PeGrid.Zoom.Mode = true;   // activates zoom
    PeFunction.ReinitializeResetImage();

  PROGRAMMATIC ZOOM + MULTIAXESSUBSETS:
    When using MultiAxesSubsets, programmatic ZoomMode = true IS supported
    but ONLY for horizontal zooming. The constraint:
      - AllowZooming MUST be set to AllowZooming.Horizontal (not HorzAndVert)
      - ZoomMinX / ZoomMaxX work normally (X-axis is shared across all axes)
      - ZoomMinY / ZoomMaxY CANNOT meaningfully address multiple independent
        Y-axis scales, so vertical zoom extents are not usable
    This is a common customer pattern: automating focus to a data region
    (e.g., most recent window, anomaly region, specific time range).
    Example 124 demonstrates this pattern.

    Key code pattern:
      Pesgo1.PeUserInterface.Allow.Zooming = AllowZooming.Horizontal;
      Pesgo1.PeUserInterface.Scrollbar.ScrollingHorzZoom = true;
      Pesgo1.PeGrid.Zoom.MinX = 40000;
      Pesgo1.PeGrid.Zoom.MaxX = 60000;
      Pesgo1.PeGrid.Zoom.Mode = true;
      Pesgo1.PePlot.ZoomWindow.Show = true;  // overview strip
      Pesgo1.PeFunction.ReinitializeResetImage();

  Undo: PeFunction.UndoZoom()
  Reset: PeGrid.Zoom.Mode = false + reinitialize

ZOOM WINDOW (overview strip -- do NOT confuse with zoom mode):
  PePlot.ZoomWindow is a VISUAL FEATURE -- a miniature overview panel
  at the bottom of the chart showing the full data range with a
  highlighted box indicating the current zoom region.
  This is purely a UI element. It does NOT control axis scaling.
  PePlot.ZoomWindow.Show = true -- shows overview when zoomed
  PePlot.ZoomWindow.ShowXAxis -- show X-axis labels in overview
  PePlot.ZoomWindow.Height -- proportion of total height (default 0.12)
  PePlot.ZoomWindow.SubsetsToShow -- filter which subsets appear
  PePlot.ZoomWindow.PlottingMethods -- override plotting style
  PePlot.ZoomWindow.CustomGridNumbersX -- enable custom grid numbers

PEGO SCROLL (point-based scrolling):
  Pego doesn't zoom numerically -- it scrolls through points.
  PeUserInterface.Scrollbar.PointsToGraph = N (visible window size)
  PeUserInterface.Scrollbar.HorzScrollPos = startIndex

  MouseWheel: MouseWheelFunction enum controls wheel behavior
  (scroll, zoom, or disabled).

MOUSEWHEEL ZOOM -- REQUIRED SCROLLBAR FLAGS:
  MouseWheelFunction controls what the wheel does, but the scrollbar
  infrastructure must also be armed or the wheel has nothing to act through.
  Always pair MouseWheelFunction with the matching Scrollbar flags:

    MouseWheelFunction.HorizontalVerticalZoom:
      ScrollingHorzZoom = true
      ScrollingVertZoom = true

    MouseWheelFunction.HorizontalZoom:
      ScrollingHorzZoom = true

    MouseWheelFunction.VerticalZoom:
      ScrollingVertZoom = true

  WITHOUT THE FLAGS: only one axis zooms, or zoom-out does not work.

  WHY THIS IS EASY TO MISS: The demo app's CreateSimpleSGraph sets
  AllowZooming = HorzAndVert which internally activates the scrollbar
  infrastructure. When example 110 then overrides with AllowZooming.None,
  the infrastructure stays armed. Standalone projects that start with
  AllowZooming.None never pass through HorzAndVert, so the flags must
  be set explicitly. This is a future engine improvement candidate --
  setting MouseWheelFunction should auto-enable the matching flags.

ZOOM EVENTS:
  PeBeforeZoom -- fires before zoom, can cancel via e.Cancel = true
  PeAfterZoom -- fires after zoom completed
  Access zoom extents in event handler to sync external UI.

KEY: pe_query.py props "AllowZooming,ZoomMode"
  pe_query.py enum "AllowZooming"
  pe_query.py recipe "zoom"