[gnome-panel/wip/segeiger/reference-documentation: 6/8] doc: Improve reference documentation



commit a5577daad62e8d961a99d7b76f32a70295a235de
Author: Sebastian Geiger <sbastig gmx net>
Date:   Sun Aug 23 17:30:00 2015 +0200

    doc: Improve reference documentation
    
    More changes
    
    Some more changes
    
    Doc: Improve the porting section
    
    Add the DBusAppletMigration guide
    
    Doc: Add DBusAppletsMigration guide
    
    Doc: Update Registration, Installation and Build System section

 doc/reference/panel-applet/Makefile.am            |    3 +-
 doc/reference/panel-applet/add_to_panel.png       |  Bin 0 -> 50415 bytes
 doc/reference/panel-applet/panel-applet-docs.sgml | 1010 +++++++++++++++++----
 3 files changed, 824 insertions(+), 189 deletions(-)
---
diff --git a/doc/reference/panel-applet/Makefile.am b/doc/reference/panel-applet/Makefile.am
index fd26b1c..b57a793 100644
--- a/doc/reference/panel-applet/Makefile.am
+++ b/doc/reference/panel-applet/Makefile.am
@@ -35,7 +35,8 @@ IGNORE_HFILES =                                       \
        panel-applet-marshal.h
 
 # Images to copy into HTML directory.
-HTML_IMAGES =
+HTML_IMAGES = \
+       add_to_panel.png
 
 # Extra SGML files that are included by $(DOC_MAIN_SGML_FILE).
 content_files = \
diff --git a/doc/reference/panel-applet/add_to_panel.png b/doc/reference/panel-applet/add_to_panel.png
new file mode 100644
index 0000000..0d6f05f
Binary files /dev/null and b/doc/reference/panel-applet/add_to_panel.png differ
diff --git a/doc/reference/panel-applet/panel-applet-docs.sgml 
b/doc/reference/panel-applet/panel-applet-docs.sgml
index 97adbe9..32430c2 100644
--- a/doc/reference/panel-applet/panel-applet-docs.sgml
+++ b/doc/reference/panel-applet/panel-applet-docs.sgml
@@ -16,19 +16,45 @@
   </bookinfo>
 
   <part id="overview">
-   <title>Panel Applet Library Overview</title>
+    <title>Panel Applet Library Overview</title>
+    <partintro>
+      <para>
+        The Panel Applet Library is used in the GNOME Flashback desktop to write applets that can be added 
to GNOME
+        Panel. GNOME Panel is the main user interface used in the GNOME Flashback desktop environment, 
through which
+        users interact with their computer and open applications.
+      </para>
 
-    <para>
-     Applets are small applications that are embedded in the GNOME panel. They can be used to give quick 
access to some features, or to display the state of something specific.
-    </para>
+      <para>
+        Applets are small applications that are embedded in the GNOME Panel. They can be used to give quick 
access
+        to some features, or to display the state of something specific. Most features in GNOME Panel such 
as the clock,
+        the application menu, the calendar and many others are written with this Panel Applet Library. 
Applets are added
+        through the "Add to Panel" dialog which can be opened from the "Add to Panel..." option on the 
context menu of
+        a GNOME Panel.
+      </para>
+
+      <mediaobject>
+        <imageobject>
+          <imagedata align="center" fileref="add_to_panel.png" format="PNG"/>
+        </imageobject>
+      </mediaobject>
 
-   <para>
-     The Panel Applet library is what should be used to write applets as it handles all the communication 
with the GNOME panel. It hides all of the embedding process of the applet behind a <link 
linkend="PanelApplet"><type>PanelApplet</type></link> widget. It also provides <link 
linkend="PanelApplet"><type>PanelApplet</type></link> API to properly integrate the applet in the panel.
-   </para>
+      <para>
+        The Panel Applet Library is what should be used to write applets as it handles all the communication 
with
+        the GNOME panel. It hides all of the embedding process of the applet behind a
+        <link linkend="PanelApplet"><type>PanelApplet</type></link> widget. It also provides
+        <link linkend="reference"><type>PanelApplet API</type></link> to properly integrate the applet in the
+        panel.
+      </para>
 
-   <note><simpara>
-    Keep in mind that starting with GNOME 3, the panel and applets are only available in the fallback mode. 
An applet will therefore not be usable in the default GNOME that users may use.
-   </simpara></note>
+      <note>
+        <simpara>
+          The Panel Applet Library was original part of the default GNOME desktop but was deprecated with 
GNOME 3,
+          when GNOME Shell was released. Nowadays development continues as part of the GNOME Flashback 
project. The
+          default desktop of GNOME now uses GNOME Shell, which uses a different system for extension, so an 
applet
+          written with the Panel Applet Library will not be usable in the default GNOME that users may use.
+        </simpara>
+      </note>
+    </partintro>
 
   </part>
 
@@ -39,56 +65,179 @@
     <title>Introduction</title>
 
     <para>
-     While applets are rather simple to write, they are not the most easy form of interaction to users for 
two reasons: it is not intuitive how to add or remove applets for many users, and the restriction in size of 
applets can limit their interface. Therefore, before writing an applet, think hard whether this is the form 
of interaction that is best for the feature you want to provide.
+     While applets are rather simple to write, they are not the most easy form of interaction to users for 
two reasons:
+     <itemizedlist>
+        <listitem>
+            It is not intuitive how to add or remove applets for many users, so users may not know about 
your applet,
+            or may not know how to add it to the GNOME Panel.
+        </listitem>
+         <listitem>
+            The restriction in size of applets can limit their interface, so you should only use applets for 
simple
+            tasks such as displaying information, or for controlling other applications and programs.
+         </listitem>
+     </itemizedlist>
+     Therefore, before writing an applet, think hard whether this is the form of interaction that
+     is best for the feature you want to provide.
     </para>
 
-    <note><simpara>
-     Keep in mind that starting with GNOME 3, the panel and applets are only available in the fallback mode. 
An applet will therefore not be usable in the default GNOME that users may use.
-    </simpara></note>
-
    </chapter>
 
    <chapter id="getting-started.concepts">
     <title>Concepts</title>
 
-    <sect2 id="getting-started.concepts.applet-types">
-     <title>Applet Types</title>
-
-     <para>
-      The applet type is the identifier representing a type of applets to the panel. It is a simple string, 
like <constant>HelloWorldApplet</constant> and is unique per <link 
linkend="getting-started.concepts.applet-factory">applet factory</link>.
-     </para>
-
-    </sect2>
-
-    <sect2 id="getting-started.concepts.applet-factory">
-     <title>Applet Factory</title>
-
-     <para>
-      The applet factory is an implementation detail that is mostly hidden by the Panel Applet library, but 
it still appears in a few places (<link 
linkend="PANEL-APPLET-OUT-PROCESS-FACTORY:CAPS"><function>PANEL_APPLET_OUT_PROCESS_FACTORY()</function></link>,
 <link 
linkend="PANEL-APPLET-IN-PROCESS-FACTORY:CAPS"><function>PANEL_APPLET_IN_PROCESS_FACTORY()</function></link> 
and <link linkend="getting-started.install.panel-applet"><filename>.panel-applet</filename> files</link>) so 
it is important to understand what is an applet factory.
-     </para>
-
-     <para>
-      The applet factory is the object that will create a new applet instance when the panel requests a new 
applet to be created. It is identified with a simple string id, for example 
<constant>HelloWorldFactory</constant>.
-     </para>
-
-     <para>
-      The requests the applet factory will receive from the panel specify which type of applet should be 
created. This is what makes it possible to have more than one applet types in one applet binary. In most 
cases, however, the applet factory will be specific to only one applet type. The map between applet types and 
the applet factory is recorded in <link 
linkend="getting-started.install.panel-applet"><filename>.panel-applet</filename> files</link>.
-     </para>
-
-     <para>
-      There is only one applet factory per applet binary, and it is always running before any applet 
instance is created by the applet binary. The applet factory is created via <link 
linkend="PANEL-APPLET-OUT-PROCESS-FACTORY:CAPS"><function>PANEL_APPLET_OUT_PROCESS_FACTORY()</function></link>
 or <link 
