gtk_toggle_button_set_mode

[John Sullivan <sullivan eazel com>]

I stumbled across this function when reading the toggle button API
documentation. The name "set_mode" is completely information-free. The
description of the function is baffling:

    void  gtk_toggle_button_set_mode (GtkToggleButton *toggle_button,
                                      gboolean draw_indicator);

    Determines whether or not the toggle button is drawn on screen.
    The default mode is FALSE, which results in the button being
    displayed. To make the button invisible, set draw_indicator
    to TRUE.


I couldn't figure out why such a function would exist (leaving aside the
matter of its meaningless name and confusingly-named parameter), so I
searched the GTK+ sources and found the only callers in gtktoolbar.c.
Toggleable or one-from-many toolbar items use this call so that they can
maintain on/off state in a gtk_toggle_button widget without actually showing
the widget (they draw differently based on the state of the widget instead).

Did I get this right? Is this toolbar code (which feels like a hack) the
only reason for the existence of this call? Is it too late to change this
design, or at least change the name of the function to something like
gtk_toggle_button_set_invisible ()? (Which brings up the issue of why
gtk_widget_hide () wasn't used in the toolbar code in the first place --
maybe so gtk_widget_show_all () could be used conveniently?)

I mostly just want to understand this, but I also think it's extremely
confusing as is and should be improved in the future if possible.

John