# iwidgets2.2.0 User Commands - panedwindow

##

## NAME

         panedwindow - Create and manipulate a paned window widget

## SYNOPSIS

         panedwindow pathName ?options?

## INHERITANCE

         itk::Widget <- panedwindow

## STANDARD OPTIONS

         background      cursor

         See the "options" manual entry for details on  the  standard
         options.

## WIDGET-SPECIFIC OPTIONS

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

              Specifies the overall height of the paned window in any
              of  the  forms acceptable to Tk_GetPixels.  The default
              is 10 pixels.

         Name:           orient
         Class:          Orient
         Command-Line Switch:           -orient

              Specifies the orientation of the  separators:  vertical
              or horizontal.  The default is horizontal.

         Name:           sashBorderWidth
         Class:          BorderWidth
         Command-Line Switch:           -sashborderwidth

              Specifies a value  indicating  the  width  of  the  3-D
              border to draw around the outside of the sash in any of
              the forms acceptable to Tk_GetPixels.  The default is 2
              pixels.

         Name:           sashCursor
         Class:          Cursor
         Command-Line Switch:           -sashcursor

              Specifies the type of cursor to  be  displayed  in  the
              sash.  The default is crosshair.

         Name:           sashHeight
         Class:          Height
         Command-Line Switch:           -sashheight
              Specifies the height of the sash in any  of  the  forms
              acceptable to Tk_GetPixels.  The default is 10 pixels.

         Name:           sashIndent
         Class:          SashIndent
         Command-Line Switch            sashindent

              Specifies the placement of the sash along the panes  in
              any  of  the forms acceptable to Tk_GetPixels.  A posi-
              tive value causes the sash to be offset from  the  near
              (left/top)  side  of  the  pane,  and  a negative value
              causes  the  sash   to   be   offset   from   the   far
              (right/bottom) side.  If the offset is greater than the
              width, then the sash is placed flush against the  side.
              The default is -10 pixels.

         Name:           sashWidth
         Class:          Width
         Command-Line Switch:           -sashwidth

              Specifies the width of the sash in  any  of  the  forms
              acceptable to Tk_GetPixels.  The default is 10 pixels.

         Name:           thickness
         Class:          Thickness
         Command-Line Switch:           -thickness

              Specifies the thickness of the separators in any of the
              forms  acceptable  to  Tk_GetPixels.   The default is 3
              pixels.

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

              Specifies the overall width of the paned window in  any
              of  the  forms acceptable to Tk_GetPixels.  The default
              is 10 pixels.

##

## DESCRIPTION

         The panedwindow command  creates  a  multiple  paned  window
         widget  capable  of orienting the panes either vertically or
         horizontally.  Each pane is itself a frame acting as a child
         site  for  other  widgets.   The border separating each pane
         contains a sash which allows user positioning of  the  panes
         relative to one another.

## METHODS

         The panedwindow command creates a new Tcl command whose name
         is  pathName.   This  command  may be used to invoke various
         operations on the widget.   It  has  the  following  general
         form:

              pathName option ?arg arg ...?

         Option and the args determine the exact behavior of the com-
         mand.

         Many of the widget commands for the panedwindow take as  one
         argument  an  indicator of which pane of the paned window to
         operate on.  These indicators are called indexes  and  allow
         reference  and  manipulation  of  panes  regardless of their
         current map state.  Paned window indexes may be specified in
         any of the following forms:

         number      Specifies  the   pane   numerically,   where   0
                     corresponds  to the nearest (top/left-most) pane
                     of the paned window.

         end         Indicates the farthest (bottom/right-most)  pane
                     of the paned window.

         pattern     If the index doesn't satisfy one  of  the  above
                     forms  then  this  form  is  used.   Pattern  is
                     pattern-matched against the tag of each pane  in
                     the  panedwindow,  in  order  from  left/top  to
                     right/left, until a  matching  entry  is  found.
                     The rules of Tcl_StringMatch are used.

