|
|
|
libhildondesktop Reference Manual | |
|---|---|---|---|---|
#include <libhildondesktop/libhildondesktop.h>
HDHomePluginItem;
DBusConnection* hd_home_plugin_item_get_dbus_connection
(HDHomePluginItem *item,
DBusBusType type,
DBusError *error);
DBusGConnection* hd_home_plugin_item_get_dbus_g_connection
(HDHomePluginItem *item,
DBusBusType type,
GError **error);
const gchar* hd_home_plugin_item_get_dl_filename (HDHomePluginItem *item);
guint hd_home_plugin_item_heartbeat_signal_add
(HDHomePluginItem *item,
guint mintime,
guint maxtime,
GSourceFunc source_func,
gpointer data,
GDestroyNotify destroy);
gchar* hd_home_plugin_item_get_applet_id (HDHomePluginItem *item);
void hd_home_plugin_item_set_settings (HDHomePluginItem *item,
gboolean settings);
GObject
+----GInitiallyUnowned
+----GtkObject
+----GtkWidget
+----GtkContainer
+----GtkBin
+----GtkWindow
+----HDHomePluginItem
HDHomePluginItem implements AtkImplementorIface, GtkBuildable and HDPluginItem.
Base class for Home widgets. To create ur own Home widgets create a subclass of HDHomePluginItem.
Eventhough HdHomePluginItem is a GtkWindow it should mostly be used just as a simple widget, where the content is drawn into it with cairo. Since there is only tapping support for desktop widgets it is not possible to add complex widgets like pannable widgets into a desktop widget. It is also not possible to use clutter directly for implementing desktop widgets eventhough the window manager (hildon-desktop) is clutter based.
To create an transparent Home widget you have to set the colormap of the widget to RGBA. See the following example:
Example 3. Create a transparent Home widget
static void
example_clock_applet_realize (GtkWidget *widget)
{
GdkScreen *screen = gtk_widget_get_screen (widget);
gtk_widget_set_colormap (widget, gdk_screen_get_rgba_colormap (screen));
gtk_widget_set_app_paintable (widget, TRUE);
GTK_WIDGET_CLASS (example_clock_applet_parent_class)->realize (widget);
}
static gboolean
example_clock_applet_expose_event (GtkWidget *widget,
GdkExposeEvent *event)
{
cairo_t *cr;
cr = gdk_cairo_create (GDK_DRAWABLE (widget->window));
gdk_cairo_region (cr, event->region);
cairo_clip (cr);
cairo_set_operator (cr, CAIRO_OPERATOR_SOURCE);
cairo_set_source_rgba (cr, 0.0, 0.0, 0.0, 0.0);
cairo_paint (cr);
cairo_destroy (cr);
return GTK_WIDGET_CLASS (example_clock_applet_parent_class)->expose_event (widget,
event);
}
static void
example_clock_applet_class_init (ExampleClockAppletClass *klass)
{
GtkWidgetClass *widget_class = GTK_WIDGET_CLASS (klass);
widget_class->realize = example_clock_applet_realize;
widget_class->expose_event = example_clock_applet_expose_event;
}
To support a settings dialog in the layout mode in the Hildon desktop
connect to the "show-settings" signal. And set the
property "settings" to TRUE.
To start and stop animations of the widgets listen to the "notify" signal of
the "is-on-current-desktop" property. And show animations
only when "is-on-current-desktop" is TRUE.
Plugin code is loaded and unloaded from memory using the Glib dynamic loader, GModule. In some cases (for example the plugin defines a GType with pointers to code in the plugin) the plugin code cannot be safely unloaded from memory even after the plugin object has been finalized. In that case, unloading can be prevented by including the following code somewhere in the code for the plugin:
const gchar *
g_module_check_init (GModule *module)
{
g_module_make_resident(module);
return NULL;
}
In this case, of course, the plugin code can only be updated by restarting hildon-home so users wanting to update the widget will need to reboot.
DBusConnection* hd_home_plugin_item_get_dbus_connection
(HDHomePluginItem *item,
DBusBusType type,
DBusError *error);
Creates a new private DBusConnection to the D-Bus session or system bus.
It is similar to the dbus_bus_get_private() function but in contrast to the
dbus_bus_get_private() function the application will not exit if the connection
closes. Additionally this function is used to map the unique D-Bus name to the
plugin.
So this function should be used by plugins to create D-Bus connections.
item : |
A HDHomePluginItem |
type : |
The DBusBusType DBUS_BUS_SESSION or DBUS_BUS_SYSTEM
|
error : |
A DBusError to return error messages |
| Returns : | A new private connection to bus type. The connection must be unrefed with
dbus_connection_unref() when it is not longer needed.
|
DBusGConnection* hd_home_plugin_item_get_dbus_g_connection
(HDHomePluginItem *item,
DBusBusType type,
GError **error);
Creates a new DBusGConnection to the D-Bus session or system bus.
Internally, calls dbus_g_bus_get(). See there for further informations.
item : |
A HDHomePluginItem |
type : |
The DBusBusType DBUS_BUS_SESSION or DBUS_BUS_SYSTEM
|
error : |
A GError to return error messages |
| Returns : | A shared connection. |
const gchar* hd_home_plugin_item_get_dl_filename (HDHomePluginItem *item);
Returns the filename of the dynamic library file from which this item was loaded. Useful for debugging purposes.
item : |
a HDHomePluginItem |
| Returns : | filename of the dynamic library file. The result must not be freed. |
guint hd_home_plugin_item_heartbeat_signal_add
(HDHomePluginItem *item,
guint mintime,
guint maxtime,
GSourceFunc source_func,
gpointer data,
GDestroyNotify destroy);
Sets a function to be called at regular intervals. The source_func is called repeatedly until
it returns FALSE, at which point it is automatically destroyed and the function will not be
called again. The advantage of using this function over g_timeout_add_seconds_full() is
that all services using iphb on the device will wakeup synchronized, which will result in a
less power consumptioess
Care must be taken when using this function not to crash hildon-home. If the plugin is removed from the desktop by the user, the timer must be cancelled in the dispose or finalize function to avoid the timer firing after the plugin code has been unloaded from memory. The only way to cancel the timer is to destroy the event source. To do this, save the event source ID returned by this function (assume it is called "timer_source") and include something like
if (timer_source)
{
g_source_remove (timer_source);
timer_source = 0;
}in the dispose or finalize function.
It is wise to have maxtime-mintime quite big so all users of this service get synced.
If iphb is not avaiable g_timeout_add_seconds_full() is used with maxtime
as interval.
See iphb_wait() for more information.
item : |
A HDHomePluginItem. |
mintime : |
Time in seconds that must be waited before source_func is called, or 0.
|
maxtime : |
Time in seconds when the wait must end. |
source_func : |
Function to call. |
data : |
Data to pass to function.
|
destroy : |
Function to call when the signal is removed, or NULL.
|
| Returns : | The ID (greater than 0) of the event source. |
gchar* hd_home_plugin_item_get_applet_id (HDHomePluginItem *item);
Returns the applet id which is used to identify the applet in the Hildon Desktop.
item : |
A HDHomePluginItem |
| Returns : | The applet id. Free it when not longer used. |
void hd_home_plugin_item_set_settings (HDHomePluginItem *item, gboolean settings);
Sets whether the applet should show a settings button in layout mode.
The applet should connect to the "show-settings" signal to get notified when it should show the settings dialog.
item : |
A HDHomePluginItem |
settings : |
Whether the applet supports settings |
"is-on-current-desktop" property"is-on-current-desktop" gboolean : Read
If the applet is shown on current desktop.
Default value: FALSE
"show-settings" signalvoid user_function (HDHomePluginItem *item, gpointer user_data) : Run Last
The "show-settings" signal is emmited when the settings button
is clicked on a desktop widget in the desktop layout mode. The settings button
is only displayed when the "settings" property is set to TRUE.
In repsonse to this signal a settings dialog should be shown.
item : |
The HDHomePluginItem which emitted the signal |
user_data : |
user data set when the signal handler was connected. |