iwidgets2.2.0 User Commands - toolbar






NAME

     toolbar - Create and manipulate a tool bar


SYNOPSIS

     toolbar pathName ?options?


STANDARD OPTIONS

     activeBackground               font            insertForegroundselectForeground
     activeForeground               foreground      orientstate
     background      highlightBackground            relieftroughColor
     borderWidth     highlightColor selectBackgroundcursor
     highlightThickness             selectBorderWidthdisabledForegroundinsertBackground
     selectColor

     See the "options" manual entry for details on  the  standard
     options.  For  widgets  added  to the toolbar, these options
     will be propogated if the widget supports  the  option.  For
     example,  all  widgets  that  support  a font option will be
     changed if the the toolbar's font option is configured.


WIDGET-SPECIFIC OPTIONS

     Name:           balloonBackground
     Class:          BalloonBackground
     Command-Line Switch:           -ballooonbackground

          Specifies the background  color  of  the  balloon  help
          displayed at the bottom center of a widget on the tool-
          bar that has a non  empty  string  for  its  balloonStr
          option. The default color is yellow.

     Name:           balloonDelay1
     Class:          BalloonDelay1
     Command-Line Switch:           -balloondelay1

          Specifies the length of time (in milliseconds) to  wait
          before  initially  posting  a balloon help hint window.
          This delay is in effect whenever 1)  the  mouse  leaves
          the  toolbar, or 2) a toolbar item is selected with the
          mouse button.

     Name:           balloonDelay2
     Class:          BalloonDelay2
     Command-Line Switch:           -balloondelay2

          Specifies the length of time (in milliseconds) to  wait
          before  continuing  to  post balloon help hint windows.
          This delay is in effect after the first time a  balloon
          hint window is activated. It remains in effect until 1)
          the mouse leaves the toolbar, or 2) a toolbar  item  is
          selected with the mouse button.

     Name:           balloonFont
     Class:          BalloonFont
     Command-Line Switch:           -balloonfont

          Specifies the font of the balloon help  text  displayed
          at  the  bottom  center of a widget on the toolbar that
          has a non empty string for its balloonStr  option.  The
          default font is 6x10.

     Name:           balloonForeground
     Class:          BalloonForeground
     Command-Line Switch:           -ballooonforeground

          Specifies the foreground  color  of  the  balloon  help
          displayed at the bottom center of a widget on the tool-
          bar that has a non  empty  string  for  its  balloonStr
          option. The default color is black.

     Name:           helpVariable
     Class:          HelpVariable
     Command-Line Switch:           -helpvariable

          Specifies the global variable to  update  whenever  the
          mouse  is  in motion over a toolbar widget. This global
          variable is updated  with  the  current  value  of  the
          active widget's helpStr. Other widgets can "watch" this
          variable with the trace command, or as is the case with
          entry or label widgets, they can set their textVariable
          to the same global variable. This allows for  a  simple
          implementation of a help status bar. Whenever the mouse
          leaves a menu entry, the helpVariable  is  set  to  the
          empty string {}.

     Name:           orient
     Class:          Orient
     Command-Line Switch:           -orient

          Specifies the  orientation  of  the  toolbar.  Must  be
          either horizontal or vertical.




DESCRIPTION

     The toolbar command creates a new window (given by the path-
     Name  argument)  and  makes  it into a toolbar widget. Addi-
     tional options, described above may be specified on the com-
     mand  line or in the option database to configure aspects of
     the toolbar such as its colors, font, and  orientation.  The
     toolbar  command  returns its pathName argument. At the time
     this command is invoked, there must not exist a window named
     pathName, but pathName's parent must exist.


     A toolbar is a widget that displays a collection of  widgets
     arranged either in a row or a column (depending on the value
     of the -orient option). This collection of widgets  is  usu-
     ally  for  user  convenience to give access to a set of com-
     mands or settings. Any widget may be placed  on  a  toolbar.
     However,  command or value-oriented widgets (such as button,
     radiobutton, etc.) are usually the most useful kind of widg-
     ets to appear on a toolbar.

     In addition, the toolbar adds two new options to all widgets
     that  are  added to it. These are the helpStr and balloonStr
     options. See the  discussion  for  the  widget  command  add
     below.



