plotly::Figure Class Reference

Handle for creating and manipulating a Plotly figure. More...

#include <plotly.hpp>

Classes
class	Impl

Public Member Functions
	Figure (const std::filesystem::path &webappPath=std::filesystem::path(PLOTLY_CPP_WEBAPP_PATH))
	Construct a new Figure instance.
	Figure (const Figure &)=delete
	Copy construction is disabled.
auto	operator= (const Figure &) -> Figure &=delete
	Copy assignment is disabled.
	~Figure ()
	Destructor.
auto	openBrowser (bool headless=false) -> bool
	Open the figure in the browser.
auto	isOpen () const -> bool
	Check whether the figure is currently open.
void	waitClose () const
	Wait until the figure is closed (no client connected).
auto	downloadImage (const Object &opts=Object()) -> bool
	Download the figure as an image.
auto	newPlot (const Object &data, const Object &layout=Object(), const Object &config=Object()) -> bool
	Create and render a new plot.
auto	update (const Object &traceUpdate, const Object &layoutUpdate=Object()) -> bool
	Update an existing plot.
auto	relayout (const Object &layout=Object()) -> bool
	Apply layout-only changes to the plot.
auto	redraw () -> bool
	Redraw the plot.
auto	purge () -> bool
	Purge the plot, removing all data and layout.
auto	restyle (const Object &aobj, const Object &traces=Object()) -> bool
	Restyle existing traces.
auto	addTraces (const Object &traces, const Object &newIndices=Object()) -> bool
	Add new traces to the plot.
auto	deleteTraces (const Object &indices) -> bool
	Delete traces from the plot.
auto	moveTraces (const Object &currentIndices, const Object &newIndices) -> bool
	Move traces to new positions.
auto	extendTraces (const Object &update, const Object &indices, const Object &maxPoints=Object()) -> bool
	Extend existing traces with new data.
auto	prependTraces (const Object &update, const Object &indices) -> bool
	Prepend data to existing traces.
auto	react (const Object &data, const Object &layout=Object(), const Object &config=Object()) -> bool
	React-style update of the plot.
auto	addFrames (const Object &frames) -> bool
	Add animation frames to the plot.
auto	deleteFrames (const Object &frames) -> bool
	Delete animation frames from the plot.
auto	animate (const Object &frameOrGroupNameOrFrameList, const Object &opts=Object()) -> bool
	Animate the plot.
auto	on (const std::string &event, const std::function< void(plotly::Object)> &callback) -> bool
	Register a listener for a Plotly event.
auto	removeAllListeners (const std::string &event) -> bool
	Remove all listeners for a specific Plotly event.
auto	setDownloadDirectory (const std::filesystem::path &directory, int remoteDebuggingPort=9222) -> bool
	Set the download directory for the browser.

Detailed Description

Handle for creating and manipulating a Plotly figure.

• Non-copyable (copy constructor and assignment are disabled)
• Some operations are asynchronous and return std::future<plotly::Object>
• Returned plotly::Object values carry Plotly.js responses and event payloads in a JSON-compatible structure

Typical usage:

1. Construct a Figure (optionally auto-opening the viewer/frontend)
2. Call newPlot to render the initial chart
3. Call update and/or relayout to modify the chart
4. Optionally call downloadImage to export an image
5. Register event listeners with on

Note

Thread-safety characteristics depend on the implementation. If multiple threads will operate on the same instance, coordinate access appropriately.

Examples

gallery_2x2_subplots.cpp, gallery_3d_surface.cpp, gallery_animate_sin_wave.cpp, gallery_box_violin_plots.cpp, gallery_clustering_animation.cpp, gallery_double_pendulum.cpp, gallery_duffing.cpp, gallery_event_handling.cpp, gallery_financial_candlestick.cpp, gallery_fractal.cpp, gallery_game_of_life.cpp, gallery_geographic_choropleth.cpp, gallery_golden_ratio.cpp, gallery_heatmap_correlation.cpp, gallery_hello_world.cpp, gallery_multi_trace_styling.cpp, gallery_parallel_coordinates.cpp, gallery_particle_physics_sim.cpp, gallery_polar_radar_chart.cpp, gallery_sankey_flow_diagram.cpp, gallery_scatter_bubble_chart.cpp, gallery_sin_curve.cpp, gallery_star.cpp, gallery_statistical_distributions.cpp, and gallery_treemap_hierarchy.cpp.

