Implements the 2D visualization of multiple chemical structures arrange in a grid. More...

#include <StructureGridView2D.hpp>

Inheritance diagram for CDPL::Vis::StructureGridView2D:

Classes
class	Cell
	Data structure storing the contents of a grid cell. More...

Public Types
typedef std::shared_ptr< StructureGridView2D >	SharedPointer
	A reference-counted smart pointer [SHPTR] for dynamically allocated `StructureGridView2D` instances. More...

Public Types inherited from CDPL::Base::ControlParameterContainer
typedef ParameterMap::value_type	ParameterEntry
	A Base::LookupKey / Base::Any pair used to store the control-parameter values and associated keys. More...

typedef ParameterMap::const_iterator	ConstParameterIterator
	A constant iterator used to iterate over the control-parameter entries. More...

typedef std::function< void(const LookupKey &, const Any &)>	ParameterChangedCallbackFunction
	A functor class that wraps callback target functions which get invoked when the value of a control-parameter has changed. More...

typedef std::function< void(const LookupKey &)>	ParameterRemovedCallbackFunction
	A functor class that wraps callback target functions which get invoked when a control-parameter entry has been removed. More...

typedef std::function< void()>	ParentChangedCallbackFunction
	A functor class that wraps callback target functions which get invoked when the parent container has been changed or was detached. More...

Public Member Functions
	StructureGridView2D ()
	Constructs and initializes a `StructureGridView2D` instance for the visualization of multiple chemical structures. More...

	StructureGridView2D (const StructureGridView2D &grid_view)
	Constructs a copy of the `StructureGridView2D` instance grid_view. More...

	~StructureGridView2D ()
	Destructor. More...

void	render (Renderer2D &renderer)
	Renders the visual representation of the model using the specified Vis::Renderer2D instance. More...

bool	write (const std::string &file_name)
	Renders the grid with the specified cell contents and stores the generated image in the file file_name. More...

bool	write (const std::string &file_name, const std::string &fmt)
	Renders the grid with the specified cell contents and stores the generated image in the file file_name. More...

bool	write (const std::string &file_name, const Base::DataFormat &fmt)
	Renders the grid with the specified cell contents and stores the generated image in the file file_name. More...

bool	write (std::ostream &os, const std::string &fmt)
	Renders the grid with the specified cell contents and writes the generated image data to the output stream os. More...

bool	write (std::ostream &os, const Base::DataFormat &fmt)
	Renders the grid with the specified cell contents and writes the generated image data to the output stream os. More...

void	setFontMetrics (FontMetrics *font_metrics)
	Specifies a font metrics object that will be used to measure the dimension of text labels. More...

FontMetrics *	getFontMetrics () const
	Returns a pointer to the used font metrics object. More...

void	getModelBounds (Rectangle2D &bounds)
	Calculates the bounding rectangle of the visualized model. More...

Cell &	operator() (std::size_t row, std::size_t col)
	Returns the Cell instance storing the contents of the specified grid cell. More...

const Cell &	operator() (std::size_t row, std::size_t col) const
	Returns the Cell instance storing the contents of the specified grid cell. More...

void	setCellSize (double width, double height)
	Allows to specify the desired width and height of the cells in grid output renderings. More...

double	getCellWidth () const
	Returns the active grid cell width. More...

double	getCellHeight () const
	Returns the active grid cell height. More...

void	resize (std::size_t num_rows, std::size_t num_cols)
	Chnages the current number of grid rows and columns. More...

std::size_t	getNumRows () const
	Returns the current number of grid rows. More...

std::size_t	getNumColumns () const
	Returns the current number of grid columns. More...

void	clearStructures ()
	Clears all specified structures. More...

void	clearAllText ()
	Clears all specified text blocks. More...

StructureGridView2D &	operator= (const StructureGridView2D &grid_view)
	Performs a copy assignment of the specified `StructureGridView2D` instance. More...

Public Member Functions inherited from CDPL::Vis::View2D
virtual	~View2D ()
	Virtual destructor. More...

