Principal plotting widget. More...

#include <gtkmm-plplot/canvas.h>

Inheritance diagram for Gtk::PLplot::Canvas:

Public Member Functions
	Canvas (Gdk::RGBA background_color=Gdk::RGBA("White"))

	Canvas (Plot &plot, Gdk::RGBA background_color=Gdk::RGBA("White"))

virtual	~Canvas ()

void	draw_plot (const Cairo::RefPtr< Cairo::Context > &cr, int width, int height)

void	add_plot (Plot &plot)

void	remove_plot (unsigned int plot_index)

void	remove_plot (Plot &plot)

sigc::signal< void(void)>	signal_changed ()

Plot *	get_plot (unsigned int plot_index)

Gdk::RGBA	get_background_color ()

void	set_background_color (Gdk::RGBA color)

Protected Member Functions
virtual void	on_draw (const ::Cairo::RefPtr<::Cairo::Context > &cr, int width, int height)

virtual void	on_button_press_event (int n_press, double x, double y)

virtual void	on_button_release_event (int n_press, double x, double y)

virtual void	on_motion_notify_event (double x, double y)

virtual bool	on_scroll_event (double dx, double dy)

virtual bool	on_key_press_event (guint keyval, guint keycode, Gdk::ModifierType state)

virtual void	on_key_release_event (guint keyval, guint keycode, Gdk::ModifierType state)

virtual void	on_changed ()

Private Member Functions
	Canvas (const Canvas &)=delete
	no copy constructor

Canvas &	operator= (const Canvas &)=delete
	no move assignment operator

bool	handle_motion_event (double x, double y)

Private Attributes
std::vector< Plot * >	plots
	A vector containing pointers to the plots.

sigc::signal< void(void)>	_signal_changed
	signal that will be emitted whenever one of the parameters of the canvas or the plots in contains changes

double	start_event [2]
	widget coordinates of the position where a `button_press_event` was generated

double	start_cairo [2]
	cairo coordinates of the position where a `button_press_event` was generated

double	end_event [2]
	widget coordinates of the position where a `button_release_event` was generated

double	end_cairo [2]
	cairo coordinates of the position where a `button_release_event` was generated

bool	selecting
	set to true if the user is currently dragging a selection box

bool	left_mouse_button_clicked
	set to true if the user is currently pressing the left mouse button

bool	shift_pressed
	set to true if the shift button is currently pressed in

Plot *	selected_plot
	`pointer` to the currently selected plot

Plot *	inside_plot
	`pointer` to the plot that currently contains the mouse cursor. It will be set to nullptr when it is not above a plot.

double	inside_plot_current_coords [2]
	coords of the current cursor position within inside_plot, updated in on_motion_notify_event();

double	mouse_current_coords [2]
	coords of the current cursor position;

Gdk::RGBA	background_color
	the currently used background color of the canvas (default = opaque White)

Detailed Description

Principal plotting widget.

Inheriting from Gtk::DrawingArea, this is by far the most important widget in PLplot, as it will contain the plots and the datasets. Depending on which constructor is chosen, either an empty canvas will be produced, or one containing a single plot. It is possible however, to add any number of plots on the canvas. The positions and dimensions of these plots are properties of the plots, that have to be provided when invoking their constructors. This is demonstrated in Example 3: Adding, removing, showing and hiding plots and Example 4: Displaying multiple plots on a single canvas. Example 1: Plot data properties and zooming shows how to write a canvas and its contents to a file as well as to send a canvas to a printer using the draw_plot method.

Constructor & Destructor Documentation

◆ Canvas() [1/3]

Gtk::PLplot::Canvas::Canvas ( const Canvas & )

privatedelete

no copy constructor

◆ Canvas() [2/3]

Gtk::PLplot::Canvas::Canvas ( Gdk::RGBA background_color = Gdk::RGBA("White") )

Canvas constructor

This is the default class constructor, which will produce only a widget with the background_color specified. Add plots using add_plot.

Parameters

background_color The color of the background for the canvas.

Exceptions

Gtk::PLplot::Exception

◆ Canvas() [3/3]

Gtk::PLplot::Canvas::Canvas	(	Plot &	plot,
		Gdk::RGBA	background_color = `Gdk::RGBA("White")`
	)

Canvas constructor

This is a Canvas constructor that takes one plot as argument, resulting in a box with data when shown. More plots may be added using add_plot.

Parameters

plot	The initial plot that will be added to the canvas.
background_color	The color of the background for the canvas.

◆ ~Canvas()

virtual Gtk::PLplot::Canvas::~Canvas ( )

virtual

Canvas destructor

Member Function Documentation

◆ add_plot()

void Gtk::PLplot::Canvas::add_plot ( Plot & plot )

Add a single plot to the canvas

Parameters

plot	Plot to be added to the canvas

◆ draw_plot()

void Gtk::PLplot::Canvas::draw_plot	(	const Cairo::RefPtr< Cairo::Context > &	cr,
		int	width,
		int	height
	)

