plot-container – Embed plot snips to GUI applications
1 plot-container% Class
class is a GUI container that can be used to
objects such as plots produced by plot-snip
GUI applications. It supports building interactive GUI applications which
display different types of data, for example, when plot snips are combined
with using set-mouse-event-callback
on-hover callbacks for the plots. The container has the following features:
will be arranged either using a specified layout (see
) or, by default, in rows and columns such that
each occupy an equal amount of space – i.e. all snips have the same size.
The snips will be resized dynamically if the container itself changes size
or new snips are added. The number of columns is specified when the
is instantiated and the number of rows will be
calculated based on the number of snips and the column count. The plot
snips must be any snip%
, but this container class was originally
intended to display plots produced by plot-snip
, thus its name.
Plot snips can be added to the container using set-snip
will show up on top of the plot snips and are not
placed in rows and columns, instead the user can drag them around and they
can be used to display additional information, such as a plot legend. Use
to add floating snips. Just as with the plot snips, any
object is a valid floating snip, in particular
instances are useful for constructing images based on
the pict package.
A Background Message
can be set up to be shown when the plot
container is empty, see set-background-message
This is useful, as the contents of the plot container can be changed
dynamically at runtime.
A Floating Snip
can be added using set-hover-pict
This is intended to support implementing tooltips or displaying additional
information when the user hovers the mouse over various plot elements.
Create a new instance of a plot-container%
which will arrange
objects in columns
pixels between them. The number of rows will be
determined by the number of plot snips added. Additional init argyments
can be passed in, they will all go to the editor-canvas%
see its documentation for what options are available.
background-message represents the message to be shown when there
are no snips in the container. It can be changed using
Return the dimensions of a plot snip when this plot-container%
would hold snip-count
snips. The dimensions will be calculated
based on the current size of the canvas plus the number of columns and
spacing between snips.
This method can be used to construct the plot snip instances with the
correct dimensions and avoid a snip resize operation when these snips are
added to the container.
WARNING: The cell dimensions are only valid if the snips are
arranged in rows and columns by calling set-snips. If a layout is used, using set-snips/layout, the cell dimensions returned by this method will not
correspond to the ones assigned to the snips in the layout.
Clear all snips from the container.
Set snip as the only snip managed by the container, replacing any
previous plot snips.
Set the contents of the container to the snip instances passed in
as paramters, replacing any previous plot snips.
Set the contents of the container to the group
, which is a group
of snips created using hgroup
. This method allows subdividing the contents of the
container area in a tree-like fashion.
Add snip as a floating snip to the container and place
it at x, y. Any previous floating snips will be kept as
Remove all existing floating snips, than add snip as a
floating snip to the container and place it at x,
Set a message to be displayed in the plot container when it
contains no snips at all. If the message is #f, no message will
Set pict to be displayed at locations x, y, or
hide the pict when #f. The pict will be displayed on top of all
other snips in the container and can be used to implement tool tips for
the contents of the container.
at the location of the mouse event
method will take the mouse event coordinates, convert them to plot
container coordinates and call set-hover-pict
Arrange all item
s with a border
around all the group and
space between items. All items will have the same
dimensions and any plot-container-group?
items will have this space
sub-divided among the items in that group. The result of these functions
are intended to be passed to set-snips/layout
vgroup will place items in one vertical column with the height
equally divided between all items.
hgroup will place items in one horizontal row with the width
equally divided between all items.
cgroup will place all items in columns, with the number of
rows depending on the number of itmes. The width is divided equally between
the number of columns and the height is divided equally between the number
2 Some utility functions to use with plots and plot containers
This module provides a collection of helper functions for building interactive
plots. The plot-snip function returns a snip% representing
the plot, and this snip has two additional methods, set-mouse-event-callback and set-overlay-renderers,
which help with this. See the plot documentation for 2d-plot-snip%
for more details.
Return #t when the x, y and event passed
to a plot snip mouse callback are valid, and hover information should be
displayed for the point at x, y.
The parameters are considered valid when the coordinates x and
y are not #f, the mouse event is a motion event and the
plot snip is directly under the mouse with no other snips above it.
The x, y coordinates can be #f when they are
inside the plot snip but not on the plot itself, for example in the axes
This function encapsulates all the logic on whether to add or clear overlay
renderers from a plot, and allows writing hover callbacks in the following
Convert the xposition received by the hover callback in a histogram
plot back to the series and the slot withing that series. skip and
gap are the #:skip and #:gap arguments passed to
the discrete-histogram renderer, they default to
discrete-histogram-gap and discrete-histogram-skip
parameters, just as they do for the discrete-histogram renderer.
Returns two values, the series, when multiple historams are plotted and the
slot within that histogram. Will return (values #f #f) if the X
position is between the bars of the histogram.
Return the location of snip
as a (cons X Y)
, or return
is not added to an editor.
Together with move-snip-to, this function can be used to retrieve
and save the location of any hover snips in a plot-container% and
restore them at a later time.
, adjusting it as necessary to remain
fully visible inside the canvas. This is intended to be used with locations
retrieved by get-snip-location
and unlike the
, this function will
adjust the location so that the snip visible in the container – this is
useful if the container has changed size since the location was retrieved
Assumes the snip is added to an editor.