Constructor & Destructor Documentation

Figure() [1/2]

plotly::Figure::Figure

(

const std::filesystem::path &

webappPath = std::filesystem::path(PLOTLY_CPP_WEBAPP_PATH)

)

Construct a new Figure instance.

Figure() [2/2]

plotly::Figure::Figure ( const Figure & )

delete

Copy construction is disabled.

~Figure()

plotly::Figure::~Figure ( )

default

Destructor.

Member Function Documentation

addFrames()

auto plotly::Figure::addFrames

(

const Object &

frames

)

-> bool

Add animation frames to the plot.

Parameters

frames

Frame data to add.

Returns

true if the frames were added successfully, false otherwise.

See also

https://plotly.com/javascript/plotlyjs-function-reference/#plotlyaddframes

Examples

gallery_animate_sin_wave.cpp.

addTraces()

auto plotly::Figure::addTraces	(	const Object &	traces,
		const Object &	newIndices = Object() ) -> bool

Add new traces to the plot.

Parameters

traces	New trace data to add.
newIndices	Optional indices where to insert the traces.

Returns

true if the traces were added successfully, false otherwise.

See also

https://plotly.com/javascript/plotlyjs-function-reference/#plotlyaddtraces

animate()

auto plotly::Figure::animate	(	const Object &	frameOrGroupNameOrFrameList,
		const Object &	opts = Object() ) -> bool

Animate the plot.

Parameters

frameOrGroupNameOrFrameList	Frame specification for animation.
opts	Animation options.

Returns

true if the animation was started successfully, false otherwise.

See also

https://plotly.com/javascript/plotlyjs-function-reference/#plotlyanimate

Examples

gallery_animate_sin_wave.cpp.

deleteFrames()

auto plotly::Figure::deleteFrames

(

const Object &

frames

)

-> bool

Delete animation frames from the plot.

Parameters

frames

Frame names or indices to delete.

Returns

true if the frames were deleted successfully, false otherwise.

See also

https://plotly.com/javascript/plotlyjs-function-reference/#plotlydeleteframes

deleteTraces()

auto plotly::Figure::deleteTraces

(

const Object &

indices

)

-> bool

Delete traces from the plot.

Parameters

indices

Indices of traces to delete.

Returns

true if the traces were deleted successfully, false otherwise.

See also

https://plotly.com/javascript/plotlyjs-function-reference/#plotlydeletetraces

downloadImage()

auto plotly::Figure::downloadImage

(

const Object &

opts = Object()

)

-> bool

Download the figure as an image.

Parameters

opts	Options compatible with Plotly.js Plotly.downloadImage.

Returns

true if the download was initiated successfully, false otherwise.

See also

https://plotly.com/javascript/plotlyjs-function-reference/#plotlydownloadimage

Examples

gallery_2x2_subplots.cpp, gallery_3d_surface.cpp, gallery_box_violin_plots.cpp, gallery_financial_candlestick.cpp, gallery_geographic_choropleth.cpp, gallery_golden_ratio.cpp, gallery_heatmap_correlation.cpp, gallery_hello_world.cpp, gallery_multi_trace_styling.cpp, gallery_parallel_coordinates.cpp, gallery_polar_radar_chart.cpp, gallery_sankey_flow_diagram.cpp, gallery_scatter_bubble_chart.cpp, gallery_sin_curve.cpp, gallery_star.cpp, gallery_statistical_distributions.cpp, and gallery_treemap_hierarchy.cpp.

extendTraces()

auto plotly::Figure::extendTraces	(	const Object &	update,
		const Object &	indices,
		const Object &	maxPoints = Object() ) -> bool

Extend existing traces with new data.

Parameters

update	Data to append to traces.
indices	Trace indices to extend.
maxPoints	Optional maximum number of points to keep.

Returns

true if the traces were extended successfully, false otherwise.

See also

https://plotly.com/javascript/plotlyjs-function-reference/#plotlyextendtraces

isOpen()

auto plotly::Figure::isOpen ( ) const -> bool

nodiscard

Check whether the figure is currently open.

Returns

true if open; false otherwise.

Examples

gallery_double_pendulum.cpp, gallery_duffing.cpp, gallery_game_of_life.cpp, and gallery_particle_physics_sim.cpp.

