Class ArberChartPanel

java.lang.Object
java.awt.Component
java.awt.Container
javax.swing.JComponent
javax.swing.JPanel
com.arbergashi.charts.ui.ArberChartPanel
All Implemented Interfaces:
ImageObserver, MenuContainer, Serializable, Accessible
public class ArberChartPanel extends JPanel

ArberChartPanel

High-performance Swing panel for rendering charts with multiple layers. This panel is the primary UI component of the framework.

Key Features:

  • Multi-Layer Architecture: Supports overlays and multiple series (e.g., candles + indicators).
  • Zero-Allocation Rendering: Optimized paint loop to minimize GC pressure.
  • Smart Hit-Testing: Snapping and multi-series tooltips.
  • Theming: Integrated with ChartTheme for dark/light mode support.
  • Interactive Navigation: High-precision zooming and panning.
  • Export & Tools: Context menu for exporting to PNG/SVG/PDF and resetting view.
Since:
2024-06-01
Version:
1.0.0
Author:
Arber Gashi
See Also:

  • Constructor Details

    • ArberChartPanel

      public ArberChartPanel(ChartModel initialModel, ChartRenderer initialRenderer)
      Creates a new high-performance chart panel with an initial dataset.
      Parameters:
      initialModel - The primary data model to display.
      initialRenderer - The renderer responsible for visualizing the data.

  • Method Details

    • addLayer

      public void addLayer(ChartModel model, ChartRenderer renderer)
      Adds a new data series to the chart.

      The chart supports stacking multiple layers. Each layer consists of a data model and a renderer. Layers are drawn in the order they are added (Painter's Algorithm).

      This method is safe to call on the EDT only; it triggers repainting.

      Parameters:
      model - The data model containing the series data.
      renderer - The renderer used to visualize this specific series.

    • addOverlay

      public void addOverlay(ChartRenderer renderer)
      Adds an overlay renderer that uses the PRIMARY model (the first one added).

      This is useful for technical indicators (e.g., Moving Averages, Regression Lines) that are derived from the main dataset but require a separate rendering pass.

      Overlay renderers share the primary model and are drawn as additional layers.

      Parameters:
      renderer - The overlay renderer.

    • clearLayers

      public void clearLayers()
      Removes all layers and clears the chart.

      Listeners are removed and the panel is repainted.

    • setMultiColorEnabled

      public void setMultiColorEnabled(boolean enabled)
      Enables or disables multi-color mode on renderers that support it.
      Parameters:
      enabled - true to enable multi-color rendering

    • updateUI

      public void updateUI()
      Overrides:
      updateUI in class JPanel

    • isOptimizedDrawingEnabled

      public boolean isOptimizedDrawingEnabled()
      Overrides:
      isOptimizedDrawingEnabled in class JComponent

    • doLayout

      public void doLayout()
      Overrides:
      doLayout in class Container

    • paintComponent

      protected void paintComponent(Graphics g)
      Render order: background fill -> grid layer -> data layers -> overlays.
      Overrides:
      paintComponent in class JComponent

    • withGridLayer

      public ArberChartPanel withGridLayer(GridLayer gridLayer)
      Sets the grid layer for this chart.
      Parameters:
      gridLayer - The grid layer to use (e.g., DefaultGridLayer or MedicalGridLayer).
      Returns:
      This panel for chaining.

    • getTheme

      public ChartTheme getTheme()
      Returns the current theme of this chart panel.

    • setRenderHints

      public ArberChartPanel setRenderHints(ChartRenderHints renderHints)
      Sets rendering hints for this panel.

    • withTheme

      public ArberChartPanel withTheme(ChartTheme theme)
      Sets the theme for this chart panel and propagates it to all existing renderers.

      Runtime Theme Switching: This method can be called at any time to change the visual appearance dynamically (e.g., Dark ↔ Light mode). All layers will be updated immediately, and the panel will repaint.

      Parameters:
      theme - The theme to apply. Must not be null.
      Returns:
      This panel for chaining.
      Throws:
      NullPointerException - if theme is null.

    • withLocale

      public ArberChartPanel withLocale(Locale locale)
      Sets the locale used for formatting axis labels and tooltips.
      Parameters:
      locale - locale to apply (null resets to JVM default)
      Returns:
      this panel for chaining

    • withTooltips

      public ArberChartPanel withTooltips(boolean enabled)
      Enables or disables tooltips.
      Parameters:
      enabled - True to enable tooltips, false to disable.
      Returns:
      This panel for chaining.

    • withLegend

      public ArberChartPanel withLegend(boolean visible)
      Controls the visibility of the chart legend.
      Parameters:
      visible - True to show the legend, false to hide it.
      Returns:
      This panel for chaining.

    • withLegendConfig

      public ArberChartPanel withLegendConfig(LegendConfig config)
      Configures legend placement.

      This is the recommended API for professional applications that need either an overlay legend or a docked legend outside of the plot area.

      Parameters:
      config - legend configuration (null uses defaults)
      Returns:
      this panel for chaining

    • withDockedLegend

      public ArberChartPanel withDockedLegend(LegendDockSide side)
      Convenience helper to dock the legend to a side.
      Parameters:
      side - dock side
      Returns:
      this panel for chaining

    • withOverlayLegend

      public ArberChartPanel withOverlayLegend(LegendPosition pos)
      Convenience helper to use overlay legend at a position.
      Parameters:
      pos - overlay position
      Returns:
      this panel for chaining

    • withAnimations

      public ArberChartPanel withAnimations(boolean enabled)
      Enables or disables smooth animations for zoom and pan operations.

      When enabled, zoom operations will use AnimationUtils for smooth eased transitions. Default is true.

      Parameters:
      enabled - true to enable animations, false for instant updates.
      Returns:
      This panel for chaining.

    • withXAxisConfig

      public ArberChartPanel withXAxisConfig(AxisConfig config)
      Configures the X-axis behavior and formatting.
      Parameters:
      config - axis configuration (null uses defaults)
      Returns:
      this panel for chaining

    • withYAxisConfig

      public ArberChartPanel withYAxisConfig(AxisConfig config)
      Configures the Y-axis behavior and formatting.
      Parameters:
      config - axis configuration (null uses defaults)
      Returns:
      this panel for chaining

    • resetZoom

      public void resetZoom()
      Resets the zoom to fit all data.

    • export

      public void export(File file)
      Exports the current chart view to a file.
      Parameters:
      file - The output file.

    • getLayerCount

      public int getLayerCount()
      Returns the number of render layers in this chart.
      Returns:
      the number of layers

    • isLegendVisible

      public boolean isLegendVisible()
      Checks if the legend is currently visible.
      Returns:
      true if the legend is visible, false otherwise

    • exportAs

      public void exportAs(String format)
      Exports the chart to a file in the specified format via the configured export handler. Supported formats: PNG, SVG, PDF.

      An export handler must be configured via withExportHandler(ChartExportHandler) before calling this method.

      Parameters:
      format - the export format ("png", "svg", or "pdf")
      Throws:
      IllegalStateException - if no export handler is configured

    • withExportHandler

      public ArberChartPanel withExportHandler(ChartExportHandler handler)
      Sets the export handler used by export actions.
      Parameters:
      handler - export handler (may be null to disable exports)
      Returns:
      this panel for chaining

    • addNotify

      public void addNotify()
      Overrides:
      addNotify in class JComponent

    • getLayerVisibilityModel

      public LayerVisibilityModel getLayerVisibilityModel()
      Returns the visibility model used by the interactive legend.
      Returns:
      layer visibility model