1<TITLE><B>toolbar</B> - Create and manipulate a tool bar</TITLE> 2<H1><B>toolbar</B> - Create and manipulate a tool bar</H1> 3 4</pre><H2>SYNOPSIS</H2> 5<B>toolbar</B> <I>pathName</I> ?<I>options</I>? 6</pre><H2>STANDARD OPTIONS</H2> 7<P> 8<table cellpadding=5> 9<td valign=top> 10<B>activeBackground</B><br> 11<B>activeForeground</B><br> 12<B>background</B><br> 13<B>borderWidth</B><br> 14<B>cursor</B><br> 15</td> 16<td valign=top> 17<B>disabledForeground</B><br> 18<B>font</B><br> 19<B>foreground</B><br> 20<B>highlightBackground</B><br> 21<B>highlightColor</B><br> 22</td> 23<td valign=top> 24<B>highlightThickness</B><br> 25<B>insertBackground</B><br> 26<B>insertForeground</B><br> 27<B>orient</B><br> 28<B>selectBackground</B><br> 29</td> 30<td valign=top> 31<B>selectBorderWidth</B><br> 32<B>selectColor</B><br> 33<B>selectForeground</B><br> 34<B>state</B><br> 35<B>troughColor</B><br> 36</td> 37</table> 38<P> 39See 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. For widgets 40added to the toolbar, these options will be propogated if the widget supports 41the option. For example, all widgets that support a font option will be changed 42if the the toolbar's font option is configured. 43</pre><H2>WIDGET-SPECIFIC OPTIONS</H2> 44<P> 45<pre> 46Name: <B>balloonBackground</B> 47Class: <B>BalloonBackground</B> 48Command-Line Switch: <B>-ballooonbackground</B> 49</pre> 50<UL> 51Specifies the background color of the balloon help displayed at the bottom 52center of a widget on the toolbar that has a non empty string for its 53balloonStr option. The default color is yellow. 54</UL> 55<P> 56<pre> 57Name: <B>balloonDelay1</B> 58Class: <B>BalloonDelay1</B> 59Command-Line Switch: <B>-balloondelay1</B> 60</pre> 61<UL> 62Specifies the length of time (in milliseconds) to wait before initially 63posting a balloon help hint window. This delay is in effect whenever 1) 64the mouse leaves the toolbar, or 2) a toolbar item is selected with the 65mouse button. 66</UL> 67<P> 68<pre> 69Name: <B>balloonDelay2</B> 70Class: <B>BalloonDelay2</B> 71Command-Line Switch: <B>-balloondelay2</B> 72</pre> 73<UL> 74Specifies the length of time (in milliseconds) to wait before continuing to 75post balloon help hint windows. This delay is in effect after the first 76time a balloon hint window is activated. It remains in effect until 1) the 77mouse leaves the toolbar, or 2) a toolbar item is selected with the mouse 78button. 79</UL> 80<P> 81<pre> 82Name: <B>balloonFont</B> 83Class: <B>BalloonFont</B> 84Command-Line Switch: <B>-balloonfont</B> 85</pre> 86<UL> 87Specifies the font of the balloon help text displayed at the bottom center 88of a widget on the toolbar that has a non empty string for its 89balloonStr option. The default font is 6x10. 90</UL> 91<P> 92<pre> 93Name: <B>balloonForeground</B> 94Class: <B>BalloonForeground</B> 95Command-Line Switch: <B>-ballooonforeground</B> 96</pre> 97<UL> 98Specifies the foreground color of the balloon help displayed at the 99bottom center of a widget on the toolbar that has a non empty string for 100its balloonStr option. The default color is black. 101</UL> 102<P> 103<pre> 104Name: <B>helpVariable</B> 105Class: <B>HelpVariable</B> 106Command-Line Switch: <B>-helpvariable</B> 107</pre> 108<UL> 109Specifies the global variable to update whenever the mouse is in motion 110over a toolbar widget. This global variable is updated with the current 111value of the active widget's helpStr. Other widgets can "watch" this 112variable with the trace command, or as is the case with entry or label 113widgets, they can set their textVariable to the same global variable. This 114allows for a simple implementation of a help status bar. Whenever the 115mouse leaves a menu entry, the helpVariable is set to the empty string {}. 116</UL> 117<P> 118<pre> 119Name: <B>orient</B> 120Class: <B>Orient</B> 121Command-Line Switch: <B>-orient</B> 122</pre> 123<UL> 124Specifies the orientation of the toolbar. Must be either horizontal or 125vertical. 126</UL> 127</pre><HR> 128</pre><H2>DESCRIPTION</H2> 129The <B>toolbar</B> command creates a new window (given by the pathName 130argument) and makes it into a <B>toolbar</B> widget. Additional options, 131described above may be specified on the command line or in the option 132database to configure aspects of the toolbar such as its colors, font, 133and orientation. The <B>toolbar</B> command returns its pathName argument. At 134the time this command is invoked, there must not exist a window named 135pathName, but pathName's parent must exist. 136<P> 137A <B>toolbar</B> is a widget that displays a collection of widgets arranged 138either in a row or a column (depending on the value of the -orient option). 139This collection of widgets is usually for user convenience to give access 140to a set of commands or settings. Any widget may be placed on a toolbar. 141However, command or value-oriented widgets (such as button, radiobutton, 142etc.) are usually the most useful kind of widgets to appear on a toolbar. 143<P> 144In addition, the toolbar adds two new options to all widgets that are added to 145it. These are the <B>helpStr</B> and <B>balloonStr</B> options. See the 146discussion for the widget command add below. 147 148</pre><H2>WIDGET-SPECIFIC METHODS</H2> 149<P> 150The toolbar command creates a new Tcl command whose name is pathName. This 151command may be used to invoke various operations on the widget. It has the 152following general form: 153<pre> 154<I>pathName</I> <I>option</I> <I>?arg arg ...?</I> 155</pre> 156Option and args determine the exact behavior of the command. 157<P> 158Many of the widget commands for a toolbar take as one argument an indicator of 159which widget item of the toolbar to operate on. The indicator is called 160an <B>index</B> and may be specified in any of the following forms: 161<DL> 162<DT> <I>number</I> 163</I></B> 164<DD> Specifies the widget numerically, where 0 corresponds to the first 165widget in the notebook, 1 to the second, and so on. (For horizontal, 0 is the 166leftmost; for vertical, 0 is the topmost). 167</DL> 168<DL> 169<DT> <B>end</B> 170</I></B> 171<DD> Specifes the last widget in the toolbar's index. If the toolbar is 172empty this will return -1. 173</DL> 174<DL> 175<DT> <B>last</B> 176</I></B> 177<DD> Same as end. 178</DL> 179<DL> 180<DT> <I>pattern</I> 181</I></B> 182<DD> If the index doesn't satisfy any of the above forms, then this form is 183used. Pattern is pattern-matched against the widgetName of each widget in the 184toolbar, in order from the first to the last widget, until a matching entry is 185found. An exact match must occur. 186</DL> 187<P> 188The following commands are possible for toolbar widgets: 189<DL> 190<DT> <I>pathName</I> <B>add</B> <I>widgetCommand</I> <I>widgetName</I> <I>?option value?</I> 191</I></B> 192<DD> Adds a widget with the command widgetCommand whose name is widgetName to the 193toolbar. If widgetCommand is radiobutton or checkbutton, its packing is 194slightly padded to match the geometry of button widgets. In addition, the 195indicatorOn option is false by default and the selectColor is that of the 196toolbar background by default. This allows Radiobutton and Checkbutton widgets 197to be added as icons by simply setting their bitmap or image options. If 198additional arguments are present, they are the set of available options 199that the widget type of <I>widgetCommand</I> supports. In addition they may 200also be one of the following options: 201</DL> 202<UL> 203<DL> 204<DT> <B>-helpstr</B> <I>value</I> 205</I></B> 206<DD> Specifes the help string to associate with the widget. When the mouse moves 207over the widget, the variable denoted by <B>helpVariable</B> is set 208to <B>helpStr</B>. Another widget can bind to the helpVariable and thus 209track status help. 210</DL> 211<DL> 212<DT> <B>-balloonstr</B> <I>value</I> 213</I></B> 214<DD> Specifes the string to display in a balloon window for this widget. A 215balloon window is a small popup window centered at the bottom of the 216widget. Usually the <B>balloonStr</B> value is the name of the item on the 217toolbar. It is sometimes known as a hint window. 218<UL> 219When the mouse moves into an item on the toolbar, a timer is set based on 220the value of <B>balloonDelay1</B>. If the mouse stays inside the item 221for <B>balloonDelay1</B>, the balloon window will pop up displaying 222the <B>balloonStr</B> value. Once the balloon window is posted, a new 223timer based on <B>balloonDelay2</B> is set. This is typically a shorter 224timer. If the mouse is moved to another item, the window is unposted and 225a new window will be posted over the item if the shorter delay time is 226satisfied. 227</UL> 228<UL> 229While the balloon window is posted, it can also be unposted if the item 230is selected. In this case the timer is reset to <B>balloonDelay1</B>. 231Whenever the mouse leaves the toolbar, the timer is also reset 232to <B>balloonDelay1</B>. 233</UL> 234<UL> 235This window posting/unposting model is the same model used in the 236Windows95 environment. 237</UL> 238</DL> 239</UL> 240<DL> 241<DT> <I>pathName</I> <B>cget</B> <I>option</I> 242</I></B> 243<DD> Returns the current value of the configuration option given by <I>option</I>. 244</DL> 245<DL> 246<DT> <I>pathName</I> <B>configure</B> ?<I>option</I> <I>value</I>? 247</I></B> 248<DD> Query or modify the configuration options of the widget. If no <I>option</I> is 249specified, returns a list describing all of the available options for pathName 250(see Tk_ConfigureInfo for information on the format of this list). If 251<I>option</I> is specified with no value, then the command returns a 252list describing the one 253named option (this list will be identical to the corresponding sublist of the 254value returned if no option is specified). If one or more option-value pairs 255are specified, then the command modifies the given widget option(s) to have the 256given value(s); in this case the command returns an empty string. 257</DL> 258<DL> 259<DT> <I>pathName</I> <B>delete</B> <I>index</I> ?<I>index2</I>? 260</I></B> 261<DD> This command deletes all items between <I>index</I> and <I>index2</I> 262inclusive. If <I>index2</I> is omitted then it defaults to <I>index</I>. 263Returns an empty string. 264</DL> 265<DL> 266<DT> <I>pathName</I> <B>index</B> <I>index</I> 267</I></B> 268<DD> Returns the widget's numerical index for the entry corresponding 269to <I>index</I>. If <I>index</I> is not found, -1 is returned. 270</DL> 271<DL> 272<DT> <I>pathName</I> <B>insert</B> <I>beforeIndex</I> <I>widgetCommand</I> <I>widgetName</I> <I>?option value?</I> 273</DL> 274<DL> 275<DT> Insert a new item named <I>widgetName</I> with the 276</I></B> 277<DD> command <I>widgetCommand</I> before the item specified by <I>beforeIndex</I>. 278If <I>widgetCommand</I> is <B>radiobutton</B> or <B>checkbutton</B>, its 279packing is slightly padded to match the geometry of button widgets. In 280addition, the <B>indicatorOn</B> option is <B>false</B> by default and the 281<B>selectColor</B> is that of the toolbar background by default. This allows 282<B>Radiobutton</B> and <B>Checkbutton</B> widgets to be added as icons by 283simply setting their <B>bitmap</B> or <B>image</B> options. The set of 284available options is the same as specified in the <B>ad</B> command. 285</DL> 286<DL> 287<DT> <I>pathName</I> <B>itemcget</B> <I>index</I> <I>option</I> 288</I></B> 289<DD> Returns the current value of the configuration option given by <I>option</I> for 290index. The item type of <I>index</I> determines the valid available options. 291</DL> 292<DL> 293<DT> <I>pathName</I> <B>itemconfigure</B> <I>index</I> <I>?option value?</I> 294</I></B> 295<DD> Query or modify the configuration options of the widget of the toolbar 296specified by <I>index</I>. If no option is specified, 297returns a list describing all of 298the available options for <I>index</I> 299(see <B>Tk_ConfigureInfo</B> for information on the 300format of this list). If <I>option</I> is specified with no value, 301then the command 302returns a list describing the one named option (this list will be identical to 303the corresponding sublist of the value returned if no option is specified). If 304one or more option-value pairs are specified, then the command modifies the 305given widget option(s) to have the given value(s); in this case the command 306returns an empty string. The item type of <I>index</I> determines the valid 307available options. The set of available options is the same as specified 308in the <B>ad</B> command. 309</DL> 310</pre><H2>EXAMPLE</H2> 311<pre> 312 toolbar .tb -helpvariable statusVar 313 314 .tb add button item1 \\ 315 -helpstr "Save It" -bitmap @/icons/Tool_32_box.xbm \\ 316 -balloonstr "Save" -command {puts 1} 317 .tb add button item2 \\ 318 -helpstr "Save It" -bitmap @/icons/Tool_32_brush.xbm \\ 319 -balloonstr "Save" -command {puts 1} 320 .tb add button item3 \\ 321 -helpstr "Save It" -bitmap @/icons/Tool_32_cut.xbm \\ 322 -balloonstr "Save" -command {puts 1} 323 .tb add button item4 \\ 324 -helpstr "Save It" -bitmap @/icons/Tool_32_draw.xbm \\ 325 -balloonstr "Save" -command {puts 1} 326 .tb add button item5 \\ 327 -bitmap @/icons/Tool_32_erase.xbm -helpstr "Play It" \\ 328 -command {puts 2} 329 .tb add frame filler \\ 330 -borderwidth 1 -width 10 -height 10 331 .tb add radiobutton item6 \\ 332 -bitmap @/icons/Tool_32_oval.xbm -command {puts 4} \\ 333 -variable result -value OPEN -helpstr "Radio Button # 1" \\ 334 -balloonstr "Radio" 335 .tb add radiobutton item7 \\ 336 -bitmap @/icons/Tool_32_line.xbm -command {puts 5} \\ 337 -variable result -value CLOSED 338 .tb add checkbutton item8 \\ 339 -bitmap @/icons/Tool_32_text.xbm -command {puts 6} \\ 340 -variable checkit -onvalue yes -offvalue no 341 .tb add checkbutton check2 \\ 342 -bitmap @/icons/Tool_32_points.xbm -command {puts 7} \\ 343 -variable checkit2 -onvalue yes -offvalue no 344 345 pack .tb -side top -anchor nw 346</pre> 347</pre><H2>AUTHOR</H2> 348Bill Scott 349</pre><H2>KEYWORDS</H2> 350toolbar, button, radiobutton, checkbutton, iwidgets, widget 351 352