1<TITLE>panedwindow - Create and manipulate a paned window widget</TITLE> 2<H1>panedwindow - Create and manipulate a paned window widget</H1> 3 4</pre><H2>SYNOPSIS</H2> 5<B>panedwindow<I> <I>pathName </I>?<I>options</I>? 6</pre><H2>INHERITANCE</H2> 7itk::Widget <- panedwindow 8</pre><H2>STANDARD OPTIONS</H2> 9<P> 10<table cellpadding=5> 11<td valign=top> 12<B>background</B><br> 13</td> 14<td valign=top> 15<B>cursor</B><br> 16</td> 17<td valign=top> 18</td> 19<td valign=top> 20</td> 21</table> 22<P> 23See the <A HREF="http://www.sco.com/Technology/tcl/man/tk_man/options.n.html"> "options" </A> manual entry for details on the standard options. 24</pre><H2>WIDGET-SPECIFIC OPTIONS</H2> 25<P> 26<pre> 27Name: <B>height</B> 28Class: <B>Height</B> 29Command-Line Switch: <B>-height</B> 30</pre> 31<UL> 32Specifies the overall height of the paned window in any of the forms 33acceptable to <B>Tk_GetPixels</B>. The default is 10 pixels. 34</UL> 35<P> 36<pre> 37Name: <B>orient</B> 38Class: <B>Orient</B> 39Command-Line Switch: <B>-orient</B> 40</pre> 41<UL> 42Specifies the orientation of the separators: <B>vertical</B> or 43<B>horizontal</B>. The default is horizontal. 44</UL> 45<P> 46<pre> 47Name: <B>sashBorderWidth</B> 48Class: <B>BorderWidth</B> 49Command-Line Switch: <B>-sashborderwidth</B> 50</pre> 51<UL> 52Specifies a value indicating the width of the 3-D border to draw 53around the outside of the sash in any of the forms acceptable to 54<B>Tk_GetPixels</B>. The default is 2 pixels. 55</UL> 56<P> 57<pre> 58Name: <B>sashCursor</B> 59Class: <B>Cursor</B> 60Command-Line Switch: <B>-sashcursor</B> 61</pre> 62<UL> 63Specifies the type of cursor to be displayed in the sash. The default 64is crosshair. 65</UL> 66<P> 67<pre> 68Name: <B>sashHeight</B> 69Class: <B>Height</B> 70Command-Line Switch: <B>-sashheight</B> 71</pre> 72<UL> 73Specifies the height of the sash in any of the forms acceptable to 74<B>Tk_GetPixels</B>. The default is 10 pixels. 75</UL> 76<P> 77<pre> 78Name: <B>sashIndent</B> 79Class: <B>SashIndent</B> 80Command-Line Switch <B>sashindent</B> 81</pre> 82<UL> 83Specifies the placement of the sash along the panes in any of the forms 84acceptable to <B>Tk_GetPixels</B>. A positive 85value causes the sash to be offset from the near (left/top) side 86of the pane, and a negative value causes the sash to be offset from 87the far (right/bottom) side. If the offset is greater than the 88width, then the sash is placed flush against the side. The 89default is -10 pixels. 90</UL> 91<P> 92<pre> 93Name: <B>sashWidth</B> 94Class: <B>Width</B> 95Command-Line Switch: <B>-sashwidth</B> 96</pre> 97<UL> 98Specifies the width of the sash in any of the forms acceptable to 99<B>Tk_GetPixels</B>. The default is 10 pixels. 100</UL> 101<P> 102<pre> 103Name: <B>showHandle</B> 104Class: <B>ShowHandle</B> 105Command-Line Switch: <B>-showhandle</B> 106</pre> 107<UL> 108Specifies whether or not to display the sashes on the window panes. 109The default is 1, and valid options are 0 and 1. 110</UL> 111<P> 112<pre> 113Name: <B>thickness</B> 114Class: <B>Thickness</B> 115Command-Line Switch: <B>-thickness</B> 116</pre> 117<UL> 118Specifies the thickness of the separators in any of the forms acceptable to 119<B>Tk_GetPixels</B>. The default is 3 pixels. 120</UL> 121<P> 122<P> 123<pre> 124Name: <B>width</B> 125Class: <B>Width</B> 126Command-Line Switch: <B>-width</B> 127</pre> 128<UL> 129Specifies the overall width of the paned window in any of the forms 130acceptable to <B>Tk_GetPixels</B>. The default is 10 pixels. 131</UL> 132<P> 133</pre><HR> 134 135</pre><H2>DESCRIPTION</H2> 136<P> 137The <B>panedwindow</B> command creates a multiple paned window widget 138capable of orienting the panes 139either vertically or horizontally. Each pane is itself a frame acting 140as a child site for other widgets. The border separating each pane 141contains a sash which allows user positioning of the panes relative to 142one another. 143 144</pre><H2>METHODS</H2> 145<P> 146The <B>panedwindow</B> command creates a new Tcl command whose 147name is <I>pathName</I>. This 148command may be used to invoke various 149operations on the widget. It has the following general form: 150<pre> 151<I>pathName option </I>?<I>arg arg ...</I>? 152</pre> 153<I>Option</I> and the <I>arg</I>s 154determine the exact behavior of the command. 155<P> 156Many of the widget commands for the <B>panedwindow</B> take as one argument an 157indicator of which pane of the paned window to operate on. These indicators 158are called <I>indexes</I> and allow reference and manipulation of panes 159regardless of their current map state. Paned window indexes may be 160specified in any of the following forms: 161<DL> 162<DT> <I>number</I> 163</I></B> 164<DD> Specifies the pane numerically, where 0 corresponds to the nearest 165(top/left-most) pane of the paned window. 166</DL> 167<DL> 168<DT> <B>end</B> 169</I></B> 170<DD> Indicates the farthest (bottom/right-most) pane of the paned window. 171</DL> 172<DL> 173<DT> <I>pattern</I> 174</I></B> 175<DD> If the index doesn't satisfy one of the above forms then this 176form is used. <I>Pattern</I> is pattern-matched against the tag of 177each pane in the panedwindow, in order from left/top to right/left, 178until a matching entry is found. The rules of <B>Tcl_StringMatch</B> 179are used. 180 181</DL> 182</pre><H2>WIDGET-SPECIFIC METHODS</H2> 183<DL> 184<DT> <I>pathName <B>add</B> <I>tag</I> ?<I>option value option value</I>? 185</I></B> 186<DD> Adds a new pane to the paned window on the far side (right/bottom). The 187following options may be specified: 188</DL> 189<UL> 190<DL> 191<DT> <B>-margin</B> <I>value</I> 192</I></B> 193<DD> Specifies the border distance between the pane and pane contents is any of 194the forms acceptable to <B>Tk_GetPixels</B>. The default is 8 pixels. 195</DL> 196<DL> 197<DT> <B>-minimum</B> <I>value</I> 198</I></B> 199<DD> Specifies the minimum size that a pane's contents may reach not 200inclusive of twice the margin in any of the forms acceptable to 201<B>Tk_GetPixels</B>. The default is 10 pixels. 202 203The <B>add</B> method returns the path name of the pane. 204</DL> 205</UL> 206<DL> 207<DT> <I>pathName <B>cget</B> <I>option</I> 208</I></B> 209<DD> Returns the current value of the configuration option given 210by <I>option</I>. 211<I>Option</I> may have any of the values accepted by the <B>panedwindow</B> 212command. 213</DL> 214<DL> 215<DT> <I>pathName <B>childsite</B> ?<I>index</I>? 216</I></B> 217<DD> Returns a list of the child site path names or a specific child site given 218an index. The list is constructed from the near side (left/top) to the far 219side (right/bottom). 220</DL> 221<DL> 222<DT> <I>pathName</I> <B>configure</B> ?<I>option</I>? ?<I>value option value ...</I>? 223</I></B> 224<DD> Query or modify the configuration options of the widget. 225If no <I>option</I> is specified, returns a list describing all of 226the available options for <I>pathName</I> (see <B>Tk_ConfigureInfo</B> for 227information on the format of this list). If <I>option</I> is specified 228with no <I>value</I>, then the command returns a list describing the 229one named option (this list will be identical to the corresponding 230sublist of the value returned if no <I>option</I> is specified). If 231one or more <I>option-value</I> pairs are specified, then the command 232modifies the given widget option(s) to have the given value(s); in 233this case the command returns an empty string. 234<I>Option</I> may have any of the values accepted by the <B>panedwindow</B> 235command. 236</DL> 237<DL> 238<DT> <I>pathName <B>delete</B> <I>index</I> 239</I></B> 240<DD> Deletes a specified pane given an <I>index</I>. 241</DL> 242<DL> 243<DT> <I>pathName <B>fraction</B> <I>percentage</I> <I>percentage</I> ?<I>percentage percentage ...</I>? 244</I></B> 245<DD> Sets the visible percentage of the panes. Specifies a set of 246percentages which are applied to the visible panes from the near side 247(left/top). The number of percentages must be equal to the current number 248of visible (mapped) panes and add up to 100. 249</DL> 250<DL> 251<DT> <I>pathName <B>hide</B> <I>index</I> 252</I></B> 253<DD> Changes the visiblity of the specified pane, allowing a previously displayed 254pane to be visually removed rather than deleted. 255</DL> 256<DL> 257<DT> <I>pathName <B>index</B> <I>index</I> 258</I></B> 259<DD> Returns the numerical index corresponding to index. 260</DL> 261<DL> 262<DT> <I>pathName <B>insert <I>index</I> <I>tag</I> ?<I>option value option value ...</I>? 263</I></B> 264<DD> Same as the <B>add</B> command except that it inserts the new 265pane just before the one given by <I>index</I>, instead of appending 266to the end of the panedwindow. The <I>option</I>, and <I>value</I> 267arguments have the same interpretation as for the <B>add</B> widget 268command. 269</DL> 270<DL> 271<DT> <I>pathName <B>paneconfigure</B> <I>index</I> ?<I>options</I>? 272</I></B> 273<DD> This command is similar to the <B>configure</B> command, except that 274it applies to the options for an individual pane, whereas <B>configure</B> 275applies to the options for the paned window as a whole. 276<I>Options</I> may have any of the values accepted by the <B>add</B> 277widget command. If <I>options</I> are specified, options are modified 278as indicated in the command and the command returns an empty string. 279If no <I>options</I> are specified, returns a list describing 280the current options for entry <I>index</I> (see <B>Tk_ConfigureInfo</B> for 281information on the format of this list). 282</DL> 283<DL> 284<DT> <I>pathName <B>reset</B> 285</I></B> 286<DD> Redisplays the pane window using default percentages. 287</DL> 288<DL> 289<DT> <I>pathName <B>show</B> <I>index</I> 290</I></B> 291<DD> Changes the visiblity of the specified pane, allowing a previously hidden 292pane to be displayed. 293 294</DL> 295</pre><H2>NOTES</H2> 296<UL> 297Dynamic changing of the margin and or minimum options to values which 298make the current configuration invalid will block subsequent sash 299movement until the fractions are modified via the fraction method. 300For example a panedwindow is created with three panes and the minimum 301and margin options are at their default settings. Next the user moves 302the sashes to compact the panes to one side. Now, if the minimum is 303increased on the most compressed pane via the paneconfigure method to 304a large enough value, then sash movement is blocked 305until the fractions are adjusted. This situation is unusual and under 306normal operation of the panedwindow, this problem will never occur. 307</UL> 308<P> 309 310</pre><H2>EXAMPLE</H2> 311<pre> 312 panedwindow .pw -width 300 -height 300 313 .pw add top 314 .pw add middle -margin 10 315 .pw add bottom -margin 10 -minimum 10 316 317 pack .pw -fill both -expand yes 318 319 foreach pane [.pw childSite] { 320 button $pane.b -text $pane -relief raised -borderwidth 2 321 pack $pane.b -fill both -expand yes 322 } 323 324 .pw fraction 50 30 20 325 .pw paneconfigure 0 -minimum 20 326 .pw paneconfigure bottom -margin 15 327</pre> 328</pre><H2>ACKNOWLEDGEMENTS:</H2> 329<P> 330Jay Schmidgall 331<UL> 3321994 - Base logic posted to comp.lang.tcl 333</UL> 334<P> 335Joe Hidebrand <hildjj@fuentez.com> 336<UL> 33707/25/94 - Posted first multipane version to comp.lang.tcl 338</UL> 339<P> 340<UL> 34107/28/94 - Added support for vertical panes 342</UL> 343<P> 344Ken Copeland <ken@hilco.com> 345<UL> 34609/28/95 - Smoothed out the sash movement and added squeezable panes. 347</UL> 348<P> 349</pre><H2>AUTHOR</H2> 350Mark L. Ulferts 351</pre><H2>KEYWORDS</H2> 352panedwindow, widget 353