Public Member Functions inherited from CDPL::Base::ControlParameterContainer
std::size_t	getNumParameters () const
	Returns the number of container entries. More...

template<typename T >
void	setParameter (const LookupKey &key, T &&val)
	Sets the value of the control-parameter specified by key to val. More...

const Any &	getParameter (const LookupKey &key, bool throw_=false, bool local=false) const
	Returns the value of the control-parameter specified by key. More...

template<typename T >
const T &	getParameter (const LookupKey &key, bool local=false) const
	Returns the value of the control-parameter specified by key as a `const` reference to an object of type T. More...

template<typename T >
const T &	getParameterOrDefault (const LookupKey &key, const T &def_val, bool local=false) const
	Returns the value of the control-parameter specified by key as a `const` reference to an object of type T, or the default value def_val if a stored value does not exist. More...

bool	removeParameter (const LookupKey &key)
	Removes the entry for the control-parameter specified by key. More...

void	clearParameters ()
	Erases all container entries. More...

bool	isParameterSet (const LookupKey &key, bool local=false) const
	Tells whether or not a value has been assigned to the control-parameter specified by key. More...

void	addParameters (const ControlParameterContainer &cntnr)
	Adds the control-parameter value entries in the `ControlParameterContainer` instance cntnr. More...

void	copyParameters (const ControlParameterContainer &cntnr)
	Replaces the current set of properties by a copy of the entries in cntnr. More...

ConstParameterIterator	getParametersBegin () const
	Returns a constant iterator pointing to the beginning of the entries. More...

ConstParameterIterator	getParametersEnd () const
	Returns a constant iterator pointing to the end of the entries. More...

ConstParameterIterator	begin () const
	Returns a constant iterator pointing to the beginning of the entries. More...

ConstParameterIterator	end () const
	Returns a constant iterator pointing to the end of the entries. More...

void	setParent (const ControlParameterContainer *cntnr)
	Sets or removes the parent control-parameter container used to resolve requests for missing entries. More...

const ControlParameterContainer *	getParent () const
	Returns a pointer to the parent control-parameter container. More...

std::size_t	registerParameterChangedCallback (const ParameterChangedCallbackFunction &func)
	Registers a callback target function that gets invoked when the value of a control-parameter has changed. More...

void	unregisterParameterChangedCallback (std::size_t id)
	Unregisters the callback specified by id. More...

std::size_t	registerParameterRemovedCallback (const ParameterRemovedCallbackFunction &func)
	Registers a callback target function that gets invoked when a control-parameter entry has been removed. More...

void	unregisterParameterRemovedCallback (std::size_t id)
	Unregisters the callback specified by id. More...

std::size_t	registerParentChangedCallback (const ParentChangedCallbackFunction &func)
	Registers a callback target function that gets invoked when the parent container has been changed or was detached. More...

void	unregisterParentChangedCallback (std::size_t id)
	Unregisters the callback specified by id. More...

const ControlParameterContainer &	getParameters () const
	Returns a `const` reference to itself. More...

Static Public Attributes
static constexpr double	DEF_CELL_WIDTH = 250.0
	The default grid cell width. More...

static constexpr double	DEF_CELL_HEIGHT = 250.0
	The default grid cell height. More...

Additional Inherited Members
Protected Member Functions inherited from CDPL::Base::ControlParameterContainer
	ControlParameterContainer ()
	Constructs an empty `ControlParameterContainer` instance. More...

	ControlParameterContainer (const ControlParameterContainer &cntnr)
	Constructs a copy of the `ControlParameterContainer` instance cntnr. More...

virtual	~ControlParameterContainer ()
	Destructor. More...

ControlParameterContainer &	operator= (const ControlParameterContainer &cntnr)
	Assignment operator. More...

Detailed Description

Implements the 2D visualization of multiple chemical structures arrange in a grid.

StructureGridView2D visualizes multiple chemical structures as 2D structure diagrams arranged in a grid of arbitrary size.

