Skip to main content
Version: 2.0.0-beta.2

Introduction

CartesianCharts stack CartesianLayers. The three built-in CartesianLayers, all of which extend BaseCartesianLayer, are described on the following pages.

A CartesianChart’s x and y ranges depend on those reported by its CartesianLayers. The x range is the narrowest one that includes all CartesianLayers’ x ranges. By default, there’s an analogously determined shared y range.

verticalAxisPosition​

A CartesianChart can have two separate y ranges, one for the start VerticalAxis and one for the end VerticalAxis. (Technically, the presence of two VerticalAxis instances isn’t necessary, but it’s generally needed for unambiguity.) To utilize this functionality, use the verticalAxisPosition parameters and properties to assign each CartesianLayer an AxisPosition.Vertical subclass—either AxisPosition.Vertical.Start or AxisPosition.Vertical.End. The final y range for either AxisPosition.Vertical subclass is the narrowest range that includes the y ranges of all CartesianLayers linked to that AxisPosition.Vertical subclass. Thus, you get two independently scaled groups of CartesianLayers, and the two VerticalAxis instances are disconnected.

CartesianLayerRangeProvider​

What x and y ranges a CartesianLayer reports depends on its CartesianLayerRangeProvider.

Set a CartesianLayer’s CartesianLayerRangeProvider via the rangeProvider parameters of rememberCandlestickCartesianLayer, rememberColumnCartesianLayer, and rememberLineCartesianLayer.

A CartesianLayer passes its intrinsic x and y ranges—which depend on the CartesianLayerModel—to its CartesianLayerRangeProvider, and the CartesianLayerRangeProvider returns the final ranges for the CartesianLayer to report. There are two CartesianLayerRangeProvider factory functions:

For more specific behavior, create a custom implementation.

The default implementations of the CartesianLayerRangeProvider functions leave the x range unchanged but do these two things:

  • They ensure that the y range includes zero.
  • They apply a y range of [0, 1] if the minimum and maximum intrinsic y values are both zero.

This also applies to the CartesianLayerRangeProvider implementations returned by CartesianLayerRangeProvider.auto and AxisValueOverrider.adaptiveYValues. Custom CartesianLayerRangeProvider implementations can override this behavior. With CartesianLayerRangeProvider.fixed, minY and maxY take precedence.

warning

When using CartesianChartModelProducer, set each CartesianLayer’s CartesianLayerRangeProvider only once. There are no restrictions on dynamic behavior, but it should be implemented as part of a single CartesianLayerRangeProvider, not by means of an CartesianLayerRangeProvider-switching mechanism.

When you need to perform calculations based on the CartesianLayer’s intrinsic x and y ranges, use the values passed to the CartesianLayerRangeProvider functions. Beyond that, use extras if needed. These are important here not only for the usual synchronization reasons, but also because they’re updated via CartesianChartModelProducer.Transactions, and a CartesianChartModelProducer.Transaction is required for a CartesianChart’s x and y ranges to be updated.

A common use case for extras is switching between externally defined x and y ranges—both in synchronization with series updates and without series updates (e.g., in response to changes in user-accessible range settings).

It can be concluded that in CartesianChartModelProducer-powered charts, CartesianLayerRangeProvider.fixed should be used only for entirely static overrides.