#include <ccanvas.h>

Description

Provides a scene graph based 2D drawing API for modules.

Notes:

all figures are under a root figure (which we try not to expose too much)
Z-order is defined by child order (bottom-to-top) and preorder traversal
layer-like functionality is provided via figure tags: the Qtenv UI allows figures to be shown or hidden according to tags they contain
cModule has one dedicated canvas, additional canvas objects can be created
initial module canvas contents comes from @figure properties inside the compound module NED file, see samples/canvas for examples!
extensibility: type=foo in a @figure property will cause the canvas to look for a registered FooFigure or cFooFigure class to instantiate
dup() makes deep copy (duplicates the figure tree too)
the submodules layer (see getSubmodulesLayer()) is currently an empty placeholder figure where Qtenv will draw modules and connections (by means outside cCanvas/cFigure) – it can be used for Z-order positioning of other figures relative to the submodules and connections

Inheritance diagram for cCanvas:

Public Member Functions
Constructors, destructor, assignment.
	cCanvas (const char *name=nullptr)

	cCanvas (const cCanvas &other)

virtual	~cCanvas ()

cCanvas &	operator= (const cCanvas &other)

Redefined cObject member functions.
virtual cCanvas *	dup () const override

virtual void	forEachChild (cVisitor *v) override

virtual std::string	str () const override

Canvas attributes.
virtual const cFigure::Color &	getBackgroundColor () const

virtual void	setBackgroundColor (const cFigure::Color &color)

virtual uint32_t	getHash () const

Managing child figures.
virtual cFigure *	getRootFigure () const

virtual void	addFigure (cFigure *figure)

virtual void	addFigure (cFigure *figure, int pos)

virtual cFigure *	removeFigure (cFigure *figure)

virtual cFigure *	removeFigure (int pos)

virtual int	findFigure (const char *name) const

virtual int	findFigure (cFigure *figure) const

virtual bool	hasFigures () const

virtual int	getNumFigures () const

virtual cFigure *	getFigure (int pos) const

virtual cFigure *	getFigure (const char *name) const

Accessing the figure tree.
virtual cFigure *	getSubmodulesLayer () const

virtual cFigure *	findFigureRecursively (const char *name) const

virtual cFigure *	getFigureByPath (const char *path) const

Figure tags.
virtual std::string	getAllTags () const

virtual std::vector< std::string >	getAllTagsAsVector () const

Animation.
virtual void	setAnimationSpeed (double animationSpeed, const cObject *source)

virtual double	getAnimationSpeed (const cObject *source)

virtual void	holdSimulationFor (double animationTimeDelta)

Public Member Functions inherited from cOwnedObject
	cOwnedObject ()

	cOwnedObject (const char *name, bool namepooling=true)

	cOwnedObject (const cOwnedObject &obj)

virtual	~cOwnedObject ()

cOwnedObject &	operator= (const cOwnedObject &o)

virtual void	parsimPack (cCommBuffer *buffer) const override

virtual void	parsimUnpack (cCommBuffer *buffer) override

virtual cObject *	getOwner () const override

virtual bool	isOwnedObject () const override

Public Member Functions inherited from cNamedObject
	cNamedObject ()

	cNamedObject (const char *name, bool namepooling=true)

	cNamedObject (const cNamedObject &obj)

virtual	~cNamedObject ()

cNamedObject &	operator= (const cNamedObject &o)

virtual void	setName (const char *s)

virtual const char *	getName () const override

virtual void	setNamePooling (bool b)

virtual bool	getNamePooling ()

Public Member Functions inherited from cObject
	cObject ()

	cObject (const cObject &other)=default

virtual	~cObject ()

virtual const char *	getClassName () const

bool	isName (const char *s) const

virtual const char *	getFullName () const

virtual std::string	getFullPath () const

virtual std::string	getClassAndFullName () const

virtual std::string	getClassAndFullPath () const

const cObject *	getThisPtr () const

virtual std::ostream &	printOn (std::ostream &os) const