linkend="PANEL-APPLET-IN-PROCESS-FACTORY:CAPS"><function>PANEL_APPLET_IN_PROCESS_FACTORY()</function></link>.
-     </para>
-
-    </sect2>
-
-    <sect2 id="getting-started.concepts.applet-instances">
-     <title>Applet Instances</title>
-
-     <para>
-      There is no restriction as to how many instances of one applet type can be created. The user might 
choose to add more than one <constant>HelloWorldApplet</constant> applets to his panels. This can have some 
implications on the design used to write applets. The most important implication is that it is generally 
wrong to have global variables to keep a state specific to an applet instance.
-     </para>
+       <para>
+         In order to write an applet it is important to understand the relationships between GNOME Panel and 
your
+         applets. For example, how are applets registered to the GNOME Panel? How does the GNOME Panel 
instantiate an
+         applet?
+       </para>
+       <para>
+         On a typical desktop there can be multiple GNOME Panels and each GNOME Panel can have several 
instances of
+         your applet. These different instances are created by an <emphasis>applet factory</emphasis> which 
must be
+         registered to the GNOME Panel. Additionally, in order to identify your applet and instantiate the 
correct
+         applet, each applet is identified by an <emphasis>applet type</emphasis>.
+       </para>
 
-    </sect2>
+       <sect1>
+           <title>Applet Registration</title>
+
+           <para>
+             To make your applets and the applet factory known to GNOME Panel - so that it can show your
+             applet in the list of applets of the "Add to Panel" dialog - and to add applets to the panel, 
you
+             must create a Panel Applet File.
+             <link linkend="getting-started.install.panel-applet">Panel Applet files</link> are introduced 
in more
+             detail later in this document. However it is important for applet authors to understand the 
relationship
+             between <emphasis>the panel applet file</emphasis>, <emphasis>the applet factory</emphasis>, 
and the
+             <emphasis>applet type</emphasis>. Therefore this section contains a short example of a Panel 
Applet file.
+           </para>
+
+           <sect2>
+               <title>Panel Applet Files</title>
+               <para>
+                   <link linkend="getting-started.install.panel-applet">Panel Applet files</link> are
+                   <constant>ini</constant>-file formatted files that contain the necessary information 
about your
+                   factory and your applet types. The following example listing shows a simple Panel Applet 
file.
+               </para>
+               <informalexample>
+                   <programlisting>
+                       [Applet Factory]
+                       Id=HelloWorldFactory
+                       Name=Hello World Applet Factory
+                       Description=Factory for our example applets
+
+                       [HelloWorldApplet]
+                       Name=Hello World
+                       Description=The Hello World example applet
+                       Icon=hello-world-icon
+                   </programlisting>
+               </informalexample>
+           </sect2>
+
+           <sect2 id="getting-started.concepts.applet-types">
+               <title>Applet Types</title>
+
+               <para>
+                   The applet type is the identifier representing a type of applets to the panel. It is a 
simple string,
+                   like <constant>HelloWorldApplet</constant> and is unique per
+                   <link linkend="getting-started.concepts.applet-factory">applet factory</link>.
+               </para>
+
+               <note>
+                   <simpara>
+                       In the example listing above the applet type can be found in the second section title
+                       (e.g. <constant>[HelloWorldApplet]</constant>, but without the square brackets).
+                   </simpara>
+               </note>
+           </sect2>
+
+           <sect2 id="getting-started.concepts.applet-factory">
+               <title>Applet Factory</title>
+
+               <para>
+                 The applet factory is an implementation detail that is mostly hidden by the Panel Applet 
Library,
+                 but it still appears in a few places such as:
+                 <itemizedlist>
+                     <listitem>
+                       <para>
+                         The <link linkend="PANEL-APPLET-OUT-PROCESS-FACTORY:CAPS">
+                         <function>PANEL_APPLET_OUT_PROCESS_FACTORY()</function></link> macro, which is used 
to build
+                         out process applets. It gets the factory id passed as its first parameter.
+                       </para>
+                     </listitem>
+                     <listitem>
+                       <para>
+                         The <link linkend="PANEL-APPLET-IN-PROCESS-FACTORY:CAPS">
+                         <function>PANEL_APPLET_IN_PROCESS_FACTORY()</function></link> macro, which is used 
to build in
+                         process applets. It gets the factory id passed as its first parameter.
+                       </para>
+                     </listitem>
+                     <listitem>
+                       <para>
+                         A Panel Applet file, which is used to register applet types and the applet factory 
to the
+                         GNOME Panel. It must contain the same applet factory id as used in the above two 
macros.
+                       </para>
+                         <warning>
+                             <simpara>By default applets are out-process, if you have used the
+                                 <function>PANEL_APPLET_IN_PROCESS_FACTORY</function>, then you must add:
+                                 <constant>InProces=true</constant> to the <constant>[Applet 
Factory]</constant>
+                                 section.
+                             </simpara>
+                         </warning>
+                     </listitem>
+                 </itemizedlist>
+               </para>
+
+               <para>
+                   The applet factory is the object that will create a new applet instance when the panel 
requests a
+                   new applet to be created. It is identified with a simple string id, for example
+                   <constant>HelloWorldFactory</constant>.
+               </para>
+
+               <note>
+                   <simpara>
+                       In the example listing above the applet factory id can be found in the
+                       <constant>ID</constant>-field of the <constant>[Applet Factory]</constant> section.
+                   </simpara>
+               </note>
+
+               <para>
+                   The requests the applet factory will receive from the GNOME Panel specify which type of 
applet should be created.
+                   This is what makes it possible to have more than one applet type in one applet binary. In 
most cases, however, the
+                   applet factory will be specific to only one applet type.
+               </para>
+
+               <para>
+                   There is only one applet factory per applet binary, and it is always running before any 
applet instance is
+                   created by the applet binary. The applet factory is created via one of these two macros:
+                   <itemizedlist>
+                       <listitem>
+                           <para><link 
linkend="PANEL-APPLET-OUT-PROCESS-FACTORY:CAPS"><function>PANEL_APPLET_OUT_PROCESS_FACTORY()</function></link></para>
+                       </listitem>, or
+                       <listitem>
+                           <para><link 
linkend="PANEL-APPLET-IN-PROCESS-FACTORY:CAPS"><function>PANEL_APPLET_IN_PROCESS_FACTORY()</function></link></para>
+                       </listitem>.
+                   </itemizedlist>
+               </para>
+
+           </sect2>
+
+       </sect1>
+
+       <sect1 id="getting-started.concepts.applet-instances">
+           <title>Applet Instances</title>
+           <para>
+               There is no restriction as to how many instances of one applet type can be created. The user 
might
+               choose to add more than one <constant>HelloWorldApplet</constant> applets to his panels. This 
can
+               have some implications on the design used to write applets. The most important implication is 
that
+               it is generally wrong to have global variables to keep a state specific to an applet instance.
+
+               <warning>
+                   <simpara>
+                       Using global variables in an applet can cause problems when the applet is instantiated
+                       several times.
+                   </simpara>
+               </warning>
+           </para>
+       </sect1>
 
    </chapter>
 
