The GNOME Panel Libraries
<<< Previous Page | Home | Up |

# StatusDocklet

## Name

StatusDocklet -- Simple way to embed a small window in the panel

## Synopsis

    #include <status-docklet.h>

    struct      StatusDocklet;
    GtkObject*  status_docklet_new              (void);
    GtkObject*  status_docklet_new_full         (int maximum_retries,
                                                 gboolean handle_restarts);
    void        status_docklet_run              (StatusDocklet *docklet);

## Object Hierarchy

      GtkObject
       +----StatusDocklet

## Signal Prototypes

    "build-plug"
                void        user_function      (StatusDocklet *statusdocklet,
                                                gpointer arg1,
                                                gpointer user_data);

## 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 */

    };

GtkWidget *`plug` | The GtkPlug widget that's embedded inside the panel

### 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.

Returns : | new status docklet object.

### 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.

`maximum_retries` : | Maximum number of times to try to contact panel
`handle_restarts` : | If you handle panel restarts
Returns : | a new docklet object

### status_docklet_run ()

    void        status_docklet_run              (StatusDocklet *docklet);

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.

`docklet` : | StatusDocklet to run

## 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.

`statusdocklet` : | the object which received the signal.
`arg1` : |
`user_data` : | user data set when the signal handler was connected.

## See Also

AppletWidget, GtkPlug

<<< Previous Page | Home | Up |
GNOME Status Docklet Library |