ref.txt

speech signal process tools

             plot_min _plot_min:: \
             _name bracket file _file \
             start _view_start_time end _view_end_time:: \
             _name set file _file \
             l_marker_time _l_marker_time \
             r_marker_time _r_marker_time":: \
             _name set file _file \
             chan _cursor_channel plot_max _t_marker_yval \
             plot_min _b_marker_yval:: \
             _name bracket file _file \
             start _l_marker_time end _r_marker_time
          add_op name restore_mag menu none op #_res_mag
          key_map key m menu wave op magnify
          key_map key M op restore_mag


     (NB: Backslashes at the end of lines in the last example only mean that
     the text is continued on the next line. Don't use backslashes in the
     COMMAND (or @file): field; just type all the following text on a single
     line.)

     The first add_op command defines the operator magnify, which is not on
     any menu. This operator executes a complex xwaves command. Its
     operation consists of three ``simple'' commands:
       1. defines a symbol res_mag, that contains a three-part complex
          command as its value. If executed, res_mag resets the symbols
          plot_max and plot_min to the values they had before the
          magnification was executed, it resets the view borders, and it
          resets the markers.
       2. sets the range of the plot to the range between the top and bottom
          marker (the horizontal marker lines).
       3. sets the view to contain the signal segment between the left and
          right marker.
     The second add_op command creates an operator restore_mag that executes
     the value of the symbol res_mag, which is set at each execution of
     magnify. The following two commands bind these two operators to keys.

add_op_panel
     GUI INTERFACE TO THE ADD_OP COMMAND

     help_file
          The name of an ASCII file explaining the use of the add_op panel.
          This file is displayed in response to a press of the Help button
          on the add_op panel. If help_file  is omitted, a useful help file
          will be made available.
     loc_x, loc_y
          The X and Y pixel coordinates desired for the upper left corner of
          the add_op panel. Reasonable defaults will be used if either of
          these is omitted.
     show_vars
          A boolean that determines if the lists of variable names should
          automatically be displayed when the add_op panel is created.
     show_ops
          A boolean that determines if the list of available display window
          commands should automatically be displayed when the add_op panel
          is created.

     The add_op_panel command creates a handy graphical interface to aid in
     building custom xwaves operators via the add_op command. When opened,
     the main add_op_panel displays the following items:
     operation name:
          This corresponds to the name keyword of the add_op command. The
          command must be named, so you need to enter the name here. Any
          ASCII string is acceptable. You need not quote names with multiple
          words.
     add_to_windows
          These two buttons determine which, if any, display window menus
          the new operation will appear on. If neither of these buttons is
          depressed, the new item will be on the none list, meaning it will
          be available for mapping to keys and for access by other means,
          but will not appear on any display window menus.
     show variables...
          This button opens another panel that displays two scrollable lists
          of xwaves global symbols and display window-specific symbols that
          may be used as components in add_op commands. It also permits
          specification of output file names.
     show commands...
          This button opens a panel providing access to the list of object
          commands and their keyword lists.
     Enter command...
          This text window is the area in which the add_op command will be
          constructed. You may type any or all of the components of an op
          value for an add_op command into this window. In many cases, you
          do not actually need to type, since selecting items from the
          scrollable lists in the variables and commands panels
          automatically adds them to the string being constructed at the
          current cursor location.
     Apply add_op
          Causes the add_op command to be executed with the components you
          have just constructed. Immediately after you Apply, you can use
          the new operation.
     Help
          Invokes a text window explaining the add_op command and the
          add_op_panel.
     Dismiss
          Closes the add_op_panel, but does NOT cause the add_op under
          construction to be installed. If you Dismiss without Apply first,
          the add_op being constructed will be lost and ignored.

     As an example, we will describe step-by-step the use of the add_op
     panel to construct a command to set the vertical display limits of a
     file to the current horizontal marker locations (vertical bracket
     markers). We assume the add_op panel is open.
       1. Left mouse the operation name: item and type in a name for the
          command: e.g vbracket.
       2. Press the show commands... and show variables... buttons.
       3. Press the current object button in the commands panel. Select the
          set command from the Commands: list.
       4. Select file from the Command attributes: list.
       5. Select file from the View-Specific Variables: list.
       6. Select plot_max from the Command attributes: list.
       7. Select t_marker_yval from the View-Specific Variables: list.
       8. select plot_min from the Command attributes: list.
       9. Select b_marker_yval from the View-Specific Variables: list.
      10. Be sure the waveform button is in, and the image button is out.
      11. Press the Apply add_op button.
     As you become more familiar with xwaves and the add_op command, you may
     prefer to to issue the command directly (or via send_xwaves). The
     direct xwaves command to create the vbracket menu item might look like
     this:

          add_op name vbracket menu wave op \
             # _name set file _file plot_max  _t_marker_yval \
             plot_min _b_marker_yval


     Note, however, that whether or not the the add_op_panel is routinely
     used to create operators, it can still serve as a quick interactive
     reference to xwaves commands, command argument names, and variable
     symbols.

