[gnome-panel/wip/segeiger/reference-documentation] Doc: Add DBusAppletsMigration guide
- From: Sebastian Geiger <segeiger src gnome org>
- To: commits-list gnome org
- Cc:
- Subject: [gnome-panel/wip/segeiger/reference-documentation] Doc: Add DBusAppletsMigration guide
- Date: Fri, 11 Sep 2015 15:24:10 +0000 (UTC)
commit 5dfa9b24ae164d3d3defd707c7064c1b1e92b006
Author: Sebastian Geiger <sbastig gmx net>
Date: Fri Sep 11 17:23:47 2015 +0200
Doc: Add DBusAppletsMigration guide
doc/reference/panel-applet/panel-applet-docs.sgml | 474 +++++++++++++++-----
1 files changed, 355 insertions(+), 119 deletions(-)
---
diff --git a/doc/reference/panel-applet/panel-applet-docs.sgml
b/doc/reference/panel-applet/panel-applet-docs.sgml
index af2b96f..4a29372 100644
--- a/doc/reference/panel-applet/panel-applet-docs.sgml
+++ b/doc/reference/panel-applet/panel-applet-docs.sgml
@@ -787,19 +787,6 @@ AC_SUBST(LIBPANEL_APPLET_DIR)
</sect2>
- <sect2 id="getting-started.install.dbus-service">
- <title>D-Bus Service File</title>
-
- <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>
-
- </sect2>
-
</chapter>
<chapter id="getting-started.integration">
@@ -888,16 +875,73 @@ g_object_bind_property (applet, "locked-down",
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.
+ </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 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.
+ 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>/usr/share/dbus-1/services/</constant>.
+ </para>
+
+ To install the service file the following rule can be placed in the applets Makefile:
+ <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.FishAppletFactory.service: $(service_in_files)
+ $(AM_V_GEN) sed -e "s|\ LOCATION\@|$(APPLET_LOCATION)|" $< > $@
+ </programlisting>
+ </informalexample>
+
</chapter>
<chapter id="getting-started.introspection">
@@ -951,108 +995,300 @@ PanelApplet.Applet.factory_main("HelloWorldFactory",
<part id="port-gnome2">
<title>Porting older Applets</title>
- <chapter id="port-gnome2.dbus">
- <title>Porting to a D-Bus-based Applet</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
API
- during the switch to Panel Applet Library version 4.0.
- </para>
-
- <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>
+ <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>
+
+ <sect1 id="port-gnome2.dbus.build-system-changes">
+ <title>Build system changes</title>
+ Build system (configure)
+
+ Check for libpanel-applet-4 in your configure file, and get the directory where .panel-applet
files should go from the pkg-config file, with something like:
+
+ LIBPANEL_APPLET_DIR=`$PKG_CONFIG --variable=libpanel_applet_dir libpanelapplet-4.0`
+
+ Build system (Makefile.am)
+
+ Add the ui xml path to the CFLAGS:
+
+ -DWNCK_MENU_UI_DIR=\""$(xmluidir)"\" \
+
+ This is the macro you use when setting up the applet menu
+
+ Panel-applet file:
+
+ appletdir = $(LIBPANEL_APPLET_DIR)
+ applet_in_files = GNOME_MixerApplet.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)|" \
+ $< > $@
+
+ %.panel-applet: %.panel-applet.in $(INTLTOOL_MERGE) $(wildcard $(top_srcdir)/po/*po) ;
$(INTLTOOL_MERGE) $(top_srcdir)/po $< $@ -d -u -c $(top_builddir)/po/.intltool-merge-cache
+
+ This rule should probably be moved to intltool as something like:
+
+ INTLTOOL_PANEL_APPLET_RULE='%.panel-applet: %.panel-applet.in $(INTLTOOL_MERGE) $(wildcard
$(top_srcdir)/po/*.po) ; $(AM_V_GEN) LC_ALL=C $(INTLTOOL_MERGE) -d -u -c
$(top_builddir)/po/.intltool-merge-cache $(top_srcdir)/po $< [$]@'
+
+ D-Bus service file:
+
+ servicedir = $(datadir)/dbus-1/services
+ service_in_files = org.gnome.panel.applet.FishAppletFactory.service.in
+ service_DATA = $(service_in_files:.service.in=.service)
+
+ org.gnome.panel.applet.FishAppletFactory.service: $(service_in_files)
+ $(AM_V_GEN)sed \
+ -e "s|\ LOCATION\@|$(APPLET_LOCATION)|" \
+ $< > $@
- <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>
+ Add panel-applet .in.in and service file to EXTRA_DIST and $(applet_DATA) $(applet_DATA).in to
CLEANFILES
+
+ 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)
+ </sect1>
- 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>
</chapter>
[
Date Prev][
Date Next] [
Thread Prev][
Thread Next]
[
Thread Index]
[
Date Index]
[
Author Index]
