Provided by: iwidgets4-doc_4.1.1-2.1_all bug

NAME

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

SYNOPSIS

       iwidgets::panedwindow pathName ?options?

INHERITANCE

       itk::Widget <- iwidgets::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 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.

_________________________________________________________________________________________________

DESCRIPTION

       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.

METHODS

       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: pathName option ?arg arg ...?  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.

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 specified:

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

       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

        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

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