%%
%% This file is part of the ViTE project.
%%
%% This software is governed by the CeCILL-A license under French law
%% and abiding by the rules of distribution of free software. You can
%% use, modify and/or redistribute the software under the terms of the
%% CeCILL-A license as circulated by CEA, CNRS and INRIA at the following
%% URL: "http://www.cecill.info".
%% 
%% As a counterpart to the access to the source code and rights to copy,
%% modify and redistribute granted by the license, users are provided
%% only with a limited warranty and the software's author, the holder of
%% the economic rights, and the successive licensors have only limited
%% liability.
%% 
%% In this respect, the user's attention is drawn to the risks associated
%% with loading, using, modifying and/or developing or reproducing the
%% software by the user in light of its specific status of free software,
%% that may mean that it is complicated to manipulate, and that also
%% therefore means that it is reserved for developers and experienced
%% professionals having in-depth computer knowledge. Users are therefore
%% encouraged to load and test the software's suitability as regards
%% their requirements in conditions enabling the security of their
%% systems and/or data to be ensured and, more generally, to use and
%% operate it in the same conditions as regards security.
%% 
%% The fact that you are presently reading this means that you have had
%% knowledge of the CeCILL-A license and that you accept its terms.
%%
%%
%% ViTE developers are:
%%
%%        - COULOMB Kevin
%%        - FAVERGE Mathieu
%%        - JAZEIX Johnny
%%        - LAGRASSE Olivier
%%        - MARCOUEILLE Jule
%%        - NOISETTE Pascal
%%        - REDONDY Arthur
%%        - VUCHENER Clément 
%%

\section{Overview}

The plugin module has been designed in order to provide more functionalities to the users.
Its main utility is to show statistics of traces but it could be used for other things like communicate with other programs, use filters on the trace...

\section{How to build a plugin}
The main classes for creating plugins are the Plugin and PluginWindow ones.

The PluginWindow class looks for plugins in your \$HOME/.vite directory (and the ones you have set in the preference window) and loads them. Also, it loads the static plugins created by ViTE developers. The plugins are loaded using the QLibrary class from Qt in order to be portable. The plugins window is shown on figure \ref{plugin_window}.

\begin{figure}[ht!]
\centering
\includegraphics[height=13cm]{images/plugins_window}
\caption{The plugins window.\label{plugin_window}}
\end{figure}


The Plugin class is the base class for plugins. It inherits the QWidget class which is the base class for showing windows in Qt.
It contains the basic methods used to load and initialize a plugin~:

\begin{c++}
class Plugin : public QWidget {
protected:
    std::string _name;
    Trace*_trace;

public:
    Plugin(QWidget *parent = 0) : QWidget(parent){}
    virtual void init() = 0;
    virtual void clear() = 0;
    virtual void execute() = 0;
    virtual std::string get_name() = 0;
    virtual void set_arguments(std::map<std::string /*argname*/,
                               QVariant */*argValue*/>) = 0;

    virtual void set_trace(Trace *t) { _trace = t; }
};
\end{c++}

The \textit{init} method is called once after the plugin is created and the trace set. It should initialize the plugin.

The  \textit{clear} method clears the window corresponding to this plugin. It is called when you change the tab.

The \textit{execute} method is called when you click on the execute button in the plugin window. It should execute the plugin.

The \textit{get\_name} method returns the name of the plugin. The name is used as the title of the tab.

The \textit{set\_arguments} method is used to set arguments... Not yet sure of the prototype :).

Moreover, your plugin must contains a \textbf{create} function as the following one (if your class is a NewPlugin one):

\begin{c++}
extern "C" {
    Plugin *create() { return new NewPlugin(); }
}
\end{c++}

In order to create the window, you can use the Qt Designer or create it from zero in the code.

To compile a plugin, the easiest way is to use a Qt .pro file and use qmake. You create a \textbf{lib} template
and put all the files you need in order to compile the plugin.

Then to use it, you put the shared library created in the \$HOME/.vite directory. You can launch \ViTE again and it
should appears in the plugin window.

You have an example of a simple plugin in the plugin\_directory directory (created from zero) and a more difficult with the statistics one.

The class should looks like this~: 

% "Q_OBJECT // Important!! Used by Qt to make the slots and signals works!" ?
\begin{c++}
#include "Plugin.hpp"

class NewPlug : public Plugin {
  
  private:
    attributes, methods...

  public:
    NewPlug(QWidget *parent = 0) : Plugin(parent){}
    void init() { printf("init\n"); }
    void clear() { printf("clear\n"); }
    void execute() { printf("execute\n");}
    std::string get_name() {return "New plug";}
    void set_arguments(std::map<std::string,
                       QVariant *>) { ... };
    ...
};

extern "C" {
  Plugin *create() { return new NewPlug();}
}
\end{c++}

\section{Existing plugins}
\subsection{The statistic window}
This plugin allows the user to watch some statistics on the code.
The statistics are provided in order to ease the access to important data. For example, without them it could be hard to compute the time for each states in a container.

It is useful when you need to know how many time a processor works.

This paragraph will describe how the statistic window works as well as the different stats already implemented.

\subsubsection*{The stats window}

The window is designed with \emph{Qt Designer}. The designed file is in the \emph{interface} folder and the source code in the \emph{statistic} folder.
It is divided in three important part as you can see in the figure \ref{Stats_window}.
The first one is to set the values for which kind of statistic you want.
There are two QLabel for the times and two box for the kind of diagram and the kind of states you want to print.

The second is the tree of each node you can have statistics.
It is a QTreeWidget filled recursively in the constructor.

The third one is the most important, it is the stats render.
It is a \textit{render\_stats\_opengl} object. This class inherits from a \emph{QGLWidget} and is used to show the diagrams.

The same idea that for the trace render has been used. That means that we did an interface for the render which enable us to convert stats in which format we want (... which is implemented of course).
This is why we can watch the stats in two formats~: the openGL one which is used for the render and the svg one which is used to be exported.

\begin{figure}[ht!]
\centering
\includegraphics[width=12cm]{images/stats_window}
\caption{\label{Stats_window} The statistic window}
\end{figure}

\subsubsection*{The DrawStats template}
This is the interface which takes as parameter the draw class you want.
It contains a lot of attributes for the geometrical informations like the start time for drawing, the size of a container...

It is designed in order to be inherited by classes which will print the stats wanted. For example, the DrawHDiagram (H for horizontal) or the DrawCounter inherit from it.


