summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorCalum Lind <calumlind+deluge@gmail.com>2019-06-15 11:49:07 +0100
committerCalum Lind <calumlind+deluge@gmail.com>2019-06-15 21:01:04 +0100
commit5b315e90c508c7fb1123d137c82a3c378e4fb69c (patch)
tree1c6e7a51ef27569d4c79b546d9463675b3857039
parentb711cd258ae3001d5f1aa69617c22a2d258b1c06 (diff)
downloaddeluge-5b315e90c508c7fb1123d137c82a3c378e4fb69c.tar.gz
deluge-5b315e90c508c7fb1123d137c82a3c378e4fb69c.tar.bz2
deluge-5b315e90c508c7fb1123d137c82a3c378e4fb69c.zip
[Docs] Cleanup updating plugin page
-rw-r--r--docs/source/devguide/how-to/update-1.3-plugin.md83
1 files changed, 62 insertions, 21 deletions
diff --git a/docs/source/devguide/how-to/update-1.3-plugin.md b/docs/source/devguide/how-to/update-1.3-plugin.md
index 837739294..99cc9fc32 100644
--- a/docs/source/devguide/how-to/update-1.3-plugin.md
+++ b/docs/source/devguide/how-to/update-1.3-plugin.md
@@ -7,17 +7,14 @@ The main changes are with Python 3 support and the new GTK3 user interface with
the dropping of GTK2. However it is still possible for a 1.3 plugin to be made
compatible with 2.0 and this guide aims to helps with that process.
-Note that the Deluge 2.0 plugins now use namespace packaging which is not
-compatible with Deluge 1.3.
-
## Python
### Python version matching
Ensure your code is both Python 2.7 and Python >=3.5 compatible.
-In `1.3-stable` the plugins that were built with a specfific version of Python
-could on be loaded if the system Python also matched.
+In `1.3-stable` the plugins that were built with a specific version of Python
+would only be loaded if the system Python also matched.
This has change in Deluge 2.0 and it will load any Python version of plugin
eggs so compatibility is essential for end-users not to encounter issues.
@@ -30,8 +27,10 @@ Use [six] to assist with compatibility.
### Unicode literals
-Add this to files to ensure strings and bytes separatation so there are no
-surprises when running on Python 3.
+Add the following to files to ensure strings and bytes separatation so there
+are no surprises when running on Python 3.
+
+ from __future__ import unicode_literals
## GTK 3 addition
@@ -48,7 +47,7 @@ XML files by default Deluge plugins used libglade but that has been deprecated
and removed in GTK3. So the libglade `.glade` files will need converted to
GtkBuilder `.ui` files and the Python code updated.
-https://developer.gnome.org/gtk2/stable/gtk-migrating-GtkBuilder.html
+See the official [Migrating to GtkBuilder][migrate-gtkbuilder] document for more details.
#### gtk-builder-convert
@@ -62,9 +61,12 @@ To convert your GTK run it like so:
#### Glade UI designer for GTK2
-The above conversion can be done in Glade UI designer (version <=3.8), ensuring
-that the minimum Gtk version is set to 2.24 and any deprecated widgets are
-fixed. The updated file should be saved with file extension `.ui`.
+The above conversion can also be done in Glade UI designer (version <=3.8).
+
+In the preferences select `GtkBuilder` as the project file format. Ensure
+that the minimum Gtk version is set to 2.24 and fix any deprecated widgets.
+
+The updated file should be saved with file extension `.ui`.
#### Python code changes
@@ -72,16 +74,25 @@ The code needs to replace `gtk.glade` references with `gtk.Builder` and the
first step is updating how the files are loaded:
```diff
-- self.glade = gtk.glade.XML(get_resource("config.glade"))
-+ self.builder = gtk.Builder()
-+ self.builder.add_from_file(get_resource("config.ui"))
+- glade = gtk.glade.XML(get_resource("config.glade"))
++ builder = Gtk.Builder.new_from_file(get_resource("config.ui"))
```
-The next stage is to replace every occurange of these `glade` methods with
-the `builder` equivalents:
+Replace signals method:
+
+```diff
+- glade.signal_autoconnect(self)
++ builder.connect_signals(self)
+```
+
+Replace `get_widget` with `get_object`:
+
+```diff
+- glade.get_widget
++ builder.get_object
+```
- glade.signal_autoconnect -> builder.connect_signals
- glade.get_widget -> builder.get_object
+Check for any remaining `glade` methods and replace with the `builder` equivalents.
### Migrate XML files to GTK3
@@ -89,7 +100,7 @@ If you open and save the file it will update with the new requirement header:
<!-- Generated with glade 3.18.3 -->
<interface>
- <requires lib="gtk+" version="3.0"/>
+ <requires lib="gtk+" version="3.10"/>
You can fix deprecated widgets but keep the minimum GTK version to <= 3.10 for
desktop compatiblity.
@@ -118,9 +129,11 @@ https://pygobject.readthedocs.io/en/latest/guide/porting.html
### Deluge GTK3
-Imports will need updated from `deluge.ui.gtkui` to `deluge.ui.gtk3`.
+#### Imports
-### PluginBase
+Imports will need renamed from `deluge.ui.gtkui` to `deluge.ui.gtk3`.
+
+There is also a new PluginBase for Gtk3 UI:
```diff
-from deluge.plugins.pluginbase import GtkPluginBase
@@ -129,4 +142,32 @@ Imports will need updated from `deluge.ui.gtkui` to `deluge.ui.gtk3`.
+class Gtk3UI(Gtk3PluginBase):
```
+#### Entry points
+
+To enable the GTK3 UI to find the plugin the entry points requires updating too.
+
+In the plugin `__init__.py` file add a new `Gtk3UIPlugin` class:
+
+```
+class Gtk3UIPlugin(PluginInitBase):
+ def __init__(self, plugin_name):
+ from .gtk3ui import Gtk3UI as _plugin_cls
+ self._plugin_cls = _plugin_cls
+ super(Gtk3UIPlugin, self).__init__(plugin_name)
+```
+
+A new entry for GTK3 UI can then be added to `setup.py`:
+
+```diff
+ [deluge.plugin.gtkui]
+ %s = %s:GtkUIPlugin
++ [deluge.plugin.gtk3ui]
++ %s = deluge_%s:Gtk3UIPlugin
+ [deluge.plugin.webui]
+ %s = %s:WebUIPlugin
+- """ % ((__plugin_name__, __plugin_name__.lower())*3)
++ """ % ((__plugin_name__, __plugin_name__.lower())*4)
+```
+
+[migrate-gtkbuilder]: https://developer.gnome.org/gtk2/stable/gtk-migrating-GtkBuilder.html
[autoadd gtkbuilder]: https://git.deluge-torrent.org/deluge/commit/?h=develop&id=510a8b50b213cab804d693a5f122f9c0d9dd1fb3