virtual bool	isSoftOwner () const

cObject *	findObject (const char *name, bool deep=true)

virtual cClassDescriptor *	getDescriptor () const

void	copyNotSupported () const

Additional Inherited Members
Static Public Member Functions inherited from cOwnedObject
static long	getTotalObjectCount ()

static long	getLiveObjectCount ()

static void	resetObjectCounters ()

static cSoftOwner *	getOwningContext ()

Protected Member Functions inherited from cObject
virtual void	take (cOwnedObject *obj)

virtual void	drop (cOwnedObject *obj)

void	dropAndDelete (cOwnedObject *obj)

Member Function Documentation

◆ dup()

virtual cCanvas* dup ( ) const

inlineoverridevirtual

Should be redefined in subclasses to create an exact copy of this object. The default implementation just throws an error, to indicate that the method was not redefined.

Reimplemented from cObject.

◆ forEachChild()

virtual void forEachChild ( cVisitor * v )

overridevirtual

Enables traversing the object tree, performing some operation on each object. The operation is encapsulated in the particular subclass of cVisitor.

This method should be redefined in every subclass to call v->visit(obj) for every obj object contained.

Reimplemented from cObject.

◆ str()

virtual std::string str ( ) const

overridevirtual

Returns a brief, one-line description of the object. The returned string does (should) NOT include the object's name and class. This method is used to display object information at several places in the Qtenv GUI, among others.

Reimplemented from cObject.

◆ getBackgroundColor()

virtual const cFigure::Color& getBackgroundColor ( ) const

inlinevirtual

Returns the background color of the canvas.

◆ setBackgroundColor()

virtual void setBackgroundColor ( const cFigure::Color & color )

inlinevirtual

Sets the background color of the canvas.

◆ getHash()

virtual uint32_t getHash ( ) const

virtual

Returns a hash computed from all figures in the canvas, for fingerprint computation.

◆ getRootFigure()

virtual cFigure* getRootFigure ( ) const

inlinevirtual

Returns the root figure of the canvas. The root figure has no visual appearance, it solely serves as a container for other figures.

◆ addFigure() [1/2]

virtual void addFigure ( cFigure * figure )

inlinevirtual

Appends the given figure to the child list of the root figure.

References cFigure::addFigure().

◆ addFigure() [2/2]

virtual void addFigure	(	cFigure *	figure,
		int	pos
	)

inlinevirtual

Inserts the given figure into the child list of the root figure at the given position. Note that relative order in the child list only affects stacking order if the respective figures have the same Z-index.

References cFigure::addFigure().

◆ removeFigure() [1/2]

virtual cFigure* removeFigure ( cFigure * figure )

inlinevirtual

Removes the given figure from the child list of the root figure. An error is raised if the figure is not a child of the root figure.

References cFigure::removeFigure().

◆ removeFigure() [2/2]

virtual cFigure* removeFigure ( int pos )

inlinevirtual

Removes the kth figure from the child list of the root figure. An error is raised if pos is not in the range 0..getNumFigures()-1.

References cFigure::removeFigure().

◆ findFigure() [1/2]

virtual int findFigure ( const char * name ) const

inlinevirtual

Finds the first figure with the given name among the children of the root figure, and returns its index. If there is no such figure, -1 is returned.

References cFigure::findFigure().

◆ findFigure() [2/2]

virtual int findFigure ( cFigure * figure ) const

inlinevirtual

Finds the given figure among the children of the root figure, and returns its index. If it is not found, -1 is returned.

References cFigure::findFigure().

◆ hasFigures()

virtual bool hasFigures ( ) const

inlinevirtual

Returns true if this canvas contains any figures (apart from the root figure), and false otherwise.

References cFigure::containsFigures().

◆ getNumFigures()

virtual int getNumFigures ( ) const

inlinevirtual

Returns the number of the root figure's child figures.

References cFigure::getNumFigures().

◆ getFigure() [1/2]

virtual cFigure* getFigure ( int pos ) const

inlinevirtual