moveTraces()

auto plotly::Figure::moveTraces	(	const Object &	currentIndices,
		const Object &	newIndices ) -> bool

Move traces to new positions.

Parameters

currentIndices	Current indices of traces to move.
newIndices	New indices for the traces.

Returns

true if the traces were moved successfully, false otherwise.

See also

https://plotly.com/javascript/plotlyjs-function-reference/#plotlymovetraces

newPlot()

auto plotly::Figure::newPlot	(	const Object &	data,
		const Object &	layout = Object(),
		const Object &	config = Object() ) -> bool

Create and render a new plot.

Parameters

data	Data array equivalent to Plotly.js Plotly.newPlot data.
layout	Optional layout specification.
config	Optional configuration.

Returns

true if the plot was created successfully, false otherwise.

See also

https://plotly.com/javascript/plotlyjs-function-reference/#plotlynewplot

Examples

gallery_2x2_subplots.cpp, gallery_3d_surface.cpp, gallery_animate_sin_wave.cpp, gallery_box_violin_plots.cpp, gallery_clustering_animation.cpp, gallery_double_pendulum.cpp, gallery_duffing.cpp, gallery_event_handling.cpp, gallery_financial_candlestick.cpp, gallery_fractal.cpp, gallery_game_of_life.cpp, gallery_geographic_choropleth.cpp, gallery_golden_ratio.cpp, gallery_heatmap_correlation.cpp, gallery_hello_world.cpp, gallery_multi_trace_styling.cpp, gallery_parallel_coordinates.cpp, gallery_particle_physics_sim.cpp, gallery_polar_radar_chart.cpp, gallery_sankey_flow_diagram.cpp, gallery_scatter_bubble_chart.cpp, gallery_sin_curve.cpp, gallery_star.cpp, gallery_statistical_distributions.cpp, and gallery_treemap_hierarchy.cpp.

on()

auto plotly::Figure::on	(	const std::string &	event,
		const std::function< void(plotly::Object)> &	callback ) -> bool

Register a listener for a Plotly event.

Parameters

event	Event name (e.g., "plotly_click", "plotly_hover").
callback	Callback invoked when the event fires; receives the event payload as plotly::Object.

Returns

true if the event listener was registered successfully, false otherwise.

See also

https://plotly.com/javascript/plotlyjs-events/

Examples

gallery_event_handling.cpp.

openBrowser()

auto plotly::Figure::openBrowser

(

bool

headless = false

)

-> bool

Open the figure in the browser.

Parameters

headless

If true, the browser will be opened in headless mode.

Returns

true if successful, false otherwise.

Examples

gallery_2x2_subplots.cpp, gallery_3d_surface.cpp, gallery_animate_sin_wave.cpp, gallery_box_violin_plots.cpp, gallery_clustering_animation.cpp, gallery_double_pendulum.cpp, gallery_duffing.cpp, gallery_event_handling.cpp, gallery_financial_candlestick.cpp, gallery_fractal.cpp, gallery_game_of_life.cpp, gallery_geographic_choropleth.cpp, gallery_golden_ratio.cpp, gallery_heatmap_correlation.cpp, gallery_hello_world.cpp, gallery_multi_trace_styling.cpp, gallery_parallel_coordinates.cpp, gallery_particle_physics_sim.cpp, gallery_polar_radar_chart.cpp, gallery_sankey_flow_diagram.cpp, gallery_scatter_bubble_chart.cpp, gallery_sin_curve.cpp, gallery_star.cpp, gallery_statistical_distributions.cpp, and gallery_treemap_hierarchy.cpp.

operator=()

auto plotly::Figure::operator= ( const Figure & ) -> Figure &=delete

delete

Copy assignment is disabled.

prependTraces()

auto plotly::Figure::prependTraces	(	const Object &	update,
		const Object &	indices ) -> bool

Prepend data to existing traces.

Parameters

update	Data to prepend to traces.
indices	Trace indices to prepend to.

Returns

true if the data was prepended successfully, false otherwise.

See also

https://plotly.com/javascript/plotlyjs-function-reference/#plotlyprependtraces

purge()

auto plotly::Figure::purge

(

)

-> bool

Purge the plot, removing all data and layout.

Returns

true if the purge was successful, false otherwise.

See also

https://plotly.com/javascript/plotlyjs-function-reference/#plotlypurge

