1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
|
<?xml version="1.0" standalone="no"?>
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
"http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">
<chapter id="nautilus-python-migrating-to-4">
<title>Migrating to Nautilus API 4.0</title>
<para>Nautilus 43 no longer allows extensions to directly manipulate GTK widgets – all UI changes now need to happen through model objects. If your script implements any of the following provider interfaces, you will need to update it:</para>
<simplesect id="nautilus-python-migrating-to-4-location-widget-provider">
<title>LocationWidgetProvider</title>
<para> The <classname>Nautilus.LocationWidgetProvider</classname> was removed without replacement. If your script requires it, you can request a new model-based API for your specific use case on the <ulink url="https://gitlab.gnome.org/GNOME/nautilus">Nautilus issue tracker</ulink>.</para>
</simplesect>
<simplesect id="nautilus-python-migrating-to-4-menu-provider">
<title>MenuProvider</title>
<para> The<link linkend="method-nautilus-python-menu-provider--get-file-items"> <methodname>get_file_items</methodname></link>, <link linkend="method-nautilus-python-menu-provider--get-file-items-full"><methodname>get_file_items_full</methodname></link>, <link linkend="method-nautilus-python-menu-provider--get-background-items"><methodname>get_background_items</methodname></link> a <link linkend="method-nautilus-python-menu-provider--get-background-items-full"><methodname>get_background_items_full</methodname></link> methods of <link linkend="class-nautilus-python-menu-provider"><classname>Nautilus.MenuProvider</classname></link> no longer take the <parameter role="keyword">window</parameter> argument. Remove it from your implementations.</para>
<para>If you need to keep supporting older versions of Nautilus, you can use <ulink url="https://docs.python.org/3/reference/compound_stmts.html#grammar-token-python-grammar-parameter_list_starargs">variadic arguments</ulink>:</para>
<informalexample>
<programlisting>def get_file_items(self, *args):
# `args` will be `[files: List[Nautilus.FileInfo]]` in Nautilus 4.0 API,
# and `[window: Gtk.Widget, files: List[Nautilus.FileInfo]]` in Nautilus 3.0 API.
files = args[-1]</programlisting>
</informalexample>
</simplesect>
<simplesect id="nautilus-python-migrating-to-4-property-page-provider">
<title>PropertyPageProvider</title>
<para> The <classname>Nautilus.PropertyPageProvider</classname> was replaced by <link linkend="class-nautilus-python-properties-model-provider"><classname>Nautilus.PropertiesModelProvider</classname></link> class. Unlike the previous unrestricted property pages that could contain any GTK widget, the new model-based interface currently only supports a pre-defined layout. Scripts can add <link linkend="class-nautilus-python-properties-model">pages</link>, each of which can display a list of <link linkend="class-nautilus-python-properties-item">text properties</link>.</para>
<para>Subclass the <link linkend="class-nautilus-python-properties-model-provider"><classname>Nautilus.PropertiesModelProvider</classname></link> abstract class and have the <link linkend="method-nautilus-python-properties-model-provider--get_models"><methodname>get_models</methodname></link> method return the list of <link linkend="class-nautilus-python-properties-model"><classname>Nautilus.PropertiesModel</classname></link>, one for each properties page.</para>
<para>If you need to keep supporting older versions of Nautilus, you can keep the old definition conditionally:</para>
<informalexample>
<programlisting language="Python">if hasattr(Nautilus, "PropertiesModelProvider"):
# For Nautilus 4.0 API
class MD5SumPropertiesModel(GObject.GObject, Nautilus.PropertiesModelProvider):
...
else:
class MD5SumPropertyPage(GObject.GObject, Nautilus.PropertyPageProvider):
...</programlisting>
</informalexample>
</simplesect>
<simplesect id="nautilus-python-migrating-to-4-other-libraries">
<title>Direct use of GTK and other libraries</title>
<para>If you use GTK directly, e.g. to create dialogue windows, you will need to <ulink url="https://docs.gtk.org/gtk4/migrating-3to4.html">upgrade the code to GTK 4</ulink> as well, since Nautilus switched to GTK 4 and it is not possible to use multiple versions of GTK in the same process. Do not forget to replace <code>gi.require_version("Gtk", "3.0")</code> with <code>gi.require_version("Gtk", "4.0")</code>, then.</para>
<para>The other option is moving the window and dialogues into a separate program and having the extension just launch it. But unless the code base is very large, migrating to GTK 4 will probably be easier.</para>
</simplesect>
<simplesect id="nautilus-python-migrating-to-4-more">
<title>More information</title>
<para>See the <ulink url="https://gitlab.gnome.org/GNOME/nautilus/-/merge_requests/927">relevant Nautilus change</ulink> for more context and the <ulink url="https://gitlab.gnome.org/GNOME/nautilus-python/-/merge_requests/11">corresponding nautilus-python update</ulink> for more migration examples.</para>
</simplesect>
</chapter>
|
