summaryrefslogtreecommitdiff
path: root/doc/reference/mate-panel-applet/mate-panel-applet-docs.sgml
diff options
context:
space:
mode:
authorPerberos <[email protected]>2011-12-01 22:56:10 -0300
committerPerberos <[email protected]>2011-12-01 22:56:10 -0300
commitc51ef797a707f4e2c6f9688d4378f2b0e9898a66 (patch)
tree019ae92bb53c19b30077545cb14743cbd1b57aef /doc/reference/mate-panel-applet/mate-panel-applet-docs.sgml
downloadmate-panel-c51ef797a707f4e2c6f9688d4378f2b0e9898a66.tar.bz2
mate-panel-c51ef797a707f4e2c6f9688d4378f2b0e9898a66.tar.xz
moving from https://github.com/perberos/mate-desktop-environment
Diffstat (limited to 'doc/reference/mate-panel-applet/mate-panel-applet-docs.sgml')
-rw-r--r--doc/reference/mate-panel-applet/mate-panel-applet-docs.sgml385
1 files changed, 385 insertions, 0 deletions
diff --git a/doc/reference/mate-panel-applet/mate-panel-applet-docs.sgml b/doc/reference/mate-panel-applet/mate-panel-applet-docs.sgml
new file mode 100644
index 00000000..3ada0d9e
--- /dev/null
+++ b/doc/reference/mate-panel-applet/mate-panel-applet-docs.sgml
@@ -0,0 +1,385 @@
+<?xml version="1.0" standalone="no"?>
+<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
+ "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [
+<!ENTITY MatePanelApplet SYSTEM "xml/mate-panel-applet.xml">
+<!ENTITY MatePanelAppletMateConf SYSTEM "xml/mate-panel-applet-mateconf.xml">
+]>
+
+<book id="libmate-panel-applet">
+ <bookinfo>
+ <title>Panel Applet Library Reference Manual</title>
+ <authorgroup>
+ <author>
+ <firstname>Mark</firstname>
+ <surname>McLoughlin</surname>
+ <affiliation>
+ <address>
+ <email>[email protected]</email>
+ </address>
+ </affiliation>
+ </author>
+ </authorgroup>
+
+ <copyright>
+ <year>2001</year>
+ <year>2003</year>
+ <holder>Sun Microsystems, Inc.</holder>
+ </copyright>
+
+ <abstract>
+ <para>
+This manual documents the interfaces of the panel applet
+library for MATE 2.x and a short guide to porting applets from
+the MATE 1.x interfaces.
+ </para>
+ </abstract>
+
+ </bookinfo>
+
+ <chapter id="applet-writing">
+ <title>Writing Applets</title>
+
+ <para>Writing applets is very simple. You take some boiler plate
+code like below, change a couple of things and write the code that
+implements your widgetry. The hardest part is writing your widgetry -
+and its completely up to yourself how hard that should be.
+ </para>
+
+ <sect1 id="hello-world">
+ <title>Hello World Applet</title>
+
+ <para>As usual, following the pointless tradition of starting with
+an example of how get 'Hello World' on the screen in some form, here's
+just about the simplest applet you could write.
+ </para>
+
+ <programlisting>
+#include &lt;string.h&gt;
+
+#include &lt;mate-panel-applet.h&gt;
+#include &lt;gtk/gtklabel.h&gt;
+
+static gboolean
+hello_applet_fill (MatePanelApplet *applet,
+ const gchar *iid,
+ gpointer data)
+{
+ GtkWidget *label;
+
+ if (strcmp (iid, "OAFIID:My_HelloApplet") != 0)
+ return FALSE;
+
+ label = gtk_label_new ("Hello World");
+ gtk_container_add (GTK_CONTAINER (applet), label);
+
+ gtk_widget_show_all (GTK_WIDGET (applet));
+
+ return TRUE;
+}
+
+
+MATE_PANEL_APPLET_MATECOMPONENT_FACTORY ("OAFIID:My_HelloApplet_Factory",
+ PANEL_TYPE_APPLET,
+ "TheHelloWorldApplet",
+ "0",
+ hello_applet_fill,
+ NULL);
+ </programlisting>
+
+ <para>The code here is very similar to writing a normal MateComponent
+control. You define a factory using MATE_PANEL_APPLET_MATECOMPONENT_FACTORY(),
+passing it a factory function like hello_applet_fill().
+ </para>
+
+ <para>libmate-panel-applet automatically creates a #MatePanelApplet object
+for you, passing this to your factory method. Here, you should fill
+the applet with your widgets just like a #GtkBin. For example, if you
+were writing a cdplayer applet you would create a #GtkHBox, pack the
+hbox with the cdplayer buttons and in turn add the hbox to the applet.
+ </para>
+
+ </sect1>
+
+ <sect1 id="server-files">
+ <title>MateComponent Activation .server Files For Applets</title>
+
+ <para>Since an applet is a matecomponent component, you must write
+a .server file so that the matecomponent activation daemon is aware that
+your component exists and how to activate it. Copy and paste is
+your friend here ...
+ </para>
+
+ <programlisting>
+&lt;oaf_info&gt;
+&lt;oaf_server iid="OAFIID:My_HelloApplet_Factory" type="exe"
+ location="test-matecomponent-applet"&gt;
+
+ &lt;oaf_attribute name="repo_ids" type="stringv"&gt;
+ &lt;item value="IDL:MateComponent/GenericFactory:1.0"/&gt;
+ &lt;item value="IDL:MateComponent/Unknown:1.0"/&gt;
+ &lt;/oaf_attribute&gt;
+ &lt;oaf_attribute name="name" type="string" value="Hello World Applet Factory"/&gt;
+ &lt;oaf_attribute name="description" type="string" value="My first applet factory"/&gt;
+&lt;/oaf_server&gt;
+
+&lt;oaf_server iid="OAFIID:My_HelloApplet" type="factory"
+ location="OAFIID:My_HelloApplet_Factory"&gt;
+
+ &lt;oaf_attribute name="repo_ids" type="stringv"&gt;
+ &lt;item value="IDL:MATE/Vertigo/MatePanelAppletShell:1.0"/&gt;
+ &lt;item value="IDL:MateComponent/Control:1.0"/&gt;
+ &lt;item value="IDL:MateComponent/Unknown:1.0"/&gt;
+ &lt;/oaf_attribute&gt;
+ &lt;oaf_attribute name="name" type="string" value="Hello World Applet"/&gt;
+ &lt;oaf_attribute name="description" type="string" value="My first applet for the MATE2 panel"/&gt;
+ &lt;oaf_attribute name="panel:icon" type="string" value="mate-applets.png"/&gt;
+&lt;/oaf_server&gt;
+&lt;/oaf_info&gt;
+ </programlisting>
+
+ <para>Probably the most important thing to note here is that, unlike
+.server files for other matecomponent components, applet .server files contain
+a special attribute called 'panel:icon'. This is used by the panel to display
+an entry for the applet in the 'Add to Panel' dialog.
+ </para>
+ </sect1>
+
+ <sect1 id="applet-popups">
+ <title>Defining a Popup Context Menu</title>
+
+ <para>FIXME: write</para>
+ </sect1>
+
+ <sect1 id="panel-signals">
+ <title>Detecting Changes in the Panel.</title>
+
+ <para>FIXME: write</para>
+ </sect1>
+
+ <sect1 id="session-saving">
+ <title>Session/Preference Saving.</title>
+
+ <para>FIXME: write</para>
+ </sect1>
+
+ <sect1 id="multi-applets">
+ <title>Multiple Applets</title>
+
+ <para>FIXME: write</para>
+ </sect1>
+
+ </chapter>
+
+ <chapter id="applet-porting">
+ <title>Porting Applets from the MATE 1.x interfaces</title>
+
+ <para>In MATE 1.x the applet interface lived in a header called
+<filename>applet-widget.h</filename>. The interface was based on GOAD,
+the MATE 1.x object activation framework. A new interface was
+designed for MATE 2.x using the power of matecomponent UI embedding and the
+new object activation framework, matecomponent-activation. The interface is
+intended to be easy to use, cruft free, but semantically similar to
+the old API in order to make porting relatively painless.</para>
+
+ <simplesect id="applet-porting-activation">
+ <title>Applet Activation</title>
+
+ <para>The first thing to change when porting to the new API is
+the header. Include <filename>mate-panel-applet.h</filename> instead of
+<filename>applet-widget.h</filename>.</para>
+
+ <para>Next you need to change how the applet is activated.
+Browsing through old applet's code, its obvious that this was done in
+various ways in the past. The best advice is to hunt out the calls to
+applet_widget_init, applet_widget_new and applet_widget_add.
+applet_widget_new and applet_widget_add are now effectively merged
+into one call mate_panel_applet_new, to which the top-level widget of the
+applet should be passed. applet_widget_init is not neccessary anymore.
+So the new code should look something like this</para>
+
+ <programlisting>
+#include &lt;mate-panel-applet.h&gt;
+
+static MateComponentObject *
+blah_applet_new ()
+{
+ MatePanelApplet *applet;
+
+ /*
+ * The old code setting up the applet widgetry
+ * goes here. So effectively delete calls to
+ * applet_widget_init and applet_widget_new
+ * and the replace applet_widget_add with a call
+ * to mate_panel_applet_new.
+ */
+
+ applet = mate_panel_applet_new (label);
+
+ return MATECOMPONENT_OBJECT (mate_panel_applet_get_control (applet));
+}
+
+static MateComponentObject *
+blah_applet_factory (MateComponentGenericFactory *this,
+ const gchar *iid,
+ gpointer data)
+{
+ MateComponentObject *applet = NULL;
+
+ if (!strcmp (iid, "OAFIID:BlahApplet"))
+ applet = blah_applet_new ();
+
+ return applet;
+}
+
+
+MATE_PANEL_APPLET_MATECOMPONENT_FACTORY ("OAFIID:BlahApplet_Factory",
+ "Blah",
+ "0",
+ blah_applet_factory,
+ NULL)
+ </programlisting>
+
+ <para>You should use MATE_PANEL_APPLET_MATECOMPONENT_FACTORY or
+MATE_PANEL_APPLET_MATECOMPONENT_SHLIB_FACTORY depending on whether you want the
+applet to be out of process or in process.</para>
+
+ </simplesect>
+
+ <simplesect id="applet-porting-activation-files">
+ <title>Activation files</title>
+
+ <para>The next thing to do may be to port from a
+<filename>.gnorba</filename> file to a matecomponent-activation
+<filename>.server</filename> file. You no longer need a .desktop file
+for applets. A <filename>.gnorba</filename> looks something like this
+:</para>
+
+ <programlisting>
+[blah]
+type=exe
+repo_id=IDL:MATE/Applet:1.0
+description=Blah
+location_info=blah-de-blah
+ </programlisting>
+
+ <para>Your <filename>.server</filename> file should look like
+this :</para>
+
+ <programlisting>
+&lt;oaf_info&gt;
+
+&lt;oaf_server iid="OAFIID:BlahApplet"
+ type="exe"
+ location="blah-de-blah-2"&gt;
+
+ &lt;oaf_attribute name="repo_ids" type="stringv"&gt;
+ &lt;item value="IDL:MateComponent/GenericFactory:1.0""/&gt;
+ &lt;item value="IDL:MateComponent/Unknown:1.0"/&gt;
+ &lt;/oaf_attribute&gt;
+ &lt;oaf_attribute name="name" type="string" value="Blah Factory"/&gt;
+ &lt;oaf_attribute name="description" type="string" value="Blah De Blah"/&gt;
+
+&lt;/oaf_server&gt;
+
+&lt;oaf_server iid="OAFIID:BlahApplet"
+ type="factory"
+ location="OAFIID:BlahApplet_Factory"&gt;
+
+ &lt;oaf_attribute name="repo_ids" type="stringv"&gt;
+ &lt;item value="IDL:MATE/MatePanelAppletShell:1.0"/&gt;
+ &lt;item value="IDL:MateComponent/Control:1.0"/&gt;
+ &lt;item value="IDL:MateComponent/Unknown:1.0"/&gt;
+ &lt;/oaf_attribute&gt;
+ &lt;oaf_attribute name="name" type="string" value="Blah Applet"/&gt;
+ &lt;oaf_attribute name="description" type="string" value="Blah De Blah"/&gt;
+ &lt;oaf_attribute name="panel:icon" type="string" value="blah-de-blah.png"/&gt;
+
+&lt;/oaf_server&gt;
+
+&lt;/oaf_info&gt;
+ </programlisting>
+
+ <para>A lot of this should be copied and pasted. The most
+important bit is "panel:icon" which specfies the icon
+that should be displayed in the "Add to Panel" dialog.</para>
+
+ </simplesect>
+
+ <simplesect id="applet-porting-menus">
+ <title>Context Menu</title>
+
+ <para>Most applets also place extra menu items into it context
+menu. It might be a good idea to port this next. In MATE 1.x this was
+done using the applet_widget_register_stock_callback API call. In
+MATE 2.x 3 things must be done</para>
+
+ <itemizedlist>
+ <listitem><para>An xml desription of the popup menu must be
+written.</para></listitem>
+ <listitem><para>A description of the verbs must be prepared.
+This is basically a list of callbacks to be call when a certain menu
+item is clicked in the popup.</para></listitem>
+ <listitem><para>The menu is registered using a call to
+mate_panel_applet_setup_menu.</para></listitem>
+ </itemizedlist>
+
+ <para>The xml description should look something like this
+:</para>
+
+ <programlisting>
+static const char fish_menu_xml [] =
+ "&lt;popup name=\"button3\"&gt;\n"
+ " &lt;menuitem name=\"Properties Item\" verb=\"BlahProperties\" _label=\"Properties ...\"\n"
+ " pixtype=\"stock\" pixname=\"gtk-properties\"/&gt;\n"
+ " &lt;menuitem name=\"Help Item\" verb=\"BlahHelp\" _label=\"Help\"\n"
+ " pixtype=\"stock\" pixname=\"gtk-help\"/&gt;\n"
+ " &lt;menuitem name=\"About Item\" verb=\"BlahAbout\" _label=\"About ...\"\n"
+ " pixtype=\"stock\" pixname=\"mate-stock-about\"/&gt;\n"
+ "&lt;/popup&gt;\n";
+ </programlisting>
+
+ <para>This could also be in a seperate
+<filename>.xml</filename> file and loaded with
+mate_panel_applet_setup_menu_from_file. The description of the verbs should
+look something like :</para>
+
+ <programlisting>
+static const MateComponentUIVerb fish_menu_verbs [] = {
+ MATECOMPONENT_UI_VERB ("BlahProperties", display_properties_dialog),
+ MATECOMPONENT_UI_VERB ("BlahHelp", display_help_dialog),
+ MATECOMPONENT_UI_VERB ("BlahAbout", display_about_dialog),
+
+ MATECOMPONENT_UI_VERB_END
+};
+ </programlisting>
+
+ <para>This is just a list of callbacks invoked when the menu
+items are clicked. There are other macros you may use other than
+MATECOMPONENT_UI_VERB - see
+<filename>matecomponent-ui-component.h</filename>.</para>
+
+ <para>To actually register the menu you just do something like
+:</para>
+
+ <programlisting>
+ mate_panel_applet_setup_menu (MATE_PANEL_APPLET (blah->applet),
+ blah_menu_xml,
+ blah_menu_verbs,
+ blah);
+ </programlisting>
+
+ <para>The last argument is the user_data argument passed back
+to the callbacks.</para>
+
+ </simplesect>
+
+ </chapter>
+
+ <chapter id="mate-panel-applet">
+ <title>The Panel Applet Library</title>
+
+ &MatePanelApplet;
+ &MatePanelAppletMateConf;
+ </chapter>
+
+</book>