Name
StatusDocklet -- Simple way to embed a small window in the panel
Object Hierarchy
GtkObject
+----StatusDocklet |
Description
Some apps want to embed a very small icon or widget in the panel to display
the status of the app. This can be done without the operational overhead of
an applet. The status docklet will embed a 22 by 22 window inside the panel.
This is not a separate applet and thus is minimally intrusive to the user and
is meant for very temporary status displays for which a full applet would not
be appropriate.
The way StatusDocklet works is a little different from how the AppletWidget
works. Firstly, StatusDocklet object is not a widget, it is just an abstract
GTK+ object. You create a new StatusDocklet object with status_docklet_new
or status_docklet_new and then bind the "build_plug" signal which is emitted
when the panel was contacted and a widget must be built. After binding the
"build_plug" signal, you call status_docklet_run to actually start trying to
contacting the panel. StatusDocklet is safe to use without a panel. By
default it will try to locate a panel for 15 minutes and after that it will
give up. It will also handle panel restarts by default. If it does, your
widget will be destroyed and "build_plug" will be emitted again when the new
panel starts. Even though the panel will never restart by itself, the user
might not run session management and thus might restart panel by hand, or due
to a bug, the panel might crash and restart itself.
Note that you should use gnome_CORBA_init rather then gnome_init when you
want to use the status docklet as corba has to be initialized for the status
docklet to work.
Here is a short example of how to use the status docklet
Example 1. Sample usage of the StatusDocklet object
/* this can be a global since you probably only need one status window
for your app */
GtkObject *status;
...
static void
build_our_plug(StatusDocklet *docklet, GtkWidget *plug, gpointer data)
{
GtkWidget *label;
/* an extremely simple status, you probably want an icon */
label = gtk_label_new("#");
gtk_widget_show(label);
/* add the status to the plug */
gtk_container_add(GTK_CONTAINER(plug), label);
}
...
/* in your main function you would do something like */
status = status_docklet_new();
/* connect our widget building function */
gtk_signal_connect(GTK_OBJECT(status), "build_plug",
GTK_SIGNAL_FUNC(build_our_plug),
NULL);
/* "run" the docklet */
status_docklet_run(STATUS_DOCKLET(status));
...
|
Details
struct StatusDocklet
struct StatusDocklet {
GtkWidget *plug; /* a pointer to the current GtkPlug
holding the docklet */
}; |
status_docklet_new ()
GtkObject* status_docklet_new (void); |
Creates a new status docklet object with the default
parameters. By default the docklet object will try to contact a panel
STATUS_DOCKLET_DEFAULT_RETRIES times (20). It will try to find a
panel every 15 seconds. You need to bind the build_plug signal
in which you build your own widget and add it to the provided container.
By default the docklet object will handle a panel restart, in which case
your widget will be destroyed and when the panel is contacted again the
build_plug signal will be emitted again. You also must call the
status_docklet_run function after you bind the build_plug signal.
status_docklet_new_full ()
GtkObject* status_docklet_new_full (int maximum_retries,
gboolean handle_restarts); |
Creates a neew status docklet object with the specified
parameters. See the description of status_docklet_new for details.
status_docklet_run ()
Search for the panel and add the plug if it finds it. This
function is also called internally from the timeout. If called externally
more times, a panel lookup will be forced and one try will be wasted. You
need to call this function at least once after binding the build_plug
signal to tell the status docklet to start looking for the panel.
If the status docklet handles restarts you don't have to call this
function ever again.
Signals
The "build-plug" signal
void user_function (StatusDocklet *statusdocklet,
gpointer arg1,
gpointer user_data); |
This signal is emitted when you actually need to build the widget that
you want to place inside the status docklet. It should be 22 by 22, and
if it is larger it will be cropped.