The 3.0.0 release introduces hardware accelerated rendering. The existing API remains compatible; the changes in behavior are listed below, starting with the ones that may need attention when upgrading.
Migration notes
A page that embeds the visualization with default options and does not look at its canvases needs no changes. Check the following points if the page does more than that:
renderer defaults to
auto, which picks WebGL when it is hardware accelerated. Set renderer to
canvas to keep the previous renderer if the page:
uses canvas gradients or patterns in onBeforeGroupDrawn (WebGL accepts CSS color
strings only); reads pixels of the main canvas, in onRedraw or with
getContext("2d") (use imageData or onFrameDrawn instead);
tunes radialTextureStep, angularTextureStep or
textureOverlapFudge (they have no effect with WebGL); or compares screenshots pixel by
pixel (edges and labels are antialiased slightly differently).
pixelRatio defaults
to auto instead of 1, so on high-density screens the canvases are larger than the
element and more work is done per frame. Set pixelRatio to 1 for the previous
resolution and cost. Code that assumed the canvas size equals the element size should use the
pixelRatio reported in the layout attribute; pages that passed
window.devicePixelRatio can drop that.
minRadialPadding, minAngularPadding, the texture steps
or percentage font sizes at a pixel ratio of 2 will see them change; re-tune them against the new
picture. Changing pixelRatio no longer reloads the model, so nothing arrives in
onModelChanged on that occasion.
autoResize on by default, a
change of the container's size lays out and redraws the picture without a resize()
call. Pages that throttle resizing or deliberately keep the picture scaled should set
autoResize to false; plain resize() calls can stay.
dispose() does something now, and embedding a new visualization in an
element that holds one disposes of the previous instance, whose methods then do nothing. Pages
that re-embed into the same element and keep using the old instance need to switch to the new one.
selection, open and zoom given in the embedding
options take effect. They used to be ignored there, so a page that passed them by mistake
will now see them applied.
groupShape() returns undefined for unknown identifiers
instead of throwing; code that caught the exception should check the result.
carrotsearch.circles.asserts.js loaded, a dataObject with a group object
under two parents, or containing itself, is reported in the console and ignored. Such a model was
never drawn correctly; fix the data.
New features
The visualization can now be drawn with WebGL 2: groups, outlines and labels are rendered by
shaders on the graphics card. The new renderer attribute selects between
webgl, canvas (the software renderer of the previous versions) and
auto, the default, which uses WebGL when it is hardware accelerated. The
read-only activeRenderer attribute tells which renderer is in use and the
onRendererChanged event reports changes, including the automatic fallback to the
canvas renderer when WebGL is not available or its context is lost.
Setting renderer to svg draws the visualization as an SVG document, with
groups as paths and labels as text along arcs. It is meant for resolution independent output; it is
slower than the other renderers and is never chosen automatically. Safari renders right-to-left
scripts on curved labels in reversed order because of a WebKit bug in text on paths
(bug 275313); the other renderers
are not affected.
Two new effects for the WebGL renderer: explode3d for
pullbackAnimation breaks the
visualization into tiles that fly towards the viewer, implode3d for
rolloutAnimation assembles it the same
way. The other renderers play explode and implode instead, and
random does not pick the new effects.
onFrameDrawnA new event fired when a frame is completely drawn. It provides the canvas with the frame, so that the picture can be copied, with either renderer.
on(), off()New methods for adding and removing listeners of individual events without replacing the listeners already registered.
defaults
A new static property CarrotSearchCircles.defaults with the default values of all attributes.
isSupported()
A new static function CarrotSearchCircles.isSupported(options) tells whether a
visualization with the given options can be displayed: it returns false when the
browser has no 2D canvas, or when the options ask for the webgl renderer and WebGL
cannot be used. The static supported property, which only checks for a 2D canvas,
is deprecated in its favor.
dispose()
The dispose() method now releases all resources held by the visualization.
isGroupHoverable
A new callback that excludes individual groups from hovering: an excluded group gets no hover
outline, is left out of hierarchy outlines and is not reported by onGroupHover.
autoResize
The visualization now follows the size of its container element: a change of the element's
size lays out and redraws the picture, as a call to resize() did before. Pages that
size the visualization under program control can set the new autoResize attribute to
false; existing resize() calls are harmless either way.
Changes in behavior
The default pixelRatio is now auto: the visualization draws at the
browser's pixel ratio (window.devicePixelRatio) and follows its changes on
resize(), so that it is as sharp as the rest of the page on high-density screens
without any configuration. Pages that passed window.devicePixelRatio explicitly can
drop that; set pixelRatio to 1 to get the previous default, which is faster on
high-density screens at the cost of sharpness. The pixel ratio in effect is reported in the
layout attribute; get("pixelRatio") returns auto.
The layout no longer depends on pixelRatio: all sizes are in logical (CSS) pixels and
the pixel ratio only sets the resolution of the picture. Nothing changes at a pixel
ratio of 1. At other pixel ratios:
minRadialPadding, minAngularPadding, radialTextureStep,
angularTextureStep and textureOverlapFudge are now in logical pixels (they
used to be in physical pixels, so their effect shrank as the pixel ratio grew), and so are the
smallest label size and the distance groups travel in the explode, implode and rollout animations;groupMinFontSize, groupMaxFontSize,
titleBarMinFontSize and titleBarMaxFontSize are no longer multiplied
by the pixel ratio twice;onLayout and groupShape() may differ by a fraction
of a pixel, and the size of the canvas is rounded, not truncated;pixelRatio redraws the visualization without reloading the data model
(no rollout animation, no onModelChanged event).
resize() now reliably returns false when the size has not changed, also
at fractional pixel ratios.
The canvases of the visualization are now placed inside a wrapper div in the element the
visualization is embedded in. Style sheets or scripts that select the canvases as direct children of
that element need to be adjusted. With the WebGL renderer, the main canvas has a WebGL context
(a 2D context cannot be obtained from it) and the canvas element is replaced when the renderer changes.
dispose()
In previous versions dispose() did nothing. It now removes the visualization from
its element; methods of a disposed instance do nothing. Embedding a visualization in an element that
already contains one disposes of the previous instance.
The following only applies when the WebGL renderer is in use (set renderer to
canvas to get the previous behavior):
radialTextureStep, angularTextureStep and
textureOverlapFudge have no effect, labels are mapped onto groups exactly;textureMappingMesh shades the area of each label instead of drawing a mesh;onBeforeGroupDrawn must set groupColor to a CSS color string, canvas
gradients and patterns are not supported;onRedraw, use the
imageData attribute to get the picture;selection, open, zoom
These attributes now take effect when passed in the embedding options; previously they were
silently ignored there and only worked with set(). A specification given at embedding
time also no longer prevents the same specification from being applied with set() later.
groupShape()
Group shapes are available right after the layout, before the first redraw, and
groupShape() returns undefined for unknown group identifiers.
With carrotsearch.circles.asserts.js loaded, a dataObject that is not
a tree, with a group under two parents or among its own descendants, is reported in the
console, naming the group and where it appears, and ignored like any other invalid attribute.
The 2.3.10 release fixes zoom triangle drawing (triangles could be drawn outside their group area).
Bug fixes
Zoom triangles could extend beyond their group area. Zoom triangles are now drawn properly. An additional improvement includes drawing narrower zoom triangles if the zoomed group is very narrow itself.
The 2.3.9 release adds a few options to allow full customization of group selection and hover coloring.
New features
These two new options groupSelectionOutlineStyle and groupHoverOutlineStyle determine the shape drawn for selected and hovered-on groups. Please see examples in the API documentation for details.
An expert-level callback onBeforeGroupDrawn has been added to aid in situations when the default color model is not sufficient or needs to be changed in between group redraws. Please see examples in the API documentation for details.
The 2.3.8 release exposes Circles as an NPM dependency for modern software building systems.
New features
Starting with version 2.3.8, in addition to the conventional downloaded package, Circles is also available as an NPM dependency. Both the branded demo and the non-branded licensed builds are available in the new format.
Bugs
Circles would not properly render visualization updates, such as data model
or attribute changes, while its container element had the
display: none style. Version 2.3.9 fixed this issue; parameter and model
updates will redraw the backing canvas accordingly.
Note that the container element must still be visible at least once (upon embedding or at least one call to resize) so that its dimensions are known to the visualization.
This is a maintenance release fixing an issue with label rendering.
Deprecations, migration guide
groupLinePadding
property has been deprecated and will be ignored. Instead, use line-height-relative
groupLinePaddingRatio.Bugs
textBaseline
property in both browsers (spec-compliant).
We rewrote the entire font metrics collection routine as part of this issue. Labels should no longer
be truncated, even if certain glyphs protruded outside of the typical line area.
This is a maintenance release fixing a regression in release 2.3.4.
Bugs
This is a maintenance release fixing a problem with expanders and invisible groups.
Bugs
This is a maintenance release fixing a critical bug in release 2.3.2.
Bugs
This is a maintenance release fixing a minor glitch in image data property rendering.
Bugs
This maintenance release brings minor new features, improvements and cosmetic bug fixes.
New features
Improvements
Other changes
This release brings a roundup of bug fixes from the maintenance branch and a few minor features.
New features, Improvements
Bugs
This is a bugfix release.
Bugs
This is a bugfix release.
Bugs
This release brings a bunch of minor fixes and tweaks.
New features, Improvements
onGroupClick and
onGroupDoubleClick
now expose ctrlKey, shiftKey, altKey and metaKey
properties.Bugs
This release corrects the example snippets for mobile devices and fixes an issue with IE10 event propagation. The visualization code is identical to 2.2.0.
Bugs
This release brings a bunch of new features.
New features, Improvements
groupShape() function to retrieve each group's current shape.
This can be used to track groups on screen and this demo shows where such a feature
may be handy.titleBar attribute and the simplest
showcase example.layout attribute
for accessing the current (most recent) layout state.Bugs
angleEnd does not work as advertised.onRedraw callback was never called. Also improved the documentation on this callback.Deprecations, migration guide
get() calls will always be an array of functions bound to the given callback (it
was previously the current function reference). Where callbacks return a value
(as in onBeforeSelection), any callback can veto the change (mutual
consensus is not required).This release brings a number of improvements to the core animation and rendering routines, documentation and examples. Make sure to check out the list of examples, as well as the new documentation.
New features, Improvements
attributionSize callback
to make attribution logo size customizable (in particular when branding is locked).angleWidth attribute. Check out this
example for the possibilities.isGroupVisible callback attribute
to allow invisible groups (gaps). Check out this example to see
an example where this can be useful.modelChangeAnimations attribute.ringShape attribute for non-uniform,
customizable per-group ring sizes.captureMouseEvents option.ratioAspectSwap allows controlling
label aspect (radial/angular).attributionFadeInTime attribute.Bugs
imageData property could still be black during onRolloutComplete
when no animations were used.centerx,
centery and diameter if pixelRatio != 1.NaN can appear in rainbow color calculation (luminance)
if parent.groups.length == 1.Deprecations, migration guide
angleEnd parameter has been deprecated and
will be removed in future versions. Please change your code to use the more flexible alternative:
angleWidth.selectionColor,
selectionOutlineColor and
selectionOutlineWidth to comply with FoamTree API. They are now called, respectively:
groupSelectionColor,
groupSelectionOutlineColor and
groupSelectionOutlineWidth.Maintenance branch for 2.0.x release.
Bugs
selectionColor,
selectionOutlineColor and
selectionOutlineWidth to comply with FoamTree API. They are now
called, respectively:
groupSelectionColor,
groupSelectionOutlineColor and
groupSelectionOutlineWidth. Aliased old attributes
will be removed in release 2.1.0.Maintenance branch for 2.0.x release.
Bugs
Maintenance branch for 2.0.x release.
New features, Improvements
modelChangeAnimations attribute.Bugs
Official release of Circles HTML5. Reimplementation from Flash to HTML5.
Circles HTML5 release candidate 2.
Circles HTML5 release candidate 1.