iwidgets::panedwindow - Create and manipulate a paned window widget

       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.

       Mark L. Ulferts

       The iwidgets::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.

        package require Iwidgets 4.0
        iwidgets::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

       itk::Widget <- iwidgets::Panedwindow

       panedwindow, widget

Tk                                                                                      iwidgets::panedwindow(1)

       The iwidgets::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: pathNameoption ?argarg...?  Option and the args determine the exact behavior of the command.

       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.

       iwidgets::panedwindow - Create and manipulate a paned window widget

              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.

backgroundcursor

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

iwidgets::panedwindowpathName ?options?

pathNameaddtag ?optionvalueoptionvalue?
              Adds  a new pane to the paned window on the far side (right/bottom).  The following options may be
              specified:

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

              -minimumvalue
                     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.

       pathNamecgetoption
              Returns the current value of the configuration option given by option.  Option may have any of the
              values accepted by the iwidgets::panedwindow command.

       pathNamechildsite ?index?
              Returns a list of the child site path names or a specific child site given an index.  The list  is
              constructed from the near side (left/top) to the far side (right/bottom).

       pathNameconfigure ?option? ?valueoptionvalue...?
              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
              iwidgets::panedwindow command.

       pathNamedeleteindex
              Deletes a specified pane given an index.

       pathNamefractionpercentagepercentage ?percentagepercentage...?
              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.

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

       pathNameindexindex
              Returns the numerical index corresponding to index.

       pathNameinsertindextag ?optionvalueoptionvalue...?
              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.

       pathNamepaneconfigureindex ?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).

       pathNamereset
              Redisplays the pane window using default percentages.

       pathNameshowindex
              Changes the visiblity of the specified pane, allowing a previously hidden pane to be displayed.

       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 positive 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:           showHandle
       Class:          ShowHandle
       Command-Line Switch:           -showhandle

              Specifies  whether  or not to display the sashes on the window panes.  The default is 1, and valid
              options are 0 and 1.

       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.

________________________________________________________________________________________________________________