1<TITLE>selectionbox - Create and manipulate a selection box widget</TITLE> 2<H1>selectionbox - Create and manipulate a selection box widget</H1> 3 4</pre><H2>SYNOPSIS</H2> 5<B>selectionbox<I> <I>pathName </I>?<I>options</I>? 6</pre><H2>INHERITANCE</H2> 7itk::Widget <- selectionbox 8</pre><H2>STANDARD OPTIONS</H2> 9<P> 10<table cellpadding=5> 11<td valign=top> 12<B>activeBackground</B><br> 13<B>exportSelection</B><br> 14<B>insertBackground</B><br> 15<B>insertWidth</B><br> 16<B>selectBackground</B><br> 17</td> 18<td valign=top> 19<B>background</B><br> 20<B>foreground</B><br> 21<B>insertBorderWidth</B><br> 22<B>relief</B><br> 23<B>selectBorderWidth</B><br> 24</td> 25<td valign=top> 26<B>borderWidth</B><br> 27<B>highlightColor</B><br> 28<B>insertOffTime</B><br> 29<B>repeatDelay</B><br> 30<B>selectForeground</B><br> 31</td> 32<td valign=top> 33<B>cursor</B><br> 34<B>highlightThickness</B><br> 35<B>insertOnTime</B><br> 36<B>repeatInterval</B><br> 37</td> 38</table> 39<P> 40See 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. 41</pre><H2>ASSOCIATED OPTIONS</H2> 42<P> 43<table cellpadding=5> 44<td valign=top> 45<B>textBackground</B><br> 46</td> 47<td valign=top> 48<B>textFont</B><br> 49</td> 50<td valign=top> 51</td> 52<td valign=top> 53</td> 54</table> 55<P> 56See the <A HREF="entryfield.n.html"> "entryfield" </A> widget class manual entry for details on the above 57associated options. 58<P> 59<table cellpadding=5> 60<td valign=top> 61<B>labelFont</B><br> 62</td> 63<td valign=top> 64<B>labelMargin</B><br> 65</td> 66<td valign=top> 67</td> 68<td valign=top> 69</td> 70</table> 71<P> 72See the <A HREF="labeledwidget.n.html"> "labeledwidget" </A> class manual entry for details on the above 73associated options. 74<P> 75<table cellpadding=5> 76<td valign=top> 77<B>activeRelief</B><br> 78</td> 79<td valign=top> 80<B>elementBorderWidth</B><br> 81</td> 82<td valign=top> 83<B>jump</B><br> 84</td> 85<td valign=top> 86<B>troughColor</B><br> 87</td> 88</table> 89<P> 90See the <A HREF="http://www.sco.com/Technology/tcl/man/tk_man/scrollbar.n.html"> "scrollbar" </A> widget class manual entry for details on the above 91associated options. 92<P> 93<table cellpadding=5> 94<td valign=top> 95<B>dblClickCommand</B><br> 96<B>textBackground</B><br> 97</td> 98<td valign=top> 99<B>hscrollMode</B><br> 100<B>textFont</B><br> 101</td> 102<td valign=top> 103<B>sbWidth</B><br> 104<B>vscrollMode</B><br> 105</td> 106<td valign=top> 107<B>scrollMargin</B><br> 108</td> 109</table> 110<P> 111See the <A HREF="scrolledlistbox.n.html"> "scrolledlistbox" </A> widget class manual entry for details on the above 112associated options. 113 114</pre><H2>WIDGET-SPECIFIC OPTIONS</H2> 115<P> 116<pre> 117Name: <B>childSitePos</B> 118Class: <B>Position</B> 119Command-Line Switch: <B>-childsitepos</B> 120</pre> 121<UL> 122Specifies the position of the child site in the selection box: <B>n</B>, 123<B>s</B>, <B>e</B>, <B>w</B>, or <B></B>. The default is center 124</UL> 125<P> 126<pre> 127Name: <B>height</B> 128Class: <B>Height</B> 129Command-Line Switch: <B>-height</B> 130</pre> 131<UL> 132Specifies the height of the selection box. The value may be specified in 133any of the forms acceptable to Tk_GetPixels. The default is 320 pixels. 134</UL> 135<P> 136<pre> 137Name: <B>itemsCommand</B> 138Class: <B>Command</B> 139Command-Line Switch: <B>-itemscommand</B> 140</pre> 141<UL> 142Specifies a command to be evaluated following selection of an item. 143</UL> 144<P> 145<pre> 146Name: <B>itemsLabel</B> 147Class: <B>Text</B> 148Command-Line Switch: <B>-itemslabel</B> 149</pre> 150<UL> 151Specifies the text of the label for the items list. The default is "List". 152</UL> 153<P> 154<pre> 155Name: <B>itemsLabelPos</B> 156Class: <B>Position</B> 157Command-Line Switch: <B>-itemslabelpos</B> 158</pre> 159<UL> 160Specifies the position of the label along the side of the items 161list: <B>n</B>, <B>ne</B>, <B>e</B>, <B>se</B>, <B>s</B>, <B>sw</B>, <B>w</B>, 162or <B>nw</B>. The default is nw. 163</UL> 164<P> 165<pre> 166Name: <B>itemsOn</B> 167Class: <B>ItemsOn</B> 168Command-Line Switch: <B>-itemson</B> 169</pre> 170<UL> 171Specifies whether or not to display the items list in any 172of the forms acceptable to <B>Tcl_GetBoolean</B>. The default is true. 173</UL> 174<P> 175<pre> 176Name: <B>margin</B> 177Class: <B>Margin</B> 178Command-Line Switch: <B>-margin</B> 179</pre> 180<UL> 181Specifies distance between the items list and selection entry in any of 182the forms acceptable to <B>Tk_GetPixels</B>. The default is 7 pixels. 183</UL> 184<P> 185<pre> 186Name: <B>selectionCommand</B> 187Class: <B>Command</B> 188Command-Line Switch: <B>-selectioncommand</B> 189</pre> 190<UL> 191Specifies a Tcl procedure to be associated with a return key press event 192in the selection entry field. 193</UL> 194<P> 195<pre> 196Name: <B>selectionLabel</B> 197Class: <B>Text</B> 198Command-Line Switch: <B>-selectionlabel</B> 199</pre> 200<UL> 201Specifies the text of the label for the selection entry field. The default 202is "Selection". 203</UL> 204<P> 205<pre> 206Name: <B>selectionLabelPos</B> 207Class: <B>Position</B> 208Command-Line Switch: <B>-selectionlabelpos</B> 209</pre> 210<UL> 211Specifies the position of the label along the side of the selection: 212<B>n</B>, <B>ne</B>, <B>e</B>, <B>se</B>, <B>s</B>, <B>sw</B>, <B>w</B>, 213or <B>nw</B>. The default is nw. 214</UL> 215<P> 216<pre> 217Name: <B>selectionOn</B> 218Class: <B>SelectionOn</B> 219Command-Line Switch: <B>-selectionon</B> 220</pre> 221<UL> 222Specifies whether or not to display the selection entry in any 223of the forms acceptable to <B>Tcl_GetBoolean</B>. The default is true. 224</UL> 225<P> 226<pre> 227Name: <B>width</B> 228Class: <B>Width</B> 229Command-Line Switch: <B>-width</B> 230</pre> 231<UL> 232Specifies the width of the selection box. The value may be specified in 233any of the forms acceptable to Tk_GetPixels. The default is 260 pixels. 234</UL> 235<P> 236</pre><HR> 237 238</pre><H2>DESCRIPTION</H2> 239<P> 240The <B>selectionbox</B> command creates a scrolled list of items and 241a selection entry field. The user may choose any of the items displayed 242in the scrolled list of alternatives and the selection field will be 243filled with the choice. The user is also free to enter a new value in 244the selection entry field. Both the list and entry areas have labels. 245A child site is also provided in which the user may create other widgets 246to be used in conjunction with the selection box. 247 248</pre><H2>METHODS</H2> 249<P> 250The <B>selectionbox</B> command creates a new Tcl command whose 251name is <I>pathName</I>. This 252command may be used to invoke various 253operations on the widget. It has the following general form: 254<pre> 255<I>pathName option </I>?<I>arg arg ...</I>? 256</pre> 257<I>Option</I> and the <I>arg</I>s 258determine the exact behavior of the command. 259 260</pre><H2>ASSOCIATED METHODS</H2> 261<P> 262<table cellpadding=5> 263<td valign=top> 264<B>curselection</B><br> 265<B>scan</B><br> 266</td> 267<td valign=top> 268<B>delete</B><br> 269<B>selection</B><br> 270</td> 271<td valign=top> 272<B>index</B><br> 273<B>size</B><br> 274</td> 275<td valign=top> 276<B>nearest</B><br> 277</td> 278</table> 279<P> 280See the <A HREF="http://www.sco.com/Technology/tcl/man/tk_man/listbox.n.html"> "listbox" </A> widget class manual entry for details on the 281associated methods. 282 283</pre><H2>WIDGET-SPECIFIC METHODS</H2> 284<DL> 285<DT> <I>pathName <B>cget</B> <I>option</I> 286</I></B> 287<DD> Returns the current value of the configuration option given 288by <I>option</I>. 289<I>Option</I> may have any of the values accepted by the <B>selectionbox</B> 290command. 291</DL> 292<DL> 293<DT> <I>pathName <B>childsite</B> 294</I></B> 295<DD> Returns the child site widget path name. 296</DL> 297<DL> 298<DT> <I>pathName <B>clear</B> <I>component</I> 299</I></B> 300<DD> Delete the contents of either the selection entry widget or 301items list. The <I>component</I> argument may be either <B>items</B> 302or <B>selection</B>. 303</DL> 304<DL> 305<DT> <I>pathName</I> <B>configure</B> ?<I>option</I>? ?<I>value option value ...</I>? 306</I></B> 307<DD> Query or modify the configuration options of the widget. 308If no <I>option</I> is specified, returns a list describing all of 309the available options for <I>pathName</I> (see <B>Tk_ConfigureInfo</B> for 310information on the format of this list). If <I>option</I> is specified 311with no <I>value</I>, then the command returns a list describing the 312one named option (this list will be identical to the corresponding 313sublist of the value returned if no <I>option</I> is specified). If 314one or more <I>option-value</I> pairs are specified, then the command 315modifies the given widget option(s) to have the given value(s); in 316this case the command returns an empty string. 317<I>Option</I> may have any of the values accepted by the <B>selectionbox</B> 318command. 319</DL> 320<DL> 321<DT> <I>pathName <B>get</B> 322</I></B> 323<DD> Returns the current value of the selection entry widget. 324</DL> 325<DL> 326<DT> <I>pathName <B>insert</B> <I>component</I> <I>args</I> 327</I></B> 328<DD> Insert element(s) into either the selection entry widget or 329items list. The <I>component</I> argument may be either <B>items</B> 330or <B>selection</B>. The <I>args</I> follow the rules of either an entry 331or list widget depending on the <I>component</I> value. 332</DL> 333<DL> 334<DT> <I>pathName <B>selectitem</B> 335</I></B> 336<DD> Replace the selection entry field contents with the currently 337selected items value. 338 339</DL> 340</pre><H2>COMPONENTS</H2> 341<P> 342<pre> 343Name: <B>childsite</B> 344Class: <B>Frame</B> 345</pre> 346<UL> 347The childsite component is the user child site for the selection box. See 348the "frame" widget manual entry for details on the childsite component item. 349</UL> 350<P> 351<pre> 352Name: <B>items</B> 353Class: <B>Scrolledlistbox</B> 354</pre> 355<UL> 356The items component provides the scrolled list box of items for the selection 357box. See the "scrolledlistbox" widget manual entry for details on the 358items component item. 359</UL> 360<P> 361<pre> 362Name: <B>selection</B> 363Class: <B>Entryfield</B> 364</pre> 365<UL> 366The selection component provides the entry field in the selection box for 367display of the selected item in the items component. See the "entryfield" 368widget manual entry for details on the selection component item. 369</UL> 370</table> 371 372</pre><H2>EXAMPLE</H2> 373<pre> 374 option add *textBackground white 375 376 selectionbox .sb -items {Hello {Out There} World} 377 pack .sb -padx 10 -pady 10 -fill both -expand yes 378 379 set cs [label [.sb childsite].label -text "Child Site"] 380 pack $cs -fill x -padx 10 -pady 10 381 382 .sb insert items 2 {Cruel Cruel} 383 384 .sb selection set 1 385</pre> 386</pre><H2>AUTHOR</H2> 387Mark L. Ulferts 388</pre><H2>KEYWORDS</H2> 389selectionbox, widget 390