\documentclass[]{article}
\usepackage{amsmath,graphicx,supertabular,hyperref,tabularx,ifthen}
\title{TIP \#41: Paned Window Tk Widget}
\date{July 04, 2001}
\author{Eric Melski}
\urlstyle{sf}
\setlength{\parskip}{1ex}
\setlength{\parindent}{0pt}
\def\tipversion$#1${\texttt{\$#1\$}}
\def\tiplangle#1{\ensuremath{<}}
\def\tiprangle#1{\ensuremath{>}}
\def\tipbar#1{\ensuremath{|}}
\def\tipmail#1#2{\(\langle\){\small\expandafter\url{#1@#2}}\(\rangle\)}
\ifx\pdfoutput\undefined
\newcommand{\tipimage}[2]{\typeout{Make sure you download #1.eps}\ifthenelse{\lengthtest{0.8\textwidth>#2}\and\lengthtest{0pt<#2}}{\includegraphics{#1.eps}}{\includegraphics[width=0.8\textwidth]{#1.eps}}}
\newcommand{\tipxref}[1]{}
\newcommand{\tipxrefend}{}
\else
\newcommand{\tipimage}[2]{\typeout{Make sure you create #1.pdf}\ifthenelse{\lengthtest{0.8\textwidth>#2}\and\lengthtest{0pt<#2}}{\includegraphics{#1.pdf}}{\includegraphics[width=0.8\textwidth]{#1.pdf}}}
\pdfcatalog{/PageMode /UseOutlines}
\newcommand{\tipxref}[1]{\pdfannotlink attr {/C [0.5 0.5 1.0] /Border [0 0 1]} goto name {#1}}
\newcommand{\tipxrefend}{\pdfendlink}
\fi
\newenvironment{tipabstract}{\begin{abstract}}{\end{abstract}}
\begin{document}\maketitle
\begin{center}\begin{tabularx}{\linewidth}{|r@{: }X|}\hline
\textbf{TIP \#41}&\textbf{Paned Window Tk Widget}\\\hline
Author&

Eric Melski \tipmail{ericm}{interwoven.com}
\\
Created&Wednesday, \(\text{4}^{\text{th}}\) July 2001\\
Type&Project\\
Tcl Version&\(8.4\alpha2\)\\
State&Final\\
Vote&Done\\
Version&\tipversion$Revision: 1.13 $\\
Keywords&widget, tk, panedwindow\\
Post History&\\
\hline\end{tabularx}\end{center}
\thispagestyle{empty}\pagestyle{empty}
\begin{tipabstract}

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.
\end{tipabstract}
\tableofcontents\setcounter{page}{0}\clearpage\pagestyle{plain}

\section{Rationale}

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 \textit{Tk\_MaintainGeometry} or \textit{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.

\begin{figure}[htbp]\begin{center}\leavevmode
\tipimage{41example}{218pt}
\caption{Example Panedwindow Widget}
\end{center}\end{figure}

\section{Specification}

The manual entry for the paned window widget is included here:
\begingroup\small\begin{verbatim}
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.
\end{verbatim}
\endgroup

\section{Reference Implementation}

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 \textit{tktable} SourceForge project at \url{http://tktable.sourceforge.net}

\section{Notes}

Suggestions for possible future enhancements:
\begin{itemize}
\item{}
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.
\item{}
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.
\item{}
Integrate with the -setgrid option such that if a pane contains a -setgrided widget, the sash can only be moved in grid size steps.
\end{itemize}

None of these are prohibited by the current design, and could be implemented at a later date as enhancements to the widget.

\section{Copyright}

This document has been placed in the public domain.

\section{Colophon}

\textit{TIP AutoGenerator --- written by Donal K. Fellows}
\end{document}
