[incr Widgets] - panedwindow manpage





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: verti­
              cal 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

              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  nega­
              tive  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 pix­
              els.

       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.


       The  panedwindow  command  creates a new Tcl command whose
       name is pathName.  This command may be used to invoke var­
       ious  operations on the widget.  It has the following gen­
       eral 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  win­
       dow  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 corre­
                   sponds  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 pat­
                   tern-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 spec­
              ified:

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

              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 available options  for  path­
              Name  (see  Tk_ConfigureInfo for information on the
              format of this list).  If option is specified  with
              no  value, then the command returns a list describ­
              ing the one named option (this list will be identi­
              cal  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.  Speci­
              fies 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, allow­
              ing  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.

              This  command  is similar to the configure command,
              except that it applies to the options for an  indi­
              vidual  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 wid­
              get command.  If options are specified, options are
              modified  as  indicated in the command and the com­
              mand 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 percent­
              ages.

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



NOTES

              Dynamic  changing  of  the  margin  and  or minimum
              options to values which make the current configura­
              tion  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

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


























Man(1) output converted with man2html