| TIP: | 41 |
| Title: | Paned Window Tk Widget |
| Version: | $Revision: 1.13 $ |
| Author: | Eric Melski <ericm at interwoven dot com> |
| State: | Final |
| Type: | Project |
| Tcl-Version: | 8.4a2 |
| Vote: | Done |
| Created: | Wednesday, 04 July 2001 |
| Keywords: | widget, tk, panedwindow |
This TIP proposes a C-based paned window widget for inclusion in the Tk core. A paned window consists of one or more vertical or horizontal "panes", each pair separated by a movable "sash" and each containing one widget, called a "slave". Paned windows are common in modern graphical user interfaces and should therefore be provided directly by the Tk core. Examples of the widget can be found in Windows Explorer; Netscape Messenger; many email clients; and virtually every graphical World Wide Web browser.
Tk has long lagged other graphical toolkits in terms of the selection of widgets provided by the toolkit. In order to keep Tk vibrant, useful, and relevant, it is imperative that the widget set be enhanced with widgets which have become commonplace in modern graphical user interfaces. One such widget is the paned window widget. A widget that makes it easy to create robust paned windows should be included with Tk.
This paned window widget could be implemented in C or in Tcl; in fact, several Tcl-based paned window widgets already exist. However, these each have quirks, mostly caused by the inability to completely manage the geometry of Tk windows from Tcl (i.e. there is no way to make calls to things like Tk_MaintainGeometry or Tk_ManageGeometry). This issue could possibly be addressed by the creation of a proper megawidget system for Tk, but that goal seems very far from reality right now. If we wait for that system before creating new widgets, it may be too late. In addition, megawidget implementations suffer from "widget bloat" - each paned window widget corresponds to, typically two widgets, plus two or more widgets for each pane after the first. For a Motif-style paned window with two panes, this means five widgets are created (one frame for the paned window container widget; one frame for each pane; one frame for the sash; one frame for the sash handle). Even assuming the existence of a proper megawidget system, we may not be able to address the widget bloat issue with a megawidget.
A C-based paned window implementation will be able to address both of these issues, and should be more robust, reliable, and lightweight. A C implementation will be able to access Tk's geometry management functions. Also, it will require only one widget for each paned window, regardless of how many panes are in the window.
One obvious argument is that this widget could easily be distributed as an extension, and need not be included directly in the Tk core. However, extension widget libraries have been largely unsuccessful in winning over users. Developers are reluctant to use those extension widgets because they cannot rely on their presence in an end-user's system, and because of concerns of version incompatibilities between the extension and the core. Users are reluctant to take on the responsibility of maintaining the extension in addition to the core. If this widget is to be truly useful to the Tk community and not just a programming exercise for the author, it must be included in the Tk core.
In addition, Tk should be a full-featured widget toolkit on its own. Other popular GUI toolkits are ready out-of-the-box to create sophisticated, modern applications. Tk should be as well, and should not require the procurement of additional extensions to provide what are truly fundamental widgets in a modern GUI toolkit. By all means, esoteric widgets should be left to the extensions, but core widgets belong in the core. This question could be made irrelevant with the introduction of a proper "Batteries Included" distribution, but like the proper megawidget system, this seems like a goal far from reality at this time.
Another possibility is to distribute the widget with the core, but have it placed in a separate package and namespace. This provides the same level of availability as direct inclusion in the core, but does not actually make the widget part of Tk directly. There are two possible arguments in favor of this approach. First, since this widget will be in its own namespace, future panedwindow widgets could be included without name conflicts. However, if each widget is put in its own namespace, the name conflict has not actually been resolved. The point of contention has simply been moved from the global command space to the global namespace space. Namespaces make sense when grouping blocks of related functions and data, but widgets have only one command. It's just as easy to pick a unique command name as a unique namespace name. The second possible advantage is that the widget could be loaded on demand, rather than automatically being pulled in with Tk. However, most machines that Tk runs on use a virtual memory system. Thus, only those pages/widgets that are actually used will be resident in memory. The benefit of incorporating this widget into the Tk distribution in this manner seem marginal.
The manual entry for the paned window widget is included here:
NAME
panedwindow - Create and manipulate panedwindow widgets
SYNOPSIS
panedwindow pathName ?options?
STANDARD OPTIONS
-background -height -width
-borderwidth -orient
-cursor -relief
See the options manual entry for details on the standard
options.
WIDGET-SPECIFIC OPTIONS
Command-Line Name:-handlepad
Database Name: handlePad
Database Class: HandlePad
When sash handles are drawn, specifies the distance
from the top or left end of the sash (depending on
the orientation of the widget) at which to draw the
handle. May be any value accepted by Tk_GetPixels.
Command-Line Name:-handlesize
Database Name: handleSize
Database Class: HandleSize
Specifies the side length of a sash handle. Han-
dles are always drawn as squares. May be any value
accepted by Tk_GetPixels.
Command-Line Name:-opaqueresize
Database Name: opaqueResize
Database Class: OpaqueResize
Specifies whether panes should be resized as a sash
is moved (true), or if resizing should be deferred
until the sash is placed (false).
Command-Line Name:-sashcursor
Database Name: sashCursor
Database Class: SashCursor
Mouse cursor to use when over a sash. If null,
sb_h_double_arrow will be used for horizontal
panedwindows, and sb_v_double_arrow will be used
for vertical panedwindows.
Command-Line Name:-sashpad
Database Name: sashPad
Database Class: SashPad
Specifies the amount of padding to leave of each
side of a sash. May be any value accepted by
Tk_GetPixels.
Command-Line Name:-sashrelief
Database Name: sashRelief
Database Class: SashRelief
Relief to use when drawing a sash. May be any of
the standard Tk relief values.
Command-Line Name:-sashwidth
Database Name: sashWidth
Database Class: SashWidth
Specifies the width of each sash. May be any value
accepted by Tk_GetPixels.
Command-Line Name:-showhandle
Database Name: showHandle
Database Class: ShowHandle
Specifies whether or not sash handles should be shown.
May be any valid Tcl boolean value.
DESCRIPTION
The panedwindow command creates a new window (given by the
pathName argument) and makes it into a panedwindow widget.
Additional options, described above, may be specified on
the command line or in the option database to configure
aspects of the panedwindow such as its default background
color and relief. The panedwindow command returns the
path name of the new window.
A panedwindow widget contains any number of panes,
arranged horizontally or vertically, according to the
value of the -orient option. Each pane contains one wid-
get, and each pair of panes is separated by a moveable
(via mouse movements) sash. Moving a sash causes the wid-
gets on either side of the sash to be resized.
WIDGET COMMAND
The panedwindow command creates a new Tcl command whose
name is the same as the path name of the panedwindow's
window. This command may be used to invoke various opera-
tions on the widget. It has the following general form:
pathName option ?arg arg ...?
PathName is the name of the command, which is the same as
the panedwindow widget's path name. Option and the args
determine the exact behavior of the command. The follow-
ing commands are possible for panedwindow widgets:
pathName add slave ?slave ...? ?option value ...?
Add one or more slaves to the panedwindow, each in
a separate pane. The arguments consist of the
names of one or more slave windows followed by
pairs of arguments that specify how to manage the
slaves. Option may have any of the values accepted
by the configure subcommand.
pathName cget option
Returns the current value of the configuration
option given by option. Option may have any of the
values accepted by the panedwindow command.
pathName configure ?option? ?value option value ...?
Query or modify the configuration options of the
widget. If no option is specified, returns a list
describing all of the available options for path-
Name (see Tk_ConfigureInfo for information on the
format of this list). If option is specified with
no value, then the command returns a list describ-
ing the one named option (this list will be identi-
cal to the corresponding sublist of the value
returned if no option is specified). If one or
more option-value pairs are specified, then the
command modifies the given widget option(s) to have
the given value(s); in this case the command
returns an empty string. Option may have any of the
values accepted by the panedwindow command.
pathName forget slave ?slave ...?
Remove the pane containing slave from the panedwin-
dow. All geometry management options for slave
will be forgotten.
pathName identify x y
Identify the panedwindow component underneath the
point given by x and y, in window coordinates. If
the point is over a sash or a sash handle, the
result is a two element list containing the index
of the sash or handle, and a word indicating
whether it is over a sash or a handle, such as {0
sash} or {2 handle}. If the point is over any
other part of the panedwindow, the result is an
empty list.
pathName proxy ?args?
This command is used to query and change the posi-
tion of the sash proxy, used for rubberband-style
pane resizing. It can take any of the following
forms:
pathName proxy coord
Return a list containing the x and y coordi-
nates of the most recent proxy location.
pathname proxy forget
Remove the proxy from the display.
pathName proxy place x y
Place the proxy at the given x and y
coordinates.
pathName sash ?args?
This command is used to query and change the posi-
tion of sashes in the panedwindow. It can take any
of the following forms:
pathName sash coord index
Return the current x and y coordinate pair
for the sash given by index. Index must be
an integer between 0 and 1 less than the
number of slaves in the panedwindow. The
coordinates given are those of the top left
corner of the region containing the sash.
pathName sash dragto index x y This command
computes the difference between the given
coordinates and the coordinates given to the
last sash coord command for the given sash.
It then moves that sash the computed differ-
ence. The return value is the empty string.
pathName sash mark index x y
Records x and y for the sash given by index;
used in conjunction with later dragto com-
mands to move the sash.
pathName sash place index x y
Place the sash given by index at the given
coordinates.
pathName slavecget slave option
Query a management option for slave. Option may be
any value allowed by the slaveconfigure subcommand.
pathName slaveconfigure slave ?option? ?value option value
...?
Query or modify the management options for slave.
If no option is specified, returns a list describ-
ing all of the available options for pathName (see
Tk_ConfigureInfo for information on the format of
this list). If option is specified with no value,
then the command returns a list describing the one
named option (this list will be identical to the
corresponding sublist of the value returned if no
option is specified). If one or more option-value
pairs are specified, then the command modifies the
given widget option(s) to have the given value(s);
in this case the command returns an empty string.
The following options are supported:
-after slave
Insert the slave after the slave specified.
slave should be the name of a window already
managed by pathName.
-before slave
Insert the slave before the slave specified.
slave should be the name of a window already
managed by pathName.
-height size
Specify a height for the slave. The height
will be the outer dimension of the slave
including its border, if any. If size is an
empty string, or if -height is not speci-
fied, then the height requested internally
by the slave will be used initially; the
height may later be adjusted by the movement
of sashes in the panedwindow. Size may be
any value accepted by Tk_GetPixels.
-minsize n
Specifies that the size of the slave cannot
be made less than n. This constraint only
affects the size of the widget in the paned
dimension -- the x dimension for horizontal
panedwindows, the y dimension for vertical
panedwindows. May be any value accepted by
Tk_GetPixels.
-padx n
Specifies a non-negative value indicating
how much extra space to leave on each side
of the slave in the X-direction. The value
may have any of the forms accepted by
Tk_GetPixels.
-pady n
Specifies a non-negative value indicating
how much extra space to leave on each side
of the slave in the Y-direction. The value
may have any of the forms accepted by
Tk_GetPixels.
-sticky style
If a slave's pane is larger than the
requested dimensions of the slave, this
option may be used to position (or stretch)
the slave within its pane. Style is a
string that contains zero or more of the
characters n, s, e or w. The string can
optionally contains spaces or commas, but
they are ignored. Each letter refers to a
side (north, south, east, or west) that the
slave will "stick" to. If both n and s (or
e and w) are specified, the slave will be
stretched to fill the entire height (or
width) of its cavity.
-width size
Specify a width for the slave. The width
will be the outer dimension of the slave
including its border, if any. If size is an
empty string, or if -width is not specified,
then the width requested internally by the
slave will be used initially; the width may
later be adjusted by the movement of sashes
in the panedwindow. Size may be any value
accepted by Tk_GetPixels.
pathName slaves
Returns an ordered list of the widgets managed by
pathName.
RESIZING PANES
A pane is resized by grabbing the sash (or sash handle if
present) and dragging with the mouse. This is accom-
plished via mouse motion bindings on the widget. When a
sash is moved, the sizes of the panes on each side of the
sash, and thus the widgets in those panes, are adjusted.
When a pane is resized from outside (eg, it is packed to
expand and fill, and the containing toplevel is resized),
space is added to the final (rightmost or bottommost) pane
in the window.
The widget described here has already been implemented, with documentation and a full test suite. The widget is included with the Vu widget extension, part of the tktable SourceForge project at http://tktable.sourceforge.net
Suggestions for possible future enhancements:
Allow specification of a weight for each pane, similar to the -weight option supported by grid, to be used when allocating space from a resize to panes in the widget.
Allow a bindable image to be placed on the window sash, a la Netscape's Messenger, or Java Swing, to allow one-click expand and collapse of the pane.
Integrate with the -setgrid option such that if a pane contains a -setgrided widget, the sash can only be moved in grid size steps.
None of these are prohibited by the current design, and could be implemented at a later date as enhancements to the widget.
This document has been placed in the public domain.
[Index] [History] [HTML Format] [Source Format] [LaTeX Format] [Text Format] [XML Format] [*roff Format (experimental)] [RTF Format (experimental)]