tix/man/PanedWin.n

   1 '\"
   2 '\" Copyright (c) 1996, Expert Interface Technologies
   3 '\"
   4 '\" See the file "license.terms" for information on usage and redistribution
   5 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
   6 '\"
   7 '\" The file man.macros and some of the macros used by this file are
   8 '\" copyrighted: (c) 1990 The Regents of the University of California.
   9 '\"              (c) 1994-1995 Sun Microsystems, Inc.
  10 '\" The license terms of the Tcl/Tk distrobution are in the file
  11 '\" license.tcl.
  12 .so man.macros
  13 '----------------------------------------------------------------------
  14 .HS tixPanedWindow tix 4.0
  15 .BS
  16 '
  17 '
  18 '----------------------------------------------------------------------
  19 .SH NAME
  20 tixPanedWindow \- Create and manipulate tixPanedWindow widgets
  21 '
  22 '----------------------------------------------------------------------
  23 .SH SYNOPSIS
  24 \fBtixPanedWindow\fI \fIpathName ?\fIoptions\fR?
  25 '
  26 '----------------------------------------------------------------------
  27 .SH "STANDARD OPTIONS"
  28 '
  29 The PanedWindow widget supports all the standard options of a frame
  30 widget. See the \fBoptions(n)\fR manual entry for details on the
  31 standard options.
  32 '
  33 '----------------------------------------------------------------------
  34 .SH "WIDGET-SPECIFIC OPTIONS"
  35 '
  36 '----------BEGIN
  37 .LP
  38 .nf
  39 '
  40 Name:           \fBcommand\fR
  41 Class:          \fBCommand\fR
  42 Switch:         \fB\-command\fR
  43 '
  44 .fi
  45 .IP
  46 '
  47 Specifies the command to invoke when the panes change their sizes.
  48 This command is called with a list of integers that record the new
  49 sizes of the panes. The sizes of the panes are listed in the order of
  50 the panes' creation.
  51 '----------END
  52 '
  53 '----------BEGIN
  54 .LP
  55 .nf
  56 Name:           \fBdynamicGeometry\fR
  57 Class:          \fBDynamicGeometry\fR
  58 Switch:         \fB\-dynamicgeometry\fR
  59 .fi
  60 .IP
  61 '
  62 If set to true, the size of the PanedWindow will dynamically change
  63 if the size of any of its panes changes. Otherwise, the size of the
  64 PanedWindow will only increase when size of any of its panes changes
  65 and will not decrease. The default value is true.
  66 '----------END
  67 '
  68 '----------BEGIN
  69 .LP
  70 .nf
  71 '
  72 Name:           \fBhandleActiveBg\fR
  73 Class:          \fBHandleActiveBg\fR
  74 Switch:         \fB\-handleactivebg\fR
  75 '
  76 .fi
  77 .IP
  78 '
  79 Specifies the active background color of the resize handles. When the
  80 mouse cursor enters a resize handle, the resize handle will adopt
  81 the active background color.
  82 '----------END
  83 '
  84 '
  85 '----------BEGIN
  86 .LP
  87 .nf
  88 '
  89 Name:           \fBhandleBg\fR
  90 Class:          \fBBackground\fR
  91 Switch:         \fB\-handlebg\fR
  92 '
  93 .fi
  94 .IP
  95 '
  96 Specifies the normal background color of the resize handles.
  97 '----------END
  98 '
  99 '----------BEGIN
 100 .LP
 101 .nf
 102 Name:           \fBheight\fR
 103 Class:          \fBHeight\fR
 104 Switch:         \fB\-height\fR
 105 .fi
 106 .IP
 107 Specifies the desired height for the window.
 108 '----------END
 109 '
 110 '----------BEGIN
 111 .LP
 112 .nf
 113 Name:           \fBorientation\fR
 114 Class:          \fBOrientation\fR
 115 Switch:         \fB\-orientation\fR
 116 Alias:          \fB\-orient\fR
 117 .fi
 118 .IP
 119 Specifies the orientation of the panes. Must be either \fBvertical\fR
 120 or \fBhorizontal\fR.
 121 '----------END
 122 '
 123 '----------BEGIN
 124 .LP
 125 .nf
 126 Name:           \fBpaneBorderWidth\fR
 127 Class:          \fBPaneBorderWidth\fR
 128 Switch:         \fB\-paneborderwidth\fR
 129 Alias:          \fB\-panebd\fR
 130 .fi
 131 .IP
 132 Specifies the border width of the panes.
 133 '----------END
 134 '
 135 '----------BEGIN
 136 .LP
 137 .nf
 138 Name:           \fBpaneRelief\fR
 139 Class:          \fBPaneRelief\fR
 140 Switch:         \fB\-panerelief\fR
 141 .fi
 142 .IP
 143 Specifies the border relief of the panes.
 144 '----------END
 145 '
 146 '----------BEGIN
 147 .LP
 148 .nf
 149 '
 150 Name:           \fBseparatorActiveBg\fR
 151 Class:          \fBSeparatorActiveBg\fR
 152 Switch:         \fB\-separatoractivebg\fR
 153 '
 154 .fi
 155 .IP
 156 '
 157 Specifies the active background color of the separators. When the user
 158 grabs a resize handle, the separators
 159 will adopt the active background color.
 160 '----------END
 161 '
 162 '----------BEGIN
 163 .LP
 164 .nf
 165 '
 166 Name:           \fBseparatorBg\fR
 167 Class:          \fBBackground\fR
 168 Switch:         \fB\-separatorbg\fR
 169 '
 170 .fi
 171 .IP
 172 '
 173 Specifies the normal background color of the separators.
 174 '----------END
 175 '
 176 '
 177 '----------BEGIN
 178 .LP
 179 .nf
 180 Name:           \fBwidth\fR
 181 Class:          \fBWidth\fR
 182 Switch:         \fB\-width\fR
 183 .fi
 184 .IP
 185 Specifies the desired width for the window.
 186 '----------END
 187 '----------------------------------------------------------------------
 188 .SH SUBWIDGETS
 189 .PP
 190 '
 191 All the pane subwidgets created as a result of the \fBadd\fR command
 192 can be accessed by the \fBsubwidget\fR command. They are identified by
 193 the \fBpaneName\fR parameter to the \fBadd\fR command.
 194 '
 195 .BE
 196 '
 197 '----------------------------------------------------------------------
 198 .SH DESCRIPTION
 199
 200 .PP
 201 '
 202 The \fBtixPanedWindow\fR command creates a new window (given by the
 203 \fIpathName\fR argument) and makes it into a PanedWindow widget.
 204 Additional options, described above, may be specified on the command
 205 line or in the option database to configure aspects of the
 206 PanedWindow widget such as its cursor and relief.
 207 '
 208 .PP
 209 '
 210 The PanedWindow widget allows the user to interactively manipulate the
 211 sizes of several panes. The panes can be arranged either vertically or
 212 horizontally. Each individual pane may have upper and lower limits of
 213 its size. The user changes the sizes of the panes by dragging the
 214 resize handle between two panes.
 215 '
 216 '----------------------------------------------------------------------
 217 .SH "WIDGET COMMAND"
 218 '
 219 .PP
 220 '
 221 The \fBtixPanedWindow\fR command creates a new Tcl command whose name is
 222 the same as the path name of the PanedWindow widget's window.  This
 223 command may be used to invoke various operations on the widget.  It
 224 has the following general form:
 225 '
 226 .DS C
 227 '
 228 \fIpathName option \fR?\fIarg arg ...\fR?
 229 .PP
 230 '
 231 .DE
 232 '
 233 \fIPathName\fR is the name of the command, which is the same as the
 234 frame widget's path name. \fIOption\fR and the \fIarg\fRs determine
 235 the exact behavior of the command.  The following commands are
 236 possible for PanedWindow widgets:
 237 '
 238 .TP
 239 '
 240 \fIpathName \fBadd\fI paneName \fR?\fIoption value ...\fR?
 241 '
 242 Adds a new pane subwidget with the name \fIpaneName\fR into the
 243 PanedWindow widget. Additional configuration options can be
 244 given to configure the new button subwidget. Three configuration
 245 options are supported:
 246 .RS
 247 '
 248 .TP
 249 \fB\-after\fR \fIpane\fR
 250 '
 251 Specifies that the new pane should be placed after \fIpane\fR in the
 252 list of panes in this PanedWindow widget.
 253 '
 254 \fB\-at\fR \fIinteger\fR
 255 '
 256 Specifies the position of the new pane in the list of panes in this
 257 PanedWindow widget. \fB0\fR means the first position, \fB1\fR means
 258 the second, and so on. In addition, \fBend\fR means the end of the
 259 list.
 260 '
 261 .TP
 262 \fB\-before\fR \fIpane\fR
 263 '
 264 Specifies that the new pane should be placed before \fIpane\fR in the
 265 list of panes in this PanedWindow widget.
 266 '
 267 .TP
 268 \fB\-expand\fR \fIfactor\fR
 269 '
 270 Specifies the \fBexpand/shrink factor\fR of this pane. \fIFactor\fR
 271 must be a non-negative floating point number. The default value is
 272 0.0. The expand/shrink factor is used to calculate how much each pane
 273 should grow or shrink when the size of the PanedWindow main window is
 274 changed. When the main window expands/shrinks by \fIn\fR pixels, then
 275 pane \fIi\fR will grow/shrink by about \fIn * factor(i) /
 276 summation(factors)\fR, where \fIfactor(i)\fR is the expand/shrink
 277 factor of pane i and \fIsummation(factors)\fR is the summation of the
 278 expand/shrink factors of all the panes. If \fIsummation(factors)\fR is
 279 0.0, however, only the last visible pane will be grown or shrunk.
 280 '
 281 .TP
 282 \fB\-min\fR \fIinteger\fR
 283 '
 284 Specifies the minimum size, in pixels, of the new pane; the default is 0.
 285 '
 286 .TP
 287 \fB\-max\fR \fIinteger\fR
 288 Specifies the maximum size, in pixels, of the new pane; the default is 10000.
 289 '
 290 .TP
 291 \fB\-size\fR \fIinteger\fR
 292 Specifies the size, in pixels, of the new pane; if the \fB\-size\fR
 293 option is not given, or set to the empty string, the PanedWindow
 294 widget will use the natural size of the pane subwidget.
 295 '
 296 .RE
 297 '
 298 .TP
 299 \fIpathName \fBcget\fR \fIoption\fR
 300 '
 301 Returns the current value of the configuration option given by
 302 \fIoption\fR. \fIOption\fR may be \fB\-min\fR, \fB\-max\fR and/or
 303 \fB\-size\fR, or any option accepted by the Tk frame widget.
 304 '
 305 .TP
 306 '
 307 \fIpathName \fBconfigure\fR ?\fIoption\fR? \fI?value option value ...\fR?
 308 '
 309 Query or modify the configuration options of the widget.  If no
 310 \fIoption\fR is specified, returns a list describing all of the
 311 available options for \fIpathName\fR (see \fBTk_ConfigureInfo\fR for
 312 information on the format of this list).  If \fIoption\fR is specified
 313 with no \fIvalue\fR, then the command returns a list describing the
 314 one named option (this list will be identical to the corresponding
 315 sublist of the value returned if no \fIoption\fR is specified).  If
 316 one or more \fIoption\-value\fR pairs are specified, then the command
 317 modifies the given widget option(s) to have the given value(s); in
 318 this case the command returns an empty string. \fIOption\fR may be any
 319 of the non-static options of the PanedWindow widget.
 320 '
 321 .TP
 322 \fIpathName \fBdelete\fR \fIpaneName\fR
 323 '
 324 Removes the pane given by \fIpaneName\fR and deletes its contents.
 325 '
 326 .TP
 327 \fIpathName \fBforget\fR \fIpaneName\fR
 328 '
 329 Removes the pane given by \fIpaneName\fR but does not delete its
 330 contents. This pane can be later added back to the PanedWindow widget
 331 by the \fBmanage\fR method.
 332 '
 333 .TP
 334 \fIpathName \fBmanage\fR \fIpaneName \fR?\fIoption value ...\fR?
 335 '
 336 Adds the pane given by \fIpaneName\fR back to the PanedWindow widget.
 337 \fIPaneName\fR must be already forgotten by the \fBforget\fR
 338 method. Additional \fIoption-value\fR pairs, same as those accepted by
 339 the \fBadd\fR method, can be given to control the appearance and
 340 position of the pane.
 341 '
 342 .TP
 343 \fIpathName \fBpanecget\fR \fIpaneName option\fR
 344 '
 345 Returns the current value of the configuration option given by
 346 \fIoption\fR in the pane given by \fIpaneName\fR. \fIOption\fR may
 347 have any of the values accepted by the \fBadd\fR widget command.
 348 '
 349 .TP
 350 '
 351 \fIpathName \fBpaneconfigure\fI paneName ?\fIoption\fR? \fI?value ...\fR?
 352 '
 353 '
 354 When no option is given, prints out the values of all options of this
 355 pane. If \fIoption\fR is specified with no \fIvalue\fR, then the
 356 command returns the current value of that option. If one or more
 357 \fIoption\-value\fR pairs are specified, then the command modifies the
 358 given pane's option(s) to have the given value(s); in this case the
 359 command returns an empty string. \fIOption\fR may be \fB\-min\fR,
 360 \fB\-max\fR and/or \fB\-size\fR, or any option accepted by the Tk
 361 frame widget. The sizes of the panes may be changed as a result of
 362 calling the \fBpaneconfigure\fR command.
 363 '
 364 .TP
 365 \fIpathName \fBpanes\fR
 366 '
 367 Returns a list of the names of all panes.
 368 '
 369 .TP
 370 \fIpathName \fBsetsize\fR \fIpaneName newSize\fR ?\fIdirection\fR?
 371 '
 372 Sets the size of the pane specified by \fIpaneName\fR to
 373 \fInewSize\fR. The \fIdirection\fR parameter specifies in which
 374 direction the pane should grow/shrink. Possible values are \fBnext\fR:
 375 the pane will grow or shrink by moving the boundary between itself and
 376 the pane to its right or bottom; \fBprev\fR: the pane will grow or
 377 shrink by moving the boundary between itself and the pane to its left
 378 or top.
 379 '
 380 .TP
 381 \fIpathName \fBsubwidget \fI name ?args?\fR
 382 '
 383 When no options are given, returns the pathname of the subwidget of
 384 the specified name.
 385
 386 When options are given, the widget command of the specified subwidget will
 387 be called with these options.
 388 '
 389 '----------------------------------------------------------------------
 390 .SH BINDINGS
 391 '
 392 The panes' sizes will be changed when the user drags the handles. The
 393 change in the panes' sizes may be subjected to the \fB\-min\fR,
 394 \fB\-max\fR and \fB\-size\fR options of the panes.
 395 '
 396 '
 397 '----------------------------------------------------------------------
 398 .SH KEYWORDS
 399 '
 400 TIX, Container Widget