home *** CD-ROM | disk | FTP | other *** search
/ Club Amiga de Montreal - CAM / CAM_CD_1.iso / files / 337.lha / Helper_v.07 / readme.pp / readme
Encoding:
Text File  |  1990-02-07  |  11.0 KB  |  224 lines
  1.  
  2.  
  3.  
  4.  
  5.  
  6.  
  7.  
  8.  
  9.  
  10.                                     Helper v0.07
  11.  
  12.                                 (c) 1989 Mike Cargal
  13.  
  14.  
  15.           NOTICE:
  16.             Helper requires  ARP 1.3  to function  correctly.  Many  thanks
  17.           to  the  folks  behind ARP who have  made programming the Amiga a
  18.           much less painful proposition.
  19.  
  20.           COPYRIGHT STUFF
  21.  
  22.              Helper is freely  redistributable but not  part of the  Public 
  23.           Domain.  You may copy and  distribute Helper as you like.  If you
  24.           make changes to Helper please either release it under a new  name
  25.           or send your changes to me for consideration in the next version.
  26.           You may not charge a  fee for Helper  other than reasonable  disk
  27.           duplication fees associated with Freely Redistributable libraries
  28.           such  as the  Fred Fish  collection.  I  retain the  Copyright to
  29.           Helper.
  30.  
  31.           GENERAL INFORMATION:
  32.  
  33.             Helper is a small utility to ease the  transition to  using the
  34.           CLI, or even to speed up certain functions if you're a CLI pro.
  35.           Helper  allows  you  to  define  up  te  12  help  keys which are
  36.           available to your CLI window.  Along with  the ability  to set up
  37.           any command  to execute  at the  touch of  a button, you may also
  38.           specify that a  file  requester  (ala  ARP  (AmigaDOS Replacement
  39.           Project) to select any file parameters required by a command.
  40.  
  41.           WHY HELPER?
  42.  
  43.             Helper was  written to bridge the gap between the WorkBench and
  44.           CLI in a manner  to  help  you  move  into  the  CLI environment.
  45.           Unlike  directory  utilities  which  give  you a gadget/requestor
  46.           interface to AmigaDOS, Helper keeps  you  in  a  CLI environment.
  47.           You will  notice that Helper always keeps your CLI window active,
  48.           and that Helper commands  are entered  exactly as  you would type
  49.           them  if  using  the  CLI  alone.   In fact this is so similar to
  50.           typing your commands at the command prompt that if you  are using
  51.           a CLI  Shell (as  comes with  AmigaDOS 1.3),  all Helper executed
  52.           commands  will  be  in  your  command  history  buffer  and  take
  53.           advantage of aliases.
  54.  
  55.           USING HELPER:
  56.  
  57.            From WorkBench:
  58.  
  59.             Double click on the Helper icon.  Helper will open  its own CLI
  60.           for your use.  You may customize the CLI which is opened by using
  61.           the INFO menu item to add tool types.  Valid tool types and their
  62.           meanings are as follows:  (Capitalization must be exact)
  63.  
  64.               1) WINDOW=<Window  Specification>  This window specification 
  65.                   must be the same as you would use for the NewCLI or      
  66.                   NewShell DOS commands.  (See your DOS manual for format)
  67.  
  68.               2) STARTUP=<name  of Startup file to execute upon opening    
  69.                   window>.
  70.  
  71.               3) CONFIG=<name of Helper configuration file to use>.
  72.  
  73.               4) SHELL=<YES or NO> to indicate whether or not you  desire a
  74.                   CLI shell.  Yes opens a Shell and NO opens a plain CLI.
  75.  
  76.            From CLI:
  77.  
  78.             Initiate helper by typing the following on your command line:
  79.  
  80.                  1> Helper
  81.  
  82.           When Helper  is executed  it will  detach itself  in order to run
  83.           concurrently with  your CLI.   At  this point  Helper will appear
  84.           with it's default commands and window placement.  Try clicking on
  85.           a couple of the  buttons ("Gadgets"  in Amiga  Lingo).   You will
  86.           notice that  some commands  will bring up a file requestor before
  87.           executing (CD is an example of this).  This allows  you to select
  88.           the file  (or directory  in the case of CD) on which your command
  89.           your command will operate.
  90.  
  91.             Once you are comfortable with Helper, try clicking  between the
  92.           buttons  in  the  helper  window.   This will activate the Helper
  93.           window so that you  have access  to it's  menu.   Normally Helper
  94.           will automatically  activate your  CLI window  when it executes a
  95.           command.  This saves  you from  having to  click back  in the CLI
  96.           window after  using Helper.   In  the Helper menu you will notice
  97.           the following items:
  98.              
  99.                   Load           L
  100.                   Change         C
  101.                   Save           S
  102.                   Save Defaults  D
  103.                   Quit           Q
  104.  
  105.              Let's begin with Change.  By  selecting Change  from the menu,
  106.           or  typing  Amiga-C  with  the  Helper window active, you will be
  107.           presented with a window of the current state of Helper commands.
  108.           The first column is the Label  which will  appear on  your Helper
  109.           button.   The second  is the command to be executed whenever that
  110.           Helper button  is clicked.   And  the third  is a  gadget to tell
  111.           Helper whether  or not  to ask  for a file name to append to your
  112.           command.  Try changing any of  these.    Remember  to  hit RETURN
  113.           after  changing  a  label  or  command.  Whenever you have Helper
  114.           customized to your needs  click on  the Close  gadget (the Square
  115.           box in  the upper left-hand corner of the window).  Now try using
  116.           the Helper buttons.  They should display your  labels and respond
  117.           with your commands.
  118.  
  119.              Since you  probably do not wish to customize Helper every time
  120.           you use  it, you  may now  select the  Save menu  option (or type
  121.           Amiga-S with  the Helper  window active).   This  will bring up a
  122.           file requestor for you  to give  your configuration  file a name.
  123.           Notice that by default, the requestor comes up pointed to your S:
  124.           device.   This is  where configurations are generally kept on the
  125.           Amiga.  Type a name to  save  your  current  configuration.   Now
  126.           click on the OK gadget.  Your current configuration will be saved
  127.           in this file.  To test  this, click  on Helper's  close gadget to
  128.           exit Helper.
  129.  
  130.              Run helper  again and notice that it comes up with the default
  131.           configuration.  Now click between the  Helper gadgets  and select
  132.           the Load  menu item.   A  file requestor  will appear  for you to
  133.           select the configuration file you desire.  Click on the  file you
  134.           just  saved  in  the  previous  step,  and then on the OK gadget.
  135.           Helper will read this  file and  return to  the configuration you
  136.           established before.   You  may even  notice that if you moved the
  137.           Helper window before saving  your configuration,  Helper will now
  138.           be  positioned   wherever  you   had  it   when  you  saved  your
  139.           configuration.
  140.  
  141.              If you have one configuration you will use  most of  the time,
  142.           you may  want to  have it be the default whenever you run helper.
  143.           To do this, set up your  configuration (including  where you want
  144.           the window  to appear),  and select Save Defaults from the Helper
  145.           menu.  This will save a file Helper.cnf in your S: device.   This
  146.           file is  searched for  and used  each time  you run  Helper.  Try
  147.           saving your default configuration  and exiting  Helper.   Now run
  148.           Helper   and   notice   that   it  comes  up  with  your  default
  149.           configuration active.
  150.  
  151.              The final menu item may be used to exit Helper,  and functions
  152.           exactly the same as closing the Helper window.
  153.  
  154.           PROGRAMMER'S NOTES:
  155.  
  156.              If you are new to the Amiga, or simply interested in Helper as
  157.           a user, then you need read no further.  The following information
  158.           is for programmers wishing to know how Helper works its magic.
  159.  
  160.              Helper  is  written  in  M2Sprint for the Amiga (a development
  161.           system which I  can  recommend  most  highly).    Source  code is
  162.           included for  your perusal.   But to save you some time, I'll try
  163.           to summarize the techniques  used  in  Helper  (You  can  get the
  164.           details from the source).
  165.  
  166.              Helper accomplishes  its "magic"  by activating the CLI window
  167.           and feeding Input Events to the Input Device.  In this manner, it
  168.           appears to  the CLI  exactly as  though those characters had been
  169.           typed from the keyboard.  This allows Helper to make  full use of
  170.           command aliases  and history.  Though this sounds straightforward
  171.           enough, there is a small hitch in that  the Input  Device expects
  172.           Raw  Key  codes.    There  is  no  system  routine for converting
  173.           characters back to Raw Key Codes,  and depending  upon the KeyMap
  174.           currently  in  use,  these  codes  can  be different for the same
  175.           character.    The  DoRawTbl  module  was  written  to  solve this
  176.           problem.    It  uses  the  current  KeyMap to build a table which
  177.           Helper can use to  translate back  to the  Raw Key  Codes for the
  178.           current map.
  179.  
  180.              Helper also  employs a  technique to  separate itself from the
  181.           CLI.  Although there is probably a better and more elegant way of
  182.           doing this, currently I'm having helper start itself up using the
  183.           ARP ASyncRun, and then ending the  initial program.   This leaves
  184.           the second helper running while the first returns control back to
  185.           the CLI.  This  also has  the added  advantage of  allowing me to
  186.           pass the  address of the CLI's process structure to Helper (which
  187.           is running as a separate process).    By  having  access  to this
  188.           structure Helper  is able  to keep  its current directory in sync
  189.           with the current  directory  of  the  CLI,  so  that  Helper file
  190.           requester's  will   come  up   initially  in  the  CLI's  current
  191.           directory.
  192.  
  193.              I might add that Helper  makes  rather  extensive  use  of the
  194.           "Easy" libraries  provided with M2Sprint.  Programmers from other
  195.           Amiga programming environments, may wish to  see how  easy it can
  196.           be to set up intuition functions.  These make initial prototyping
  197.           a pleasure.  I had the initial version  of Helper  up and running
  198.           in a matter of about 3-4 hours.
  199.  
  200.             Oh yes,  special thanks  to Martin  Taillefer and the others on
  201.           BIX who were helpful in answering my questions.
  202.  
  203.           (*------------------------------------------------------------*)
  204.  
  205.           Flames, bug reports, large  sums of  money and  general accolades
  206.           may be sent to me through the following means:
  207.  
  208.           Local Boards I frequent Regularly:
  209.  
  210.              Ami-GA               (404) 327-3450
  211.              C.I.A.               (404) 561-5359
  212.              Columbus Connection  (404) 687-3151
  213.  
  214.           National service:
  215.            
  216.              BIX -- mcargal
  217.  
  218.           U.S. Mail
  219.  
  220.              Mike Cargal
  221.              7857 Crescent Drive
  222.              Columbus, GA 31909
  223.  
  224.