Tulip  4.3.0
Better Visualization Through Research
 All Classes Namespaces Files Functions Variables Enumerations Enumerator Properties Groups Pages
tlp::View Class Referenceabstract

#include <View.h>

Inherits QObject, tlp::Plugin, and tlp::Observable.

Inherited by tlp::ViewWidget.

Public Slots

void addRedrawTrigger (tlp::Observable *)
 
virtual void applySettings ()
 
virtual void centerView (bool graphChanged=false)
 
void clearRedrawTriggers ()
 
virtual void draw ()=0
 
void emitDrawNeededSignal ()
 
virtual void refresh ()
 
void removeRedrawTrigger (tlp::Observable *)
 
void setCurrentInteractor (tlp::Interactor *currentInteractor)
 
void setGraph (tlp::Graph *graph)
 
void setInteractors (const QList< tlp::Interactor * > &)
 
virtual void setState (const tlp::DataSet &)=0
 
virtual void setupUi ()=0
 
void showContextMenu (const QPoint &point, const QPointF &scenePoint)
 
virtual void treatEvent (const Event &)
 
virtual void undoCallback ()
 

Signals

void drawNeeded ()
 
void graphSet (tlp::Graph *)
 

Public Member Functions

 View ()
 
virtual ~View ()
 
virtual std::string category () const
 
virtual QGraphicsItem * centralItem () const
 
virtual QList< QWidget * > configurationWidgets () const
 
virtual QString configurationWidgetsStyleSheet () const
 
tlp::InteractorcurrentInteractor () const
 
tlp::Graphgraph () const
 
virtual QGraphicsView * graphicsView () const =0
 
std::string icon () const
 
QList< tlp::Interactor * > interactors () const
 
virtual QPixmap snapshot (const QSize &outputSize=QSize()) const =0
 
virtual tlp::DataSet state () const =0
 
void treatEvents (const std::vector< Event > &events)
 
QSet< tlp::Observable * > triggers () const
 
- Public Member Functions inherited from tlp::Plugin
virtual std::string author () const =0
 
virtual std::string date () const =0
 
virtual std::string group () const =0
 
virtual int id () const
 
virtual std::string info () const =0
 
virtual std::string major () const
 
virtual std::string minor () const
 
virtual std::string name () const =0
 
virtual std::string programmingLanguage () const
 
virtual std::string release () const =0
 
virtual std::string tulipMajor () const
 
virtual std::string tulipMinor () const
 
virtual std::string tulipRelease () const =0
 
- Public Member Functions inherited from tlp::WithParameter
template<typename T >
void addInOutParameter (const std::string &name, const std::string &help=std::string(), const std::string &defaultValue=std::string(), bool isMandatory=true)
 
template<typename T >
void addInParameter (const std::string &name, const std::string &help, const std::string &defaultValue, bool isMandatory=true)
 
template<typename T >
void addOutParameter (const std::string &name, const std::string &help=std::string(), const std::string &defaultValue=std::string(), bool isMandatory=true)
 
template<typename T >
void addParameter (const std::string &name, const std::string &help=std::string(), const std::string &defaultValue=std::string(), bool isMandatory=true)
 
const
tlp::ParameterDescriptionList
getParameters () const
 
bool inputRequired () const
 
- Public Member Functions inherited from tlp::WithDependency
void addDependency (const char *name, const char *release)
 
const std::list< Dependency > & dependencies () const
 
- Public Member Functions inherited from tlp::Observable
void addListener (Observable *const listener) const
 
void addObserver (Observable *const observer) const
 
unsigned int countListeners () const
 
unsigned int countObservers () const
 
unsigned int getReceived () const
 
unsigned int getSent () const
 
void removeListener (Observable *const listener) const
 
void removeObserver (Observable *const observerver) const
 

Protected Slots

virtual void currentInteractorChanged (tlp::Interactor *)
 
virtual void fillContextMenu (QMenu *, const QPointF &)
 
virtual void graphChanged (tlp::Graph *)=0
 
virtual void graphDeleted (tlp::Graph *parentGraph)=0
 
virtual void interactorsInstalled (const QList< tlp::Interactor * > &interactors)
 

Additional Inherited Members

- Static Public Member Functions inherited from tlp::Observable
static ObservablegetObject (tlp::node n)
 
