OMNeT++ Simulation Library  5.6.1
cFigure Class Referenceabstract

#include <ccanvas.h>

Description

A lightweight graphical object for cCanvas.

This is the central class of OMNeT++'s 2D drawing API. Graphical elements are called figures, and are represented by subclasses of cFigure. To display a figure-based drawing, one needs to add figures to a canvas (cCanvas). Every module has its own canvas, accessible via cModule::getCanvas(), and one may also create additional ones.

Notes:

  • figures can be hierarchical (resulting in a figure tree)
  • coordinates are in canvas units, not in pixels (interactive zooming!)
  • coordinates are transformed with the figure's own transform plus the transforms of all ancestors
  • a figure subtree can be hidden by calling setVisible(false)
  • the order of child figures also denotes drawing order (of overlapping figures, the last one will appear on top)
  • dup() makes shallow copy (doesn't copy child figures); see dupTree() as well
  • figures are only data storage classes, rendering is done in the back-end (e.g. Tkenv) by separate renderer classes.
See also
cCanvas
Inheritance diagram for cFigure:
cOwnedObject cNamedObject cObject cAbstractImageFigure cAbstractLineFigure cAbstractShapeFigure cAbstractTextFigure cGroupFigure cPanelFigure cImageFigure cPixmapFigure cArcFigure cLineFigure cPolylineFigure cOvalFigure cPathFigure cPieSliceFigure cPolygonFigure cRectangleFigure cRingFigure cLabelFigure cTextFigure

Classes

struct  Color
 Represents an RGB color. More...
 
struct  Font
 Represents properties of a font. More...
 
class  Pixmap
 A rectangular RGBA pixel array. More...
 
struct  Point
 Represents a point as (x,y) coordinates. More...
 
struct  Rectangle
 Represents a rectangle as an (x,y,width,height) tuple. More...
 
struct  RGBA
 Represents an RGBA pixel, for Pixmap manipulation. More...
 
struct  Transform
 Homogeneous 2D transformation matrix. More...
 

Public Types

enum  FontStyle
 Font style constants: FONT_NONE, FONT_BOLD, etc. More...
 
enum  LineStyle
 Line style constants: LINE_SOLID, LINE_DOTTED, etc. More...
 
enum  CapStyle
 Line cap style constants: CAP_BUTT, CAP_SQUARE, etc. More...
 
enum  JoinStyle
 Line join style constants: JOIN_BEVEL, JOIN_MITER, etc. More...
 
enum  FillRule
 Fill rule constants: FILL_EVENODD, FILL_NONZERO. More...
 
enum  Arrowhead
 Arrowhead style constants: ARROW_NONE, ARROW_SIMPLE, etc. More...
 
enum  Interpolation
 Image interpolation mode constants: INTERPOLATION_NONE, INTERPOLATION_FAST, etc. More...
 
enum  Anchor
 Anchoring mode constants: ANCHOR_CENTER, ANCHOR_N, etc. More...
 

Public Member Functions

Constructors, destructor, assignment
 cFigure (const char *name=nullptr)
 
 cFigure (const cFigure &other)
 
virtual ~cFigure ()
 
cFigureoperator= (const cFigure &other)
 
Redefined cObject member functions.
virtual cFiguredup () const override
 
virtual void forEachChild (cVisitor *v) override
 
virtual std::string str () const override
 
Common figure attributes.
int getId () const
 
virtual bool isVisible () const
 
virtual void setVisible (bool visible)
 
virtual const TransformgetTransform () const
 
virtual void setTransform (const Transform &transform)
 
virtual void resetTransform ()
 
virtual double getZIndex () const
 
virtual void setZIndex (double zIndex)
 
virtual double getEffectiveZIndex () const
 
virtual const char * getTooltip () const
 
virtual void setTooltip (const char *tooltip)
 
virtual cObjectgetAssociatedObject () const
 
virtual void setAssociatedObject (cObject *obj)
 
virtual const char * getTags () const
 
virtual void setTags (const char *tags)
 
Accessing the parent figure and child figures.
virtual cFiguregetParentFigure () const
 
virtual cCanvasgetCanvas () const
 
virtual int getNumFigures () const
 
virtual cFiguregetFigure (int pos) const
 
virtual cFiguregetFigure (const char *name) const
 
virtual int findFigure (const char *name) const
 
virtual int findFigure (const cFigure *figure) const
 
virtual bool containsFigures () const
 
virtual cFigurefindFigureRecursively (const char *name) const
 
virtual cFiguregetFigureByPath (const char *path) const
 
Managing child figures.
virtual void addFigure (cFigure *figure)
 
virtual void addFigure (cFigure *figure, int pos)
 
_OPPDEPRECATED void addFigureAbove (cFigure *figure, cFigure *referenceFigure)
 
_OPPDEPRECATED void addFigureBelow (cFigure *figure, cFigure *referenceFigure)
 
virtual cFigureremoveFigure (cFigure *figure)
 
virtual cFigureremoveFigure (int pos)
 
virtual cFigureremoveFromParent ()
 
Managing stacking order
virtual bool isAbove (const cFigure *figure) const
 
virtual bool isBelow (const cFigure *figure) const
 
virtual void insertAbove (cFigure *referenceFigure)
 
virtual void insertBelow (cFigure *referenceFigure)
 
virtual void insertAfter (const cFigure *referenceFigure)
 
virtual void insertBefore (const cFigure *referenceFigure)
 
virtual void raiseAbove (cFigure *figure)
 
virtual void lowerBelow (cFigure *figure)
 
virtual void raiseToTop ()
 
virtual void lowerToBottom ()
 
virtual cFiguredupTree () const
 
Operations on the transformation matrix.
virtual void translate (double dx, double dy)
 
virtual void scale (double s)
 
virtual void scale (double sx, double sy)
 
virtual void scale (double sx, double sy, double cx, double cy)
 
virtual void scale (double sx, double sy, const Point &c)
 
virtual void rotate (double phi)
 
virtual void rotate (double phi, double cx, double cy)
 
virtual void rotate (double phi, const Point &c)
 
virtual void skewx (double coeff)
 
virtual void skewy (double coeff)
 
virtual void skewx (double coeff, double cy)
 
virtual void skewy (double coeff, double cx)
 
Miscellaneous.
virtual void parse (cProperty *property)
 
virtual const char ** getAllowedPropertyKeys () const
 
virtual void moveLocal (double dx, double dy)=0
 
virtual void move (double dx, double dy)
 
virtual void refreshDisplay ()
 
virtual const char * getRendererClassName () const =0
 
- Public Member Functions inherited from cOwnedObject
 cOwnedObject ()
 
 cOwnedObject (const char *name, bool namepooling=true)
 
 cOwnedObject (const cOwnedObject &obj)
 
virtual ~cOwnedObject ()
 
cOwnedObjectoperator= (const cOwnedObject &o)
 
virtual void parsimPack (cCommBuffer *buffer) const override
 
virtual void parsimUnpack (cCommBuffer *buffer) override
 
virtual cObjectgetOwner () const override
 
virtual bool isOwnedObject () const override
 
virtual bool isSoftOwner () const
 
- Public Member Functions inherited from cNamedObject
 cNamedObject ()
 
 cNamedObject (const char *name, bool namepooling=true)
 
 cNamedObject (const cNamedObject &obj)
 
virtual ~cNamedObject ()
 
cNamedObjectoperator= (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)
 
virtual ~cObject ()
 
virtual const char * getClassName () const
 
bool isName (const char *s) const
 
virtual const char * getFullName () const
 
virtual std::string getFullPath () const
 
const cObjectgetThisPtr () const
 
virtual _OPPDEPRECATED std::string info () const
 
virtual _OPPDEPRECATED std::string detailedInfo () const
 
cObjectfindObject (const char *name, bool deep=true)
 
void copyNotSupported () const
 

Static Public Attributes

Predefined colors.
static const Color BLACK
 
static const Color WHITE
 
static const Color GREY
 
static const Color RED
 
static const Color GREEN
 
static const Color BLUE
 
static const Color YELLOW
 
static const Color CYAN
 
static const Color MAGENTA
 
static const int NUM_GOOD_DARK_COLORS
 
static const int NUM_GOOD_LIGHT_COLORS
 
static const Color GOOD_DARK_COLORS [14]
 
static const Color GOOD_LIGHT_COLORS [10]
 

Additional Inherited Members

- Static Public Member Functions inherited from cOwnedObject
static long getTotalObjectCount ()
 
static long getLiveObjectCount ()
 
static void resetObjectCounters ()
 
static cDefaultListgetDefaultOwner ()
 
- Protected Member Functions inherited from cObject
virtual void take (cOwnedObject *obj)
 
virtual void drop (cOwnedObject *obj)
 
void dropAndDelete (cOwnedObject *obj)
 

Constructor & Destructor Documentation

◆ cFigure() [1/2]

cFigure ( const char *  name = nullptr)
explicit

Constructor.

◆ cFigure() [2/2]

cFigure ( const cFigure other)
inline

Copy constructor. Child figures and the figure ID are not copied.

◆ ~cFigure()

virtual ~cFigure ( )
virtual

Destructor

Member Function Documentation

◆ operator=()

cFigure& operator= ( const cFigure other)

Assignment operator. It copies all data members except the object name, figure ID and child figures. (See cNamedObject's operator=() for details.)

◆ dup()

virtual cFigure* dup ( ) const
inlineoverridevirtual

Clones the figure, ignoring its child figures. (The copy will have no children.) To clone a figure together with its figure subtree, use dupTree().

Reimplemented from cObject.

Reimplemented in cPixmapFigure, cIconFigure, cImageFigure, cAbstractImageFigure, cLabelFigure, cTextFigure, cAbstractTextFigure, cPathFigure, cPolygonFigure, cPieSliceFigure, cRingFigure, cOvalFigure, cRectangleFigure, cAbstractShapeFigure, cPolylineFigure, cArcFigure, cLineFigure, cAbstractLineFigure, cPanelFigure, and cGroupFigure.

◆ forEachChild()

virtual void forEachChild ( cVisitor v)
overridevirtual

Calls v->visit(this) on each child figure. See cObject for more details.

Reimplemented from cObject.

◆ str()

virtual std::string str ( ) const
overridevirtual

◆ getId()

int getId ( ) const
inline

Returns the unique ID of this figure object. This ID is mostly intended for internal use.

◆ isVisible()

virtual bool isVisible ( ) const
inlinevirtual

Returns the visibility flag of the figure.

◆ setVisible()

virtual void setVisible ( bool  visible)
virtual

Sets the visibility flag of the figure. Setting the visibility flag to false will cause the whole figure subtree to be omitted from rendering.

◆ getTransform()

virtual const Transform& getTransform ( ) const
inlinevirtual

Returns the transform associated with this figure.

◆ setTransform()

virtual void setTransform ( const Transform transform)
virtual

Sets the transform associated with this figure. The transform will affect the rendering of this figure and its whole figure subtree. The transform may also be modified with the various translate(), scale(), rotate(), skewx()/skewy() methods.

◆ resetTransform()

virtual void resetTransform ( )
inlinevirtual

Convenience method: sets the transformation to identity transform.

◆ getZIndex()

virtual double getZIndex ( ) const
inlinevirtual

Returns the Z-index of the figure.

See also
getEffectiveZIndex()

◆ setZIndex()

virtual void setZIndex ( double  zIndex)
virtual

Sets the Z-index of the figure. The Z-index affects the stacking order of figures via the effective Z-index. The effective Z-index is computed as the sum of the Z-indices of this figure and its ancestors'. A figure with a greater effective Z-index is always in front of an element with a lower effective Z-index. For figures with the same effective Z-index, their relative order in the preorder traversal of the figure hierarchy defines the stacking order. (A later figure is in front of the earlier ones.)

◆ getEffectiveZIndex()

virtual double getEffectiveZIndex ( ) const
virtual

Returns the effective Z-index of the figure. The effective Z-index is computed as the sum of the Z-indices of this figure and its ancestors'. A figure with a greater effective Z-index is always in front of an element with a lower effective Z-index.

◆ getTooltip()

virtual const char* getTooltip ( ) const
inlinevirtual

Returns the tooltip of the figure, or nullptr if it does not have one.

◆ setTooltip()

virtual void setTooltip ( const char *  tooltip)
virtual

Sets the tooltip of the figure. Pass nullptr to clear the tooltip. If nullptr is set, the effective tooltip will be inherited from the associated object if there is one (see getAssociatedObject()), or from the parent figure. Empty tooltips will not be shown.

◆ getAssociatedObject()

virtual cObject* getAssociatedObject ( ) const
inlinevirtual

Returns the simulation object associated with this figure, or nullptr if it does not have one. The GUI may use this function to provide a shortcut access to the specified object, e.g. select the object in an inspector when the user clicks the figure.

◆ setAssociatedObject()

virtual void setAssociatedObject ( cObject obj)
virtual

Sets the simulation object associated with this figure. The user is responsible for ensuring that the pointer is valid (the corresponding object exists), and remains valid while it is associated with the figure.

◆ getTags()

virtual const char* getTags ( ) const
inlinevirtual

Returns the space-separated list of the tags associated with the figure. Tags may be used in the GUI displaying a canvas for implementing layers or other kind of filtering.

◆ setTags()

virtual void setTags ( const char *  tags)
virtual

Sets the list of tags associated with the figure. This method accepts a space-separated list of tags. (Tags themselves may not contain spaces; underscores are recommended instead where needed.)

◆ getParentFigure()

virtual cFigure* getParentFigure ( ) const
inlinevirtual

Returns the parent figure of this figure, or nullptr if it has none.

◆ getCanvas()

virtual cCanvas* getCanvas ( ) const
virtual

Returns the canvas object to which this figure was added, or nullptr if there is no such canvas. Note that the runtime cost of this method is proportional to the depth of this figure in the figure tree.

◆ getNumFigures()

virtual int getNumFigures ( ) const
inlinevirtual

Returns the number of child figures.

Referenced by cCanvas::getNumFigures().

◆ getFigure() [1/2]

virtual cFigure* getFigure ( int  pos) const
virtual

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

Referenced by cCanvas::getFigure().

◆ getFigure() [2/2]

virtual cFigure* getFigure ( const char *  name) const
virtual

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

◆ findFigure() [1/2]

virtual int findFigure ( const char *  name) const
virtual

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

Referenced by cCanvas::findFigure().

◆ findFigure() [2/2]

virtual int findFigure ( const cFigure figure) const
virtual

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

◆ containsFigures()

virtual bool containsFigures ( ) const
inlinevirtual

Returns true if this figure has child figures, and false otherwise.

Referenced by cCanvas::hasFigures().

◆ findFigureRecursively()

virtual cFigure* findFigureRecursively ( const char *  name) const
virtual

Find the first figure with the given name in this figure's subtree, including the figure itself. Returns nullptr if no such figure is found.

Referenced by cCanvas::findFigureRecursively().

◆ getFigureByPath()

virtual cFigure* getFigureByPath ( const char *  path) const
virtual

Finds a figure in the subtree, given by its absolute or relative path. The path is a string of figure names separated by dots; the special module name ^ (caret) stands for the parent figure. If the path starts with a dot or caret, it is understood as relative to this figure, otherwise it is taken to mean an absolute path (i.e. relative to the root figure, see getRootFigure()). Returns nullptr if the figure was not found.

Examples:

  • "." means this figure;
  • ".icon" means the child figure name "icon";
  • ".group.label" means the "label" child of the "group" child figure;
  • "^.icon" or ".^.icon" means the "icon" sibling of this figure;
  • "icon" means the "icon" child of the root figure

The above syntax is similar to the one used by cModule::getModuleByPath()

Referenced by cCanvas::getFigureByPath().

◆ addFigure() [1/2]

virtual void addFigure ( cFigure figure)
virtual

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

Referenced by cCanvas::addFigure().

◆ addFigure() [2/2]

virtual void addFigure ( cFigure figure,
int  pos 
)
virtual

Inserts the given figure into the child list of this 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.

◆ addFigureAbove()

_OPPDEPRECATED void addFigureAbove ( cFigure figure,
cFigure referenceFigure 
)
inline

DEPRECATED. Use figure->insertAbove(referenceFigure) instead.

References cFigure::insertAbove().

◆ addFigureBelow()

_OPPDEPRECATED void addFigureBelow ( cFigure figure,
cFigure referenceFigure 
)
inline

DEPRECATED. Use figure->insertBelow(referenceFigure) instead.

References cFigure::insertBelow().

◆ removeFigure() [1/2]

virtual cFigure* removeFigure ( cFigure figure)
virtual

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

Prefer removeFromParent() to this method.

Referenced by cCanvas::removeFigure().

◆ removeFigure() [2/2]

virtual cFigure* removeFigure ( int  pos)
virtual

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

Prefer removeFromParent() to this method.

◆ removeFromParent()

virtual cFigure* removeFromParent ( )
virtual

Removes this figure from the child list of its parent figure. It has no effect if the figure has no parent figure.

◆ isAbove()

virtual bool isAbove ( const cFigure figure) const
virtual

Returns true if this figure is above the given reference figure in stacking order, based on their Z-index values and their relative order in the parent's child list, and false if not. The method throws an error if the two figures are not under the same parent.

◆ isBelow()

virtual bool isBelow ( const cFigure figure) const
virtual

Returns true if this figure is below the given reference figure in stacking order, based on their Z-index values and their relative order in the parent's child list, and false if not. The method throws an error if the two figures are not under the same parent.

◆ insertAbove()

virtual void insertAbove ( cFigure referenceFigure)
virtual

Inserts this figure under the same parent as the reference figure, guaranteeing that it will appear above the reference figure in stacking order. In order to achieve the latter, the Z-index of the figure is set to the Z-index of the reference figure if it was smaller. In case of equal Z-indices, the figure is inserted right after the reference figure. If the Z-index of the figure is already greater than that of the reference figure, nothing should be assumed about the insertion position.

See also
insertAfter()

Referenced by cFigure::addFigureAbove(), and cCanvas::addFigureAbove().

◆ insertBelow()

virtual void insertBelow ( cFigure referenceFigure)
virtual

Inserts this figure under the same parent as the reference figure, guaranteeing that it will appear below the reference figure in stacking order. In order to achieve the latter, the Z-index of the figure is set to the Z-index of the reference figure if it was greater. In case of equal Z-indices, the figure is inserted right before the reference figure. If the Z-index of the figure is already smaller than that of the reference figure, nothing should be assumed about the insertion position.

See also
insertBefore()

Referenced by cFigure::addFigureBelow(), and cCanvas::addFigureBelow().

◆ insertAfter()

virtual void insertAfter ( const cFigure referenceFigure)
virtual

Inserts this figure after the given reference figure in its parent's child list. BEWARE: Relative order in the child list only affects stacking order if the respective figures have the same Z-index.

◆ insertBefore()

virtual void insertBefore ( const cFigure referenceFigure)
virtual

Inserts this figure in front of the given reference figure in its parent's child list. BEWARE: Relative order in the child list only affects stacking order if the respective figures have the same Z-index.

◆ raiseAbove()

virtual void raiseAbove ( cFigure figure)
virtual

If this figure is below the given reference figure in stacking order, move it directly above. This is achieved by updating its Z-index if needed, and moving it in the parent's child list. An error is raised if the two figures do not share the same parent.

◆ lowerBelow()

virtual void lowerBelow ( cFigure figure)
virtual

If this figure is above the given reference figure in stacking order, move it directly below. This is achieved by updating its Z-index if needed, and moving it in the parent's child list. An error is raised if the two figures do not share the same parent.

◆ raiseToTop()

virtual void raiseToTop ( )
virtual

Raise this figure above all other figures under the same parent. This is achieved by updating its Z-index if needed (setting it to be at least the maximum of the Z-indices of the other figures), and moving it in the parent's child list. It is an error if this figure has no parent.

◆ lowerToBottom()

virtual void lowerToBottom ( )
virtual

Lower this figure below all other figures under the same parent. This is achieved by updating its Z-index if needed (setting it to be at most the minimum of the Z-indices of the other figures), and moving it in the parent's child list. It is an error if this figure has no parent.

◆ dupTree()

virtual cFigure* dupTree ( ) const
virtual

Duplicate the figure subtree.

◆ parse()

virtual void parse ( cProperty property)
virtual

This method is invoked by the simulation library to initialize the figure from a @figure NED property. Custom figure classes usually need to override this method (and call the super class' similar method in it).

Note: When overriding parse(), it is usually also necessary to override getAllowedPropertyKeys(), in order to allow new keys in the @figure property.

Reimplemented in cPixmapFigure, cImageFigure, cAbstractImageFigure, cLabelFigure, cAbstractTextFigure, cPathFigure, cPolygonFigure, cPieSliceFigure, cRingFigure, cOvalFigure, cRectangleFigure, cAbstractShapeFigure, cPolylineFigure, cArcFigure, cLineFigure, cAbstractLineFigure, and cPanelFigure.

◆ getAllowedPropertyKeys()

virtual const char** getAllowedPropertyKeys ( ) const
virtual

Returns the list of allowed keys in @figure properties with this figure type, in a nullptr-terminated array of const char* elements. This method is invoked e.g. from parse(), in order to be able to issue error messages for invalid keys in the property. Note that property keys starting with "x-" are already allowed by default. Custom figure classes usually need to override this method together with parse(); see the source code of the library classes for example implementations.

Reimplemented in cPixmapFigure, cImageFigure, cAbstractImageFigure, cLabelFigure, cAbstractTextFigure, cPathFigure, cPolygonFigure, cPieSliceFigure, cRingFigure, cOvalFigure, cRectangleFigure, cAbstractShapeFigure, cPolylineFigure, cArcFigure, cLineFigure, cAbstractLineFigure, and cPanelFigure.

◆ moveLocal()

virtual void moveLocal ( double  dx,
double  dy 
)
pure virtual

Change the figure's position by the given x and y deltas. Child figures will not be affected.

Implemented in cAbstractImageFigure, cAbstractTextFigure, cPathFigure, cPolygonFigure, cPieSliceFigure, cRingFigure, cOvalFigure, cRectangleFigure, cPolylineFigure, cArcFigure, cLineFigure, cPanelFigure, and cGroupFigure.

◆ move()

virtual void move ( double  dx,
double  dy 
)
virtual

Change the position of this figure and the figures in its subtree by the given x and y deltas. The implementation of this method calls moveLocal() on this figure, then move() recursively on child figures.

Reimplemented in cPanelFigure.

◆ refreshDisplay()

virtual void refreshDisplay ( )
inlinevirtual

This method is invoked by runtime GUIs on every display refresh, and can be overridden if the figure needs to be able to update its contents dynamically (self-refreshing figures.) The changes done inside this method should be restricted to this figure and its subfigure tree.

◆ getRendererClassName()

virtual const char* getRendererClassName ( ) const
pure virtual

Returns the name of the class responsible for rendering this figure. Renderer classes are specific to, and are usually implemented as part of, the graphical user interface library (Tkenv or Qtenv).

Implemented in cPixmapFigure, cIconFigure, cImageFigure, cLabelFigure, cTextFigure, cPathFigure, cPolygonFigure, cPieSliceFigure, cRingFigure, cOvalFigure, cRectangleFigure, cPolylineFigure, cArcFigure, cLineFigure, cPanelFigure, and cGroupFigure.


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