Documentation/Maemo 5 Developer Guide/Application Development/Writing Control Panel Applets

m (Functions)
 
(11 intermediate revisions not shown)
Line 1: Line 1:
-
= Writing control panel applets =
+
The control panel is designed to be extendable, and items can be added to it with dynamic libraries with certain functions and [[desktop file format|desktop files]] describing the library.
-
The control panel is designed to be extendable, and items can be added to it with dynamic libraries with certain functions and desktop files describing the library.
+
-
 
+
== Functions ==
== Functions ==
-
A control panel applet ([https://garage.maemo.org/svn/maemoexamples/trunk/maemo-examples/libapplet.c libapplet.c]) needs two functions. These functions are defined in
 
-
<tt><span>'''<span><font color="#000080"><nowiki>#include</nowiki></font></span>'''</span> <span><font color="#FF0000">&lt;hildon-cp-plugin/hildon-cp-plugin-interface.h&gt;</font></span></tt>
+
A control panel applet ([https://vcs.maemo.org/svn/maemoexamples/tags/maemo_5.0/maemo-examples/libapplet.c libapplet.c]) needs two functions. These functions are defined in the following:
-
The first and more important one, execute, is called when the applet is activated from Control Panel. Usually this function creates a dialog and waits until it is done. Any dialog created should be modal to the window in parameter.
+
<source lang="c">
-
'''N.B.''' The library might be unloaded when execute returns, so no g_timeouts, gconf_notifys or such should be left when done. Gtk or osso initialization is not needed, as they are already done at this point.
+
#include <hildon-cp-plugin/hildon-cp-plugin-interface.h>
 +
</source>
-
<tt><span>'''<span><font color="#000080"><nowiki>#include</nowiki></font></span>'''</span> <span><font color="#FF0000">&lt;hildon-cp-plugin/hildon-cp-plugin-interface.h&gt;</font></span>
+
The first and more important one, <code>execute</code>, is called when the applet is activated from Control Panel. Usually this function creates a dialog and waits until it is done. Any dialog created should be modal to the window in parameter.
-
<span>'''<span><font color="#000080"><nowiki>#include</nowiki></font></span>'''</span> <span><font color="#FF0000">&lt;gtk/gtk.h&gt;</font></span>
+
-
osso_return_t <span>'''<span><font color="#000000">execute</font></span>'''</span><span><font color="#990000">(</font></span>osso_context_t <span><font color="#990000"><nowiki>*</nowiki></font></span>osso<span><font color="#990000">,</font></span> gpointer data<span><font color="#990000">,</font></span> gboolean user_activated<span><font color="#990000">)</font></span>
+
-
<span><font color="#FF0000">{</font></span>
+
-
GtkWidget <span><font color="#990000"><nowiki>*</nowiki></font></span>dialog<span><font color="#990000"><nowiki>;</nowiki></font></span>
+
-
gint response<span><font color="#990000"><nowiki>;</nowiki></font></span>
+
-
<span>''<span><font color="#9A1900">/* Create dialog with OK and Cancel buttons. Leave the separator out,</font></span>''</span>
+
-
<span>''<span><font color="#9A1900"> * as we do not have any content. */</font></span>''</span>
+
-
dialog <span><font color="#990000"><nowiki>=</nowiki></font></span> <span>'''<span><font color="#000000">gtk_dialog_new_with_buttons</font></span>'''</span><span><font color="#990000">(</font></span>
+
-
<span><font color="#FF0000">"Hello control panel"</font></span><span><font color="#990000">,</font></span>
+
-
<span>'''<span><font color="#000000">GTK_WINDOW</font></span>'''</span><span><font color="#990000">(</font></span>data<span><font color="#990000">),</font></span>
+
-
GTK_DIALOG_MODAL <span><font color="#990000"><nowiki>|</nowiki></font></span> GTK_DIALOG_NO_SEPARATOR<span><font color="#990000">,</font></span>
+
-
GTK_STOCK_OK<span><font color="#990000">,</font></span>
+
-
GTK_RESPONSE_OK<span><font color="#990000">,</font></span>
+
-
GTK_STOCK_CANCEL<span><font color="#990000">,</font></span>
+
-
GTK_RESPONSE_CANCEL<span><font color="#990000">,</font></span>
+
-
NULL<span><font color="#990000">);</font></span>
+
-
<span>''<span><font color="#9A1900">/* ... add something to the dialog ... */</font></span>''</span>
+
-
<span>'''<span><font color="#0000FF">if</font></span>'''</span> <span><font color="#990000">(!</font></span>user_activated<span><font color="#990000">)</font></span>
+
-
<span><font color="#FF0000">{</font></span>
+
-
<span>''<span><font color="#9A1900">/* ... load state ... */</font></span>''</span>
+
-
<span><font color="#FF0000">}</font></span>
+
-
<span>''<span><font color="#9A1900">/* Wait until user finishes the dialog. */</font></span>''</span>
+
-
response <span><font color="#990000"><nowiki>=</nowiki></font></span> <span>'''<span><font color="#000000">gtk_dialog_run</font></span>'''</span><span><font color="#990000">(</font></span><span>'''<span><font color="#000000">GTK_DIALOG</font></span>'''</span><span><font color="#990000">(</font></span>dialog<span><font color="#990000">));</font></span>
+
-
<span>'''<span><font color="#0000FF">if</font></span>'''</span> <span><font color="#990000">(</font></span>response <span><font color="#990000"><nowiki>==</nowiki></font></span> GTK_RESPONSE_OK<span><font color="#990000">)</font></span>
+
-
<span><font color="#FF0000">{</font></span>
+
-
<span>''<span><font color="#9A1900">/* ... do something with the dialog stuff ... */</font></span>''</span>
+
-
<span><font color="#FF0000">}</font></span>
+
-
<span>''<span><font color="#9A1900">/* Free the dialog (and it's children) */</font></span>''</span>
+
-
<span>'''<span><font color="#000000">gtk_widget_destroy</font></span>'''</span><span><font color="#990000">(</font></span><span>'''<span><font color="#000000">GTK_WIDGET</font></span>'''</span><span><font color="#990000">(</font></span>dialog<span><font color="#990000">));</font></span>
+
-
<span>'''<span><font color="#0000FF">return</font></span>'''</span> OSSO_OK<span><font color="#990000"><nowiki>;</nowiki></font></span>
+
-
<span><font color="#FF0000">}</font></span>
+
-
</tt>
+
-
The other function is called save_state. It is called when application using the applet is saving state. Usually this does nothing, but if support for state saving is needed, this should be used.
+
N.B. The library can be unloaded when execute returns, so no <code>g_timeout</code>s, <code>gconf_notify</code>s or such must be left when done. GTK+ or osso initialization is not needed, because they are already done at this point.
-
<tt>osso_return_t <span>'''<span><font color="#000000">save_state</font></span>'''</span><span><font color="#990000">(</font></span>osso_context_t <span><font color="#990000"><nowiki>*</nowiki></font></span>osso<span><font color="#990000">,</font></span> gpointer data<span><font color="#990000">)</font></span>
+
<source lang="c">
-
<span><font color="#FF0000">{</font></span>
+
#include <hildon-cp-plugin/hildon-cp-plugin-interface.h>
-
<span>''<span><font color="#9A1900">/* ... save state ... */</font></span>''</span>
+
#include <gtk/gtk.h>
-
<span>'''<span><font color="#0000FF">return</font></span>'''</span> OSSO_OK<span><font color="#990000"><nowiki>;</nowiki></font></span>
+
 
-
<span><font color="#FF0000">}</font></span>
+
osso_return_t execute(osso_context_t *osso, gpointer data, gboolean user_activated)
-
</tt>
+
{
 +
GtkWidget *dialog;
 +
gint response;
 +
/* Create dialog with OK and Cancel buttons. Leave the separator out,
 +
* as we do not have any content. */
 +
dialog = gtk_dialog_new_with_buttons(
 +
"Hello control panel",
 +
GTK_WINDOW(data),
 +
GTK_DIALOG_MODAL | GTK_DIALOG_NO_SEPARATOR,
 +
GTK_STOCK_OK,
 +
GTK_RESPONSE_OK,
 +
GTK_STOCK_CANCEL,
 +
GTK_RESPONSE_CANCEL,
 +
NULL);
 +
/* ... add something to the dialog ... */
 +
if (!user_activated)
 +
{
 +
/* ... load state ... */
 +
}
 +
/* Wait until user finishes the dialog. */
 +
response = gtk_dialog_run(GTK_DIALOG(dialog));
 +
if (response == GTK_RESPONSE_OK)
 +
{
 +
/* ... do something with the dialog stuff ... */
 +
}
 +
/* Free the dialog (and it's children) */
 +
gtk_widget_destroy(GTK_WIDGET(dialog));
 +
return OSSO_OK;
 +
}
 +
</source>
 +
 
 +
The other function is called <code>save_state</code>. It is called when application using the applet is saving state. Usually this does nothing, but if support for state saving is needed, use it.
 +
 
 +
<source lang="c">
 +
osso_return_t save_state(osso_context_t *osso, gpointer data)
 +
{
 +
/* ... save state ... */
 +
return OSSO_OK;
 +
}
 +
</source>
== Building applet ==
== Building applet ==
-
To use the applet, it needs to be built into a dynamic library aka shared object. This can be accomplished by giving flag -shared to gcc.
 
-
<div class="graybox">
+
To use the applet, build it into a dynamic library aka shared object by passing the <code>-shared</code> flag to gcc.
-
[sbox-FREMANTLE_X86: ~] &gt; gcc -shared `pkg-config gtk+-2.0 libosso --libs --cflags` libapplet.c
+
-
-o libapplet.so
+
-
</div>
+
-
The binary produced by gcc should be installed to path specified in hildon-control-panel pkg-config entry. This path can be obtained with pkg-config hildon-control-panel --variable=pluginlibdir. By default this is /usr/lib/hildon-control-panel.
+
[sbox-FREMANTLE_X86: ~] > gcc -shared `pkg-config gtk+-2.0 hildon-control-panel libosso --libs --cflags` libapplet.c -o libapplet.so
 +
 
 +
Install the binary produced by gcc to a path specified in hildon-control-panel pkg-config entry. You can obtain this path with:
 +
pkg-config hildon-control-panel --variable=pluginlibdir
 +
By default it is <code>/usr/lib/hildon-control-panel</code>.
==The .desktop file ==
==The .desktop file ==
 +
Any control panel applet needs a desktop file describing it. The file contains metadata like name, icon name and library of the applet. The applet desktop file is much like the desktop file for any other application.
Any control panel applet needs a desktop file describing it. The file contains metadata like name, icon name and library of the applet. The applet desktop file is much like the desktop file for any other application.
-
Here is an example desktop file (applet.desktop) for the applet created above.  
+
Here is an example desktop file (<code>applet.desktop</code>) for the applet created above:
 +
 
 +
<pre>
 +
[Desktop Entry]
 +
Encoding=UTF-8
 +
Version=1.0
 +
Name=Control Panel Hello World
 +
Comment=A control panel example applet
 +
Type=HildonControlPanelPlugin
 +
Icon=qgn_list_cp_isetup
 +
X-control-panel-plugin=libapplet.so
 +
Categories=general
 +
</pre>
 +
 
 +
Install the desktop file to directory specified in pkg-config file for hildon-control-panel. This directory can be obtained with:
 +
pkg-config hildon-control-panel --variable=plugindesktopentrydir
-
<div class="graybox">
+
By default, it is <code>/usr/share/applications/hildon-control-panel</code>.
-
[Desktop Entry]
+
-
Encoding=UTF-8
+
-
Version=1.0
+
-
Name=Control Panel Hello World
+
-
Comment=A control panel example applet
+
-
Type=HildonControlPanelPlugin
+
-
Icon=qgn_list_cp_isetup
+
-
X-control-panel-plugin=libapplet.so
+
-
Categories=general
+
-
</div>
+
Icon file should be placed in the folder <code>/usr/share/pixmaps</code>. Specify the icon name without the .png suffix.
-
The desktop file must be installed to directory specified in pkg-config file for hildon-control-panel. This directory can be obtained by  ''`pkg-config hildon-control-panel --variable=plugindesktopentrydir`''. By default, this is /usr/share/applications/hildon-control-panel.
+
[[Category:Development]]
 +
[[Category:Documentation]]
 +
[[Category:Fremantle]]

Latest revision as of 14:11, 14 June 2012

The control panel is designed to be extendable, and items can be added to it with dynamic libraries with certain functions and desktop files describing the library.

Functions

A control panel applet (libapplet.c) needs two functions. These functions are defined in the following:

#include <hildon-cp-plugin/hildon-cp-plugin-interface.h>

The first and more important one, execute, is called when the applet is activated from Control Panel. Usually this function creates a dialog and waits until it is done. Any dialog created should be modal to the window in parameter.

N.B. The library can be unloaded when execute returns, so no g_timeouts, gconf_notifys or such must be left when done. GTK+ or osso initialization is not needed, because they are already done at this point.

#include <hildon-cp-plugin/hildon-cp-plugin-interface.h>
#include <gtk/gtk.h>
 
osso_return_t execute(osso_context_t *osso, gpointer data, gboolean user_activated)
{
	GtkWidget *dialog;
	gint response;
	/* Create dialog with OK and Cancel buttons. Leave the separator out,
	 * as we do not have any content. */
	dialog = gtk_dialog_new_with_buttons(
		"Hello control panel",
		GTK_WINDOW(data),
		GTK_DIALOG_MODAL | GTK_DIALOG_NO_SEPARATOR,
		GTK_STOCK_OK,
		GTK_RESPONSE_OK,
		GTK_STOCK_CANCEL,
		GTK_RESPONSE_CANCEL,
		NULL);
	/* ... add something to the dialog ... */
	if (!user_activated)
	{
		/* ... load state ... */
	}
	/* Wait until user finishes the dialog. */
	response = gtk_dialog_run(GTK_DIALOG(dialog));
	if (response == GTK_RESPONSE_OK)
	{
		/* ... do something with the dialog stuff ... */
	}
	/* Free the dialog (and it's children) */
	gtk_widget_destroy(GTK_WIDGET(dialog));
	return OSSO_OK;
}

The other function is called save_state. It is called when application using the applet is saving state. Usually this does nothing, but if support for state saving is needed, use it.

osso_return_t save_state(osso_context_t *osso, gpointer data)
{
	/* ... save state ... */
	return OSSO_OK;
}

Building applet

To use the applet, build it into a dynamic library aka shared object by passing the -shared flag to gcc.

[sbox-FREMANTLE_X86: ~] > gcc -shared `pkg-config gtk+-2.0 hildon-control-panel libosso --libs --cflags` libapplet.c -o libapplet.so

Install the binary produced by gcc to a path specified in hildon-control-panel pkg-config entry. You can obtain this path with:

pkg-config hildon-control-panel --variable=pluginlibdir

By default it is /usr/lib/hildon-control-panel.

The .desktop file

Any control panel applet needs a desktop file describing it. The file contains metadata like name, icon name and library of the applet. The applet desktop file is much like the desktop file for any other application.

Here is an example desktop file (applet.desktop) for the applet created above:

[Desktop Entry] 
Encoding=UTF-8
Version=1.0
Name=Control Panel Hello World
Comment=A control panel example applet
Type=HildonControlPanelPlugin
Icon=qgn_list_cp_isetup
X-control-panel-plugin=libapplet.so
Categories=general

Install the desktop file to directory specified in pkg-config file for hildon-control-panel. This directory can be obtained with:

pkg-config hildon-control-panel --variable=plugindesktopentrydir

By default, it is /usr/share/applications/hildon-control-panel.

Icon file should be placed in the folder /usr/share/pixmaps. Specify the icon name without the .png suffix.