--- a/nautilus-python.xml Sun Nov 12 17:23:26 2006 -0300
+++ b/nautilus-python.xml Wed Nov 15 21:41:06 2006 -0300
@@ -1,4 +1,4 @@
-<?xml version="1.0" encoding="ISO-8859-1"?>
+<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
"/usr/share/sgml/docbook/dtd/xml/4.1.2/docbookx.dtd" [
<!ENTITY Nautilus "<application>Nautilus</application>">
@@ -12,8 +12,8 @@
<authorgroup>
<author>
- <firstname>Germán</firstname>
- <surname>Poó-Caamaño</surname>
+ <firstname>Germán</firstname>
+ <surname>Poó-Caamaño</surname>
<affiliation>
<address>
<email>gpoo@gnome.org</email>
@@ -38,36 +38,208 @@
<sect1 id="introduction">
<title>Introduction</title>
- <para>
-
- </para>
- <sect1 id="hints">
- <title>Hints for develop</title>
<para>
- To try any of the examples, copy them over to
- <filename>~/.nautilus/python-extensions/</filename>.
- Then restart nautilus.
</para>
- <para>
- If you're testing an extension that you're developing, it may
- be useful to start a 'private' instance of nautilus, like this:
-<programlisting>
+ <sect2 id="providers-and-interfaces">
+ <para>
+ There are two kind of objects: Providers and the interfaces
+ for providers.
+ </para>
+ <para>
+ There are 4 providers:
+ <itemizedlist>
+ <listitem>
+ <para>NautilusInfoProvider. To add file information and
+ emblems.
+ </para></listitem>
+ <listitem>
+ <para>NautilusColumnProvider. To add columns to the list
+ and icon views.
+ </para></listitem>
+ <listitem>
+ <para>NautilusMenuProvider. To add context menus
+ for files, active folder an toolbar.
+ </para></listitem>
+ <listitem>
+ <para>NautilusPagePropertyProvider. To add pages to file
+ property dialog.
+ </para></listitem>
+ </itemizedlist>
+ </para>
+ </sect2>
+ <sect2 id="hints">
+ <title>Hints for develop</title>
+ <para>
+ To try any of the examples, copy them over to
+ <filename>~/.nautilus/python-extensions/</filename>.
+ Then restart nautilus.
+ </para>
+ <para>
+ If you're testing an extension that you're developing, it may
+ be useful to start a 'private' instance of nautilus, like this:
+ <programlisting>
$ mkdir /tmp/testing
$ export TMPDIR=/tmp/testing
- $ nautilus --no-desktop
-</programlisting>
- </para>
+ $ nautilus --no-desktop</programlisting>
+ </para>
+ </sect2>
</sect1>
-
- </sect1>
<sect1 id="column-provider">
<title>ColumnProvider</title>
<para></para>
</sect1>
<sect1 id="menu-provider">
<title>MenuProvider</title>
- <para></para>
+ <para>
+ In order to add a menu item to &Nautilus; is needed the interface
+ <function>MenuProvider</function>. There are three different places
+ where a menu can be shown:
+ <itemizedlist>
+ <listitem>
+ <para>As a context menu over a file (also Edit menu)
+ </para></listitem>
+ <listitem><para>As a menu in the background of the current window
+ (also File menu), which is a valid action for the folder currently
+ shown)</para></listitem>
+ <listitem><para>Add an action into the toolbar</para></listitem>
+ </itemizedlist>
+ </para>
+ <para>
+ Whichever will be the type of menu you like to add, it is requested
+ to create a class which parent must be MenuProvider and then
+ override the method(s) according you want your extension do.
+ </para>
+ <sect2 id="per-file">
+ <title>Add menu for a file o group of files</title>
+ <para>
+ <programlisting>
+import nautilus
+from gtk import MessageDialog, BUTTONS_CLOSE
+
+class MyExtension(nautilus.MenuProvider):
+ def __init__(self):
+ # The constructor must be exists, even if there is nothing
+ # to initialize
+ pass
+
+ def show_files(self, menu, files):
+ # This is the method invoked when our extension is activated
+ # Do whatever you want to do with the files selected.
+ if len(files) == 1:
+ primary_text = '<b>The file selected is:</b>'
+ else:
+ primary_text = '<b>The files selected are:</b>'
+
+ names = [file.get_name() for file in files]
+
+ dialog = MessageDialog(buttons=BUTTONS_CLOSE)
+ dialog.set_markup(primary_text)
+ dialog.format_secondary_text(', '.join(names))
+ dialog.run()
+ dialog.destroy()
+
+ def get_file_items(self, window, files):
+ # If we have files selected, we will add a menu entry
+ if len(files) == 0:
+ return
+
+ item = nautilus.MenuItem('MyFileExtension::show_files',
+ 'Show selected files',
+ 'Show the selected files in a message dialog')
+ item.connect('activate', self.show_files, files)
+
+ return item,</programlisting>
+ </para>
+ <para>
+ It must be noted that <function>get_file_items</function> is
+ invoked any time that Nautilus must to show the Edit menu or
+ the contextual menu (right click over file(s) selected).
+ </para>
+ <para>
+ <function>get_file_items</function> receive two parametes:
+ <parameter>window</parameter> and <parameter>files</parameter>.
+ <parameter>window</parameter> is a reference of the current
+ window (gtk.Window) where the action was done and
+ <parameter>files</parameter> represents a set of selected files
+ (a sequence of nautilus.MenuItems).
+ </para>
+ <para>
+ In this case, <constant>None</constant> is returned if there
+ is no file selected. It avoid to fill the menu with useless
+ actions. A menu entry is added creating an instance of
+ a nautilus.MenuItem, and it is possible to create an arbitrary
+ number of entries, which are returned as a sequence of
+ nautilus.MenuItem.
+ </para>
+ </sect2>
+ <sect2 id="per-folder">
+ <title>Add menu for the current folder</title>
+ <para>
+ <programlisting>
+import nautilus
+from gtk import MessageDialog, BUTTONS_CLOSE
+from urllib import unquote
+
+class MyExtension(nautilus.MenuProvider):
+ def __init__(self):
+ # The constructor must be exists, even if there is nothing
+ # to initialize
+ pass
+
+ def showme(self, menu, file):
+ # This is the method invoked when our extension is activated
+ filename = unquote(file.get_uri()[7:])
+
+ dialog = MessageDialog(buttons=BUTTONS_CLOSE)
+ dialog.set_markup('<b>I am browsing:</b>')
+ dialog.format_secondary_text(filename)
+ dialog.run()
+ dialog.destroy()
+
+ def get_background_items(self, window, file):
+ item = nautilus.MenuItem('MyExtension::showme',
+ 'Where am I?' ,
+ 'Show where I am located in my computer')
+ item.connect('activate', self.showme, file)
+
+ return item,</programlisting>
+ </para>
+ </sect2>
+ <sect2 id="toolbar">
+ <title>Add an action into the toolbar</title>
+ <para>
+ <programlisting>
+import nautilus
+import gtk
+from urllib import unquote
+
+class MyToolbarExtension(nautilus.MenuProvider):
+ def __init__(self):
+ # The constructor must be exists, even if there is nothing
+ # to initialize
+ pass
+
+ def showme(self, menu, file):
+ # This is the method invoked when our extension is activated
+ filename = unquote(file.get_uri()[7:])
+
+ dialog = gtk.MessageDialog(buttons=gtk.BUTTONS_CLOSE)
+ dialog.set_markup('<b>I am browsing:</b>')
+ dialog.format_secondary_text(filename)
+ dialog.run()
+ dialog.destroy()
+
+ def get_toolbar_items(self, window, file):
+ item = nautilus.MenuItem('MyToolbarExtension::showme',
+ 'Where am I?' ,
+ 'Show where I am located in my computer',
+ gtk.STOCK_CLOSE)
+ item.connect('activate', self.showme, file)
+
+ return item,</programlisting>
+ </para>
+ </sect2>
</sect1>
<sect1 id="property-page-provider">
<title>PropertyPageProvider</title>