Documentation always lies: GNOME Panel Applet edition

The GNOME Panel Applet Library Reference Manual mentions the following about the panel_applet_set_size_hints function:

Set a list of desired size ranges for an applet with the PANEL_APPLET_EXPAND_MAJOR flags set.

This is a lie. The applet must also have the PANEL_APPLET_HAS_HANDLE flag set; otherwise, the applet will not display after you call the function.

Why? panel_applet_set_size_hints packages its arguments up in a Bonobo (i.e., CORBA) message and sends them to the PanelAppletFrame object that manages the space allocated to the applet in the panel. They eventually find their way to the following internal function, which is supposed to do the actual setting of the size hints:

static void
panel_applet_frame_set_size_hints_from_any (PanelAppletFrame *frame,
                                            const CORBA_any  *any)
        CORBA_sequence_CORBA_long *seq;
        int                       *size_hints;
        int                        extra_size;
        int                        i;
        seq = any->_value;
        size_hints = g_new0 (int, seq->_length);
        if (frame->priv->has_handle) {
                extra_size = HANDLE_SIZE + 1;
                for (i = 0; i < seq->_length; i++)
                        size_hints [i] = seq->_buffer [i] + extra_size;
        panel_widget_set_applet_size_hints (frame->priv->panel,
                                            GTK_WIDGET (frame),

This function is supposed to set up the size_hints array with the list of hints that you originally passed to panel_applet_set_size_hints. However, it only populates the array if the applet has a handle — i.e., if it has the PANEL_APPLET_HAS_HANDLE flag set. If it doesn’t, the array stays initialized to all zeros, which the panel is for some reason perfectly OK with. Now your applet is guaranteed to be exactly 0 pixels in size, and thus invisible.

This is really a bug in the GNOME Panel, since it should handle the case where there isn’t a handle. (No pun intended.) Since the two applets shipped with GNOME that set size hints both use handles, apparently nobody noticed until now. I’ll file a bug tomorrow about this.

Remember kids, the moral is: trust the source code, not the documentation.