Provided by: tk8.5-doc_8.5.19-3_all bug

NAME

       panedwindow - Create and manipulate panedwindow widgets

SYNOPSIS

       panedwindow pathName ?options?

STANDARD OPTIONS

       -background           -borderwidth         -cursor
       -orient               -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.  Handles are always drawn as squares.
              May be any value accepted by Tk_GetPixels.

       Command-Line Name:-height
       Database Name:  height
       Database Class: Height

              Specifies a desired height for the overall panedwindow widget.  May  be  any  value
              accepted  by  Tk_GetPixels. If an empty string, the widget will be made high enough
              to allow all contained widgets to have their natural height.

       Command-Line Name:-proxybackground
       Database Name:  proxyBackground
       Database Class: ProxyBackground

              Background color to use when drawing the proxy. If an empty string,  the  value  of
              the -background option will be used.

       Command-Line Name:-proxyborderwidth
       Database Name:  proxyBorderWidth
       Database Class: ProxyBorderWidth

              Specifies the borderwidth of the proxy. May be any value accepted by Tk_GetPixels.

       Command-Line Name:-proxyrelief
       Database Name:  proxyRelief
       Database Class: ProxyRelief

              Relief  to use when drawing the proxy. May be any of the standard Tk relief values.
              If an empty string, the value of the -sashrelief option will be used.

       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 sash handles should be shown.   May  be  any  valid  Tcl  boolean
              value.

       Command-Line Name:-width
       Database Name:  width
       Database Class: Width

              Specifies  a  desired  width  for  the overall panedwindow widget. May be any value
              accepted by Tk_GetPixels. If an empty string, the widget will be made  wide  enough
              to allow all contained widgets to have their natural width.
_________________________________________________________________________________________________

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  widget,  and  each
       pair of panes is separated by a moveable (via mouse movements) sash.  Moving a sash causes
       the widgets 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 operations 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 following
       commands are possible for panedwindow widgets:

       pathName add window ?window ...? ?option value ...?
              Add one or more windows to the panedwindow, each in a separate pane.  The arguments
              consist  of  the  names  of one or more windows followed by pairs of arguments that
              specify how to manage the windows.  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 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. Option may have any of
              the values accepted by the panedwindow command.

       pathName forget window ?window ...?
              Remove the pane containing window from the panedwindow.   All  geometry  management
              options for window 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 position 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 coordinates 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 position 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 panes 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 mark command for the given sash.  It then
                     moves  that  sash  the  computed  difference.  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
                     sash dragto commands to move the sash.

              pathName sash place index x y
                     Place the sash given by index at the given coordinates.

       pathName panecget window option
              Query  a  management  option  for  window.   Option may be any value allowed by the
              paneconfigure subcommand.

       pathName paneconfigure window ?option? ?value option value ...?
              Query or modify the management options for window.   If  no  option  is  specified,
              returns  a  list  describing  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 window
                     Insert the window after the window specified.  window should be the name  of
                     a window already managed by pathName.

              -before window
                     Insert the window before the window specified.  window should be the name of
                     a window already managed by pathName.

              -height size
                     Specify a height for the window.  The height will be the outer dimension  of
                     the  window including its border, if any.  If size is an empty string, or if
                     -height is not specified, then the height requested internally by the window
                     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.

              -hide boolean
                     Controls the visibility of a pane.  When the boolean is true  (according  to │
                     Tcl_GetBoolean)  the  pane  will  not  be  visible,  but  it  will  still be │
                     maintained in the list of panes.

              -minsize n
                     Specifies that the size of the window 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 window 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 window in the Y-direction.  The value may have any  of  the
                     forms accepted by Tk_GetPixels.

              -sticky style
                     If  a  window's  pane is larger than the requested dimensions of the window,
                     this option may be used to position (or stretch) the window 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 window will “stick” to.  If both n and s (or e and w) are specified, the
                     window will be stretched to fill the entire height (or width) of its cavity.

              -stretch when
                     Controls  how extra space is allocated to each of the panes.  When is one of │
                     always, first, last, middle, and never.  The panedwindow will calculate  the │
                     required  size  of  all  its panes. Any remaining (or deficit) space will be │
                     distributed to  those  panes  marked  for  stretching.  The  space  will  be │
                     distributed based on each panes current ratio of the whole.  The when values │
                     have the following definition:                                               │

                     always                                                                       │
                            This pane will always stretch.                                        │

                     first                                                                        │
                            Only if this pane is the first pane (left-most or top-most)  will  it │
                            stretch.                                                              │

                     last                                                                         │
                            Only  if  this pane is the last pane (right-most or bottom-most) will │
                            it stretch.  This is the default value.                               │

                     middle                                                                       │
                            Only if this pane is not the first or last pane will it stretch.      │

                     never                                                                        │
                            This pane will never stretch.                                         │

              -width size
                     Specify a width for the window.  The width will be the  outer  dimension  of
                     the  window including its border, if any.  If size is an empty string, or if
                     -width is not specified, then the width requested internally by  the  window
                     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 panes
              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  accomplished  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  (e.g.  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.

       Unlike  slave  windows managed by e.g. pack or grid, the panes managed by a panedwindow do
       not change width or height to accomodate changes in the requested widths or heights of the
       panes,  once  these  have become mapped.  Therefore it may be advisable, particularly when
       creating layouts interactively, to not add a pane to the panedwindow  widget  until  after
       the  geometry  requests  of that pane has been finalized (i.e., all components of the pane
       inserted, all options affecting geometry set to their proper values, etc.).

SEE ALSO

       ttk::panedwindow(3tk)

KEYWORDS

       panedwindow, widget, geometry management