static const tlp::VectorGraph & getObservableGraph ()
 
static void holdObservers ()
 
static bool isAlive (tlp::node n)
 
static unsigned int observersHoldCounter ()
 
static void unholdObservers ()
 
- Protected Member Functions inherited from tlp::Observable
 Observable (const Observable &)
 
tlp::Iterator< tlp::Observable * > * getObservables () const
 
bool hasOnlookers () const
 
void notifyObservers ()
 
void observableDeleted ()
 
Observableoperator= (const Observable &)
 
void sendEvent (const Event &message)
 
virtual void treatEvent (const Event &message)
 
- Protected Attributes inherited from tlp::WithParameter
ParameterDescriptionList parameters
 
- Protected Attributes inherited from tlp::WithDependency
std::list< Dependency_dependencies
 

Detailed Description

View plugins provide a way to dynamically add to a Tulip plateform various ways to visualize a graph.

A view takes the following elements as inputs:

  • A graph which contains the data to be displayed.
  • A state (tlp::DataSet) which contains initialization parameters.

As an output, a View must provide a QGraphicsView instance where all drawing is done. User interaction on a View is handled by the tlp::Interactor class. Several interactors can be installed on the same view but there can be only one active interactor at the same time. In the end, the view can provide several configuration widgets used to set up additional parameters.

When a View gets created, the following methods will always be called in the following order:

  • The constructor. Basically, you don't want to do anything in this method as View instance may be created at Tulip startup when the plugin system gets initialized. Subsequent methods will be called in order for the view to build UI elements
  • View::setupUi(). Notifies the view it can now build GUI components since every part of its initial state should be valid by now. Once this method is called, any call to View::graphicsView() is expected to return a valid pointer object.
  • View::setGraph. Sets the graph that is meant to be visualized in the View's panel.
  • View::setState(). Sets initial data. This method may be used to restore a previously backed-up state retrieved from the View::state() method.
  • View::interactorsInstalled(). Notifies the view of the available interactors. Interactors objects taken from the list have already been initialized.

Once the View is initialized, none of the previously mentioned methods, except View::setGraph(), can be called again. View::setGraph method may be called again to notify the view that another graph should be displayed (this may be a sub/parent graph of the previously displayed graph or a graph coming from a totally different hierarchy)

Views are meant to be managed by an overleying system. As a consequence, a view may not decide directly when to redraw. Thus, you should never call the View::draw() method. To notify the overleying system that your view needs to be redrawn, emit the View::drawNeeded() signal instead.

A tlp::View subclass automatically inherits from the tlp::Observable interface. The tlp::View interface also automatically listn to its active graph to trigger handling trigger when this graph gets deleted. When the graph associated to a View gets deleted, the View::graphDeleted() callback is triggered.

See Also
graphDeleted() for more informations.
Examples:
interactor_plugin/interactor_plugin.cpp.

Definition at line 73 of file View.h.

Constructor & Destructor Documentation

tlp::View::View ( )

Default constructor.

Warning
Code of this method should almost be a no-op. Subsequent calls on other methods should allow you to setup your view.
virtual tlp::View::~View ( )
virtual

Destructor View's GUI components (graphics view, configuration widgets) responisbility belongs to the overleying system. Thus, the View is not in charge of deleting its graphcis view. View's interactors are already deleted in the top class.

Member Function Documentation

void tlp::View::addRedrawTrigger ( tlp::Observable )
slot

Registers a new trigger for automatic view drawing. Triggers are tlp::Observable subclasses. Once registered, the view will listen to the trigger's events and emit the drawNeeded signal each time the Observable::treatEvents() callback is run. For more information about the Observable system,.

See Also
tlp::Observable
Note
This is a convenience function. However, using triggers prevent from performign extra checks on the data structure to know if a redraw must me made or not. For more control over event handling, you will have to implement your own treatEvent/treatEvents callback.
Warning
If your tlp::View subclass overloads the treatEvents method. You must make sure to call the View::treatEvents method in order to keep the triggers system working.
virtual void tlp::View::applySettings ( )
virtualslot

This method applies settings changed in the configuration widgets This method may be called from the overleying system in various situations. The View is expected to apply settings in an optimized way to prevent extra redraws. By default, this method does nothing.

