There is a limit to how much one can do with step_shape callback.
By its nature it can only have three parameters, and that list
can't be extended, because the user is expected to set
the property to a function from gears.shape, all of which have
different meanings for parameters past the first 3.
Moreover step_shape requires the current coordinate system
to be modified accordingly because it draws the shape at (0,0).
Lastly it's not expected to handle NaN heights and thus is
never called for NaN values.
This makes it hard to implement things like the following:
1) drawing steps which depend on knowing their position
relative to other steps. (e.g. connecting data points with
bezier curves)
2) drawing steps while appropriately handling NaN values in
any way other than not drawing anything, which might be still
wrong or not sufficient. (e.g. interpolating data points
requires to know *where* there are gaps in data, not simply
continuing with the next present value)
3) drawing steps that need the knowledge of the exact value
that is being drawn (e.g. drawing value tooltips over bars)
The step_hook callback (name bikeshedding welcome) is designed
to solve the problems (for now only the first two of the 3).
Whenever it's set, it takes precedence over step_shape property
and is used to draw steps.
No coordinate transformation before calling it takes place
like for step_shape(). The (0, 0) is always the top-left corner
of the graph drawing area (sans borders), when it's called.
In contrast to step_shape() which only accepts three parameters
(cairo, width, height), step_hook() accepts
(cairo, x, y, baseline_y, step_width, options).
(x, y) is what would be (0, 0) in step_shape, i.e. the
coordinates of the bar top. The y parameter can be NaN,
and step_hook() is expected to handle that.
baseline_y is the y coordinate of the bar bottom.
(baseline_y - y) is what is known as `height` in step_shape.
But note that baseline_y is never NaN, so even in the
NaN case step_hook() can at least know where the baseline is.
step_width is the bar's width, just like in step_shape.
options is the same table that is passed to the
group_start()/group_finish() callbacks, it contains
some useful data for nontrivial drawing needs and it could be
extended later with more useful data at leisure,
e.g. with `value`, if such need arises, without fear of
coming in conflict with other user's parameters.
3e3b0ca9de