Skip to main content

2.0.0-beta.1

This release includes bug fixes and API enhancements.

Breaking changesAddressed
Moderate#856, #865
warning

The views module’s minimum SDK version has been raised to 21, as Appcompat now requires this. Since compose already had such a minimum SDK version, and core is intended for use with compose or views, the minimum SDK version of core has been raised to the same value.

Some APIs have been renamed, moved, or removed in favor of others:

2.0.0-alpha.282.0.0-beta.1
cartesian.HorizontalInsetscommon.HorizontalInsets
cartesian.Insetscommon.Insets
ChartInsetterCartesianLayerInsetter
Dimensions.ofdimensions
Shape.PillCorneredShape.Pill
Shape.cutCorneredShape.cut
Shape.dasheddashedShape
Shape.markerCorneredmarkerCorneredShape
Shape.roundedCorneredShape.rounded
rememberBottomAxisHorizontalAxis.rememberBottom
rememberCandleCandlestickCartesianLayer.Candle constructor
rememberEndAxisVerticalAxis.rememberEnd
rememberHorizontalBoxHorizontalBox constructor
rememberHorizontalLineHorizontalLine constructor
rememberLineLineCartesianLayer.rememberLine
rememberPointLineCartesianLayer.point
rememberShadowshadow
rememberStartAxisVerticalAxis.rememberStart
rememberTopAxisHorizontalAxis.rememberTop

All deprecated APIs have been removed.

AxisValueOverrider is now called CartesianLayerRangeProvider, and the axisValueOverrider parameters and properties have been renamed to rangeProvider.

AxisValueOverrider.adaptiveYValues has been removed due to being overly specific for a built-in factory function (primarily in terms of rounding). Migrate by creating a suitable CartesianLayerRangeProvider implementation. For example, the following sets the maximum y value to the default multiplied by 1.5 and rounded to the nearest whole number:

object : CartesianLayerRangeProvider {
    override fun getMaxY(minY: Double, maxY: Double, extraStore: ExtraStore) =
        ceil(1.5 * maxY)
}

ChartValues is now called CartesianChartRanges. In CartesianMeasuringContext, ranges replaces chartValues. Unlike ChartValues, CartesianChartRanges has no model property—use the new CartesianMeasuringContext.model property instead.

CartesianValueFormatter.format has a new signature—use context.ranges and context.model instead of chartValues. Also, empty HorizontalAxis and VerticalAxis labels are no longer permitted—an exception occurs when such a label is detected. As described in the wiki, you should use HorizontalAxis.ItemPlacer and VerticalAxis.ItemPlacer to customize for what x and y values labels and lines are displayed. Utilizing empty strings instead could produce undesirable results, including unexpected label truncation.

HorizontalLayout and HorizontalAxis.ItemPlacer.default have been replaced by three new APIs:

  • CartesianLayerPadding, which lets you add scalable and unscalable CartesianLayer padding
  • HorizontalAxis.ItemPlacer.aligned, which is used by default and places items as HorizontalAxis.ItemPlacer.default did with HorizontalLayout.FullWidth
  • HorizontalAxis.ItemPlacer.segmented, which places items as HorizontalAxis.ItemPlacer.default did with HorizontalLayout.Segmented

Instantiate CartesianLayerPadding via the cartesianLayerPadding function.

The horizontalLayout parameter of rememberCartesianChart has been replaced by a layerPadding parameter. Similarly, in CartesianMeasuringContext, the horizontalLayout property has been replaced by a layerPadding property.

How to migrate to the new APIs depends on what HorizontalLayout you have applied. Start by removing the code that applies the HorizontalLayout (if such code is present). Then, add the appropriate amount of CartesianLayer padding:

  • Case A:
    1. Determine the greatest of the following, depending on what CartesianLayers your CartesianChart has: CandlestickCartesianLayer.candleSpacingDp (default: 4), ColumnCartesianLayer.columnCollectionSpacingDp (default: 32), and LineCartesianLayer.pointSpacingDp (default: 32).
    2. Let p be half of the value from step 1.
    3. Using the CartesianLayerPadding APIs, apply p dp of scalable padding on either end.
  • Case B: Use CartesianLayerPadding to apply the same amount of padding as previously.
  • Case C: Do nothing.

If there are HorizontalAxis instances, do the following for each one:

  • Case A: Use HorizontalAxis.ItemPlacer.segmented().
  • Case B: Do nothing.
  • Case C: Modify the HorizontalAxis.ItemPlacer for compatibility with the API changes.
  • Case D: Use HorizontalAxis.ItemPlacer.segmented. If shiftExtremeTicks was set to false, set shiftExtremeLines to false.
  • Case E: There’s no longer built-in spacing and offset customization for the segmented style. This is because the two aren’t entirely compatible. In particular, with the segmented style, there’s no reasonable way to reflect spacing and offset customization in tick and guideline positioning—which is why previously, with HorizontalLayout.Segmented, it affected only labels. Generally, the only instance in which this setup produced a desirable result was when no ticks or guidelines were present, and in such cases, you can migrate as described below. In the unlikely event that you’re setting offset to a value other than 0 or spacing to a value other than 1, and your HorizontalAxis does have ticks or guidelines, migrate by creating a suitable HorizontalAxis.ItemPlacer implementation. (You can do so easily by copying and modifying the SegmentedHorizontalAxisItemPlacer definition. Also copy this code, which SegmentedHorizontalAxisItemPlacer uses. All that’s required is updating the calls to CartesianDrawingContext.getLabelValues, which has offset and spacing parameters.)
  • Case F: Use HorizontalAxis.ItemPlacer.aligned, using the same arguments as previously. Note that shiftExtremeTicks is now called shiftExtremeLines, and the default value of addExtremeLabelPadding is now true.

An issue where a LineCartesianLayer-related IllegalArgumentException could occur in composable previews has been addressed. The root cause is a bug in the preview renderer—we’ve worked around it.