virtual std::string tlp::View::category ( ) const
inlinevirtual

A string identifier for a plugin used for categorization purposes.

Returns
std::string the category of the plugin.

Implements tlp::Plugin.

Definition at line 96 of file View.h.

virtual void tlp::View::centerView ( bool  graphChanged = false)
virtualslot

Reset the visualization to the center. This method is called after major changes into the data structure. At this point, the user point of view should be reset and brought back to a point where all the data can be seen.

Note
It is expected for the view to be redrawn when calling centerView For a 3D visualization, this method could be implemented by centering the camera. For a table, this could be done by setting the scroll bar to the top position etc... By default, this method calls draw().
virtual QGraphicsItem* tlp::View::centralItem ( ) const
virtual

defines which item is considered as the central item in the view. The central item is considered to be a background item that will be set as parent of every graphics item added by the workspace into the view. By default, this method returns NULL, which means that no central item is defined.

Reimplemented in tlp::ViewWidget.

void tlp::View::clearRedrawTriggers ( )
slot

Clears the list of attached triggers This method removes all triggers associated to the View.

Note
From the moment this method is called, no update on previous triggers will be considered. Even if this is called during an Observable::holdObservers()
virtual QList<QWidget*> tlp::View::configurationWidgets ( ) const
virtual
Returns
a list of widgets that can be used to set up the view. Since several widgets can be retrived, user will be able to select them from a combo box where each widget will be identified by its windowsTitle.
See Also
View::applySettings()
Warning
This method must not instantiate configuration widgets on the fly.

Reimplemented in tlp::GlMainView.

virtual QString tlp::View::configurationWidgetsStyleSheet ( ) const
virtual

This method can be used to change the configuration widgets' style sheet. From Qt documentation: The style sheet contains a textual description of customizations to the widget's style, as described in the Qt Style Sheets document. see http://qt-project.org/doc/qt-4.7/stylesheet.html.

Returns
The stylesheet to use
tlp::Interactor* tlp::View::currentInteractor ( ) const
Returns
The currently active interactor. The active interactor is the one that currently recieve user inputs.
See Also
setCurrentInteractor();
Warning
This method may return a NULL pointer if no interactor is currently active.
virtual void tlp::View::currentInteractorChanged ( tlp::Interactor )
protectedvirtualslot

Callback method after setCurrentInteractor() was called. At this point, a call to View::currentInteractor() is considered valid and return the newly active interactor.

Warning
The interactor passed down to this method MAY BE a NULL pointer ! This means that no current interactor should be set.
virtual void tlp::View::draw ( )
pure virtualslot

Asks the view to draw. A call to draw() means that internal data has most probably been modified and that the View should take that into account when drawing.

void tlp::View::drawNeeded ( )
signal

Inform the overleying subsystem that this view needs to be drawn.

Note
Dependeing on the overlying implementation, a subsequent call to draw might not be immediate.
void tlp::View::emitDrawNeededSignal ( )
slot

This function emit the signal drawNeeded.

virtual void tlp::View::fillContextMenu ( QMenu *  ,
const QPointF &   
)
inlineprotectedvirtualslot

fills the context menu with entries related to the view. This method is called whenever the context menu is displayed on the panel.

Parameters
QMenuThe popup menu that will be displayed. This menu should be populated with context action related to the panel.

Definition at line 334 of file View.h.

tlp::Graph* tlp::View::graph ( ) const
Returns
the graph displayed by the view.
Note
This method MUST return the same graph pointer that was previously passed down to setGraph.
virtual void tlp::View::graphChanged ( tlp::Graph )
protectedpure virtualslot

Callback method after setGraph() was called. At this point, a call to View::graph() is considered valid and return the lastly set graph.

virtual void tlp::View::graphDeleted ( tlp::Graph parentGraph)
protectedpure virtualslot

Called when the graph associated to the view gets deleted. This method should call setGraph to input a new graph pointer (NULL or valid)

Parameters
parentGraphThe parent of the graph that was just deleted. If there is no parent available (eg. the graph was root), parentGraph is NULL
virtual QGraphicsView* tlp::View::graphicsView ( ) const
pure virtual
Returns
the View's panel as a QGraphicsView instance.
Note
This method MUST ALWAYS return the same instance of a QGraphicsView.

