ABCDEFGHIJKLMNOPQRSTUVWXYZ

panedwindow

panedwindow(1)                  [incr Widgets]                  panedwindow(1)



______________________________________________________________________________

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  hori-
              zontal.  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:           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  path-
       Name.   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 indi-
       cators 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/bot-
              tom).  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 pix-
                     els.

                     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 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 avail-
              able 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 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 previ-
              ously 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  previ-
              ously 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  subse-
              quent  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



Tk                                                              panedwindow(1)