WIDGET-SPECIFIC METHODS

     The toolbar command creates a new Tcl command whose name  is
     pathName.  This command may be used to invoke various opera-
     tions on the widget. It has the following general form:

          pathName option ?arg arg ...?

     Option and args determine the exact behavior of the command.

     Many of the widget commands for a toolbar take as one  argu-
     ment  an  indicator  of  which widget item of the toolbar to
     operate on. The indicator is called  an  index  and  may  be
     specified in any of the following forms:

     number
          Specifies the widget numerically, where  0  corresponds
          to  the  first widget in the notebook, 1 to the second,
          and so on. (For horizontal,  0  is  the  leftmost;  for
          vertical, 0 is the topmost).

     end  Specifes the last widget in the toolbar's index. If the
          toolbar is empty this will return -1.

     last Same as end.

     pattern
          If the index doesn't satisfy any of  the  above  forms,
          then  this  form  is  used.  Pattern is pattern-matched
          against the widgetName of each widget in  the  toolbar,
          in  order  from  the  first to the last widget, until a
          matching entry is found. An exact match must occur.

     The following commands are possible for toolbar widgets:

     pathName add widgetCommand widgetName ?option value?
          Adds a widget with the command widgetCommand whose name
          is  widgetName  to  the  toolbar.  If  widgetCommand is
          radiobutton or checkbutton,  its  packing  is  slightly
          padded  to  match  the  geometry  of button widgets. In
          addition, the indicatorOn option is  false  by  default
          and  the  selectColor is that of the toolbar background
          by default. This  allows  Radiobutton  and  Checkbutton
          widgets  to  be  added as icons by simply setting their
          bitmap or image options. If  additional  arguments  are
          present, they are the set of available options that the
          widget type of widgetCommand supports. In addition they
          may also be one of the following options:

          -helpstr value
               Specifes the help string  to  associate  with  the
               widget.  When the mouse moves over the widget, the
               variable  denoted  by  helpVariable  is   set   to
               helpStr.  Another widget can bind to the helpVari-
               able and thus track status help.

          -balloonstr value
               Specifes the string to display in a balloon window
               for this widget. A balloon window is a small popup
               window centered at the bottom of the widget.  Usu-
               ally  the balloonStr value is the name of the item
               on the toolbar. It is sometimes known  as  a  hint
               window.

               When the mouse moves into an item on the  toolbar,
               a  timer  is  set based on the value of balloonDe-
               lay1. If the mouse stays inside the item for  bal-
               loonDelay1,   the   balloon  window  will  pop  up
               displaying the balloonStr value. Once the  balloon
               window  is posted, a new timer based on balloonDe-
               lay2 is set. This is typically a shorter timer. If
               the  mouse is moved to another item, the window is
               unposted and a new window will be posted over  the
               item if the shorter delay time is satisfied.

               While the balloon window is posted, it can also be
               unposted if the item is selected. In this case the
               timer is  reset  to  balloonDelay1.  Whenever  the
               mouse  leaves the toolbar, the timer is also reset
               to balloonDelay1.

               This window posting/unposting model  is  the  same
               model used in the Windows95 environment.

     pathName cget option
          Returns the current value of the  configuration  option
          given by option.

     pathName configure ?option value?
          Query  or  modify  the  configuration  options  of  the
          widget.  If  no  option  is  specified,  returns a list
          describing all of the available  options  for  pathName
          (see  Tk_ConfigureInfo for information on the format of
          this list). If option is specified with no value,  then
          the  command  returns  a  list describing the one named
          option (this list will be identical to the  correspond-
          ing  sublist  of  the  value  returned  if no option is
          specified). If  one  or  more  option-value  pairs  are
          specified,  then  the command modifies the given widget
          option(s) to have the given value(s); in this case  the
          command returns an empty string.

     pathName delete index ?index2?
          This command deletes all items between index and index2
          inclusive.  If  index2  is  omitted then it defaults to
          index. Returns an empty string.

     pathName index index
          Returns the widget's  numerical  index  for  the  entry
          corresponding  to  index.  If index is not found, -1 is
          returned.