## WIDGET-SPECIFIC METHODS

         pathName add tag ?option value option value?
              Adds a new pane to the paned window  on  the  far  side
              (right/bottom).   The  following  options may be speci-
              fied:

              -margin value
                   Specifies the border distance between the pane and
                   pane  contents  is  any of the forms acceptable to
                   Tk_GetPixels.  The default is 8 pixels.

              -minimum value
                   Specifies the minimum size that a pane's  contents
                   may reach not inclusive of twice the margin in any
                   of the  forms  acceptable  to  Tk_GetPixels.   The
                   default is 10 pixels.

                   The add method returns the path name of the pane.

         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 childsite ?index?
              Returns a list of  the  child  site  path  names  or  a
              specific  child  site given an index.  The list is con-
              structed from the near side (left/top) to the far  side
              (right/bottom).

         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  correspond-
              ing  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 delete index
              Deletes a specified pane given an index.

         pathName fraction percentage  percentage  ?percentage  percentage
              Sets  the visible percentage of the panes.  Specifies a
              set of percentages which are  applied  to  the  visible
              panes  from  the  near  side (left/top).  The number of
              percentages must be equal  to  the  current  number  of
              visible (mapped) panes and add up to 100.

         pathName hide index
              Changes the visiblity of the specified pane, allowing a
              previously displayed pane to be visually removed rather
              than deleted.

         pathName index index
              Returns the numerical index corresponding to index.

         pathName insert index tag ?option value option value ...?
              Same as the add command except that it inserts the  new
              pane  just  before  the  one given by index, instead of
              appending to the end of the panedwindow.   The  option,
              and value arguments have the same interpretation as for
              the add widget command.

         pathName paneconfigure index ?options?
              This command  is  similar  to  the  configure  command,
              except that it applies to the options for an individual
              pane, whereas configure applies to the options for  the
              paned  window  as a whole.  Options may have any of the
              values accepted by the add widget command.  If  options
              are specified, options are modified as indicated in the
              command and the command returns an empty string.  If no
              options  are  specified,  returns a list describing the
              current options for entry index  (see  Tk_ConfigureInfo
              for information on the format of this list).

         pathName reset
              Redisplays the pane window using default percentages.

         pathName show index
              Changes the visiblity of the specified pane, allowing a
              previously hidden pane to be displayed.

## NOTES

              Dynamic changing of the margin and or  minimum  options
              to  values which make the current configuration invalid
              will block subsequent sash movement until the fractions
              are  modified  via  the fraction method.  For example a
              panedwindow is created with three panes and the minimum
              and margin options are at their default settings.  Next
              the user moves the sashes to compact the panes  to  one
              side.   Now,  if  the  minimum is increased on the most
              compressed pane via the paneconfigure method to a large
              enough  value,  then sash movement is blocked until the
              fractions are adjusted.  This situation is unusual  and
              under normal operation of the panedwindow, this problem
              will never occur.

## EXAMPLE

               panedwindow .pw -width 300 -height 300
               .pw add top
               .pw add middle -margin 10
               .pw add bottom -margin 10 -minimum 10

               pack .pw -fill both -expand yes

               foreach pane [.pw childSite] {
                  button $pane.b -text $pane -relief raised -borderwidth 2
                  pack $pane.b -fill both -expand yes
               }

               .pw fraction 50 30 20
               .pw paneconfigure 0 -minimum 20
               .pw paneconfigure bottom -margin 15

## ACKNOWLEDGEMENTS:

         Jay Schmidgall

              1994 - Base logic posted to comp.lang.tcl

         Joe Hidebrand <hildjj@fuentez.com>

              07/25/94  -   Posted   first   multipane   version   to
              comp.lang.tcl

              07/28/94 - Added support for vertical panes

         Ken Copeland <ken@hilco.com>

              09/28/95 - Smoothed out the  sash  movement  and  added
              squeezable panes.

## AUTHOR

         Mark L. Ulferts

## KEYWORDS

         panedwindow, widget