Returns the kth figure in the child list of the root figure. The index must be in the range 0..getNumFigures()-1. An out-of-bounds index will cause a runtime error.

References cFigure::getFigure().

◆ getFigure() [2/2]

virtual cFigure* getFigure ( const char * name ) const

inlinevirtual

Returns the first child figure of the root figure with the given name, or nullptr if there is no such figure.

References cFigure::getFigure().

◆ getSubmodulesLayer()

virtual cFigure* getSubmodulesLayer ( ) const

virtual

Returns the figure that (conceptionally) contains the figures displaying the submodules and connection arrows in the compound module. It may be used for positioning figures in Z order relative to submodules. This method returns nullptr for extra canvases that don't display submodules.

◆ findFigureRecursively()

virtual cFigure* findFigureRecursively ( const char * name ) const

inlinevirtual

Returns the first figure with the given name in the figure tree of the canvas, or nullptr if there is no such figure.

References cFigure::findFigureRecursively().

◆ getFigureByPath()

virtual cFigure* getFigureByPath ( const char * path ) const

inlinevirtual

Returns the figure identified by the given path, a string of figure names separated by dots. See cFigure::getFigureByPath().

References cFigure::getFigureByPath().

◆ getAllTags()

virtual std::string getAllTags ( ) const

virtual

Returns the union of the tags used by figures in this canvas as a single space-separated string.

◆ getAllTagsAsVector()

virtual std::vector<std::string> getAllTagsAsVector ( ) const

virtual

Returns the union of the tags used by figures in this canvas as a vector of strings.

◆ setAnimationSpeed()

virtual void setAnimationSpeed	(	double	animationSpeed,
		const cObject *	source
	)

virtual

Sets the preferred animation speed associated with the given source object. Specify zero or a negative speed value to clear (withdraw) a previously set animation speed request. The source object only serves as a key to allow clients register several animation speed requests with the option to later update and clear any of them.

The UI of the simulation will take these requests into account when determining the speed used for actual animation. (For example, the UI may take the minimum of the requested animation speeds across all currently viewed canvases, or it may ignore the requests and use an interactively given animation speed.)

See also: cEnvir::getAnimationSpeed(), cEnvir::getAnimationTime()

◆ getAnimationSpeed()

virtual double getAnimationSpeed ( const cObject * source )

virtual

Returns the animation speed request associated with the given source object, or 0 if none exists.

◆ holdSimulationFor()

virtual void holdSimulationFor ( double animationTimeDelta )

virtual

Requests a "hold" interval of the given length, starting at the current animation time. During a hold interval, only animation takes place, but simulation time does not progress and no events are processed. Hold intervals are intended for animating actions that take zero simulation time.

If a hold request is issued when there is one already in progress, the current hold will be extended as needed to incorporate the request. A hold request cannot be cancelled or shrunk.

When rendering (i.e. inside refreshDisplay()), use getEnvir()->getRemainingAnimationHoldTime() or getEnvir()->getAnimationTime() to query the progress of the animation.

See also: cEnvir::getRemainingAnimationHoldTime(), cEnvir::getAnimationTime()

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

ccanvas.h

Description

Public Member Functions

Additional Inherited Members

Member Function Documentation

◆ dup()

◆ forEachChild()

◆ str()

◆ getBackgroundColor()

◆ setBackgroundColor()

◆ getHash()

◆ getRootFigure()

◆ addFigure() [1/2]

◆ addFigure() [2/2]

◆ removeFigure() [1/2]

◆ removeFigure() [2/2]

◆ findFigure() [1/2]

◆ findFigure() [2/2]

◆ hasFigures()

◆ getNumFigures()

◆ getFigure() [1/2]

◆ getFigure() [2/2]

◆ getSubmodulesLayer()

◆ findFigureRecursively()

◆ getFigureByPath()

◆ getAllTags()

◆ getAllTagsAsVector()

◆ setAnimationSpeed()

◆ getAnimationSpeed()

◆ holdSimulationFor()