Charts-kt visual elements

This guide details the terms used for every visual element, note that these elements are tightly tied to the chart's DSL, so knowing them helps you build charts faster.

The chart

Charts-kt%20visual%20elements%20db643a2602f34bcf81cb1551327b171f/Untitled.png

The Chart is the main visual container. The Charts.kt DSL reflects this by making Chart the root element of every visualization.

private fun VizContainer.createChart(data: List<Record>): Chart<Record> = chart(data) { // all your chart's code goes here }

The mark

A Mark is a way to represent data, for example, Line, Column, Area... In the previous image, the mark is a PlotMark, a mark used to create a scatter plot.

There can be several marks in a Chart like in this image, a BarMark (in blue) and a LineMark (in black):

Charts-kt%20visual%20elements%20db643a2602f34bcf81cb1551327b171f/Untitled%201.png

private fun VizContainer.createChart(data: List<Record>): Chart<Record> = chart(data) { (...) // your first "mark" is a BarMark bar(dimension1, dimension2) // your second "mark" is a LineMark, note that it share the same X-dimension line(dimension1, dimension3) }

The marker

In this documentation, we'll sometimes refer to a marker.

The marker is the visual representation that a Mark draws to display a single element.

In a scatterplot, the marker would be a single "plot", for a bubble chart, each unique bubble would also be called a marker.

The mark decorator

You may also hear in this doc about mark decorators. Mark decorators are functions that are used to draw each marker and which you can overload with your code to draw custom decorations (annotations, labels, ...)

Charts-kt%20visual%20elements%20db643a2602f34bcf81cb1551327b171f/Untitled%202.png

Mark decorators are an easy and quick way to customize your chart, if you want more information about mark decorators you can have a look at this detailed guide: How-to customize a Mark?

The axis

The axis is composed of several parts you can customize:

  • the title
  • the ticks
  • the axis line
  • the labels

Charts-kt%20visual%20elements%20db643a2602f34bcf81cb1551327b171f/image.png

You can also place it at different position (top, left, right...).

You can also choose from the axis to display in the charting zone "gridlines" or "alternate background" to help with reading the chart. They will be placed based on the ticks values from your axis.

Look at this chart, it's the same as the previous one, but with a different theme, not that for the Y-axes:

  • axis lines and ticks are disabled
  • gridlines are enabled

Charts-kt%20visual%20elements%20db643a2602f34bcf81cb1551327b171f/Untitled%203.png

The title

Once you set a title value to your chart, a title will be displayed at the top position by default.

Don't forget that you're in Kotlin code, so you can display any information you want.

To change your title properties, you can use your own custom configuration, or change it inline, in the config block:

Charts-kt%20visual%20elements%20db643a2602f34bcf81cb1551327b171f/Untitled%204.png

private fun VizContainer.createChart(data: List<Record>): Chart<Record> = chart(data) { title = "Self-Reports of Height and Weight (${data.size} records)" config { title { layout = LayoutPosition.Bottom fontColor = Colors.Web.darkred fontSize = 14.0 } } (...) }

The legend

You can enable a legend in your chart, to display informations about your series.

By default, the legend is placed in the chart where there is enough space to display it, but, in the config DSL, you can force the legend to be displayed "outside" the charting zone at a given position, like here at the bottom of the chart:

Charts-kt%20visual%20elements%20db643a2602f34bcf81cb1551327b171f/Untitled%205.png

private fun VizContainer.createChart(data: List<Record>): Chart<Record> = chart(data) { (...) config { legend { show = LegendVisibility.Show layout = LegendLayout.Horizontal position = LegendPosition.Bottom } } }

The tooltip

The tooltip is used to display information when highlighting markers.

By default, your tooltip will use available information like dimensions' names and formatters to display itself automatically:

Charts-kt%20visual%20elements%20db643a2602f34bcf81cb1551327b171f/Untitled%206.png

However, it is possible to override every aspect of the tooltip and use it to display your own custom information using custom formatters:

Charts-kt%20visual%20elements%20db643a2602f34bcf81cb1551327b171f/Untitled%207.png

private fun VizContainer.createChart(data: List<Record>): Chart<Record> = chart(data) { (...) tooltip { formatter = { "${domain.name} ${domain.age} years, ${domain.gender}," +" ${domain.weight} kg. / ${domain.height} cm." } } }

The cursor

The cursor is used to identify a highlighted marker, it enhances greatly the readability of your chart when there is a lot of information on the screen.

A cursor can be horizontal, vertical or both (crosshair), depending on the chart type, the cursor automatically switch to the the best option, but you can change it in the config DSL:

Charts-kt%20visual%20elements%20db643a2602f34bcf81cb1551327b171f/Untitled%208.png

private fun VizContainer.createChart(data: List<Record>): Chart<Record> = chart(data) { (...) config { cursor { show = true type = CursorType.Vertical strokeColor = Colors.Web.red strokeWidth = 2.0 } } }