itcl/iwidgets/demos/html/toolbar.n.html

   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>
  39 See 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
  40 added to the toolbar, these options will be propogated if the widget supports
  41 the option. For example, all widgets that support a font option will be changed
  42 if the the toolbar's font option is configured.
  43 </pre><H2>WIDGET-SPECIFIC OPTIONS</H2>
  44 <P>
  45 <pre>
  46 Name:                   <B>balloonBackground</B>
  47 Class:                  <B>BalloonBackground</B>
  48 Command-Line Switch:    <B>-ballooonbackground</B>
  49 </pre>
  50 <UL>
  51 Specifies the background color of the balloon help displayed at the bottom
  52 center of a widget on the toolbar that has a non empty string for its
  53 balloonStr option. The default color is yellow.
  54 </UL>
  55 <P>
  56 <pre>
  57 Name:                   <B>balloonDelay1</B>
  58 Class:                  <B>BalloonDelay1</B>
  59 Command-Line Switch:    <B>-balloondelay1</B>
  60 </pre>
  61 <UL>
  62 Specifies the length of time (in milliseconds) to wait before initially
  63 posting a balloon help hint window. This delay is in effect whenever 1)
  64 the mouse leaves the toolbar, or 2) a toolbar item is selected with the
  65 mouse button.
  66 </UL>
  67 <P>
  68 <pre>
  69 Name:                   <B>balloonDelay2</B>
  70 Class:                  <B>BalloonDelay2</B>
  71 Command-Line Switch:    <B>-balloondelay2</B>
  72 </pre>
  73 <UL>
  74 Specifies the length of time (in milliseconds) to wait before continuing to
  75 post balloon help hint windows. This delay is in effect after the first
  76 time a balloon hint window is activated. It remains in effect until 1) the
  77 mouse leaves the toolbar, or 2) a toolbar item is selected with the mouse
  78 button.
  79 </UL>
  80 <P>
  81 <pre>
  82 Name:                   <B>balloonFont</B>
  83 Class:                  <B>BalloonFont</B>
  84 Command-Line Switch:    <B>-balloonfont</B>
  85 </pre>
  86 <UL>
  87 Specifies the font of the balloon help text displayed at the bottom center
  88 of a widget on the toolbar that has a non empty string for its
  89 balloonStr option. The default font is 6x10.
  90 </UL>
  91 <P>
  92 <pre>
  93 Name:                   <B>balloonForeground</B>
  94 Class:                  <B>BalloonForeground</B>
  95 Command-Line Switch:    <B>-ballooonforeground</B>
  96 </pre>
  97 <UL>
  98 Specifies the foreground color of the balloon help displayed at the
  99 bottom center of a widget on the toolbar that has a non empty string for
 100 its balloonStr option. The default color is black.
 101 </UL>
 102 <P>
 103 <pre>
 104 Name:                   <B>helpVariable</B>
 105 Class:                  <B>HelpVariable</B>
 106 Command-Line Switch:    <B>-helpvariable</B>
 107 </pre>
 108 <UL>
 109 Specifies the global variable to update whenever the mouse is in motion
 110 over a toolbar widget. This global variable is updated with the current
 111 value of the active widget's helpStr. Other widgets can "watch" this
 112 variable with the trace command, or as is the case with entry or label
 113 widgets, they can set their textVariable to the same global variable. This
 114 allows for a simple implementation of a help status bar. Whenever the
 115 mouse leaves a menu entry, the helpVariable is set to the empty string {}.
 116 </UL>
 117 <P>
 118 <pre>
 119 Name:                   <B>orient</B>
 120 Class:                  <B>Orient</B>
 121 Command-Line Switch:    <B>-orient</B>
 122 </pre>
 123 <UL>
 124 Specifies the orientation of the toolbar. Must be either horizontal or
 125 vertical.
 126 </UL>
 127 </pre><HR>
 128 </pre><H2>DESCRIPTION</H2>
 129 The <B>toolbar</B> command creates a new window (given by the pathName
 130 argument) and makes it into a <B>toolbar</B> widget. Additional options,
 131 described above may be specified on the command line or in the option
 132 database to configure aspects of the toolbar such as its colors, font,
 133 and orientation. The <B>toolbar</B> command returns its pathName argument. At
 134 the time this command is invoked, there must not exist a window named
 135 pathName, but pathName's parent must exist.
 136 <P>
 137 A <B>toolbar</B> is a widget that displays a collection of widgets arranged
 138 either in a row or a column (depending on the value of the -orient option).
 139 This collection of widgets is usually for user convenience to give access
 140 to a set of commands or settings. Any widget may be placed on a toolbar.
 141 However, command or value-oriented widgets (such as button, radiobutton,
 142 etc.) are usually the most useful kind of widgets to appear on a toolbar.
 143 <P>
 144 In addition, the toolbar adds two new options to all widgets that are added to
 145 it. These are the <B>helpStr</B> and <B>balloonStr</B> options. See the
 146 discussion for the widget command add below.
 147
 148 </pre><H2>WIDGET-SPECIFIC METHODS</H2>
 149 <P>
 150 The toolbar command creates a new Tcl command whose name is pathName. This
 151 command may be used to invoke various operations on the widget. It has the
 152 following general form:
 153 <pre>
 154 <I>pathName</I> <I>option</I> <I>?arg arg ...?</I>
 155 </pre>
 156 Option and args determine the exact behavior of the command.
 157 <P>
 158 Many of the widget commands for a toolbar take as one argument an indicator of
 159 which widget item of the toolbar to operate on. The indicator is called
 160 an <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
 165 widget in the notebook, 1 to the second, and so on. (For horizontal, 0 is the
 166 leftmost; 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
 172 empty 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
 183 used. Pattern is pattern-matched against the widgetName of each widget in the
 184 toolbar, in order from the first to the last widget, until a matching entry is
 185 found. An exact match must occur.
 186 </DL>
 187 <P>
 188 The 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
 193 toolbar. If widgetCommand is radiobutton or checkbutton, its packing is
 194 slightly padded to match the geometry of button widgets. In addition, the
 195 indicatorOn option is false by default and the selectColor is that of the
 196 toolbar background by default. This allows Radiobutton and Checkbutton widgets
 197 to be added as icons by simply setting their bitmap or image options. If
 198 additional arguments are present, they are the set of available options
 199 that the widget type of <I>widgetCommand</I> supports. In addition they may
 200 also 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
 207 over the widget, the variable denoted by <B>helpVariable</B> is set
 208 to <B>helpStr</B>. Another widget can bind to the helpVariable and thus
 209 track 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
 215 balloon window is a small popup window centered at the bottom of the
 216 widget. Usually the <B>balloonStr</B> value is the name of the item on the
 217 toolbar. It is sometimes known as a hint window.
 218 <UL>
 219 When the mouse moves into an item on the toolbar, a timer is set based on
 220 the value of <B>balloonDelay1</B>. If the mouse stays inside the item
 221 for <B>balloonDelay1</B>, the balloon window will pop up displaying
 222 the <B>balloonStr</B> value. Once the balloon window is posted, a new
 223 timer based on <B>balloonDelay2</B> is set. This is typically a shorter
 224 timer. If the mouse is moved to another item, the window is unposted and
 225 a new window will be posted over the item if the shorter delay time is
 226 satisfied.
 227 </UL>
 228 <UL>
 229 While the balloon window is posted, it can also be unposted if the item
 230 is selected. In this case the timer is reset to <B>balloonDelay1</B>.
 231 Whenever the mouse leaves the toolbar, the timer is also reset
 232 to <B>balloonDelay1</B>.
 233 </UL>
 234 <UL>
 235 This window posting/unposting model is the same model used in the
 236 Windows95 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
 249 specified, 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
 252 list describing the one
 253 named option (this list will be identical to the corresponding sublist of the
 254 value returned if no option is specified). If one or more option-value pairs
 255 are specified, then the command modifies the given widget option(s) to have the
 256 given 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>
 262 inclusive. If <I>index2</I> is omitted then it defaults to <I>index</I>.
 263 Returns 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
 269 to <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>.
 278 If <I>widgetCommand</I> is <B>radiobutton</B> or <B>checkbutton</B>, its
 279 packing is slightly padded to match the geometry of button widgets. In
 280 addition, 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
 283 simply setting their <B>bitmap</B> or <B>image</B> options. The set of
 284 available 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
 290 index. 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
 296 specified by <I>index</I>. If no option is specified,
 297 returns a list describing all of
 298 the available options for <I>index</I>
 299 (see <B>Tk_ConfigureInfo</B> for information on the
 300 format of this list). If <I>option</I> is specified with no value,
 301 then the command
 302 returns a list describing the one named option (this list will be identical to
 303 the corresponding sublist of the value returned if no option is specified). If
 304 one or more option-value pairs are specified, then the command modifies the
 305 given widget option(s) to have the given value(s); in this case the command
 306 returns an empty string. The item type of <I>index</I> determines the valid
 307 available options. The set of available options is the same as specified
 308 in 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>
 348 Bill Scott
 349 </pre><H2>KEYWORDS</H2>
 350 toolbar, button, radiobutton, checkbutton, iwidgets, widget
 351