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