Draw onto a given cairo context

Enables drawing the canvas and its plot(s) onto a particular cairo context, whose surface is not necessarily connected to a widget. Use this method if you want to write to PNG, EPS, PDF etc. files or if you would like to send this to a print job

◆ get_background_color()

Gdk::RGBA Gtk::PLplot::Canvas::get_background_color ( )

Get the background color

Returns: The currently selected background color.

◆ get_plot()

Plot * Gtk::PLplot::Canvas::get_plot ( unsigned int plot_index )

Get a pointer to a plot included in the canvas

Parameters

plot_index index of the plot in the plots vector

Exceptions

Gtk::PLplot::Exception

Returns: a pointer to the Plot in the plots vector.

◆ handle_motion_event()

bool Gtk::PLplot::Canvas::handle_motion_event	(	double	x,
		double	y
	)

private

This is a default handler for Gtk::EventControllerMotion::signal_motion().

This method tracks the mouse movement event that leads to a selection box being drawn within the plot box. When deriving from Canvas and if overriding this method, you may still want to call it to ensure that the selection box will still be drawn.

Parameters

x	Coordinates of pointer location.
y	Coordinates of pointer location.

Returns: true if the key press was handled, false otherwise.

◆ on_button_press_event()

virtual void Gtk::PLplot::Canvas::on_button_press_event	(	int	n_press,
		double	x,
		double	y
	)

protectedvirtual

This is a default handler for signal_button_press_event().

This method tracks the button press event that may lead to a selection box being dragged, as well as the double press event that will bring a previously zoomed-in range back to its default view. When deriving from Canvas and if overriding this method, you may still want to call it to ensure that the selection box will still be drawn.

Parameters

n_press	How many touch/button presses happened with this one.
x	The X coordinate, in widget allocation coordinates.
y	The Y coordinate, in widget allocation coordinates.

◆ on_button_release_event()

virtual void Gtk::PLplot::Canvas::on_button_release_event	(	int	n_press,
		double	x,
		double	y
	)

protectedvirtual

This is a default handler for signal_button_release_event().

This method tracks the button release event that leads to a selection box being completed and thus deleted, which is then followed by signal_select_region being emitted by the plot that had the selection box. When deriving from Canvas and if overriding this method, you may still want to call it to ensure that the selection box will still be drawn.

Parameters

n_press	How many touch/button presses happened with this one.
x	The X coordinate, in widget allocation coordinates.
y	The Y coordinate, in widget allocation coordinates.

◆ on_changed()

virtual void Gtk::PLplot::Canvas::on_changed ( )

protectedvirtual

This is a default handler for signal_changed().

This signal is emitted whenever any of the canvas properties changes, or any of the properties of the plots contained therein. This default handler does one thing only: asking for a redraw of the complete canvas.

◆ on_draw()

virtual void Gtk::PLplot::Canvas::on_draw	(	const ::Cairo::RefPtr<::Cairo::Context > &	cr,
		int	width,
		int	height
	)

protectedvirtual

This is a default handler for signal_draw().

When deriving from Canvas and if overriding this method, you may still want to call it to ensure proper drawing of the plots provided by Gtkmm-PLplot

Parameters

cr	The cairo context to draw to.
width	The cairo draw width
height	The cairo draw height

◆ on_key_press_event()

virtual bool Gtk::PLplot::Canvas::on_key_press_event	(	guint	keyval,
		guint	keycode,
		Gdk::ModifierType	state
	)

protectedvirtual

This is a default handler for signal_key_press_event().

This method gets called whenever a key is pressed. In this class, the method will only be useful whenever the SHIFT key is pressed, as this will lead to the plot being moved around within its box.

Parameters

keyval	The pressed key.
keycode	The raw code of the pressed key.
state	The bitmask, representing the state of modifier keys and pointer buttons. See `GdkModifierType`.

Returns: true if the key press was handled, false otherwise.

Since: 2.2

◆ on_key_release_event()

virtual void Gtk::PLplot::Canvas::on_key_release_event	(	guint	keyval,
		guint	keycode,
		Gdk::ModifierType	state
	)

protectedvirtual

This is a default handler for signal_key_release_event().

This method gets called whenever a key is released. In this class, the method will only be useful whenever the SHIFT key is released, as this will lead to the plot being moved around within its box.

Parameters

keyval	The released key.
keycode	The raw code of the pressed key.
state	The bitmask, representing the state of modifier keys and pointer buttons. See `GdkModifierType`.

Since: 2.2

◆ on_motion_notify_event()

virtual void Gtk::PLplot::Canvas::on_motion_notify_event	(	double	x,
		double	y
	)

protectedvirtual

This is a default handler for Gtk::EventControllerMotion::signal_motion().

This method tracks the mouse movement event that leads to a selection box being drawn within the plot box. When deriving from Canvas and if overriding this method, you may still want to call it to ensure that the selection box will still be drawn.

Parameters

