# Copyright (c) 2025-2026 Gigasoft, Inc. All rights reserved. === ProEssentials Legends (knowledge rev 4.2) === ProEssentials legends display subset labels with their visual identifiers (colors, line types, point symbols). Configuration is under PeLegend. LEGEND STYLE (LegendStyle enum -- Pego, Pesgo, Pe3do): PeLegend.Style = LegendStyle.xxx; TwoLine (0) -- symbol above, text below (default) OneLine (1) -- symbol and text on single line OneLineInsideAxis (2) -- inside the graph area per-axis OneLineTopOfAxis (3) -- between axis regions (SeparateAxes only) OneLineInsideOverlap (4) -- inside graph, compact overlap OneLineLeftOfAxis (5) -- to the left of axis area Pepso uses SimpleLegendStyle enum (TwoLine=0, OneLine=1 only). OneLineInsideAxis is ideal for multi-axis SeparateAxes layouts -- each axis section gets its own legend showing only its subsets. LEGEND LOCATION (LegendLocation enum -- all chart objects): PeLegend.Location = LegendLocation.xxx; Top (0), Bottom (1), Left (2), Right (3) OneLine style only works with Top and Bottom locations. Left/Right locations use TwoLine layout regardless of Style setting. LEGEND VISIBILITY: PeLegend.Show = true/false -- master show/hide LEGEND APPEARANCE: PeLegend.SimplePoint = true -- draw point symbol only (no bounding box) PeLegend.SimpleLine = true -- simpler line representation PeLegend.AllowLargerLegendWidth = 250 -- pixel threshold below which top/bottom legend uses full control width instead of grid-justified PeString.SubsetLabels[s] = "Series Name" -- text per subset PeLegend.SubsetLineTypes[s] -- LineType enum per subset in legend PeLegend.SubsetPointTypes[s] -- PointType enum per subset in legend SUBSET ORDERING AND FILTERING: SubsetsToLegend -- controls which subsets appear and their ORDER in legend: PeLegend.SubsetsToLegend[i] = subsetIndex; If empty, all subsets appear in default order. Fill with zero-based subset indices to filter and/or reorder. Example -- show only subsets 0 and 2, in that order: PeLegend.SubsetsToLegend[0] = 0; PeLegend.SubsetsToLegend[1] = 2; INDEPENDENT CONTROL -- plotting order, legend order, and table order are three independently controllable dimensions: PeData.RandomSubsetsToGraph -- controls draw order and visibility PeLegend.SubsetsToLegend -- controls legend order and visibility PeTable.SubsetsToTable -- controls table order and visibility (Pego only) Example 033 demonstrates reversing stacked bar draw order (3,2,1,0) while keeping legend and table in natural order (0,1,2,3). SubsetsToShow -- simpler visibility + draw order control: PeData.SubsetsToShow[subsetIndex] = priority; // 0--9 0 = hidden, 1--9 = visible, higher values drawn first (behind). Applies to: Pego, Pesgo, Pepso. Easier than RandomSubsetsToGraph for basic show/hide needs. RandomSubsetsToGraph -- older, more explicit visibility control: PeData.RandomSubsetsToGraph[i] = subsetIndex; Lists subset indices to include. Order controls draw order. Applies to: Pego, Pesgo, Pepso. Related to ScrollingSubsets for permanent vs. scrollable subsets. LEGEND REPLACEMENT VIA VERTICAL GRID NUMBERS (Pego, Pesgo): When using overlapped multi-axes, a traditional legend can be confusing because multiple subsets share the same visual space. Example 129 demonstrates replacing the legend entirely with colored axis labels that include embedded point symbols. REQUIRED PROPERTY CONSTELLATION: PeGrid.Option.YAxisVertGridNumbers = true; -- rotates Y-axis grid numbers to vertical orientation, freeing horizontal space normally consumed by the axis label PeGrid.Option.VgnAxisLabelLocation = true; -- moves YAxisLabel to the TOP of each axis instead of the side, where it serves as a compact per-axis legend entry PER-AXIS LABEL WITH EMBEDDED SYMBOL (pipe code): PeString.YAxisLabel = "Subset 1|4"; The |N suffix embeds the GraphAnnotationType symbol N (integer value) as a colored marker inline with the label text. Common values: |4 = DotSolid, |6 = SquareSolid, |8 = DiamondSolid, |10 = UpTriangleSolid, |12 = DownTriangleSolid The symbol inherits its color from PeColor.YAxis for that axis. COLOR MATCHING: PeGrid.WorkingAxis = i; PeColor.YAxis = PeColor.SubsetColors[i]; This makes the axis label, grid numbers, and embedded symbol all match the subset's plot color -- creating an implicit per-axis legend. COMPLEMENTARY SETTINGS: PeLegend.Show = false -- suppress the now-redundant legend PeGrid.Option.ShowYAxis = ShowAxis.GridNumbers -- numbers only PeGrid.Option.ShowRYAxis = ShowAxis.GridNumbers -- same for RY PeString.TextShadows = TextShadows.NoShadows -- cleaner vertical text PeColor.TickColor = Color.FromArgb(0,1,0,0) -- hide ticks (PE empty) PeConfigure.ImageAdjustLeft/Right = 50 -- extra margin space See Example 129 for complete implementation. NOTE: The |N pipe code on YAxisLabel only works when YAxisVertGridNumbers = true AND VgnAxisLabelLocation = true. Without both properties, the symbol will not render properly. LEGEND ANNOTATIONS (custom items added to legend area): Beyond standard subset legends, you can add arbitrary custom entries with their own symbols, text, and colors: PeLegend.AnnotationType[i] = (int)LegendAnnotationType.xxx; PeLegend.AnnotationText[i] = "Custom Label"; PeLegend.AnnotationColor[i] = Color.FromArgb(255, r, g, b); LegendAnnotationType uses same symbols as GraphAnnotationType. BITMAP LEGEND ANNOTATIONS: Resource Bitmaps can serve as legend annotation symbols by setting AnnotationType to (10001 + bitmapIndex): PeLegend.AnnotationType[i] = 10001; PeLegend.AnnotationText[i] = "Custom Label"; PREREQUISITE: the bitmap slot must already be registered, by either a graph annotation (PeAnnotation.Graph.Type) or a SubsetPointTypes / PointTypes assignment using that slot. Set legend bitmap AnnotationType AFTER the registering assignment. Non-colorized (ColorizeMode.None) bitmap legend annotations do not need AnnotationColor set. See pe-pointcolors for the full bitmap reference. REQUIREMENT: LegendAnnotations attach to the existing legend area -- they require a chart type/mode that natively produces a legend. If no legend is generated, there is nothing for them to attach to. Pe3do only produces a native subset legend in Scatter mode. Surface, ThreeDBar, and PolygonData modes do NOT generate a subset legend, so LegendAnnotations will not appear. For legends on Pe3do Bar charts, use ContourLegendII or Table Annotations instead -- see pe-pe3do-patterns knowledge file "LEGEND FOR 3D BAR CHARTS" section. Applies to: Pego, Pesgo, Pepso, and Pe3do Scatter mode only. Multi-axis targeting for legend annotations: PeLegend.AnnotationAxis[i] = axisIndex; // 0--15 Associates the annotation with a specific axis. If that axis is hidden or removed, the legend annotation also hides automatically. KEY: Always query exact paths before coding: pe_query.py enum "LegendStyle" pe_query.py enum "LegendLocation" pe_query.py props "SubsetsToLegend,SubsetsToShow,SubsetsToTable" pe_query.py props "LegendAnnotationType,LegendAnnotationText"