Implemented in tlp::ViewWidget.

Examples:
interactor_plugin/interactor_plugin.cpp.
void tlp::View::graphSet ( tlp::Graph )
signal

Emitted after the setGraph method has been called.

Note
This signal is emitted from the non-virtual View::setGraph() method thus cannot be prevented.
std::string tlp::View::icon ( ) const
inlinevirtual

The icon (preferably a thumbnail) of the plugin.

Returns
std::string the icon path

Reimplemented from tlp::Plugin.

Definition at line 99 of file View.h.

QList<tlp::Interactor*> tlp::View::interactors ( ) const
Returns
The list of interactors installed on this view. The list is always the same as the one given when View::setInteractors() was called.
See Also
setInteractors();
virtual void tlp::View::interactorsInstalled ( const QList< tlp::Interactor * > &  interactors)
protectedvirtualslot

Callback method after setInteractors() was called. At this point, a call to View::interactors() is considered valid.

virtual void tlp::View::refresh ( )
inlinevirtualslot

Refresh the View's panel. Calling refresh() means that no internal data has been modified. This can happen when the view's panel gets resized, restored etc.

Definition at line 245 of file View.h.

void tlp::View::removeRedrawTrigger ( tlp::Observable )
slot

Removes a trigger from the list of registered triggers. Event coming from this trigger will no longer trigger the drawNeeded signal.

See Also
View::addRedrawTrigger()
void tlp::View::setCurrentInteractor ( tlp::Interactor currentInteractor)
slot

defines the active interactor that will receive user inputs.

Note
This method will first remove the previously active interactor (if any) using Interactor::uninstall()
Calling this will trigger the View::currentInteractorChanged() callback for custom handling.
Calling View::setCurrentInteractor(NULL) will only remove the previous current interactor.
void tlp::View::setGraph ( tlp::Graph graph)
slot

Defines the graph that should be displayed by the View.

Note
Calling setGraph triggers the View::graphChanged() callback for custom handling.
Warning
This method and its subsequent callback might be called several times.
void tlp::View::setInteractors ( const QList< tlp::Interactor * > &  )
slot

defines the list of interactors available on this View

Note
Calling this will trigger the View::interactorsInstalled() callback for custom handling.
virtual void tlp::View::setState ( const tlp::DataSet )
pure virtualslot

Restores the state of the view. DataSet passed down to this method can come from a previous backup or be generated by the overleying system. It's up to the view to use this data or not.

virtual void tlp::View::setupUi ( )
pure virtualslot

Sets up GUI elements belonging to the View. This method is called once the initial state as been set (using setGraph and setState) and is called only once.

void tlp::View::showContextMenu ( const QPoint &  point,
const QPointF &  scenePoint 
)
slot

This method is called whenever the context menu is required on the view.

Parameters
pointThe screen coordinates where the context menu should be displayed.
virtual QPixmap tlp::View::snapshot ( const QSize &  outputSize = QSize()) const
pure virtual

Takes a snapshot of the view's screen and saves it into the given pixmap. The snapshot is scaled to outputSize. If a null size is given, the snapshot is to be on a 1:1 ratio.

Returns
A non-null pixmap of the snapshot was correctly taken.

Implemented in tlp::ViewWidget, and tlp::GlMainView.

virtual tlp::DataSet tlp::View::state ( ) const
pure virtual

Backup the state of the view. This method is used to restore the View's parameters when it's re-opened.

virtual void tlp::View::treatEvent ( const Event )
virtualslot

This method is inherited from tlp::Observable and allows the view to trigger custom callback when its associated graph gets deleted.

Warning
When overriding this method. You MUST always make a call to View::treatEvent before doing anything in order to keep this callback working.
void tlp::View::treatEvents ( const std::vector< Event > &  events)
virtual

reimplemented from tlp::Observable to provide the triggers mechanism.

See Also
View::addRedrawTrigger()

Reimplemented from tlp::Observable.

QSet<tlp::Observable*> tlp::View::triggers ( ) const
Returns
The list of currently registered triggers.
See Also
View::addRedrawTrigger()
virtual void tlp::View::undoCallback ( )
virtualslot

This method is a callback to notify the panel that the pop() method (undo) has just been called on the graph. By default, this method will make a call to centerView()