diff options
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.sgml | 385 |
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 <string.h> + +#include <mate-panel-applet.h> +#include <gtk/gtklabel.h> + +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> +<oaf_info> +<oaf_server iid="OAFIID:My_HelloApplet_Factory" type="exe" + location="test-matecomponent-applet"> + + <oaf_attribute name="repo_ids" type="stringv"> + <item value="IDL:MateComponent/GenericFactory:1.0"/> + <item value="IDL:MateComponent/Unknown:1.0"/> + </oaf_attribute> + <oaf_attribute name="name" type="string" value="Hello World Applet Factory"/> + <oaf_attribute name="description" type="string" value="My first applet factory"/> +</oaf_server> + +<oaf_server iid="OAFIID:My_HelloApplet" type="factory" + location="OAFIID:My_HelloApplet_Factory"> + + <oaf_attribute name="repo_ids" type="stringv"> + <item value="IDL:MATE/Vertigo/MatePanelAppletShell:1.0"/> + <item value="IDL:MateComponent/Control:1.0"/> + <item value="IDL:MateComponent/Unknown:1.0"/> + </oaf_attribute> + <oaf_attribute name="name" type="string" value="Hello World Applet"/> + <oaf_attribute name="description" type="string" value="My first applet for the MATE2 panel"/> + <oaf_attribute name="panel:icon" type="string" value="mate-applets.png"/> +</oaf_server> +</oaf_info> + </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 <mate-panel-applet.h> + +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> +<oaf_info> + +<oaf_server iid="OAFIID:BlahApplet" + type="exe" + location="blah-de-blah-2"> + + <oaf_attribute name="repo_ids" type="stringv"> + <item value="IDL:MateComponent/GenericFactory:1.0""/> + <item value="IDL:MateComponent/Unknown:1.0"/> + </oaf_attribute> + <oaf_attribute name="name" type="string" value="Blah Factory"/> + <oaf_attribute name="description" type="string" value="Blah De Blah"/> + +</oaf_server> + +<oaf_server iid="OAFIID:BlahApplet" + type="factory" + location="OAFIID:BlahApplet_Factory"> + + <oaf_attribute name="repo_ids" type="stringv"> + <item value="IDL:MATE/MatePanelAppletShell:1.0"/> + <item value="IDL:MateComponent/Control:1.0"/> + <item value="IDL:MateComponent/Unknown:1.0"/> + </oaf_attribute> + <oaf_attribute name="name" type="string" value="Blah Applet"/> + <oaf_attribute name="description" type="string" value="Blah De Blah"/> + <oaf_attribute name="panel:icon" type="string" value="blah-de-blah.png"/> + +</oaf_server> + +</oaf_info> + </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 [] = + "<popup name=\"button3\">\n" + " <menuitem name=\"Properties Item\" verb=\"BlahProperties\" _label=\"Properties ...\"\n" + " pixtype=\"stock\" pixname=\"gtk-properties\"/>\n" + " <menuitem name=\"Help Item\" verb=\"BlahHelp\" _label=\"Help\"\n" + " pixtype=\"stock\" pixname=\"gtk-help\"/>\n" + " <menuitem name=\"About Item\" verb=\"BlahAbout\" _label=\"About ...\"\n" + " pixtype=\"stock\" pixname=\"mate-stock-about\"/>\n" + "</popup>\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> |