home *** CD-ROM | disk | FTP | other *** search
/ Amiga MA Magazine 1998 #6 / amigamamagazinepolishissue1998.iso / varia / toolsdaemon / toolsdaemon.doc < prev    next >
Text File  |  1995-05-28  |  20KB  |  542 lines
  1.  
  2.  
  3.      
  4.  
  5.  
  6.                                 ToolsDaemon 2.1a
  7.  
  8.                                   User Manual
  9.  
  10.                                 January 30, 1994
  11.  
  12.  
  13.  
  14.      PREFACE 
  15.  
  16.         The programs   and   files   in   this   distribution   are  freely
  17.      distributable,  but  are also Copyright (c) Nico Francois. They may be
  18.      freely  distributed  as  long as no more than a nominal fee is charged
  19.      to cover time and copying costs.  
  20.         No commercial  usage  is  permitted without written permission from
  21.      the  author. Everything in this distribution must be kept together, in
  22.      original unmodified form.  
  23.         The above is generally known as freeware.  
  24.  
  25.         If you  have  suggestions  or remarks about this program, or if you
  26.      find any bugs, please let me know.  
  27.  
  28.         Contacting the author: 
  29.  
  30.           Internet:   nico@augfl.be
  31.           FidoNet :   2:292/603.10
  32.           AmigaNet:   39:120/102.10
  33.  
  34.           Snail-mail: Nico François
  35.                       Corbielaan 13
  36.                       B-3060 Bertem
  37.                       BELGIUM
  38.  
  39.         If you  can  please use e-mail. That way you'll stand a much better
  40.      chance of getting a reply quickly.  
  41.  
  42.         ToolsDaemon uses  and  requires  reqtools.library  V38 (or higher).
  43.      ReqTools is also Copyright © 1991-1994 Nico François.  
  44.  
  45.         NOTE: ToolsDaemon  2.1a requires Kickstart 2.0 and Workbench 2.0 or
  46.      higher to run! 
  47.  
  48.  
  49.      1. Introduction 
  50.      --------------- 
  51.  
  52.         Your Workbench  2.0  manual will tell you:  It is possible to run a
  53.      program  by  choosing  a  menu  item  from the Tools menu of Workbench
  54.      2.0.   But  only  if  your application software supports this feature.
  55.      Your  application software will have instructions on how to create the
  56.      new menu item.  
  57.  
  58.  
  59.  
  60.                                      Page 1
  61.  
  62.  
  63.      
  64.  
  65.  
  66.         But what  if  you  want  to  add programs to Workbench's menu strip
  67.      which do not have this feature?  Then there is ToolsDaemon 2.1a.  
  68.  
  69.         ToolsDaemon allows  you  to run programs simply by selecting a menu
  70.      item  from  the  menu  strip  of  Workbench  2.0.  Shell and Workbench
  71.      programs  are  supported,  including arguments and tool types for both
  72.      of  these.   The  menu  items  can  be arranged in several menus, with
  73.      sub-items and keyboard shortcuts.  
  74.  
  75.         ToolsPrefs is  designed as a preferences editor for the ToolsDaemon
  76.      menus.   It  features  a full intuition front-end and supports the 2.0
  77.      AppWindow  feature.   This  means  it allows you to drag programs into
  78.      its  window  and  they  will  be automatically added to the menu items
  79.      list.  
  80.  
  81.         ToolsDaemon is  the  background  program that will launch the tools
  82.      you  select  from  the menu strip.  It is meant to be dragged into the
  83.      WbStartup drawer so it will automatically be launched on startup.  
  84.  
  85.  
  86.      2. Installation 
  87.      --------------- 
  88.  
  89.         Installation is  very  easy.   Double-click  the  'Install' icon to
  90.      install ToolsDaemon.  
  91.  
  92.         You will  need  Commodore's  standard  Installer utility to run the
  93.      install  script.   If  you  have Workbench 2.1, 3.0 or higher you will
  94.      find  Installer  on  your Workbench installation disk.  Simply copy it
  95.      to  your  'SYS:Utilities'  directory  (or  anywhere  in your Workbench
  96.      command path).  
  97.  
  98.         To install  ToolsDaemon  manually simply copy 'ToolsDaemon-Handler'
  99.      to  'L:',  drag 'ToolsDaemon' to 'SYS:WbStartup' and drag 'ToolsPrefs'
  100.      to 'SYS:Prefs'.  
  101.  
  102.  
  103.      3. Usage 
  104.      -------- 
  105.  
  106.         Once everything   is   installed   run  ToolsDaemon  and  then  the
  107.      ToolsPrefs  program.  This will allow you to define the menus and menu
  108.      items  you  would  like  to  add  to  the menu strip of the Workbench.
  109.      ToolsPrefs  has  two  lists:   'Menu  Items' and 'Commands'.  The menu
  110.      items  list  corresponds  to  the  text  that  will appear in the menu
  111.      items.   Each  menu item has its own command list.  So by choosing one
  112.      menu item you can invoke several commands (asynchronously).  
  113.  
  114.         ToolsPrefs features  a  full  intuition front-end to edit the items
  115.      and  commands  lists.   Everything  is fairly self-explanatory, except
  116.      maybe  the  'Move  Up'  and 'Move Down' menu items in the 'Edit' menu.
  117.      These  allow  you  to  change the order of the menu items, by allowing
  118.  
  119.  
  120.                                      Page 2
  121.  
  122.  
  123.      
  124.  
  125.  
  126.      you  to  move  the  current item closer to the top or to the bottom of
  127.      the list.  
  128.  
  129.         Items can  be  set  to  be  a menu title, a sub-item or a seperator
  130.      bar.   Use  the  'Menu' and 'Sub' checkboxes to set an item's type (if
  131.      none  of  these is checked the item is a normal menu item).  The 'Bar'
  132.      button will set the current menu item to be a seperator bar.  
  133.  
  134.         The 'Key'  string  gadget can be used to assign a keyboard shortcut
  135.      to  an  item.  Note that you can only use keys that aren't used by the
  136.      Workbench.   You  are  not  limited to using letters, but you can also
  137.      use  numbers  or  other  symbols  (e.g.   '1',  '-', '/').  If you are
  138.      running  Kickstart  3.0  or  higher  there  will  be  an  extra gadget
  139.      underneath  the  'Key'  gadget.   In this gadget you can enter a short
  140.      description  string for the hotkey (see below), which will be shown in
  141.      the menu.  
  142.  
  143.         The hotkey  gadget  holds  an optional hotkey for the current item.
  144.      A  hotkey  entered  here will work even if the Workbench window is not
  145.      active.   Hotkeys  are described according to the Commodities standard
  146.      (for example: 'control alt t').  
  147.  
  148.         Commands can  be  run  as  Workbench  or  Shell commands.  Commands
  149.      indicated  as Workbench commands will be loaded and run by ToolsDaemon
  150.      just  as  if  you  had  double-clicked  them  in the Workbench.  Shell
  151.      commands  will  be  executed with a command line as if they were typed
  152.      in in a Shell window.  
  153.  
  154.         ToolsPrefs supports  the  use  of  arguments.  If you select one or
  155.      more  icons before selecting an item from the 'Tools' menu these files
  156.      will be passed as arguments.  
  157.  
  158.         If the  command is a Workbench command the arguments will be passed
  159.      as  if  you  selected  the program's icon and Shift-clicked some other
  160.      icons.   For  this  to  work  the  command  has to be followed by '[]'
  161.      indicating  it  expects  to  get  arguments.   For  example:   '(WB  )
  162.      C:PPMore []'.  
  163.  
  164.         If the  command  is  a Shell command the arguments will be expanded
  165.      onto  its  command line.  You should indicate with '[]' where you want
  166.      the arguments to appear.  For example:  '(CLI) Type [] HEX'.  
  167.  
  168.         The number  gadget next to the command string gadget determines the
  169.      stack  size  for  the  command  (in  case of a Shell command).  If the
  170.      command  is  launched  as a Workbench tool the stack size will be read
  171.      from the tool's icon.  
  172.  
  173.         The easiest  way  to  add an item is to pick up an icon and drop it
  174.      in  the  ToolsPrefs  window.   This will create a new item named after
  175.      the  program with a command list to run the program.  Dropping an icon
  176.      in  the  'Commands'  listview will not result in the creation of a new
  177.      item, but in adding a new command to the current command list.  
  178.  
  179.  
  180.                                      Page 3
  181.  
  182.  
  183.      
  184.  
  185.  
  186.  
  187.         When you  select  'Save'  ToolsPrefs  will  check if ToolsDaemon is
  188.      running  and  will  tell  it  to  update  the  menus  if it is.  It is
  189.      therefore  advisable  to  call ToolsPrefs if ToolsDaemon is already up
  190.      and  running.   If  you  have  dragged  ToolsDaemon  to your WbStartup
  191.      drawer  as  suggested  above it will always be running and you'll have
  192.      nothing to worry about.  
  193.  
  194.         Double-clicking the  icon  of  a  menu file saved with 'Save As...'
  195.      will  result  in  adding  the  menus to the Workbench's menu strip (if
  196.      ToolsDaemon  is  already  running the previously added menu items will
  197.      be removed first).  
  198.  
  199.      NOTE: - ToolsDaemon will search the path for Shell commands and
  200.              Workbench tools, but not for the icons of Workbench tools!
  201.              This exactly emulates the behaviour of Workbench 2.0.  
  202.            - Start ToolsDaemon again to quit it.  
  203.            - ToolsDaemon always adds an item to the 'Tools' menu of the
  204.              Workbench.  The item is called 'ToolsPrefs...' and when
  205.              picked will run the ToolsPrefs program.  The program will be
  206.              looked for in your command path and will be run as a Shell
  207.              command.  
  208.  
  209.  
  210.      4. Arguments and tooltypes 
  211.      -------------------------- 
  212.  
  213.      4.1 CLI or Shell 
  214.  
  215.         ToolsPrefs offers following command line arguments: 
  216.  
  217.           ToolsPrefs [FROM] [<menufile>] [PUBSCREEN <pubscreenname>] 
  218.  
  219.      [FROM] [<menufile>]         : Menu file to load instead of the
  220.                                    default 's:ToolsDaemon.menu' 
  221.      [SCREENFONT=<YES or NO>]    : Use screen font for editor or use the
  222.                                    standard Topaz 8 font.  Default is
  223.                                    YES.  
  224.      [PUBSCREEN <pubscreen name>]: Open editor on this public screen.  
  225.  
  226.  
  227.      4.2 Workbench 
  228.  
  229.         Following tooltypes are recognized by ToolsPrefs: 
  230.  
  231.      CREATEICONS=<YES or NO>     : State of 'Create Icons?' menu item.
  232.                                    Default is YES.  Note that if
  233.                                    ToolsPrefs is started from the Shell
  234.                                    the menu item will not be checked so no
  235.                                    icons will be created.  
  236.      PUBSCREEN=<pubscreen name>  : Open editor on this public screen.  
  237.      SCREENFONT=<YES or NO>      : Use screen font for editor or use the
  238.  
  239.  
  240.                                      Page 4
  241.  
  242.  
  243.      
  244.  
  245.  
  246.                                    standard Topaz 8 font.  Default is
  247.                                    YES.  
  248.  
  249.         Following tooltypes are recognized by ToolsDaemon: 
  250.  
  251.      WINDOW=<console description>: Change output console window
  252.                                    description.  Default is
  253.                                    "CON:0/25//150/Tools Output
  254.                                    Window/AUTO/WAIT/CLOSE".  
  255.      CX_PRIORITY=<pri>           : Set priority of ToolsDaemon's
  256.                                    commodity. Default is 0.  
  257.  
  258.                          As always, I hope you find these programs useful! 
  259.  
  260.  
  261.  
  262.  
  263.  
  264.  
  265.  
  266.  
  267.  
  268.  
  269.  
  270.  
  271.  
  272.  
  273.  
  274.  
  275.  
  276.  
  277.  
  278.  
  279.  
  280.  
  281.  
  282.  
  283.  
  284.  
  285.  
  286.  
  287.  
  288.  
  289.  
  290.  
  291.  
  292.  
  293.  
  294.  
  295.  
  296.  
  297.  
  298.  
  299.  
  300.                                      Page 5
  301.  
  302.  
  303.      
  304.  
  305.  
  306.                                 PROGRAM HISTORY
  307.  
  308.      ********************************************************************** 
  309.      VERSION 1.0 
  310.  
  311.      o First release.  
  312.  
  313.      ********************************************************************** 
  314.      VERSION 2.0 
  315.  
  316.      SEVERAL MAJOR ENHANCEMENTS! 
  317.      ~~~~~~~~~~~~~~~~~~~~~~~~~~~ 
  318.      o Features  multiple  menus,  submenus  and  keyboard shortcuts.  Much
  319.        more useful now! 
  320.      o Internal  function of preferences editor rewritten (now uses a state
  321.        machine), thanks to Marc Duponcheel for suggesting this.  
  322.      o More compatible Workbench startup: 
  323.        - All  tools  will  be  looked  for in Workbench's path.  The icon's
  324.          path must however be complete.  
  325.        - PROGDIR: is now supported (also for default tools, see below).  
  326.        - Workbench  tooltype  'TOOLPRI' supported (to set the task priority
  327.          of the tool).  
  328.        - Project   icons  supported.   ToolsDaemon  will  now  run  project
  329.          icons.   It  will  look  for  the  default tool of the icon in the
  330.          Workbench's  path  and  will  start  it  (even if it hasn't got an
  331.          icon) passing the project icon as the first argument.  
  332.      o More compatible Shell command execution: 
  333.        - Commands  are  now  sent  to  the  user shell, instead of the boot
  334.          shell.  
  335.        - Commands  now  receive  input  from  as well as send output to the
  336.          default console window.  
  337.  
  338.      RED ALERT -- RED ALERT -- RED ALERT...  
  339.      ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 
  340.      ToolsDaemon  is  no  longer  a 100% legal program!  It patches certain
  341.      Intuition  functions  to  attach  menu items to Workbench's menu strip
  342.      (which  it  shouldn't touch) and redirects Workbench's message port in
  343.      order  to  trap  IDCMP_MENUPICK  messages  before Workbench sees them.
  344.      Everything  has  been  done  as  cleanly  as possible and should be as
  345.      future  compatible  as  it  can  be, but there is no real guarantee it
  346.      will  still work on future versions of the Amiga operating system.  If
  347.      you  can't  live  with  this continue to use ToolsDaemon 1.0, but know
  348.      that  the  features  ToolsDaemon  offers (multiple menus, submenus and
  349.      keyboard  shortcuts)  CANNOT be offered in a legal way, simply because
  350.      workbench.library  V37  doesn't support them.  If a new version of the
  351.      Amiga  operating  system is released and ToolsDaemon is not compatible
  352.      I will rectify this as soon as possible.  
  353.  
  354.  
  355.  
  356.  
  357.  
  358.  
  359.  
  360.                                      Page 6
  361.  
  362.  
  363.      
  364.  
  365.  
  366.      ********************************************************************** 
  367.      VERSION 2.0a 
  368.  
  369.      o Fixed  small  bug:  No  more  problems  with  using an international
  370.        character  (like 'é') as the first chararcter of a menu item.  Thanks
  371.        to Roger Nordin for reporting this bug.  
  372.  
  373.      ********************************************************************** 
  374.      VERSION 2.0b 
  375.  
  376.      o Fixed  small  bug:  No longer possible to delete first menu title by
  377.        entering an empty name.  
  378.      o ToolsDaemon  and ToolsPrefs will now complain if the first line of a
  379.        menu file isn't a menu title line (instead of crashing :).  
  380.      o Fixed  bug:   No longer creates invalid menu files when you change a
  381.        menu item with command(s) into a seperator bar.  
  382.      o Cancel button moved two pixels to the right :) 
  383.  
  384.      ********************************************************************** 
  385.      VERSION 2.0c 
  386.  
  387.      o Some  enforcer  hits  removed.   Hits would occur when saving a menu
  388.        file or when deleting the last menu item.  
  389.      o I  received  a  bug  report that picking a menu item would sometimes
  390.        result  in  a couple of enforcer hits and nothing happening.  I have
  391.        been  unable  to  reproduce  this,  but  I  have changed the code in
  392.        question a bit to try and fix this.  
  393.      o ToolsDaemon  didn't  find  default tools (of project icons) if these
  394.        could _not_ be found in the command path.  Fixed.  
  395.      o No  longer saves WB commands that are changed to CLI commands with a
  396.        stack size of 0.  
  397.      o Release 2.0c of reqtools.library included.  
  398.  
  399.      ********************************************************************** 
  400.      VERSION 2.1 
  401.  
  402.      o ToolsPrefs    interface    is    now    completely   font-sensitive.
  403.        Automatically adapts itself to the screen font.  
  404.      o New tooltype and command line option for ToolsPrefs: 'SCREENFONT'.  
  405.      o ToolsDaemon and ToolsPrefs have been fully localized.  
  406.      o It  is  now possible to use real hotkeys to launch the programs.  On
  407.        Kickstart  3.0  or  higher  you  may also supply a small description
  408.        string  to show in the menu.  Supports the 'CX_PRIORITY' tooltype to
  409.        set the commodities priority of any hotkeys it installs.  
  410.      o The  menu  items  listview  will  now  show  the  optional  keyboard
  411.        shortcut  for the menu items.  On Kickstart 3.0 or higher ToolsPrefs
  412.        will  use  new  3.0  features  like  a  scalable  Amiga  image and a
  413.        listview with custom rendering hook.  
  414.      o ToolsDaemon  output console is now user configurable with a 'WINDOW'
  415.        tooltype in the ToolsDaemon icon.  
  416.      o ToolsDaemon  will  now  check  if someone else has patched Intuition
  417.        before exiting and removing its patches.  
  418.  
  419.  
  420.                                      Page 7
  421.  
  422.  
  423.      
  424.  
  425.  
  426.      o Bug  fix:  if you managed to select a menu item a split second after
  427.        activating a Workbench window ToolsDaemon would hang.  
  428.      o Bug  fix:  cycle  gadget was incorrectly implemented.  Gave problems
  429.        with CycleToMenu.  
  430.      o Bug  fix:  pressing  'Insert'  right  after  'Add' under the command
  431.        listview would cause a crash.  
  432.      o Bug  fix:  ToolsPrefs  allowed  you to type 6 characters too many in
  433.        the command string gadget.  
  434.      o Release 2.1f (38.1095) of reqtools.library included.  
  435.  
  436.      ********************************************************************** 
  437.      VERSION 2.1a 
  438.  
  439.      o Really  fixed the hanging problem I fixed in ToolsDaemon 2.1 :-)  If
  440.        you  managed  to select *the* *first* menu item a split second after
  441.        activating  a  Workbench  window  ToolsDaemon would still hang.  The
  442.        same  problem  occured  on machines running TWA and when picking the
  443.        first item just after quitting Directory Opus.  
  444.      o ToolsPrefs will now set its current directory to PROGDIR:.  
  445.      o ToolsPrefs  window  is now simple refresh and uses the Kickstart 3.0
  446.        or higher zoom-in-place feature.  
  447.      o Dropping  a  "fake"  icon  (Show all files) in the ToolsPrefs window
  448.        will now automatically enter the program as a CLI command.  
  449.      o There  was a problem with ToolsDaemon on Workbench 2.0.  ToolsDaemon
  450.        would  abort  silently  if  it  was the first Commodity that was run
  451.        (probably  due  to  a bug in commodities.library V37; V38 and higher
  452.        worked fine).  This is fixed now.  
  453.      o Updated icons to Workbench 3 look :-) 
  454.      o New french catalog included, translated by Benoit Mortier.  
  455.      o Italian catalog included, translated by Nicola Salmoria.  
  456.      o Release 2.2a (38.1210) of reqtools.library included.  
  457.  
  458.      ********************************************************************** 
  459.  
  460.      ToolsDaemon 2.1a by Nico François (Yes, Nico is my first name :-) 
  461.                       thanks to Magnus Holmgren, Stefan Zeiger, Roger
  462.                                 Nordin, Nicola Salmoria, Marc Duponcheel,
  463.                                 Jorrit Tyberghein, Peter Stuer, Ives
  464.                                 Aerts, Gunter Indenhoek and Alain Penders
  465.                                 for beta-testing and all the useful
  466.                                 suggestions, Johan Van Houtven for the
  467.                                 editing of this manual.  
  468.  
  469.  
  470.      "He was struck by a bullet
  471.       and he melted into fluid named extinction" - The Pixies
  472.  
  473.  
  474.      Copyright (c) 1991-1994 Nico François 
  475.  
  476.                  //
  477.      Thanks to \X/ Amiga for being the best computer ever!
  478.  
  479.  
  480.                                      Page 8
  481.  
  482.  
  483.      
  484.  
  485.  
  486.                                Table Of Contents
  487.  
  488.                                 ToolsDaemon 2.1a
  489.  
  490.      PREFACE.........................................................    1
  491.  
  492.      1. Introduction.................................................    1
  493.  
  494.      2. Installation.................................................    2
  495.  
  496.      3. Usage........................................................    2
  497.  
  498.      4. Arguments and tooltypes......................................    4
  499.         4.1 CLI or Shell.............................................    4
  500.         4.2 Workbench................................................    4
  501.  
  502.      PROGRAM HISTORY.................................................    6
  503.  
  504.  
  505.  
  506.  
  507.  
  508.  
  509.  
  510.  
  511.  
  512.  
  513.  
  514.  
  515.  
  516.  
  517.  
  518.  
  519.  
  520.  
  521.  
  522.  
  523.  
  524.  
  525.  
  526.  
  527.  
  528.  
  529.  
  530.  
  531.  
  532.  
  533.  
  534.  
  535.  
  536.  
  537.  
  538.  
  539.  
  540.      
  541.  
  542.