@@ -96,7 +245,57 @@
     <title>Hello World Example</title>
 
     <para>
-     An example is worth a million words, so here is a simple one:
+      In this section we will write a simple example applet. This simple applet will have no functionality 
and
+      only displays a label with "Hello World" on the panel. For this simple applet only following three 
parts
+      are needed:
+    </para>
+
+    <itemizedlist>
+       <listitem>
+           <para>
+               <link linkend="PANEL-APPLET-OUT-PROCESS-FACTORY:CAPS">
+                   <function>PANEL_APPLET_OUT_PROCESS_FACTORY()</function>
+               </link>: this creates an <link linkend="getting-started.concepts.applet-factory">applet 
factory</link> named
+               <constant>HelloWorldFactory</constant>, and each time our applet is added to a GNOME Panel, 
this applet
+               factory will create an applet instance, and calls 
<function>hello_world_factory_callback()</function>
+               with a <link linkend="PanelApplet"><type>PanelApplet</type></link> object already created.
+           </para>
+       </listitem>
+       <listitem>
+           <para>
+               <function>hello_world_factory_callback()</function>: this checks if the request to create an 
applet
+               instance is for an <link linkend="getting-started.concepts.applet-types">applet type</link> 
supported
+               by our <link linkend="getting-started.concepts.applet-factory">applet factory</link>. Here we 
can see
+               that we only support the <constant>HelloWorldApplet</constant> applet type. This function 
returns
+               <constant>TRUE</constant> on success and <constant>FALSE</constant> on failures.
+
+               <note>
+                   <simpara>If you return <constant>FALSE</constant> here, GNOME Panel will show a dialog and
+                   notify the user that the applet loading failed.</simpara>
+               </note>
+           </para>
+       </listitem>
+       <listitem>
+           <para>
+               <function>hello_world_applet_start()</function>: this is where we actually setup the
+               <link linkend="PanelApplet"><type>PanelApplet</type></link> widget for the work the applet 
should do.
+               This can include adding widgets to the applet, connecting to signals, loading settings via 
GSettings,
+               etc.
+
+               <note>
+                 <simpara>
+                   The PanelApplet is a subclass of <link linkend="GtkBin"><type>GtkBin</type></link>
+                   container, to add more than one widget to it you will need to use another GtkContainer
+                   implementation such as <link linkend="GtkBox"><type>GtkBox</type></link> or
+                   <link linkend="GtkGrid"><type>GtkGrid</type></link>.
+                 </simpara>
+               </note>
+           </para>
+       </listitem>
+    </itemizedlist>
+
+    <para>
+      An example is worth a million words, so here is the code for our <emphasis>Hello World</emphasis> 
applet.
     </para>
 
     <example id="getting-started.example.simple">
@@ -105,7 +304,7 @@
 #include &lt;gtk/gtk.h&gt;
 #include &lt;panel-applet.h&gt;
 
-static gboolean
+static void
 hello_world_applet_start (PanelApplet *applet)
 {
     GtkWidget *label;
@@ -113,8 +312,6 @@ hello_world_applet_start (PanelApplet *applet)
     label = gtk_label_new ("Hello World");
     gtk_container_add (GTK_CONTAINER (applet), label);
     gtk_widget_show_all (GTK_WIDGET (applet));
-
-    return TRUE;
 }
 
 static gboolean
