Bars
To work with single bars, it's possible to use ChartBarsLayer as well as ChartPointsViewsLayer. It's of course recommended to use the dedicated bars layers but you may find situations sometimes where you need more flexibility and decide to create them just as generic views, using ChartPointsViewsLayer.
Bars example uses custom views instead of a dedicated bars layer just for demonstrative purposes. Bars +/- example uses a dedicated bars layer, to which it passes the +/- parts of the bars as individual bars (the gap in the middle is done by creating a white overlay using ChartPointsViewsLayer:
We will focus here on the dedicated bar layers.
To pass bars to ChartBarsLayer we use instances of ChartBarModel. A bar model is defined by:
-
constant: The domain value of the bar that doesn't change between top/bottom (or left/right). For a vertical bar this is the x domain coordinate, and for an horizontal bar this is the y domain coordinate. -
axisValue1,axisValue2: The first and last variable domain coordinate. For a left-to-right (horizontal) bar,axisValue1is the "left" x value,axisValue2is the right axis value, for a bottom-to-top (vertical) bar,axisValue1is the "bottom" y value andaxisValue2is the "top" y value.
Besides of the bars models and some other self explanatory parameters, we can pass following to bars layer:
-
tapHandler: This will be called when a bar is tapped, passing all relevant information, including the bar's view, so you can highlight, animate it, show an info bubble next to it, etc. -
mode: This defines how the bar views handle zooming - if they scale themselves or keep their size unchanged. Thecustommode is available but not supported for bars yet. For more details aboutmode, see https://github.com/i-schuetz/SwiftCharts/wiki/View-hierarchy-and-transforms#chartpointsviewslayer-transform-modes (this is from a different layer but everything applies, exceptcustommode). -
viewGenerator: This is in case you want to generate your own custom views for bars. This was added in0.6, which makes the alternative usage ofChartPointsViewsLayerto display bars in most cases unnecessary.
All the bar layers are focused only on displaying bars. To add labels you can use either a separate ChartPointsViewsLayer, to which you have to pass an array of chart points representing the edges of the bars where the labels should be placed (like it's done in +/- example), or GroupedBarsCompanionLayer when working with grouped bars (it currently requires the bars to be grouped and stacked, though this should be fixed as the stacked requirement isn't necessary. You can in the meantime model your grouped bars as grouped and stacked with only 1 stack frame). More about GroupedBarsCompanionsLayer in TODO.
To display stacked bars we use ChartStackedBarsLayer. It's also possible to use ChartGroupedStackedBarsLayer with groups containing only 1 bar, in case you want to keep your implementation generic, prepared for possible future scenarios where you need both.
ChartStackedBarsLayer is structured similarly to ChartBarsLayer, except of course that it has additional functionality to manage stack frames inside the bars. As models we use ChartStackedBarModel, which extends ChartBarModel from ChartBarsLayer. Here instead of passing axisValue1 and axisValue2, we pass start (which stands basically for axisValue1) and an array of ChartStackedBarItemModel, which represent the stack frames inside the bar. A ChartStackedBarItemModel has quantity and a color. quantity is simply the "length" of the frame in the bar, in domain coordinates. E.g. in the following chart:
The first bar model, from left to right, has 4 ChartStackedBarItemModels. The first ChartStackedBarItemModel is gray and has a quantity of 20. The second is blue and has a quantity of 60 (remember, this is the length of the frame, not the y position).
Similarly to ChartBarsLayer it's also possible to pass a selection handler, with provides data like the selected bar and stack frame, including the views, such that it's possible to show info overlays or animate the bars as well as individual stack frames. See stacked bars example (to which screenshot above belongs) for this.
For grouped plain bars you need ChartGroupedPlainBarsLayer. It's also possible to use ChartGroupedStackedBarsLayer with stack frames containing only 1 item, in case you want to keep your implementation generic, prepared for possible future scenarios where you need both.
This layer has the same features that can be found in plain bars layer + grouping capabilities.
Parameters:
barSpacing: Spacing between bars in a group, in pt.
groupSpacing: Spacing between groups, in pt.
barWidth: Width (or height in case of horizontal bars) of the bars.
ChartGroupedPlainBarsLayer offers 2 ways to setup the dimensions/spacing, via different initializers:
-
In terms of only spacing: you pass only
barSpacingandgroupSpacing.barWidthis derived from this and the available chart space. -
Spacing + fixed bar width: you pass
barSpacing,groupSpacingas well asbarWidth. The available space in the chart is ignored.
For grouped and stacked bars there's (surprise!) ChartGroupedStackedBarsLayer. There's nothing to say about this layer that can't be inferred from reading about the layers above, as it's only the sum of all features already described.
See view hierachy and transforms.
All bar layers allow to pass a generator that returns instances of ChartPointViewBar (or ChartPointViewBarStacked in the case of stacked bars), which extends UIView. You can subclass these classes to customize the views however you want, allowing to add e.g. outlines, patterns (e.g. for hatched bars) or any other kind of effect.
It's also possible to pass a tap handler to the bar layers initializer, which is a function that receives the tapped view as a parameter, allowing you to execute any kind of actions, like showing a tooltip or adding effects to the view (change its color, transform, etc). The stacked bars layers have an analogous additional tap handler for the stack frames.