StructureGridView2D relies on Vis::StructureView2D for structure visualization and thus supports all all of its parameters controlling the graphical details of the generated structure diagrams (colors, fonts, line-widths etc.). Structure visualization parameters of a StructureGridView2D instance can be set for individual grid cells as well as for the whole grid. Furthermore, any Chem::Atom, Chem::Bond and Chem::MolecularGraph relevant for 2D visualization properties will also be regarded (see Vis::StructureView2D for the list of supported properties). Properties of the visualized structures have a higher priority than the corresponding control-parameters of the grid cells hosting the structures. Likewise, control-parameters set for individual grid cells override the corresponding settings of the StructureGridView2D instance.

Each grid cell can host up to nine text blocks which are located at the corners, edges and the cell center. Text blocks are stored as Vis::TextBlockPrimitive2D instances which allow the text to span multiple lines and support the styling (colors, italic, bold, sub/super-scripting, etc.) of individual text fragments.

StructureGridView2D supports the following control-parameters in addition to the ones regarded by Vis::StructureView2D:

Control-Parameter	Description
Vis::ControlParameter::OUTPUT_SCALING_FACTOR	Specifies a factor for the scaling of logical to drawing surface coordinates
Vis::ControlParameter::GRID_VIEW_BORDER_PEN	Specifies the pen used for drawing a rectangle enclosing all cells of the grid
Vis::ControlParameter::GRID_VIEW_ROW_SEPARATOR_PEN	Specifies the pen used for drawing lines separating the grid rows
Vis::ControlParameter::GRID_VIEW_COLUMN_SEPARATOR_PEN	Specifies the pen used for drawing lines separating the grid columns
Vis::ControlParameter::GRID_VIEW_MARGIN	Specifies the amount of free space added around the grid borderline
Vis::ControlParameter::GRID_VIEW_CELL_PADDING	Specifies the amount of free space added around the content of the grid cells
Vis::ControlParameter::GRID_VIEW_TEXT_FONT	Specifies the font used for text blocks
Vis::ControlParameter::GRID_VIEW_TEXT_COLOR	Specifies the default text color

Default values for most of the control-parameters are defined in namespace Vis::ControlParameterDefault.

Since: 1.2

Member Typedef Documentation

◆ SharedPointer

typedef std::shared_ptr<StructureGridView2D> CDPL::Vis::StructureGridView2D::SharedPointer

A reference-counted smart pointer [SHPTR] for dynamically allocated StructureGridView2D instances.

Constructor & Destructor Documentation

◆ StructureGridView2D() [1/2]

CDPL::Vis::StructureGridView2D::StructureGridView2D ( )

Constructs and initializes a StructureGridView2D instance for the visualization of multiple chemical structures.

◆ StructureGridView2D() [2/2]

CDPL::Vis::StructureGridView2D::StructureGridView2D ( const StructureGridView2D & grid_view )

Constructs a copy of the StructureGridView2D instance grid_view.

Parameters

grid_view The StructureGridView2D instance to copy;

◆ ~StructureGridView2D()

CDPL::Vis::StructureGridView2D::~StructureGridView2D ( )

Destructor.

Member Function Documentation

◆ render()

void CDPL::Vis::StructureGridView2D::render ( Renderer2D & renderer )

virtual

Renders the visual representation of the model using the specified Vis::Renderer2D instance.

Parameters

renderer The Renderer2D instance.

Implements CDPL::Vis::View2D.

◆ write() [1/5]

bool CDPL::Vis::StructureGridView2D::write ( const std::string & file_name )

Renders the grid with the specified cell contents and stores the generated image in the file file_name.

The output format will be deduced from the file name extension. Supported formats are PNG, SVG, PDF and PS.

Parameters

file_name The path to the file storing the rendered image.

Returns: true if no errors occurred and false otherwise.

Exceptions

Base::IOError if the file format is invalid/not supported.

◆ write() [2/5]