x	Coordinates of pointer location.
y	Coordinates of pointer location.

◆ on_scroll_event()

virtual bool Gtk::PLplot::Canvas::on_scroll_event	(	double	dx,
		double	dy
	)

protectedvirtual

This is a default handler for signal_scroll_event().

This method tracks the scroll movement that may be used to trigger a zoom-in or zoom-out event on a particular plot. When deriving from Canvas and if overriding this method, you may still want to call it to ensure that the selection box will still be drawn.

Parameters

dx	X delta.
dy	Y delta.

Returns: true if the scroll event was handled, false otherwise.

Since: 2.2

◆ operator=()

Canvas & Gtk::PLplot::Canvas::operator= ( const Canvas & )

privatedelete

no move assignment operator

◆ remove_plot() [1/2]

void Gtk::PLplot::Canvas::remove_plot ( Plot & plot )

Remove a single plot from the canvas

Parameters

plot	pointer to the plot in the `plots` vector

Exceptions

Gtk::PLplot::Exception

◆ remove_plot() [2/2]

void Gtk::PLplot::Canvas::remove_plot ( unsigned int plot_index )

Remove a single plot from the canvas

Parameters

plot_index index of the plot in the plots vector

Exceptions

Gtk::PLplot::Exception

◆ set_background_color()

void Gtk::PLplot::Canvas::set_background_color ( Gdk::RGBA color )

Set the background color

Parameters

color Set a new background color.

◆ signal_changed()

sigc::signal< void(void)> Gtk::PLplot::Canvas::signal_changed ( )

inline

signal_changed is emitted whenever any of the canvas properties or any of the plot properties has changed.

See default handler on_changed()

Exceptions

Gtk::PLplot::Exception

Returns: signal

Member Data Documentation

◆ _signal_changed

sigc::signal<void(void)> Gtk::PLplot::Canvas::_signal_changed

private

signal that will be emitted whenever one of the parameters of the canvas or the plots in contains changes

◆ background_color

Gdk::RGBA Gtk::PLplot::Canvas::background_color

private

the currently used background color of the canvas (default = opaque White)

◆ end_cairo

double Gtk::PLplot::Canvas::end_cairo[2]

private

cairo coordinates of the position where a button_release_event was generated

◆ end_event

double Gtk::PLplot::Canvas::end_event[2]

private

widget coordinates of the position where a button_release_event was generated

◆ inside_plot

Plot* Gtk::PLplot::Canvas::inside_plot

private

pointer to the plot that currently contains the mouse cursor. It will be set to nullptr when it is not above a plot.

◆ inside_plot_current_coords

double Gtk::PLplot::Canvas::inside_plot_current_coords[2]

private

coords of the current cursor position within inside_plot, updated in on_motion_notify_event();

◆ left_mouse_button_clicked

bool Gtk::PLplot::Canvas::left_mouse_button_clicked

private

set to true if the user is currently pressing the left mouse button

◆ mouse_current_coords

double Gtk::PLplot::Canvas::mouse_current_coords[2]

private

coords of the current cursor position;

◆ plots

std::vector<Plot *> Gtk::PLplot::Canvas::plots

private

A vector containing pointers to the plots.

◆ selected_plot

Plot* Gtk::PLplot::Canvas::selected_plot

private

pointer to the currently selected plot

◆ selecting

bool Gtk::PLplot::Canvas::selecting

private

set to true if the user is currently dragging a selection box

◆ shift_pressed

bool Gtk::PLplot::Canvas::shift_pressed

private

set to true if the shift button is currently pressed in

◆ start_cairo

double Gtk::PLplot::Canvas::start_cairo[2]

private

cairo coordinates of the position where a button_press_event was generated

◆ start_event

double Gtk::PLplot::Canvas::start_event[2]

private

widget coordinates of the position where a button_press_event was generated

Public Member Functions

Protected Member Functions

Private Member Functions

Private Attributes

Detailed Description

Constructor & Destructor Documentation

◆ Canvas() [1/3]

◆ Canvas() [2/3]

◆ Canvas() [3/3]

◆ ~Canvas()

Member Function Documentation

◆ add_plot()

◆ draw_plot()

◆ get_background_color()

◆ get_plot()

◆ handle_motion_event()

◆ on_button_press_event()

◆ on_button_release_event()

◆ on_changed()

◆ on_draw()

◆ on_key_press_event()

◆ on_key_release_event()

◆ on_motion_notify_event()

◆ on_scroll_event()

◆ operator=()

◆ remove_plot() [1/2]

◆ remove_plot() [2/2]

◆ set_background_color()

◆ signal_changed()

Member Data Documentation

◆ _signal_changed

◆ background_color

◆ end_cairo

◆ end_event

◆ inside_plot

◆ inside_plot_current_coords

◆ left_mouse_button_clicked

◆ mouse_current_coords

◆ plots

◆ selected_plot

◆ selecting

◆ shift_pressed

◆ start_cairo

◆ start_event