@@ -122,12 +319,12 @@ hello_world_factory_callback (PanelApplet  *applet,
                               const gchar  *iid,
                               gpointer      data)
 {
-    gboolean retval = FALSE;
+    if (g_strcmp0 (iid, "HelloWorldApplet") != 0)
+         return FALSE;
 
-    if (g_strcmp0 (iid, "HelloWorldApplet") == 0)
-        retval = hello_world_applet_start (applet);
+    hello_world_applet_start (applet);
 
-    return retval;
+    return TRUE;
 }
 
 PANEL_APPLET_OUT_PROCESS_FACTORY ("HelloWorldFactory",
@@ -138,29 +335,12 @@ PANEL_APPLET_OUT_PROCESS_FACTORY ("HelloWorldFactory",
     </example>
 
     <para>
-     Here are the few things that are important in this example:
-    </para>
-
-    <itemizedlist>
-     <listitem>
-      <para>
-       <link 
linkend="PANEL-APPLET-OUT-PROCESS-FACTORY:CAPS"><function>PANEL_APPLET_OUT_PROCESS_FACTORY()</function></link>:
 this creates an <link linkend="getting-started.concepts.applet-factory">applet factory</link> named 
<constant>HelloWorldFactory</constant>, and each time this applet factory will create an applet instance, it 
will call <function>hello_world_factory_callback()</function> with a <link 
linkend="PanelApplet"><type>PanelApplet</type></link> object already created.
-      </para>
-     </listitem>
-     <listitem>
-      <para>
-      <function>hello_world_factory_callback()</function>: this checks if the request to create an applet 
instance is for an <link linkend="getting-started.concepts.applet-types">applet type</link> supported by the 
<link linkend="getting-started.concepts.applet-factory">applet factory</link>. Here we can see that we only 
support the <constant>HelloWorldApplet</constant> applet type. This function returns 
<constant>TRUE</constant> on success and <constant>FALSE</constant> on failures.
-      </para>
-     </listitem>
-     <listitem>
-      <para>
-      <function>hello_world_applet_start()</function>: this is where we actually setup the <link 
linkend="PanelApplet"><type>PanelApplet</type></link> widget for the work the applet should do. This can 
include filling the widget, connecting to signals, etc.
-      </para>
-     </listitem>
-    </itemizedlist>
-
-    <para>
-     While the previous example is simple, it can be useful to directly subclass the <link 
linkend="PanelApplet"><type>PanelApplet</type></link> type. This makes it easy to have a per-applet instance 
private structure, among other benefits.
+      While the previous example is simple, it can be useful to directly subclass the
+      <link linkend="PanelApplet"><type>PanelApplet</type></link> type. This makes it easy to have a 
per-applet
+      instance private structure, among other benefits. Most of the code below is related to the GObject 
system
+      and needed to subclass the Panel Applet. The only noteworthy difference is that the
+      <constant>PANEL_APPLET_OUT_PROCESS_FACTORY</constant> macro now takes our subclassed type (e.g. 
<constant>HELLO_WORLD_TYPE_APPLET</constant>)
+      as its second parameter, instead of <constant>PANEL_TYPE_APPLET</constant>.
     </para>
 
     <example id="getting-started.example.subclass">
@@ -212,12 +392,10 @@ hello_world_applet_class_init (HelloWorldAppletClass *klass)
   g_type_class_add_private (class, sizeof (HelloWorldAppletPrivate));
 }
 
-static gboolean
+static
 hello_world_applet_start (HelloWorldApplet *applet)
 {
     gtk_widget_show (GTK_WIDGET (applet));
-
-    return TRUE;
 }
 
 static gboolean
@@ -225,17 +403,17 @@ hello_world_factory_callback (HelloWorldApplet *applet,
                               const gchar      *iid,
                               gpointer          data)
 {
-    gboolean retval = FALSE;
+    if (g_strcmp0 (iid, "HelloWorldApplet") != 0)
+         return FALSE;
 
-    if (g_strcmp0 (iid, "HelloWorldApplet") == 0)
-        retval = hello_world_applet_start (applet);
+    hello_world_applet_start (applet);
 
-    return retval;
+    return TRUE;
 }
 
 PANEL_APPLET_OUT_PROCESS_FACTORY ("HelloWorldFactory",
                                   HELLO_WORLD_TYPE_APPLET,
-                                  (PanelAppletFactoryCallback) hello_world_factory_callback,
+                                  hello_world_factory_callback,
                                   NULL)
      </programlisting>
     </example>
@@ -246,42 +424,48 @@ PANEL_APPLET_OUT_PROCESS_FACTORY ("HelloWorldFactory",
     <title>Using a Context Menu</title>
 
     <para>
-     The Panel Applet library uses <type>GtkAction</type> to define menu items appearing in the context menu 
of the applet.
+     The Panel Applet library uses <type>GAction</type> to define menu items appearing in the context menu 
of the
+     applet. This chapter provides some guidelines to applet developers and explains how to setup the 
context menu.
     </para>
 
-    <sect2 id="getting-started.context-menu.content">
+    <sect1 id="getting-started.context-menu.content">
      <title>Guidelines for Context Menu</title>
 
      <para>
-      To help guarantee consistency in the interaction with applets, there are some guidelines that are 
recommended to follow:
+      To help guarantee consistency in the interaction with applets, there are some guidelines that are
+      recommended to follow:
      </para>
 
      <itemizedlist>
       <listitem>
        <para>
-        Do not make the context menu too long: if you have more than five or six menu items, then it might 
be worth investing efforts on rethinking what is important in the menu.
+        Do not make the context menu too long: if you have more than five or six menu items, then it might 
be worth
+        investing efforts on rethinking what is important in the menu.
        </para>
       </listitem>
       <listitem>
        <para>
-        For the menu item that will enable the user to configure the applet, use "Preferences" for the 
label, and try to avoid "Configure", "Configuration", "Settings", etc.
+        For the menu item that will enable the user to configure the applet, use "Preferences" for the label,
+        and try to avoid "Configure", "Configuration", "Settings", etc.
        </para>
       </listitem>
       <listitem>
        <para>
-        Avoid putting a "Help" menu item. The user will usually explicitly add the applet, so it is expected 
that he knows what the applet is about. Putting a "Help" menu item in the context menu is therefore too 
prominent. It might make sense to add a "Help" button in the Preferences dialog, though.
+        Avoid putting a "Help" menu item. The user will usually explicitly add the applet, so it is expected 
that he knows what the applet is about.
+        Putting a "Help" menu item in the context menu is therefore too prominent. It might make sense to 
add a "Help" button in the Preferences dialog, though.
        </para>
       </listitem>
       <listitem>
        <para>
-        If you agree, avoid putting a "About" menu item. To the user, applets are not different applications 
but elements of one global application, the panel. Of course, this means that credits for working on the 
applet are not visible to the user.
+        If you agree, avoid putting a "About" menu item. To the user, applets are not different applications 
but elements of one global application, the panel. Of course, this means that credits
+        for working on the applet are not visible to the user.
        </para>
       </listitem>
      </itemizedlist>
 
-    </sect2>
+    </sect1>
 
-    <sect2 id="getting-started.context-menu.setup">
+    <sect1 id="getting-started.context-menu.setup">
      <title>Setting Up the Menu</title>
 
      <para>
@@ -414,7 +598,7 @@ PANEL_APPLET_OUT_PROCESS_FACTORY ("HelloWorldFactory",
      </listitem>
     </itemizedlist>
 
-    </sect2>
+    </sect1>
 
     <sect2 id="getting-started.context-menu.xml-file">
      <title>Menu XML File</title>
@@ -449,69 +633,93 @@ PANEL_APPLET_OUT_PROCESS_FACTORY ("HelloWorldFactory",
     <itemizedlist>
      <listitem>
       <para>
-       Global settings: those are settings that should be shared among all instances of the same applets. 
For instance, the preferred unit for temperature is something that the user will want to set only one. The 
way to store those settings is in no way specific to the Panel Applet library, as it should work like in any 
other application.
+       Global settings: those are settings that should be shared among all instances of the same applets.
+       For instance, the preferred unit for temperature is something that the user will want to set only one.
+       The way to store those settings is in no way specific to the Panel Applet library, as it should work
+       like in any other application.
       </para>
      </listitem>
      <listitem>
       <para>
-       Per-applet instance settings: those are settings that might be different depending on the instance of 
an applet. For instance, an applet whose goal is to display a picture should make it possible for the user to 
choose a different picture for each instance of the applet. The Panel Applet library provides API to help 
with this.
+       Per-applet instance settings: those are settings that might be different depending on the instance
+       of an applet. For instance, an applet whose goal is to display a picture should make it possible for
+       the user to choose a different picture for each instance of the applet. The Panel Applet library
+       provides API to help with this.
       </para>
      </listitem>
     </itemizedlist>
 
     <para>
-     There is actually a third case, which is rather rare, though: per-screen settings. It might be that 
some applets control some per-screen settings, like the layout of the workspaces. There is currently no API 
to help with this as it is a very specific case that you will probably never have to deal with for a usual 
applet.
+     There is actually a third case, which is rather rare, though: per-screen settings.
+     It might be that some applets control some per-screen settings, like the layout of the workspaces.
+     There is currently no API to help with this as it is a very specific case that you will probably
+     never have to deal with for a usual applet.
     </para>
 
-     TODO: describe settings-oriented API
+    <sect1 id="getting-started.settings.per-instance">
+       <title>Per Instance Settings</title>
+       <para>
+           In order to store per instance settings for an applet it is recommended to use GSettings. The
+           Panel Applet Library privides a function named <function>panel_applet_settings_new()</function>
+           for this purpose. You need to provide a GSettings schema file for your applet and the Panel
+           Applet library will setup the GSettings object for you.
+       </para>
+
+        TODO: describe settings-oriented API in more detail and give an example for per instance settings.
+
+    </sect1>
    </chapter>
 
    <chapter id="getting-started.install">
-    <title>Making the Applet Visible to the Panel</title>
+    <title>Applet Registration, Installation and Build System</title>
 
     <para>
-     Simply installing the applet binary will obviously not be enough to make this applet working in the 
panel. Two files should be installed for this:
+      Simply installing the applet binary will obviously not be enough. The applet also needs to be 
registered to the
+      panel. In order to do this you need to provide a Panel Applet File. Panel Applet files are ini-style 
text
+      files with an extension named <constant>.panel-applet</constant>.
     </para>
 
-    <itemizedlist>
-     <listitem>
-      <para>
-       a <filename>.panel-applet</filename> file so that the panel knows that the applet.
-      </para>
-     </listitem>
-     <listitem>
-      <para>
-       a D-Bus service file to autostart the binary when the panel wants to create an applet.
-      </para>
-     </listitem>
-    </itemizedlist>
+    <warning>
+        <simpara>
+          If you are creating an out-process applet, then you also need to provide a D-Bus service file
+          to automatically start the binary when the panel wants to create an applet.
+        </simpara>
+    </warning>
+
+       <para>
+           This chapter explains the syntax of <constant>.panel-applet</constant> files and gives the 
necessary
+           information to setup the build system in order to install all the required parts of the applet on 
the system.
+           For the build system part it is assumed that GNU Autotools (e.g. autoconf and automake) are used.
+       </para>
 
-    <sect2 id="getting-started.install.panel-applet">
-     <title>Panel Applet File</title>
+    <sect1 id="getting-started.install.panel-applet">
+     <title>Panel Applet File Syntax</title>
 
      <para>
-      The <filename>.panel-applet</filename> file is a key file about the applet binary, describing the 
<link linkend="getting-started.concepts.applet-factory">applet factory</link> from the binary and the <link 
linkend="getting-started.concepts.applet-types">applet types</link> this factory can create.
+      The <filename>.panel-applet</filename> file is a key file about the applet binary, describing the
+         <link linkend="getting-started.concepts.applet-factory">applet factory</link> of the binary and the
+         <link linkend="getting-started.concepts.applet-types">applet types</link> this factory can create.
      </para>
 
-     <sect3>
-      <title>Example</title>
+     <sect2>
+      <title>Panel Applet File Example</title>
       <informalexample>
        <programlisting>
-[Applet Factory]
-Id=HelloWorldFactory
-Name=Hello World Applet Factory
-Description=Factory for the window navigation related applets
-
-[HelloWorldApplet]
-Name=Hello World
-Description=Factory for the Hello World applet example
-Icon=hello-world-icon
+            [Applet Factory]
+            Id=HelloWorldFactory
+            Name=Hello World Applet Factory
+            Description=Factory for the our example applets
+
+            [HelloWorldApplet]
+            Name=Hello World
+            Description=Factory for the Hello World example applet
+            Icon=hello-world-icon
        </programlisting>
       </informalexample>
-     </sect3>
+     </sect2>
 
-     <sect3>
-      <title>Format</title>
+     <sect2>
+      <title>File Format and well known Fields</title>
       <para>
        The file must contain a <constant>Applet Factory</constant> group with the following keys:
       </para>
@@ -565,38 +773,197 @@ Icon=hello-world-icon
         </para>
        </listitem>
       </itemizedlist>
+     </sect2>
 
-     </sect3>
-
-     <sect3>
+     <sect2>
       <title>Installation</title>
       <para>
-       The <filename>.panel-applet</filename> file must be installed in a specific directory to be 
discoverable by the panel. You can fetch this directory during <constant>configure</constant> withe following 
code:
-      </para>
-
-      <informalexample>
-       <programlisting>
-LIBPANEL_APPLET_DIR=`$PKG_CONFIG --variable=libpanel_applet_dir libpanel-applet`
-AC_SUBST(LIBPANEL_APPLET_DIR)
-       </programlisting>
-      </informalexample>
-
-     </sect3>
-
-    </sect2>
+       The <filename>.panel-applet</filename> file must be installed in a specific directory to be 
discoverable by the panel. The exact path of this directory can be queried with 
<constant>pkg-config</constant>:
 
-    <sect2 id="getting-started.install.dbus-service">
-     <title>D-Bus Service File</title>
+          <informalexample>
+              <programlisting>
+                  pkg-config --variable=libpanel_applet_dir libpanel-applet
+              </programlisting>
+          </informalexample>
 
-     <para>
-      The communication between the panel and the applet factory is done over D-Bus. When creating an 
applet, the panel will send a message to the D-Bus service of the applet factory. If the D-Bus service is not 
running yet, it must be started automatically. We use D-Bus activation for this, which requires install a 
standard D-Bus service file. Please refer to the <ulink 
url="http://dbus.freedesktop.org/doc/dbus-specification.html#message-bus-starting-services";>D-Bus 
documentation</ulink> for more information about D-Bus service files.
-     </para>
-
-     <para>
-      This is only needed for <link linkend="getting-started.in-out-process">out-of-process applets</link>, 
because in-process applets do no need to have their binary autostarted for obvious reasons.
-     </para>
+          By default it is <constant>/usr/share/gnome-panel/5.0/applets</constant>. Please see the
+          <link linkend="getting-started.install.build-system">Build System</link> section for more 
information.
+      </para>
 
-    </sect2>
+         </sect2>
+
+       </sect1>
+
+       <sect1 id="getting-started.in-out-process">
+           <title>Out-of-Process vs In-Process</title>
+
+           <para>
+               Applets can either live in their own process ("out-of-process") or in the panel process 
("in-process").
+               The decision to choose one or the other is done at build time, with the macro that you use to 
define the applet
+               factory:
+               <link linkend="PANEL-APPLET-OUT-PROCESS-FACTORY:CAPS">
+                   <function>PANEL_APPLET_OUT_PROCESS_FACTORY()</function>
+               </link>
+               is used for out-of-process applets while
+               <link linkend="PANEL-APPLET-IN-PROCESS-FACTORY:CAPS">
+                   <function>PANEL_APPLET_IN_PROCESS_FACTORY()</function>
+               </link> is used for in-process applets. Obviously, only one of those two macros can be used. 
If both
+               types should be supported, then each macro must be placed between preprocessor conditions and 
switched on
+               through a configure option. For example:
+
+               <informalexample>
+                   <programlisting>
+                       #ifdef MY_APPLET_OUT_PROCESS_ENABLED
+                       PANEL_APPLET_OUT_PROCESS_FACTORY (...)
+                       #else
+                       PANEL_APPLET_IN_PROCESS_FACTORY (...)
+                       #endif
+                   </programlisting>
+               </informalexample>
+
+           </para>
+
+           <para>
+               For most practical matters, from the applet perspective, the two options are the same.
+               In-process applets do offer a slightly better performance when the applet is loaded, but this 
should not have
+               much effect on the user experience. However, an in-process applet can potentially affect the 
whole behavior of
+               the panel, especially in case of crashes or memory corruptions: a crash in an in-process 
applet will crash the
+               whole panel. It is therefore recommended to use out-of-process applets.
+           </para>
+
+           <para>
+               The communication between the panel and the applet factory is done over D-Bus. When creating 
an applet,
+               the panel will send a message to the D-Bus service of the applet factory. If the D-Bus 
service is not
+               running yet, it must be started automatically. We use D-Bus activation for this, which 
requires install a
+               standard D-Bus service file. This is only needed for, because in-process applets do no need 
to have their
+               binary autostarted for obvious reasons.
+           </para>
+
+           <note>
+               <simpara>
+                   Please refer to the
+                   <ulink 
url="http://dbus.freedesktop.org/doc/dbus-specification.html#message-bus-starting-services";>
+                       D-Bus documentation</ulink> for more information about D-Bus service files.
+               </simpara>
+           </note>
+
+           <para>
+               Here is an example for a D-Bus Service file. It should be named 
<constant>org.gnome.panel.applet.HelloWorldFactory.service.in</constant>
+           </para>
+           <informalexample>
+               <programlisting>
+                   [D-BUS Service]
+                   Name=org.gnome.panel.applet.HelloWorldFactory
+                   Exec= LOCATION@
+               </programlisting>
+           </informalexample>
+           <para>
+               Additionally you should adjust the build system to replace <constant>@LOCATION@</constant> by 
the install location of the applet binary. The file itself must be installed into
+               <constant>$(datadir)/dbus-1/services/</constant>.
+           </para>
+
+           <para>
+               The next section contains an explanation how to setup the Makefile in order to install the 
service file
+               to the correct location on the system.
+           </para>
+       </sect1>
+
+
+
+       <sect1 id="getting-started.install.build-system">
+           <title>Build system</title>
+
+           <sect2>
+               <title>Configure</title>
+
+               <para>
+                   In <constant>configure.ac</constant> a variable should be defined that contains the 
location
+                   where the .panel-applet files are installed.
+
+                   You can fetch this directory during <constant>configure</constant> with the following 
code:
+               </para>
+
+               <informalexample>
+                   <programlisting>
+                       LIBPANEL_APPLET_DIR=`$PKG_CONFIG --variable=libpanel_applet_dir libpanel-applet`
+                       AC_SUBST(LIBPANEL_APPLET_DIR)
+                   </programlisting>
+               </informalexample>
+
+           </sect2>
+
+           <sect2>
+               <title>Makefiles</title>
+
+               A typical Makefile for that is used to build and install an applet contains the following 
declarations:
+               <itemizedlist>
+                   <listitem>
+                       <para>A rule to install the <constant>.panel-applet</constant> file.</para>
+                   </listitem>
+                   <listitem>
+                       <para>A rule to install the D-Bus service file if the applet is an out process 
applet.</para>
+                   </listitem>
+                   <listitem>
+                       <para>The <constant>.panel-applet</constant> file and the D-Bus 
<constant>.service</constant> file
+                       are added to EXTRA_DIST and CLEANFILES.</para>
+                   </listitem>
+               </itemizedlist>
+
+               <sect3>
+                   <title>Installing the Panel Applet File</title>
+                   <informalexample>
+                       <programlisting language="bash">
+                           appletdir       = $(LIBPANEL_APPLET_DIR)
+                           applet_in_files = org.gnome.HelloWorld.panel-applet.in
+                           applet_DATA     = $(applet_in_files:.panel-applet.in=.panel-applet)
+
+                           $(applet_in_files): $(applet_in_files).in Makefile
+                               $(AM_V_GEN)sed \
+                               -e "s|\ LIBEXECDIR\@|$(libexecdir)|" \
+                               -e "s|\ VERSION\@|$(PACKAGE_VERSION)|" \
+                               $&lt; &gt; $@
+
+                           %.panel-applet: %.panel-applet.in \
+                                           $(INTLTOOL_MERGE) $(wildcard $(top_srcdir)/po/*po) ; \
+                                           $(INTLTOOL_MERGE) $(top_srcdir)/po $&lt; $@ -d -u -c 
$(top_builddir)/po/.intltool-merge-cache
+                       </programlisting>
+                   </informalexample>
+               </sect3>
+
+               <sect3>
+                   <title>Installing the D-Bus service file</title>
+
+                   <para>To install the service file the following rule can be placed in the applets 
Makefile:</para>
+                   <informalexample>
+                       <programlisting>
+                           servicedir       = $(datadir)/dbus-1/services
+                           service_in_files = org.gnome.panel.applet.HelloWorldFactory.service.in
+                           service_DATA     = $(service_in_files:.service.in=.service)
+
+                           org.gnome.panel.applet.HelloWorldFactory.service: $(service_in_files)
+                               $(AM_V_GEN) sed -e "s|\ LOCATION\@|$(APPLET_LOCATION)|" $&lt; &gt; $@
+                       </programlisting>
+                   </informalexample>
+               </sect3>
+
+               <sect3>
+                   <title>Distribution and Cleanup</title>
+                   <para>Add panel-applet .in.in and service file to EXTRA_DIST and $(applet_DATA) 
$(applet_DATA).in to CLEANFILES</para>
+                   <informalexample>
+                   <programlisting>
+                       EXTRA_DIST = \
+                           GNOME_MixerApplet.panel-applet.in.in \
+                           $(service_in_files) \
+                           $(ui_DATA) \
+                           $(schemas_in_files)
+
+                       CLEANFILES = $(applet_DATA) $(applet_DATA).in $(service_DATA) $(schemas_DATA)
+                   </programlisting>
+                   </informalexample>
+               </sect3>
+
+           </sect2>
+       </sect1>
 
    </chapter>
 
@@ -619,7 +986,13 @@ AC_SUBST(LIBPANEL_APPLET_DIR)
      </para>
 
      <para>
-      In some rare cases, though, <link 
linkend="panel-applet-set-background-widget"><function>panel_applet_set_background_widget()</function></link> 
will not be enough. The solution is then to connect to the <link 
linkend="PanelApplet-change-background"><function>"change-background"</function></link> signal of the <link 
linkend="PanelApplet"><type>PanelApplet</type></link> object: it will be emitted when the background has 
changed, and it will provide the <type>cairo_pattern_t</type> pattern to use as a basis to draw the 
background.
+      In some rare cases, though,
+      <link linkend="panel-applet-set-background-widget">
+          <function>panel_applet_set_background_widget()</function>
+      </link> will not be enough. The solution is then to connect to the
+      <link linkend="PanelApplet-change-background"><function>"change-background"</function></link> signal 
of the
+      <link linkend="PanelApplet"><type>PanelApplet</type></link> object: it will be emitted when the 
background has
+      changed, and it will provide the <type>cairo_pattern_t</type> pattern to use as a basis to draw the 
background.
      </para>
 
     </sect2>
@@ -628,15 +1001,24 @@ AC_SUBST(LIBPANEL_APPLET_DIR)
      <title>Panel Lockdown</title>
 
      <para>
-      The panel has proper support for lockdown, and when it is locked down, it is expected that all applets 
behave consistently in a lockdown mode too. This generally means that the preferences of the applet should 
not be accessible, but it could also imply a restriction on the behavior of the applet.
+      The panel has proper support for lockdown, and when it is locked down, it is expected that all applets 
behave
+      consistently in a lockdown mode too. This generally means that the preferences of the applet should 
not be
+      accessible, but it could also imply a restriction on the behavior of the applet.
      </para>
 
      <para>
-      The <link 
linkend="panel-applet-get-locked-down"><function>panel_applet_get_locked_down()</function></link> function 
can be used to query the state of the panel lockdown. It is also possible to react to changes by monitoring 
the <link linkend="PanelApplet--locked-down"><function>"locked-down"</function></link> property of the <link 
linkend="PanelApplet"><type>PanelApplet</type></link> object. You can achieve this by connecting to the 
<function>"notify::locked-down"</function> event.
+      The <link 
linkend="panel-applet-get-locked-down"><function>panel_applet_get_locked_down()</function></link>
+      function can be used to query the state of the panel lockdown. It is also possible to react to changes 
by
+      monitoring the <link linkend="PanelApplet--locked-down"><function>"locked-down"</function></link>
+      property of the <link linkend="PanelApplet"><type>PanelApplet</type></link> object. You can achieve 
this
+      by connecting to the <function>"notify::locked-down"</function> event.
      </para>
 
      <para>
-       In most cases, the <type>GBinding</type> API is enough to respect the panel lockdown: 
<function>g_object_bind_property()</function> can be used to automatically update the visiblity of a menu 
item in the context menu of the applet. In the following example, the <function>"HelloWorldPrefs"</function> 
action (which is an action from the context menu) will only be displayed if the panel is not locked down.
+       In most cases, the <type>GBinding</type> API is enough to respect the panel lockdown:
+       <function>g_object_bind_property()</function> can be used to automatically update the visiblity of a 
menu
+       item in the context menu of the applet. In the following example, the 
<function>"HelloWorldPrefs"</function>
+       action (which is an action from the context menu) will only be displayed if the panel is not locked 
down.
 
       <informalexample>
        <programlisting language="c">
@@ -648,7 +1030,8 @@ g_object_bind_property (applet, "locked-down",
       </informalexample>
 
       <para>
-       It is obviously possible to use <function>g_object_bind_property()</function> to change the 
visibility of widgets that appear outside of the context menu, like a button in a window.
+       Of course it is also possible to use <function>g_object_bind_property()</function> to change the 
visibility of
+       widgets that appear outside of the context menu, like a button in a window.
       </para>
 
      </para>
@@ -657,23 +1040,14 @@ g_object_bind_property (applet, "locked-down",
 
    </chapter>
 
-   <chapter id="getting-started.in-out-process">
-    <title>Out-of-Process vs In-Process</title>
-
-    <para>
-     Applets can either live in their own process ("out-of-process") or in the panel process ("in-process"). 
The decision to choose one or the other is done at build time, with the macro that you use to define the 
applet factory: <link 
linkend="PANEL-APPLET-OUT-PROCESS-FACTORY:CAPS"><function>PANEL_APPLET_OUT_PROCESS_FACTORY()</function></link>
 is used for out-of-process applets while <link 
linkend="PANEL-APPLET-IN-PROCESS-FACTORY:CAPS"><function>PANEL_APPLET_IN_PROCESS_FACTORY()</function></link> 
is used for in-process applets. Obviously, only one of those two macros can be used.
-    </para>
-
-    <para>
-      For most practical matters, from the applet perspective, the two options are the same. In-process 
applets do offer a slightly better performance when the applet is loaded, but this should not affect much the 
user experience. However, an in-process applet can potentially affect the whole behavior of the panel, 
especially in case of crashes or memory corruptions: a crash in an in-process applet will crash the whole 
panel. It is therefore recommended to use out-of-process applets.
-    </para>
-   </chapter>
-
    <chapter id="getting-started.introspection">
     <title>Writing an applet in languages other than C</title>
 
     <para>
-     The Panel Applet library comes with support for <ulink 
url="http://live.gnome.org/GObjectIntrospection";>GObject Introspection</ulink>. This makes it possible to 
write applets in the languages that have <ulink 
url="http://live.gnome.org/GObjectIntrospection/Users";>bindings based on GObject Introspection</ulink>.
+     The Panel Applet library comes with support for
+     <ulink url="http://live.gnome.org/GObjectIntrospection";>GObject Introspection</ulink>.
+     This makes it possible to write applets in the languages that have
+     <ulink url="http://live.gnome.org/GObjectIntrospection/Users";>bindings based on GObject 
Introspection</ulink>.
     </para>
 
     <para>
@@ -706,23 +1080,283 @@ PanelApplet.Applet.factory_main("HelloWorldFactory",
     </para>
 
     <para>
-     The only limitation of writing an applet in a language other than C is that the applet will not be able 
to run in the panel process: it will have to stay out-of-process. However, since it is recommended to leave 
applets out-of-process, this limitation is mitigated.
+     The only limitation of writing an applet in a language other than C is that the applet will
+     not be able to run in the panel process: it will have to stay out-of-process. However, since
+     it is recommended to leave applets out-of-process, this limitation is mitigated.
     </para>
    </chapter>
 
   </part>
 
   <part id="port-gnome2">
-    <title>Porting Applets from GNOME 2.x</title>
+    <title>Porting older Applets</title>
+
+    <chapter id="port-gnome2.dbus">
+       <title>Porting to a D-Bus-based Applet</title>
+
+        <sect1 id="port-gnome2.dbus.introduction">
+            <title>Introduction</title>
+            <para>
+                Applets that were written for Gnome 2.x must we ported to be usable with Gnome 3 and the 
latest Panel Applet
+                Library. First of all if the applet was written for Gnome 2.x then it will still use GTK+ 2 
and must be migrated
+                to GTK+ 3. Please refer to the
+                <ulink url="http://library.gnome.org/devel/gtk3/stable/gtk-migrating-2-to-3.html";>GTK+ 2 to 
GTK+ 3 migration guide</ulink>
+                for further details.
+            </para>
+
+            <para>
+                Once the GTK+ 2 to 3 migration has been completed you must migrate the Panel Applet Library 
specific
+                parts of the applet. During Gnome 2 times, the Panel Applet Library used LibBonobo, which 
was replaced
+                by a DBUS based API during the switch to Panel Applet Library version 4.0. During the change 
to
+                version 5.0 additional API have been replaced in particular the GConf related functions have 
been
+                removed and were replaced by the GSettings API. Also GtkAction related functions have been 
replaced
+                by the GAction API.
+            </para>
+
+            <note>
+                <simpara>
+                    The following migration guide is based on the
+                    <ulink url="https://wiki.gnome.org/Initiatives/GnomeGoals/AppletsDbusMigration";>
+                        AppletsDBUsMigration
+                    </ulink> guide in the GNOME Wiki. This guide was originally written for the migration of 
GNOME 2
+                    applets to GNOME 3 and Panel Applet Library version 4.0. Based on the information of the
+                    original guide this section improves some of the explanations, adds references to other 
parts
+                    of this manual and has been updated for the migration to version 5.0 of this library.
+                </simpara>
+            </note>
+        </sect1>
+
+        <sect1 id="port-gnome2.dbus.remove-libbonobo-factory">
+            <title>Removing LibBonobo factory</title>
+            <para>
+                To migrate from LibBonobo to the DBUS API remove PANEL_APPLET_BONOBO_FACTORY and replace it 
with
+                either PANEL_APPLET_OUT_PROCESS_FACTORY or PANEL_APPLET_IN_PROCESS_FACTORY depending if you 
want
+                an out-process or in-process applet, respectively.
+            </para>
+            <para>
+                The new macros have the same parameters as the old, except the version and description 
parameters have been
+                removed. Also the <constant>OAFIID:GNOME_</constant> prefix of the first parameter can be 
dropped both from
+                the factory ID and the applet type name. The following
+                two code listings show the difference between the old and new macro definitions:
+            </para>
+
+            <informalexample>
+                <programlisting>
+                    PANEL_APPLET_BONOBO_FACTORY ("OAFIID:GNOME_HelloWorldFactory",
+                                                 PANEL_TYPE_APPLET,
+                                                 "WindowNavigationApplets",
+                                                 "0",
+                                                 hello_world_factory,
+                                                 NULL)
+                </programlisting>
+            </informalexample>
+
+            The new version of the macro should be:
+
+            <informalexample>
+                <programlisting>
+                    PANEL_APPLET_OUT_PROCESS_FACTORY ("HelloWorldFactory",
+                                                      PANEL_TYPE_APPLET,
+                                                      hello_world_factory,
+                                                      NULL)
+                </programlisting>
+            </informalexample>
+
+            <para>
+                The applet factory callback, in this case the <function>hello_world_factory</function> 
usually contains a
+                check to ensure that the applet factory supports the requested applet. Here the
+                <constant>OAFIID:GNOME_</constant> prefix should be dropped as well, see the following two 
code listings.
+            </para>
+
+            <note>
+                <simpara>
+                    When you drop the prefix here, you must also remove the prefix from the applet name in 
the Panel Applet File.
+                </simpara>
+            </note>
+
+            Old definition:
+
+            <informalexample>
+                <programlisting>
+                    static gboolean
+                    hello_world_factory (PanelApplet *applet,
+                    const char  *iid,
+                    gpointer     data)
+                    {
+
+                    if (!g_strcmp (iid, "OAFIID:GNOME_HelloWorldApplet") != 0)
+                    return FALSE;
+
+                    hello_world_applet_fill (applet);
+
+                    return TRUE;
+                    }
+                </programlisting>
+            </informalexample>
+
+            The new version of of the factory callback should be:
+
+            <informalexample>
+                <programlisting>
+                    static gboolean
+                    hello_world_factory (PanelApplet *applet,
+                    const char  *iid,
+                    gpointer     data)
+                    {
+
+                    if (!g_strcmp0 (iid, "HelloWorldApplet") != 0)
+                    return FALSE;
+
+                    hello_world_applet_fill (applet);
+
+                    return TRUE;
+                    }
+                </programlisting>
+            </informalexample>
+
+            <sect2 id="port-gnome2.dbus.migrate-to-panel-applet-file">
+                <title>Migrating Service file to Panel Applet File</title>
+
+                <para>
+                    The old applet will have a <constant>service.in.in</constant> file that was used to 
register the
+                    applet with the GNOME Panel. This file must be renamed to 
<constant>.panel-applet</constant> and its
+                    content changed to match the format of the new file type. See
+                    <link linkend="getting-started.install">Panel Applet Files</link> for a detailed 
explanation of the
+                    valid fields. If you decided to use the out-process factory macro, then you should also 
supply a
+                    <link linkend="getting-started.in-out-process">D-BUS Service File</link> so your applet 
can be started
+                    using D-BUS activation.
+                </para>
+
+                <para>
+                    For compatibility you can keep the old <constant>BonoboId</constant>. This field can 
contain the old
+                    bonobo identifier. It allows the panel to load applets using existing configuration data 
in your panels
+                    settings. It can be a single string or a list of strings in case of applets with more 
than one
+                    identifier.
+                </para>
+
+                Example for the migrated panel applet file:
+                <informalexample>
+                    <programlisting>
+                        [Applet Factory]
+                        Id=HellWorldFactory
+                        Location= LOCATION@
+                        _Name=Hello World Applet Factory
+                        _Description=Factory for the our example applets
+
+                        [HelloWorldApplet]
+                        _Name=Hello World
+                        _Description=Factory for the Hello World example applet
+                        Icon=hello-world-icon
+                        BonoboId=OAFIID:GNOME_HelloWorldApplet
+                        X-GNOME-Bugzilla-Bugzilla=GNOME
+                        X-GNOME-Bugzilla-Product=gnome-panel
+                        X-GNOME-Bugzilla-Component=hello-world-applet
+                        X-GNOME-Bugzilla-Version= VERSION@
+                        X-GNOME-Bugzilla-OtherBinaries=hello-world-applet
+                    </programlisting>
+                </informalexample>
+            </sect2>
+        </sect1>
+
+        <sect1 id="port-gnome2.dbus.migrate-menus-to-gaction">
+            <title>Migrating LibBonobo menus to GAction</title>
+            <para>
+                During GNOME 2 days the context menu of the applet was based on the 
<constant>BonoboUiVerb</constant>
+                class. These old menu verb definitions have been removed and should be replaced by
+                the <type>GAction</type> interface family of objects.
+
+                <note>
+                    <simpara>
+                        Previous versions of this migration guide suggested to migrate to the family of
+                        <type>GtkActionGroup</type> classes. Since Gtk+ 3.10 these are deprecated and with 
the
+                        change of the Panel Applet Library API to version 5.0 the 
<function>panel_applet_setup_menu</function>
+                        family of functions now accept the <type>GActionGroup</type> interface and its 
related classes.
+                    </simpara>
+                </note>
+            </para>
+
+            If the applet that is being ports had a context menu then it should contain code that looks 
similar to the
+            following listing:
+
+            <informalexample>
+                <programlisting>
+                    static const BonoboUIVerb show_desktop_menu_verbs [] = {
+                        BONOBO_UI_UNSAFE_VERB ("ShowDesktopPreferences", display_preferences_dialog),
+                        BONOBO_UI_UNSAFE_VERB ("ShowDesktopAbout",       display_about_dialog),
+                        BONOBO_UI_VERB_END
+                    };
+                </programlisting>
+            </informalexample>
+
+            The new code instead looks like this:
+
+            <informalexample>
+                <programlisting>
+                    static const GActionEntry menu_actions[] = {
+                        { "preferences", display_preferences_dialog },
+                        { "about",       display_about_dialog }
+                    };
+                </programlisting>
+            </informalexample>
+
+            This change also means that the callbacks must be changed to match the GAction API:
+
+            Old callback looked like this:
+            <informalexample>
+                <programlisting>
+                    static void
+                    display_preferences_dialog (BonoboUIComponent *uic,
+                                                gpointer          *user_data,
+                                                const gchar       *verbname)
+                </programlisting>
+            </informalexample>
+
+            The new version should have the following signature:
+            <informalexample>
+                <programlisting>
+                    static void
+                    display_preferences_dialog (GSimpleAction *action,
+                                                GVariant      *parameter,
+                                                gpointer       user_data)
+                </programlisting>
+            </informalexample>
+
+            <para>
+                Additionally you should use GtkBuilder to define a GMenuModel in XML and use the
+                <function>panel_applet_setup_menu</function> family of functions to setup the menu. See
+                <link linkend="getting-started.context-menu">Using a context menu</link> for more details.
+                For more information about using the GMenu and GAction APIs please refer to the GIO Reference
+                Manual.
+            </para>
+        </sect1>
+   </chapter>
 
-   <refsect1 id="port-gnome2.dbus">
-    <title>Porting a D-Bus-based Applet</title>
+   <chapter>
+     <title>Porting Applets from Panel Applet Library 4.0</title>
+       <para>
+           The Panel Applet Library name has been renamed during the switch from version 4.0 to 5.0 and is 
now called
+           <constant>libpanel-applet</constant>.
+       </para>
+       <note>
+           <simpara>
+               Note that the version information in the library name has been dropped and there is now an
+               additional hypen between 'panel' and 'applet'.
+           </simpara>
+       </note>
 
-    <para>
-     There is no major issue porting a D-Bus-based applet from GNOME 2.x, from a Panel Applet library 
perspective. It is actually likely that the main issues will be that the applet has to be ported to GTK+ 3. 
Please refer to the <ulink url="http://library.gnome.org/devel/gtk3/stable/gtk-migrating-2-to-3.html";>GTK+ 2 
to GTK+ 3 migration guide</ulink> for this.
-    </para>
+       <para>
+           GConf support has been removed and was replaced by GSettings. If the applet still uses GConf it 
must
+           migrate to GSettings. It is recommended to use the 
<function>panel_applet_settings_new()</function> function
+           to store your settings.
+       </para>
 
-   </refsect1>
+       <para>
+           The <function>panel_applet_setup_menu</function> familiy of functions have been changed and now 
accept the
+           <type>GActionGroup</type> interface instead of the deprecated <type>GtkActionGroup</type>. Thus 
older applets
+           need to be changed and must migrate their menus to the <type>GAction</type> model. Please refer 
to the Gtk+
+           documentation for more details about <type>GAction</type> and the related interfaces.
+       </para>
+   </chapter>
 
   </part>
 


[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]