bool CDPL::Vis::StructureGridView2D::write	(	const std::string &	file_name,
		const std::string &	fmt
	)

Renders the grid with the specified cell contents and stores the generated image in the file file_name.

The output format is specified by the second argument fmt. Supported formats are "PNG", "SVG", "PDF" and "PS" (not case sensitive).

Parameters

file_name	The path to the file storing the rendered image.
fmt	A string specifying the desired output format.

Returns: true if no errors occurred and false otherwise.

Exceptions

Base::IOError if the file format is invalid/not supported.

◆ write() [3/5]

bool CDPL::Vis::StructureGridView2D::write	(	const std::string &	file_name,
		const Base::DataFormat &	fmt
	)

Renders the grid with the specified cell contents and stores the generated image in the file file_name.

The output format is specified by the second argument fmt. Supported formats are Vis::DataFormat::PNG, Vis::DataFormat::SVG, Vis::DataFormat::PDF and Vis::DataFormat::PS.

Parameters

file_name	The path to the file storing the rendered image.
fmt	A descriptor specifying the desired output format.

Returns: true if no errors occurred and false otherwise.

Exceptions

Base::IOError if the file format is invalid/not supported.

◆ write() [4/5]

bool CDPL::Vis::StructureGridView2D::write	(	std::ostream &	os,
		const std::string &	fmt
	)

Renders the grid with the specified cell contents and writes the generated image data to the output stream os.

The output format is specified by the second argument fmt. Supported formats are "PNG", "SVG", "PDF" and "PS" (not case sensitive).

Parameters

os	A `std::ostream` instance storing the generated image data.
fmt	A string specifying the desired output format.

Returns: true if no errors occurred and false otherwise.

Exceptions

Base::IOError if the file format is invalid/not supported.

◆ write() [5/5]

bool CDPL::Vis::StructureGridView2D::write	(	std::ostream &	os,
		const Base::DataFormat &	fmt
	)

Renders the grid with the specified cell contents and writes the generated image data to the output stream os.

The output format is specified by the second argument fmt. Supported formats are Vis::DataFormat::PNG, Vis::DataFormat::SVG, Vis::DataFormat::PDF and Vis::DataFormat::PS.

Parameters

os	A `std::ostream` instance storing the generated image data.
fmt	A string specifying the desired output format.

Returns: true if no errors occurred and false otherwise.

Exceptions

Base::IOError if the file format is invalid/not supported.

◆ setFontMetrics()

void CDPL::Vis::StructureGridView2D::setFontMetrics ( FontMetrics * font_metrics )

virtual

Specifies a font metrics object that will be used to measure the dimension of text labels.

Parameters

font_metrics A pointer to the font metrics object or null.

Implements CDPL::Vis::View2D.

◆ getFontMetrics()

FontMetrics* CDPL::Vis::StructureGridView2D::getFontMetrics ( ) const

Returns a pointer to the used font metrics object.

Returns: A pointer to the used font metrics object, or null if none was specified.

◆ getModelBounds()

void CDPL::Vis::StructureGridView2D::getModelBounds ( Rectangle2D & bounds )

virtual

Calculates the bounding rectangle of the visualized model.

Parameters

bounds A Rectangle2D object storing the calculated bounding rectangle.

Implements CDPL::Vis::View2D.

◆ operator()() [1/2]

Cell& CDPL::Vis::StructureGridView2D::operator()	(	std::size_t	row,
		std::size_t	col
	)

Returns the Cell instance storing the contents of the specified grid cell.

If row and col specify a cell outside of the current grid bounds the grid will be automatically resized to accommodate the new cell.

Parameters

row	The zero-based row index of the cell.
col	The zero-based columns index of the cell.

Returns: A non-const reference to the Cell instance.

◆ operator()() [2/2]

const Cell& CDPL::Vis::StructureGridView2D::operator()	(	std::size_t	row,
		std::size_t	col
	)		const

Returns the Cell instance storing the contents of the specified grid cell.

