TIP: 18
Title: Add Labels to Frames
Version: $Revision: 2.3 $
Author: Peter Spjuth <[email protected]>
State: Final
Type: Project
Vote: Done
Created: 12-Dec-2000
Post-History:
Tcl-Version: 8.4
~ Abstract
This TIP proposes to add a labelled frame widget to Tk.
~ Introduction
Labelled frames are a common thing in a GUI and the need for them are
rather clear by the fact that practically every widget package
implements some version of it.
This proposal wants to add simple labelled frames to Tk. Even though a
labelled frame can be built by three frames and label,
this requires some skill and a bit work. I believe such a basic thing
should be easier and this change would make creating a labelled frame
as simple as it deserves to be.
Below is an example of what I mean with a labelled frame.
#image:18labframe Example of labelled frame
~ Specification
A new widget class, labelframe, is added. It works like a frame, with
the following changes.
These options are added:
-text: Standard option. Default value "".
-font: Standard option. Default value same as Label widget.
-fg: Standard option. Default value same as Label widget.
-labelwidget: Specify a widget to use as label. Default value "".
This option overrides any -text, -font and -fg setting. The widget
used must exist before using it as -labelwidget, and if it is not a
descendant of the frame it is automatically raised in the stacking
order to be visible.
-labelanchor: Sets where to place the label. Takes the values nw, n,
ne, en, e, es, se, s, sw, ws, w and wn, listing them clockwise.
Default value "nw".
-padx, -pady: Standard options. Adds some "air" between the border
and the interior of the frame. Default value 0.
These options changes default values:
-borderwidth, new default value 2.
-relief, new default value groove.
-padx and -pady are useful in frames and toplevels too, and since
it is easy and cheap to add them at the same time, this TIP proposes
to add them there too.
~ Rationale
My main approach has been to make a simple but still general
solution. The most typical usage should be really easy, more advanced usage
possible, and more features should be possible to add later if needed.
Trying to mimic all the abilities of a label widget is rather
futile. It leads to code duplication and future updates to the label
widget would need to be copied too to keep up. Since the most common label
is a simple text, the labelframe only mimics options -text, -font and -fg
to be able to handle that case in a simple manner. If you want a more
advanced label, e.g. with an image or with a checkbutton, you can get
it with -labelwidget.
For placement of the label I chose a style I found in IWidget's
"labeledframe" widget. It's the most general solution I can see since
it allows access to all twelve obvious positions in an easy way.
Options -padx and -pady does not have anything directly to do with
labels, but are a generally nice addition to frames that I
have missed a lot in the past. Such padding is not possible without
part of the changes to geometry management (see Implementing section)
that are required for displaying the label.
The thing about raising the -labelwidget in the stacking order comes
from this:
With the most simple implementation, using -labelwidget could be done
in two ways:
|# Way #1
|labelframe .f
|label .f.l -text Mupp
|.f configure -labelwidget .f.l
|# Way #2
|label .l -text Mupp
|labelframe .f -labelwidget .l
|raise .l .f
In the first you want the label to be a child but since it has to
exist, the -labelwidget can't be used on the labelframe creation line.
In the second you try to circumvent it by creating the label first,
but then you have to raise it above the labelframe to be visible.
Even though it's just one extra line of code I find it a bit awkward
when it's so easy to do something about. The first can be fixed by
not trying to do anything with the label widget until idle time when
it has had a chance to be created. This is not a good solution though
since it leads to some rather awkward things in implementation. The
second can be fixed by automatically raising the label in the stacking
order when used as -labelwidget. If this is documented clearly I
don't have a problem with it, and that is why I chose it.
~ Alternatives to this TIP
An alternative way to implement a labelled frame is using mega widget
style with a subframe where children are placed. This is how current
widget packages do it. I think that is an awkward and unnatural way
to handle such a simple thing as a labelled frame. The only reason
to do so is that current limitations in geometry management prevents
a simpler solution.
I believe that a labelled frame should work like a normal frame. That
it displays a label should not matter more than displaying a border
or a blue background. A labelled frame megawidget would be different
from a frame, the most noticeable difference being that you can't
pack/grid things directly into the labelled frame,
instead you have to go via a subframe. Having the labelled frame work
like a normal frame is more consistent and easier for the programmer
at Tcl level.
~ Implementing
Implementing this is mostly rather straightforward. The labelframe
will share most code with the frame, just like toplevel and frame
share code today, and like the spinbox was built on the entry. The
tricky part is that limitations in geometry management does not
leave room for displaying a label. The changes needed in geometry
management are simple but introduces a slight backward incompatibility.
The problem is this. Today a widget can set an internal border
width. This defines a uniform width area around the edge of the
widget that geometry managers should stay away from. This is not enough
though, since to display a label the frame needs to get more space on
one side where it will put the label. Also, there is no way for a widget
to affect its own size (anything it says is overridden by pack/grid), so
the labelframe cannot make sure that enough size is requested to make
room for the label.
By adding some more fields to the TkWindow structure, the
information needed can be transferred to the geometry manager.
First, the present internalBorderWidth field is split into
four fields, one for each side.
Second, minimum requested width/height fields are added.
This requires one macro per field for reading them and
two new APIs to set the fields:
|void Tk_SetInternalBorderWidthEx(tkwin, left, right, top, bottom)
|void Tk_SetMinimumRequestedSize(tkwin, minWidth, minHeight)
Geometry managers would need to be updated to take the new fields
into consideration, and here is where backwards compatibility comes
in. Any extension implementing a geometry manager would need to be
updated in the same way as grid/pack/place will be. The change is
trivial, and even if not done most things will work anyway. An
updated Tk plus an old extension plus an old script will still
work and thus no one needs to worry about upgrading.
I consider this a minor thing since it wont break any existing
applications. The only thing that will break is if someone would try
to use a geometry manager that is not updated within a labelframe. And
even in that case you can work around it with an extra frame.
~ Rejected alternatives
The ability to display a label could have been given to the normal
frame by adding the options above to it. Having a new widget class
has the following advantages:
The separate widget class can have its own default values, and the
user can control it separately from the frame in the option database.
The normal frame does not need to store all the new options, thus
saving memory.
For handling of geometry management, some other solutions was regarded.
Instead of splitting the internalBorderWidth in four, an alternative
is just adding two fields. One pointing at a side and one telling how
much extra border to put on that side. This only saves one field
and is less general. For example, it is not possible to implement -padx
and -pady with this one.
A more complex solution using callbacks which was featured in revision
1.1 of this TIP has also been discarded because it was too complex.
It would be possible to do without the minimum requested size fields
if you give the responsibility to make sure the label has room to
the GUI programmer. This could be rather awkward though, e.g. when
making an internationalized application where labels can vary a lot.
~ Reference Implementation
An almost finished implementation exists, and it's just a matter of
polishing the last bits to create a patch for this proposal if it
is accepted.
At http://www.dtek.chalmers.se/~d1peter/labframe.tcl you can find a
pure Tcl demo of labelled frames. Even though it uses sub-frames and
thus do not live up to what I want to accomplish here it implements
all new options as specified here and can be played with if you want
to know more.
~ Copyright
This document has been placed in the public domain.