HDHomePluginItem

HDHomePluginItem — Base class for Home widgets.

Synopsis


#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);

Object Hierarchy

  GObject
   +----GInitiallyUnowned
         +----GtkObject
               +----GtkWidget
                     +----GtkContainer
                           +----GtkBin
                                 +----GtkWindow
                                       +----HDHomePluginItem

Implemented Interfaces

HDHomePluginItem implements HDPluginItem, AtkImplementorIface and GtkBuildable.

Properties

  "is-on-current-desktop"    gboolean              : Read
  "settings"                 gboolean              : Write

Signals

  "show-settings"                                  : Run Last

Description

Base class for Home widgets. To create ur own Home widgets create a subclass of HDHomePluginItem.

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.

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;
}


Details

HDHomePluginItem

typedef struct _HDHomePluginItem HDHomePluginItem;


hd_home_plugin_item_get_dbus_connection ()

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.

hd_home_plugin_item_get_dbus_g_connection ()

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.

hd_home_plugin_item_get_dl_filename ()

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.

hd_home_plugin_item_heartbeat_signal_add ()

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.

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.

hd_home_plugin_item_get_applet_id ()

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.

hd_home_plugin_item_set_settings ()

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

Property Details

The "is-on-current-desktop" property

  "is-on-current-desktop"    gboolean              : Read

If the applet is shown on current desktop.

Default value: FALSE


The "settings" property

  "settings"                 gboolean              : Write

If the applet should show a settings button in the layout mode.

Default value: FALSE

Signal Details

The "show-settings" signal

void                user_function                      (HDHomePluginItem *hdhomepluginitem,
                                                        gpointer          user_data)             : Run Last

hdhomepluginitem : the object which received the signal.
user_data : user data set when the signal handler was connected.