If row and col specify a cell outside of the current grid bounds the grid will not be automatically resized to accommodate the new cell. For such cells a reference to an "empty" Cell instance is returned. The same is done for not yet touched cells (within the current grid bounds).

Parameters

row	The zero-based row index of the cell.
col	The zero-based columns index of the cell.

Returns: A const reference to the Cell instance.

◆ setCellSize()

void CDPL::Vis::StructureGridView2D::setCellSize	(	double	width,
		double	height
	)

Allows to specify the desired width and height of the cells in grid output renderings.

The default width and height is given by the constants DEF_CELL_WIDTH and DEF_CELL_HEIGHT, respectively.

Parameters

width	The new cell width.
height	The new cell height.

Exceptions

Base::ValueError if either width or height is negative.

◆ getCellWidth()

double CDPL::Vis::StructureGridView2D::getCellWidth ( ) const

Returns the active grid cell width.

Returns: The active grid cell width.

◆ getCellHeight()

double CDPL::Vis::StructureGridView2D::getCellHeight ( ) const

Returns the active grid cell height.

Returns: The active grid cell height.

◆ resize()

void CDPL::Vis::StructureGridView2D::resize	(	std::size_t	num_rows,
		std::size_t	num_cols
	)

Chnages the current number of grid rows and columns.

The grid gets resized dynamically if a cell outside the currently sized grid is requested by operator(). Calling this method is thus only necessary if a specific grid size is desired. Any already existing cells that are located outside the new grid dimensions will be deleted.

Parameters

num_rows	The new numer of grid rows.
num_cols	The new numer of grid columns.

◆ getNumRows()

std::size_t CDPL::Vis::StructureGridView2D::getNumRows ( ) const

Returns the current number of grid rows.

Returns: The current number of grid rows.

◆ getNumColumns()

std::size_t CDPL::Vis::StructureGridView2D::getNumColumns ( ) const

Returns the current number of grid columns.

Returns: The current number of grid columns.

◆ clearStructures()

void CDPL::Vis::StructureGridView2D::clearStructures ( )

Clears all specified structures.

See also: Cell::clearStructure()

◆ clearAllText()

void CDPL::Vis::StructureGridView2D::clearAllText ( )

Clears all specified text blocks.

See also: Cell::clearAllText()

◆ operator=()

StructureGridView2D& CDPL::Vis::StructureGridView2D::operator= ( const StructureGridView2D & grid_view )

Performs a copy assignment of the specified StructureGridView2D instance.

Parameters

grid_view The StructureGridView2D instance to copy.

Returns: A reference to itslef.

Member Data Documentation

◆ DEF_CELL_WIDTH

constexpr double CDPL::Vis::StructureGridView2D::DEF_CELL_WIDTH = 250.0

staticconstexpr

The default grid cell width.

◆ DEF_CELL_HEIGHT

constexpr double CDPL::Vis::StructureGridView2D::DEF_CELL_HEIGHT = 250.0

staticconstexpr

The default grid cell height.

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

StructureGridView2D.hpp

Classes

Public Types

Public Member Functions

Static Public Attributes

Additional Inherited Members

Detailed Description

Member Typedef Documentation

◆ SharedPointer

Constructor & Destructor Documentation

◆ StructureGridView2D() [1/2]

◆ StructureGridView2D() [2/2]

◆ ~StructureGridView2D()

Member Function Documentation

◆ render()

◆ write() [1/5]

◆ write() [2/5]

◆ write() [3/5]

◆ write() [4/5]

◆ write() [5/5]

◆ setFontMetrics()

◆ getFontMetrics()

◆ getModelBounds()

◆ operator()() [1/2]

◆ operator()() [2/2]

◆ setCellSize()

◆ getCellWidth()

◆ getCellHeight()

◆ resize()

◆ getNumRows()

◆ getNumColumns()

◆ clearStructures()

◆ clearAllText()

◆ operator=()

Member Data Documentation

◆ DEF_CELL_WIDTH

◆ DEF_CELL_HEIGHT