value?

     pathName  insert  beforeIndex  widgetCommand  widgetName  ?option

     Insert a new item named widgetName with the
          command widgetCommand  before  the  item  specified  by
          beforeIndex.  If widgetCommand is radiobutton or check-
          button, its packing is slightly  padded  to  match  the
          geometry  of  button  widgets. In addition, the indica-
          torOn option is false by default and the selectColor is
          that  of the toolbar background by default. This allows
          Radiobutton and Checkbutton  widgets  to  be  added  as
          icons  by simply setting their bitmap or image options.
          The set of available options is the same  as  specified
          in the ad command.

     pathName itemcget index option
          Returns the current value of the  configuration  option
          given  by  option  for  index.  The  item type of index
          determines the valid available options.

     pathName itemconfigure index ?option value?
          Query or modify the configuration options of the widget
          of  the  toolbar  specified  by  index. If no option is
          specified, returns a list describing all of the  avail-
          able options for index (see Tk_ConfigureInfo for infor-
          mation on the format of this list). If option is speci-
          fied  with  no  value,  then the command returns a list
          describing the one named  option  (this  list  will  be
          identical  to  the  corresponding  sublist of the value
          returned if no option is specified).  If  one  or  more
          option-value  pairs  are  specified,  then  the command
          modifies the given widget option(s) to have  the  given
          value(s);  in  this  case  the command returns an empty
          string. The item type of  index  determines  the  valid
          available  options. The set of available options is the
          same as specified in the ad command.


EXAMPLE

           toolbar .tb -helpvariable statusVar

           .tb add button item1 \
              -helpstr "Save It" -bitmap @./icons/Tool_32_box.xbm \
              -balloonstr "Save" -command {puts 1}
           .tb add button item2 \
              -helpstr "Save It" -bitmap @./icons/Tool_32_brush.xbm \
              -balloonstr "Save" -command {puts 1}
           .tb add button item3 \
              -helpstr "Save It" -bitmap @./icons/Tool_32_cut.xbm \
              -balloonstr "Save" -command {puts 1}
           .tb add button item4 \
              -helpstr "Save It" -bitmap @./icons/Tool_32_draw.xbm \
              -balloonstr "Save" -command {puts 1}
           .tb add button item5 \
              -bitmap @./icons/Tool_32_erase.xbm -helpstr "Play It" \
              -command {puts 2}
           .tb add frame filler \
              -borderwidth 1 -width 10 -height 10
           .tb add radiobutton item6 \
              -bitmap @./icons/Tool_32_oval.xbm -command {puts 4} \
              -variable result -value OPEN -helpstr "Radio Button # 1" \
              -balloonstr "Radio"
           .tb add radiobutton item7 \
              -bitmap @./icons/Tool_32_line.xbm -command {puts 5} \
              -variable result -value CLOSED
           .tb add checkbutton item8 \
              -bitmap @./icons/Tool_32_text.xbm -command {puts 6} \
              -variable checkit -onvalue yes -offvalue no
           .tb add checkbutton check2 \
              -bitmap @./icons/Tool_32_points.xbm -command {puts 7} \
               -variable checkit2 -onvalue yes -offvalue no

           pack .tb -side top -anchor nw



AUTHOR

     Bill Scott


KEYWORDS

     toolbar, button, radiobutton, checkbutton, iwidgets, widget