react()

auto plotly::Figure::react	(	const Object &	data,
		const Object &	layout = Object(),
		const Object &	config = Object() ) -> bool

React-style update of the plot.

Parameters

data	New data array.
layout	Optional layout specification.
config	Optional configuration.

Returns

true if the react update was successful, false otherwise.

See also

https://plotly.com/javascript/plotlyjs-function-reference/#plotlyreact

redraw()

auto plotly::Figure::redraw

(

)

-> bool

Redraw the plot.

Returns

true if the redraw was successful, false otherwise.

See also

https://plotly.com/javascript/plotlyjs-function-reference/#plotlyredraw

relayout()

auto plotly::Figure::relayout

(

const Object &

layout = Object()

)

-> bool

Apply layout-only changes to the plot.

Parameters

layout

Layout specification (equivalent to Plotly.js Plotly.relayout). If omitted, defaults are used.

Returns

true if the relayout was successful, false otherwise.

See also

https://plotly.com/javascript/plotlyjs-function-reference/#plotlyrelayout

Examples

gallery_clustering_animation.cpp, gallery_event_handling.cpp, and gallery_game_of_life.cpp.

removeAllListeners()

auto plotly::Figure::removeAllListeners

(

const std::string &

event

)

-> bool

Remove all listeners for a specific Plotly event.

Parameters

event

Event name (e.g., "plotly_click", "plotly_hover").

Returns

true if the listeners were removed successfully, false otherwise.

See also

https://plotly.com/javascript/plotlyjs-events/

restyle()

auto plotly::Figure::restyle	(	const Object &	aobj,
		const Object &	traces = Object() ) -> bool

Restyle existing traces.

Parameters

aobj	Style updates to apply.
traces	Optional trace indices to target (defaults to all).

Returns

true if the restyle was successful, false otherwise.

See also

https://plotly.com/javascript/plotlyjs-function-reference/#plotlyrestyle

Examples

gallery_clustering_animation.cpp, gallery_game_of_life.cpp, and gallery_particle_physics_sim.cpp.

setDownloadDirectory()

auto plotly::Figure::setDownloadDirectory	(	const std::filesystem::path &	directory,
		int	remoteDebuggingPort = 9222 ) -> bool

Set the download directory for the browser.

Parameters

directory	Path to the directory where downloads should be saved.
remoteDebuggingPort	Port for Chrome DevTools remote debugging (default: 9222).

Returns

true if successful, false otherwise.

This function sets the download directory for the browser instance used by the Figure. It communicates with the browser via Chrome DevTools Protocol to configure the download behavior.

update()

auto plotly::Figure::update	(	const Object &	traceUpdate,
		const Object &	layoutUpdate = Object() ) -> bool

Update an existing plot.

Parameters

traceUpdate	Trace updates (equivalent to the data portion of Plotly.js Plotly.update).
layoutUpdate	Optional layout updates.

Returns

true if the update was successful, false otherwise.

See also

https://plotly.com/javascript/plotlyjs-function-reference/#plotlyupdate

Examples

gallery_double_pendulum.cpp, and gallery_duffing.cpp.

waitClose()

void plotly::Figure::waitClose

(

)

const

Wait until the figure is closed (no client connected).

This method blocks until the WebSocket client disconnects, indicating that the figure viewer has been closed.

Examples

gallery_2x2_subplots.cpp, gallery_3d_surface.cpp, gallery_animate_sin_wave.cpp, gallery_box_violin_plots.cpp, gallery_clustering_animation.cpp, gallery_event_handling.cpp, gallery_financial_candlestick.cpp, gallery_fractal.cpp, gallery_game_of_life.cpp, gallery_geographic_choropleth.cpp, gallery_golden_ratio.cpp, gallery_heatmap_correlation.cpp, gallery_hello_world.cpp, gallery_multi_trace_styling.cpp, gallery_parallel_coordinates.cpp, gallery_particle_physics_sim.cpp, gallery_polar_radar_chart.cpp, gallery_sankey_flow_diagram.cpp, gallery_scatter_bubble_chart.cpp, gallery_sin_curve.cpp, gallery_star.cpp, gallery_statistical_distributions.cpp, and gallery_treemap_hierarchy.cpp.

---

The documentation for this class was generated from the following files:

• include/plotly/plotly.hpp
• src/plotly.cpp