add_waves
     RESTORE (OR ADD) AN ITEM TO A DATA DISPLAY WINDOW MENU

     name
          a quoted string to be used as an entry in xwaves menus.
     menu
          one of the strings wave, spect, and all. This indicates whether
          the new item is to be added only to the menu for waveform windows,
          only to the menu for spectrogram windows, or to both menus. The
          default is all.
     op
          any named operator on the spect, wave or all menu-operator lists.
          This includes the built-in operators that are compiled into xwaves
          and any operators you have added with the add_op command. Note
          that the name of the menu-operator list containing the operator
          must be all or the same as the menu name specified to the
          add_waves command. See the chapter ``Data Window Menu Items'' of
          the full manual for discussions of the built-in menu items. The
          built-in Button Modes item is not an acceptable op.
     submenu
          identifier of a submenu to be added to the menu. In the current
          version, only the standard Button Modes  pull-right menu can be
          added as a submenu. For example, the command:

               add_waves submenu buttons


          will add the Button Modes, if one is not already present, to both
          window menus. The submenus for the waveform window menu and the
          spectrogram window menu are different; the appropriate submenu is
          added to each menu. The keyword menu can be used to restrict the
          operation to a specific menu. The keyword name can be used to make
          the added item appear with a name other than Button Modes. The
          argument of the submenu keyword, shown above as buttons, must be
          present for consistency with command syntax, but the value is
          ignored in the present implementation, submenu foo would do just
          as well. In a future extension of xwaves, the argument may be used
          to distinguish among different submenus to be added to a menu.
     command
          an arbitrary quoted string (may contain blanks) that is executed
          as an xwaves command when the new menu item is selected. So this
          may not be a UNIX command. The keywords command, builtin, and
          submenu are mutually exclusive. This means of adding a new command
          to menus by use of add_waves is now considered obsolete. See the
          add_op command.

     The command that is specified with the op option of the add_waves
     command is added to one or both of the xwaves window menus. Thus an
     item that has been removed with either the delete_item  or
     delete_all_items  command can be restored to a menu. In fact this
     should be the main function of add_waves .

     If name is specified, the function will be identified in the menu by
     that name, rather than by the string in the menu-operator list. The
     keywords command, op, and submenu are mutually exclusive. In the
     context of the add_waves command, builtin is an exact synonym for the
     op keyword.

attach
     ATTACH A FUNCTION

     function
          the name of the desired function (e.g. xspectrum or xlabel.)

     Several attachments may be active simultaneously. If more than one
     invocation of a given attachment is to be active at a time, create
     alternate names for the attachment that are symbolically linked to the
     same executable and refer to these names when creating the extra
     invocations.

branch
     TRANSFER CONTROL TO ANOTHER xwaves COMMAND FILE

     commandname
          the path name of the new command file. No return to the original
          command file is possible (although it may be branched to). The
          branch command provides a means for chaining together command
          files.

     The call, branch, and return xwaves commands are only used in xwaves
     command files. They are of no use as direct commands. Before writing a
     new xwaves command file, consider using a UNIX shell script with
     send_xwaves , instead.

call
     CALL AN xwaves COMMAND FILE AS A SUBROUTINE

     commandname
          the path name of the subroutine command file. There is currently
          no mechanism for argument passing other than mutually agreed-upon
          use of xwaves global symbols or the UNIX file system.

     The call, branch, and return xwaves commands are only used in xwaves
     command files. They are of no use as direct commands. Before writing a
     new xwaves command file, consider using a UNIX shell script with
     send_xwaves, instead.

cd
     CHANGE WORKING DIRECTORY

     path
          the new working directory. Subsequent relative file names passed
          to xwaves are interpreted relative to this directory. Path must be
          specified.

close_ctlwin
     CLOSE (ICONIZE) MAIN CONTROL PANEL

     invisible
          This boolean if set to 1 makes the view completely invisible. So
          there no icon left on the screen.

     The main xwaves control panel is closed down to an icon. Note that the
     global ctlwin_iconized  can be used to start xwaves in this state.

close_panel
     CLOSE AUXILIARY CONTROL PANEL

     name
          contiguous string of non-blank characters that has been used in
          creating an auxiliary control panel with the make_panel  command.
          The named panel is closed (i.e. iconized).
     invisible
          This boolean if set to 1 makes the view completely invisible. So
          there no icon left on the screen.

delete_all_items
     REMOVE EVERYTHING FROM xwaves MENUS

     menu
          one of the strings wave, spect, and all. This indicates whether
          the new item is to be removed only from the menu for waveform
          windows, only from the menu for spectrogram windows or from both
          menus. The default is all.

     All items are removed from the specified menus. Note that the
     underlying operator definitions are not affected, so the named
     menu-operator lists may still be accessed for key_map, save_add_ops,
     op, etc.

delete_item
     REMOVE ITEM FROM xwaves MENUS

     name
          a quoted string that exactly matches an entry in the data display
          window menu(s).
     menu
          one of the strings wave, spect, or all. This indicates whether the
          new item is to be removed only from the menu for waveform windows,
          only from the menu for spectrogram windows, or from both menus.
          The default is all.

     The named item is removed from any of the specified menus in which it
     occurs. As with delete_all_items, the underlying operator definition in
     the menu-operator list(s) is not affected.

detach
     DETACH ANY FUNCTION CURRENTLY ATTACHED TO xwaves

     function
          the name of the function to detach. If the function specification
          is omitted, all attachments will be detached.