commit f10a3d04859a1aed9d6b5e1c7bbad7b2fc29adf5
Author: Tomás Touceda <chiiph(a)torproject.org>
Date: Sat Apr 14 14:39:15 2012 -0300
Write plugin tutorial
---
changes/pluginTutorial | 2 +
doc/plugin-tutorial.txt | 544 +++++++++++++++++++++++++++++++++++++++++++++++
2 files changed, 546 insertions(+), 0 deletions(-)
diff --git a/changes/pluginTutorial b/changes/pluginTutorial
new file mode 100644
index 0000000..5babab3
--- /dev/null
+++ b/changes/pluginTutorial
@@ -0,0 +1,2 @@
+ Internal cleanups and improvements:
+ o Document how to write plugins in a tutorial fashion.
\ No newline at end of file
diff --git a/doc/plugin-tutorial.txt b/doc/plugin-tutorial.txt
new file mode 100644
index 0000000..4d4fb11
--- /dev/null
+++ b/doc/plugin-tutorial.txt
@@ -0,0 +1,544 @@
+== How to write Vidalia Plugins ===
+
+=== Sections ==
+
+ * Foreword
+ * Directory structure for plugins
+ * How Vidalia executes the plugin
+ * GUI handling
+ * Settings handling
+ * Simple example
+ * I know Qt, how do I use signals and slots?
+ * I made a plugin, what now?
+
+=== Foreword ===
+
+This document intends to be a simple tutorial that will help you write
+Vidalia plugins. It is not intended to be an exhaustive plugin API
+reference, there will be another document for that. This is also not a
+Javascript reference nor a Qt one, although you will need knowledge of
+both in order to write a plugin.
+
+This is not also a complete plugin engine specification, for that
+there is already a doc named plugin-framework.txt inside Vidalia's doc
+directory.
+
+We assume in this document that you have basic Qt and Javascript
+knowledge, and that you have Vidalia with the qtscriptgenerator libs
+available.
+
+To check this last point, you can open Vidalia, go to Plugins->Debug
+output and you should be able to see the following:
+
+{{{
+
+Available extensions:
+ qt
+ qt.core
+ qt.dbus
+ qt.gui
+ qt.network
+ qt.uitools
+ qt.xml
+
+}}}
+
+The actual important extensions are: qt, qt.core, qt.gui and qt.uitool
+(only if it's a GUI plugin). Depending on the functionality you intend
+your plugin to have, you can ignore the rest.
+
+=== Directory structure for plugins ===
+
+If you open vidalia.conf for Vidalia >= 0.3.1, you will notice a
+variable named "PluginPath" in the [General] section. This variable
+points to the root of where all the plugins are placed. So, the plugin
+root will look something like this:
+
+{{{
+
+pluginRoot/
+ \_ plugin1/
+ |_ plugin2/
+ |_ plugin3/
+
+}}}
+
+Vidalia expects every installed plugin to be a directory inside the
+plugins root.
+
+For every plugin, the directory structure should have at least the
+following files:
+
+{{{
+
+plugin1/
+ \_ info.xml
+ |_ plugin1.js
+
+}}}
+
+You can distribute any files other than these, may be as a dependency
+for your plugin (icons, another complete application that is executed
+by your plugin, .ui files, etc).
+
+==== The info.xml file ====
+
+The most important file (besides the actual plugin code) is the
+info.xml one. This contains the basic information that Vidalia needs
+to understand what to do with this plugin, how to execute it, how to
+and if it should display it in the Plugins menu, and what files to
+load.
+
+Lets take a look at the info.xml file from the Tor Browser Bundle
+plugin:
+
+{{{
+
+<VidaliaPlugin>
+ <name>Browser Bundle Configuration</name>
+ <date>15/06/2011</date>
+ <author>chiiph</author>
+ <type persistent="true" gui="true" />
+ <files>
+ <file>tbb.js</file>
+ </files>
+ <namespace>tbb</namespace>
+</VidaliaPlugin>
+
+}}}
+
+For a complete description of each tag, please read secrion 2 of the
+plugin-framework.txt doc.
+
+In practise, the name tag will be used as the menu entry for this
+plugin if it is of type gui="true". Vidalia will load every file
+descripted in the files tag, so they should all be valid Javascript
+files. And the namespace should be unique (i.e. do not create a plugin
+with tbb as its namespace, unless you want to have one of the two
+overriden by the other). This namespace should be the same as the name
+of the main variable you will use inside the javascript files, as we
+will see later on.
+
+=== How Vidalia executes the plugin ===
+
+As a quick reference for how plugins are executed, there are three
+main functions: start(), stop(), and buildGUI(). The functions that
+must be implemented are start and stop, since they will always be
+executed one way or the other. buildGUI depends on whether your plugin
+is of type gui="true" or not.
+
+Here's a basic skeleton for a plugin's main Javascript file:
+
+{{{
+
+importExtension("qt");
+importExtension("qt.core");
+importExtension("qt.gui"); // optional
+importExtension("qt.uitools"); // optional
+
+var tbb = {
+ someStaticVariable: 1,
+ someOtherStaticVar: "Some string",
+
+ start: function() {
+ // Start code here...
+ },
+
+ buildGUI: function() {
+ // GUI creation here...
+ },
+
+ stop: function() {
+ // Stop function in here...
+ },
+};
+
+}}}
+
+The start function is executed when Vidalia starts if type
+persistent="true", or before the GUI is created when type gui="true".
+
+If a plugin is not of type persistent or gui, it will never be started
+in any way.
+
+The idea behind persistent is that you can run things in background,
+like a UNIX daemon (sort of). As an example, you could start a QTimer
+in your start() function and check something periodically. We use this
+in the Thandy plugin, if you want to read a "real world" example.
+
+=== GUI handling ===
+
+If you want your plugin to have a GUI, we have made kind of a template
+that you can follow:
+
+(This is a part of the Tor Browser Bundles complete buildGUI
+implementation, you can see it in tbb.js in the plugins official
+repository.)
+
+{{{
+ buildGUI: function() {
+ this.tab = new VidaliaTab("Browser Bundle Settings", "TBB");
+
+ var file = new QFile(pluginPath+"/tbb/tbb.ui");
+ var loader = new QUiLoader(this.tab);
+ file.open(QIODevice.ReadOnly);
+ this.widget = loader.load(file);
+ var layout = new QVBoxLayout();
+ layout.addWidget(this.widget, 0, Qt.AlignCenter);
+ this.tab.setLayout(layout);
+ file.close();
+
+ var portInfo = this.widget.children()[findWidget(this.widget, "portInfo")];
+ if(portInfo == null) {
+ return this.tab;
+ }
+
+ var groupBox = this.widget.children()[findWidget(this.widget, "browserBox")];
+ if(groupBox == null) {
+ return this.tab;
+ }
+
+ this.btnLaunch = groupBox.children()[findWidget(groupBox, "btnLaunch")];
+ if(this.btnLaunch != null) {
+ this.btnLaunch["clicked()"].connect(this, this.startSubProcess);
+ }
+
+ return this.tab;
+ },
+}}}
+
+If you read Qt's documentation, what this function does is quite
+straight forward, but I will give you a quick summarization:
+
+{{{
+ buildGUI: function() {
+ this.tab = new VidaliaTab("Browser Bundle Settings", "TBB");
+}}}
+
+First, we need to create a new VidaliaTab. The first parameter is its
+name, which can be an arbitrary string. The second one is important,
+because Vidalia will use it as its section inside the vidalia.conf
+file, if you want to store some kind of settings (we will get to this
+in the next section).
+
+{{{
+ var file = new QFile(pluginPath+"/tbb/tbb.ui");
+ var loader = new QUiLoader(this.tab);
+ file.open(QIODevice.ReadOnly);
+ this.widget = loader.load(file);
+}}}
+
+We encourage you to build your GUIs with Qt Designer, but you are free
+to craft them in the code. In this example we use a .ui Designer file.
+
+So we first load the file as a regular one. The pluginPath variable is
+a variable provided by Vidalia for you to know the location of the
+plugin's root directory. From that point, you should know where your
+files are supposed to be located, in this case it is
+pluginsPath+"/tbb/tbb.ui".
+
+We then create the QUiLoader object, open the file and ask the loader
+to do its magic.
+
+{{{
+ var layout = new QVBoxLayout();
+ layout.addWidget(this.widget, 0, Qt.AlignCenter);
+ this.tab.setLayout(layout);
+ file.close();
+}}}
+
+The QUiLoader creates a QWidget derived object in this.widget and now
+we need to put it somewhere the user can see. We could just display
+the widget, but we encourage you to try to integrate your plugin to
+Vidalia as much as possible, so we will add it to a vertical layout,
+and set it as the tab's main layout.
+
+{{{
+ var portInfo = this.widget.children()[findWidget(this.widget, "portInfo")];
+ if(portInfo == null) {
+ return this.tab;
+ }
+
+ var groupBox = this.widget.children()[findWidget(this.widget, "browserBox")];
+ if(groupBox == null) {
+ return this.tab;
+ }
+
+ this.btnLaunch = groupBox.children()[findWidget(groupBox, "btnLaunch")];
+ if(this.btnLaunch != null) {
+ this.btnLaunch["clicked()"].connect(this, this.startSubProcess);
+ }
+}}}
+
+We can access each widget from this.widget, but it is recommended to
+create variables for each component that you'd like to access.
+
+To make that job easier, Vidalia provides a findWidget function that
+takes a widget and finds the one with the provided name inside the
+first one's children.
+
+For example, in this.btnLaunch, we want to find the widget called
+btnLaunch inside the groupBox widget.
+
+{{{
+ return this.tab;
+ },
+}}}
+
+As the last step, we return the tab for Vidalia to display. Depending
+on how you code your buildGUI function, you may want to check if
+this.tab is already created and return it instead of executing the
+whole function every time Vidalia wants to display the plugins GUI.
+
+Keep in mind that Vidalia deletes the returned tab when the user
+closes it, that's why we create the tab every time buildGUI is
+executed..
+
+=== Settings handling ===
+
+For settings handling, Vidalia provides two methods that belong to the
+VidaliaTab class: saveSetting and getSetting. These methods will get
+and set values inside the plugin's section, in the case of the Tor
+Browser Bundle plugin, it will be the TBB section, as we described
+before.
+
+As an example, we will look at an extract of the saveSettings function
+from tbb.js:
+
+{{{
+this.tab.saveSetting(this.BrowserExecutable, this.lineExecutable.text);
+this.tab.saveSetting(this.BrowserDirectory, this.lineDirectory.text);
+}}}
+
+this.BrowserExecutable is a variable defined before, which is
+"BrowserExecutable". this.lineExecutable is a QLineEdit from the GUI.
+
+This first call, assuming the content of this.lineExecutable is
+"/some/path", will lead to the following text in vidalia.conf:
+
+{{{
+
+[TBB]
+BrowserExecutable=/some/path
+
+}}}
+
+Note that there might be other values before and after
+"BrowserExecutable".
+
+For retrieving settings from the plugins own section you can use the
+method getSetting, which receives the name of the setting and the
+default value as parameters.
+
+Here's an example from the buildGUI() method in tbb.js:
+
+{{{
+if(this.lineExecutable != null) {
+ this.lineExecutable.text = this.tab.getSetting(this.BrowserExecutable, "");
+}
+}}}
+
+=== I know Qt, how do I use signals and slots? ===
+
+Signals and slots are available inside the plugins environment. the
+only restriction is that you can't emit signals properly (there are
+some hacks to get around this though).
+
+As an example, lets look at a part of the start() function of tbb.js:
+
+{{{
+torControl["authenticated()"].connect(this, this.showWaitDialog);
+}}}
+
+The torControl variable is one that Vidalia provides to interact with
+the code that is able to talk to Tor inside Vidalia. This object emits
+a signal called "authenticated()" at some point.
+
+So the syntax to use for connecting a certain signal to a certain slot
+is the following:
+
+{{{
+<object that emits the signal>["<signal name>"].connect(<receiver>, <slot>);
+}}}
+
+It is not a complicated issue, but it may not be intuitive at first if
+you are familliar with Qt's way of doing this in C++.
+
+=== Simple example ===
+
+We have been through the most important parts of a plugin, you can
+always look at how the Tor Browser Bundle plugin works and learn from
+it, but if you are going to start a plugin from scratch, it may not be
+the best option since it a bit big. So in this section I will give you
+a really simple plugin that uses everything we've been talking about
+and it is still clear enough for you to have it as a quick reference
+for your own plugin.
+
+The plugin we are going to be implementing for this section is a
+simple bandwidth history recorder. This means that every certain
+amount of bytes tor sends or receives, it notifies the controllers
+through an event how many have been sent or received since the last
+time it notified.
+
+Looking at how Vidalia TorControl class works, we notice a signal
+called:
+
+{{{
+ /** Emitted when Tor sends a bandwidth usage update (roughly once every
+ * second). <b>bytesReceived</b> is the number of bytes read by Tor over
+ * the previous second and <b>bytesWritten</b> is the number of bytes
+ * sent over the same interval.
+ */
+ void bandwidthUpdate(quint64 bytesReceived, quint64 bytesSent);
+}}}
+
+(This is from src/vidalia/plugin/prototypes/TorControlPrototype.h)
+
+What we need to do is connect this signal with a slot that records
+these bytes, and we have half of our work done.
+
+Once we have that, we can create a simple GUI to display this as a tab
+inside Vidalia. For added fun, we added a button to reset the counter
+and the start date.
+
+Here's the complete Javascript source code for this:
+
+{{{
+importExtension("qt");
+importExtension("qt.core");
+importExtension("qt.gui");
+importExtension("qt.uitools");
+
+var tutorial = {
+ From: "From",
+ Sent: "Sent",
+ Recv: "Recv",
+
+ start: function() {
+ vdebug("Tutorial@start");
+ torControl["bandwidthUpdate(quint64, quint64)"].connect(this, this.saveBandwidth);
+ this.tab = new VidaliaTab("Display bandwidth history", "BandwidthHistory");
+
+ this.recv = parseInt(this.tab.getSetting(this.Sent, 0));
+ this.sent = parseInt(this.tab.getSetting(this.Recv, 0));
+ this.from = this.tab.getSetting(this.From, "");
+
+ if(this.from.length == 0)
+ this.from = QDateTime.currentDateTime().toString();
+
+ // null labels so that we don't update them until the GUI is created
+ this.lblFrom = null;
+ this.lblSent = null;
+ this.lblRecv = null;
+ },
+
+ saveBandwidth: function(recv, sent) {
+ vdebug("Tutorial::Recv", recv);
+ vdebug("Totorial::Sent", sent);
+
+ this.recv += recv;
+ this.sent += sent;
+ this.tab.saveSetting(this.Recv, this.recv);
+ this.tab.saveSetting(this.Sent, this.sent);
+ this.tab.saveSetting(this.From, this.from);
+
+ if(this.lblFrom)
+ this.lblFrom.text = this.from;
+ if(this.lblSent)
+ this.lblSent.text = this.sent.toString();
+ if(this.lblRecv)
+ this.lblRecv.text = this.recv.toString();
+ },
+
+ resetCounters: function() {
+ this.recv = 0;
+ this.sent = 0;
+ this.from = QDateTime.currentDateTime().toString();
+ this.saveBandwidth(0,0);
+ },
+
+ buildGUI: function() {
+ vdebug("Tutorial@buildGUI");
+ // Load the GUI file
+
+ if(this.tab)
+ delete this.tab;
+
+ this.tab = new VidaliaTab("Display bandwidth history", "BandwidthHistory");
+
+ var file = new QFile(pluginPath+"/tutorial/tutorial.ui");
+ var loader = new QUiLoader(this.tab);
+ file.open(QIODevice.ReadOnly);
+ this.widget = loader.load(file);
+ var layout = new QVBoxLayout();
+ layout.addWidget(this.widget, 0, Qt.AlignCenter);
+ this.tab.setLayout(layout);
+ file.close();
+
+ var grpBandwidth = this.widget.children()[findWidget(this.widget, "grpBandwidth")];
+ if(grpBandwidth == null)
+ return this.tab;
+
+ this.lblFrom = grpBandwidth.children()[findWidget(grpBandwidth, "lblFrom")];
+ if(this.lblFrom == null)
+ return this.tab;
+
+ this.lblSent = grpBandwidth.children()[findWidget(grpBandwidth, "lblSent")];
+ if(this.lblSent == null)
+ return this.tab;
+
+ this.lblRecv = grpBandwidth.children()[findWidget(grpBandwidth, "lblRecv")];
+ if(this.lblRecv == null)
+ return this.tab;
+
+ this.btnReset = grpBandwidth.children()[findWidget(grpBandwidth, "btnReset")];
+ if(this.btnReset == null)
+ return this.tab;
+
+ this.lblFrom.text = this.from;
+ this.lblSent.text = this.sent.toString();
+ this.lblRecv.text = this.recv.toString();
+
+ this.btnReset["clicked()"].connect(this, this.resetCounters);
+
+ return this.tab;
+ },
+
+ stop: function() {
+ vdebug("Tutorial@stop");
+ this.saveBandwidth(0,0);
+ },
+};
+}}}
+
+With just 105 lines we have a nice byte history recorder. You can find
+the tutorial.ui and info.xml files in our repository:
+
+https://gitweb.torproject.org/vidalia-plugins.git
+
+=== I made a plugin, what now? ===
+
+So you have your cool plugin with a crazy new idea and it works great,
+what is the next step? We have a repository for official plugins
+(official as in "some folk from Tor made it"), and you can give us
+your plugin to put it there and may be convince us why we should
+distribute your plugin along with the rest.
+
+The idea to have plugins though is to let people develop functionality
+in one of the main Tor controllers, and not depend on us to merge new
+stuff into the main line of distribution.
+
+In the (near) future, we will have a Vidalia Plugins web section where
+plugins that we think are good and won't compromise the users privacy
+will be listed.
+
+Right now the plugin distribution and installation is not something
+that any user might be able to do, so the other future plan is to
+create a distribution file format (probably just a zip file with
+certain internal structure) and a graphical way of installing plugins.
+
+If you are interested in helping with the infrastructure for plugins,
+please don't hesitate to join us on IRC at OFTC #vidalia.
+
+If you find any bugs, do not hesitate to report them in
+https://trac.torproject.org with Vidalia as the component.
