Teaching an old widget a new trick ;-)

[Deon Ramsey <ramsey dfki uni-kl de>]

Hello everyone, appended below is the README for a patch I've been developing 
the
last while. It adds some new functionality to gtk's togglebuttons, so, the 1.0
funtionality freezeout being set, I don't expect it to be accepted, even though
I'm of the opinion that it's something that is necessary for not only the 
toolkit,
but gimp1.0 . However, I've decided to put it on the gtk site anyhow so that 
people can try it out and give me feedback for when I resubmit it after the
freezeout. Look for the patch itself under the name: 
gtk-draco-980313-0.patch.gz
og ftp.gimp.org . Hope you like it, bye

Deon Ramsey

-------------------------------------------------------------------------------
-

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:
<A HREF="http://www.dfki.uni-kl.de/~ramsey/">Deon Ramsey</A>

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