This patch is slightly large, so I'll give the reasons for doing it before the actual patch, and some data about what it's new functionality and how it was implemented, as well as things to beware of to prevent code from malfunctioning when using this functionality. If those don't interest you, skip to the section named 'Changes' to see what the patch itself does. 1. Motivation The toggle buttons and subclassed widgets are good ways to let the user choose between two or more alternatives, but it is sometimes hard to see whether a button is active or not, and also, whether a button being active/inactive means for instance 'editing is enabled' or 'editing is disabled', it was even easy for a programmer to mix up the way he had intended to mean these and implement them the other way around. Especially on low color or bw screens, it is almost impossible to make out the state of the button. In checking the sources, I found that gtk didn't have a basic mechanism for something that most other widget toolkits have: The ability to change the labels depending on state. It was of course possible to add this functionality in the application, however this kind of gets around the basic theory of having a library to do these things for you. I decided to add this functionality to gtk, and in the spirit of gtk, add it in such a way that not just labels, but whole widgets may be provided for display that change depending on the state of the gadget. 2. Implementation Since it proved possible to add this functionality in a totally 'downward com- patible' way, I changed the GtkToggleButton class, along with it's two sub- classes to add the functionality, but act *exactly* the same as before, as long as none of the new functionality is made use of. As long as labels/widgets are supplied for only the inactive state, the widgets will show these whether active or not, and in fact, the application code may stay exactly the same. As soon as an active widget is supplied, the widgets will starts showing their state by switching between the widgets until such time as the active widget is removed, then it's back to the same old behavior as before. Internally, the implementation was simple, I added two member variables to the GtkToggleButton class' structure that hold pointers to the inactive and active widgets (reffed to prevent their suddenly disappearing on me :-), and changed the gtk_toggle_button_toggled method to swap between the two widgets when appropriate. To prevent the widget from resizing every time a button was hit, I also changed the requisition/allocation routines to use the maximum of both widget's sizes (provided there *is* an active widgets, otherwise, things are computed as before). Note that this may lead to children widgets getting size_requisition calls even if they're not visible. In order to take advantage of the new functionality, new creation methods were provided (and the old creation methods changed transparently to use the newer ones where appropriate, though always keeping the same behavior), and two new calls were provided to change the active/inactive labels, and the add/ remove calls inherited from the Button class were overridden to work properly with the new functionality. Finally, I added documentation for the new calls to the texinfo files, and modified testgtk to use my new functionality. Don't you agree that this makes it easier to see what the tree widget example is set to at a glance ? 3. Caveats (or how to change code depending on the old behavior) If you are simply using these widgets, your code can stay quite the same as before, though I highly recommend replacing every call to gtk_(toggle|check|radio)_button_new_with_label (widget, label) with the newer gtk_(toggle|check|radio)_button_new_with_labels (widget, label_inac, label_ac) to take advantage of the new functionality. If you subclassed a widget class off of the toggle/check/radio button classes, they will continue to work, provided you either didn't provide your own size requisition/allocation, add/remove and toggled methods, or you overrode them properly by calling the superclass methods for that inside your own methods. You may want to add new gtk_yourclass_new_with_labels () methods to enable application programmers to easily make use of the new functionality (you may see how to do this easily and transparently in the GtkCheckButton's implemen- tation of this method), it is however not necessary that you do so. If you *did* override the said methods without calling the parent's methods, you'll have to change your code, or strange things may happen. Please *do* call your parent class' methods when overriding them if at all possible, it's only good Object-Oriented programming style. The only other problem with your classes that may pop up is if any widget classes' size requisition/allocation methods assume that they are currently visible, which may not be the case anymore. 4. Todo I plan to add support for the gtk_*_[gs]et_arg() functionality, as soon as I figure out just exactly how it works ;-) Is there any reason that gtkbutton.c provides only a get call, not a set call ? I may add (in|)active_widget_set signals to the class to alert programs when a button's widget was changed. I'm not exactly sure whether this is necessary though, most of the time, a program will already know, right ? For reasons I don't quite understand yet, the box classes seem to add a single pixel's padding to a togglebutton's origin after it is first clicked, I'm still tracing that, but I decided it's not important enough to prevent me from showing my work to others. I'll be sending patches as soon as I figure it out. 5. Changes The following files are changed by this patch: -gtk/gtktogglebutton.[ch] : Adds the functionality as outlined above. -gtk/gtkcheckbutton.[ch] : A few changes to correctly function with the new functionality, in particular to creation and allocation. -gtk/gtkradiobutton.[ch] : Added new creation methods, and changed 'toggled' to use it's parent's toggled routine instead of doing it all right there (and thus missing the new functionality). -docs/gtk.texi : All new calls and functionality documented (as well as adding some definitions and data to make the documentation on toggle/check/ radiobuttons complete). There is also one small bug-fix for a misnamed section heading. Unfortunately, I don't have access to the CVS tree, so the changes may not patch properly against it (Hope this isn't too much of a problem, you should have no problem integrating the two). It *will* patch correctly against the gtk+-0.99.5 gtk.texi though. -gtk/testgtk.c : Modified several gadgets to make use of the new functionality. In particular, have a look at togglebuttons themselves, where you may see that the widget switching doesn't just work for labels, but also for general widgets (I use pixmap widget to show this). Also have a look at the tree widgets, where one can see immediately how the changes make it easy to see what state the program is in (and not just see whether the button is up or down). The patch was generated against gtk+-0.99.5 as distributed on ftp://ftp.gimp.org Enjoy Deon Ramsey (Draco) ----------------------------------------------------------------------------- Deon Ramsey (general Librarygopher) may be reached as: Work: Private: dfkidok@dfki.uni-kl.de ramsey@rhrk.uni-kl.de WWW: Deon Ramsey Or via Snail-Mail: Deon Ramsey Koenigstr. 11 67655 Kaiserslautern Germany Program (Pro'-gram) n. A magic spell cast over a computer, causing it to turn one's input into error messages. There are many intelligent species in the Universe. They are all owned by cats. Be discreet, be polite, but be yourself. -- Per Aspera