home *** CD-ROM | disk | FTP | other *** search
/ The CDPD Public Domain Collection for CDTV 4 / CDPD_IV.bin / fish / 931-950 / ff947 / smaus / smaus.doc < prev    next >
Text File  |  1993-12-22  |  23KB  |  539 lines
  1.  
  2.  
  3.  
  4.  
  5.                                Documentation
  6.  
  7.                                     for
  8.  
  9.                                    SMaus
  10.  
  11.  
  12.  
  13.                     Copyright © 1991-1993 Stefan Sticht
  14.  
  15.                             All rights reserved
  16.  
  17.  
  18.  
  19.  
  20.  
  21.  
  22.                                  Shareware
  23.  
  24.      SMaus is shareware. SMaus is not freeware. If you use  SMaus  you
  25.      must register your copy.
  26.  
  27.  
  28.                                Registration
  29.  
  30.      To  register  your  copy  of  SMaus  print  out  the  file  named
  31.      "Registration", fill it out and send  it  to  me  along  with  an
  32.      euro-cheque, money order or cash.  The  registration  fee  is  US
  33.      $5.-/DM 5.-.
  34.  
  35.  
  36.                                 No warranty
  37.  
  38.      THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED  BY
  39.      APPLICABLE LAW. EXCEPT  WHEN  OTHERWISE  STATED  IN  WRITING  THE
  40.      COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE  THE  PROGRAM  "AS
  41.      IS" WITHOUT WARRANTY OF ANY KIND, EITHER  EXPRESSED  OR  IMPLIED,
  42.      INCLUDING,  BUT  NOT  LIMITED  TO,  THE  IMPLIED  WARRANTIES   OF
  43.      MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE  ENTIRE
  44.      RISK AS TO THE QUALITY AND PERFORMANCE OF  THE  PROGRAM  IS  WITH
  45.      YOU. SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE  COST  OF
  46.      ALL NECESSARY SERVICING, REPAIR OR CORRECTION.
  47.      IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW  OR  AGREED  TO  IN
  48.      WRITING WILL ANY COPYRIGHT HOLDER, OR ANY  OTHER  PARTY  WHO  MAY
  49.      REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR
  50.      DAMAGES,  INCLUDING   ANY   GENERAL,   SPECIAL,   INCIDENTAL   OR
  51.      CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO  USE
  52.      THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF  DATA  OR  DATA
  53.      BEING RENDERED INACCURATE OR LOSSES SUSTAINED  BY  YOU  OR  THIRD
  54.      PARTIES OR A FAILURE OF THE PROGRAM TO  OPERATE  WITH  ANY  OTHER
  55.      PROGRAM), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED  OF
  56.      THE POSSIBILITY OF SUCH DAMAGES.
  57.  
  58.  
  59.                                Distribution
  60.  
  61.      You may copy and distribute  verbatim  copies  of  the  program's
  62.      executable code and documentation  as  you  receive  it,  in  any
  63.      medium, provided that you conspicuously and appropriately publish
  64.      only the original, unmodified program, with all copyright notices
  65.      and  disclaimers  of  warranty  intact  and  including  all   the
  66.      accompanying documentation, example files and anything else  that
  67.      came with the original. You may only charge a small fee  for  the
  68.      costs  of  media,  handling  and  postage.  SMaus  may   not   be
  69.      distributed along with or as part of commercial products  without
  70.      a license from the author.
  71.  
  72.      SMaus_nowin is a special version of SMaus  without  a  graphical
  73.      user interface. Everything said for SMaus applies to SMaus_nowin,
  74.      too.
  75.  
  76.  
  77.                                Introduction
  78.  
  79.      SMaus has been written to replace the commodity AutoPoint,  which
  80.      is part of AmigaOS 2.0 and above. SMaus is highly configurable.
  81.  
  82.      The primary purpose  is  to  activate  windows  under  the  mouse
  83.      pointer. There  are  different  actions  which  will  activate  a
  84.      window:
  85.  
  86.      Mouse movement: while or after moving the mouse the window  under
  87.      the pointer gets activated. You can select a  speed  below  which
  88.      windows get activated. If you move the mouse fast, no window gets
  89.      activated. If you move the mouse slowly, the  windows  under  the
  90.      mouse  get  activated.  In  the  one  extrem,  windows  only  get
  91.      activated after  you  stopped  the  mouse  movement.  This  helps
  92.      minizing the "jumping" of the pointer on 68000 based Amigas  when
  93.      a window gets activated, because AmigaOS has to redraw the border
  94.      of the window which got activated and has no time left for moving
  95.      the pointer. After the  border  has  been  redrawn,  the  pointer
  96.      jumps. On faster Amigas, e.g. the A3000, the  "jumping"  is  less
  97.      noticable, at least when you  move  the  mouse  slowly.  On  this
  98.      machines you can allow SMaus to activate windows at once, as long
  99.      as you move the mouse slowly.
  100.  
  101.      Time: Unfortunately SMaus and Autopoint can't be informed by  the
  102.      OS, if a new window or screen has been opened or the front screen
  103.      has been changed. Therefore SMaus and Autopoint  always  have  to
  104.      look which window is under the  mouse  pointer  after  a  certain
  105.      time. This technic is known as "polling" and  must  be avoided on
  106.      multitasking operating systems like AmigaOS. But  as  the  window
  107.      under the mouse pointer should be active, SMaus  for  example has
  108.      to test if another window opened active and the window under  the
  109.      pointer has to be reactivated, etc. With SMaus you can select the
  110.      time, after which SMaus tests this, or  disable  this  option  at
  111.      all. You may increase the timeout to minimize CPU usage. With the
  112.      additional option "Keypress" (described below) you may  select  a
  113.      great timeout without disadvantages.
  114.  
  115.      Keypress: If you like it, SMaus activates the  window  under  the
  116.      pointer at any key pressed.
  117.  
  118.      Mousemovement by keyboard: SMaus recognizes  mousemovements  done
  119.      by keyboard using  an  Amiga  key  and  the  cursor  keys.  SMaus
  120.      activates the window under the pointer after movement.
  121.  
  122.      Often it would be better not to activate  the  window  under  the
  123.      pointer. The  following  options disable  the  window  activation
  124.      temporarily:
  125.  
  126.      Window title: you can specify titles of windows, which are  never
  127.      to  be  deactivated.  You  can  use  normal   AmigaOS   wildcards
  128.      therefore. Thus you can tell SMaus not to deactivate e.g. windows
  129.      called "System request" or "Arq", because you'd  like  to  answer
  130.      this requesters with the keyboard immediately.
  131.  
  132.      Screen title: like window titles, you may specify screen  titles.
  133.      If the screen title of the frontmost screen matches,  SMaus  does
  134.      nothing on this screen.
  135.  
  136.      System  requesters:  they  don't  get  deactivated.  This  option
  137.      doesn't work with some requester replacements like "Arq".
  138.  
  139.      Already active windows don't get activated  again.  SMaus  has  a
  140.      graphical user interface for easy configuration. You can  save  a
  141.      configuration and load it. SMaus has been  programmed  respecting
  142.      the rules of AmigaOS. No OS functions get patched. SMaus has been
  143.      programmed on an A3000 with SAS/C and has been  tested  with  the
  144.      debugging tools Enforcer and Mungwall.
  145.  
  146.  
  147.                             System requirements
  148.  
  149.      SMaus requires at least AmigaOS 2.04, Kickstart  version  37.175.
  150.      If you have Workbench 2.1, version 38.xx or better, you can use a
  151.      localized user interface. This means SMaus uses messages in  e.g.
  152.      german language. SMaus will not work with AmigaOS 1.2 or 1.3.
  153.  
  154.  
  155.                               Starting SMaus
  156.  
  157.      Before you test  SMaus,  please  make  sure  you're  not  running
  158.      autopoint at  the  same  time.  Remove  autopoint  by  using  the
  159.      Commodities Exchange utility provided by AmigaOS.
  160.  
  161.      You may start SMaus either from Shell or by  double  clicking  on
  162.      its icon. If you haven't changed any tool type in  SMaus's  icon,
  163.      double clicking on it starts SMaus and tells the program to  open
  164.      its window immediately. As SMaus can't run  twice  simultanously,
  165.      because there's no sense in doing so. Starting SMaus  twice  will
  166.      tell the first running copy of SMaus to open its window.  If  you
  167.      want to start SMaus from the shell and be able to close the shell
  168.      afterwards, use
  169.  
  170.                            Run >NIL: <path>SMaus
  171.  
  172.      to start it.
  173.  
  174.      Now it's time to explain the various options:
  175.  
  176.  
  177.                                   Options
  178.  
  179.      Activation Threshold:
  180.  
  181.      With the top most slider in SMaus's window  you  can  change  the
  182.      threshold for the speed of mouse movement,  above  which  windows
  183.      don't get activated at once. The speed of movement is measured in
  184.      pixel/event. Just test this: select a threshold of  0.  Now  move
  185.      the pointer across window borders. Nothing will  happen.  But  if
  186.      you  stop  the  movement,  the  window  under  the  pointer  gets
  187.      activated. Threshold 0 means: activate after movement. You  might
  188.      prefer this on 68000 based machines. Now select a threshold of  2
  189.      and move the mouse very slowly across window borders. The windows
  190.      will get activated immediately. Now move the pointer fast over a
  191.      window without stopping in his boundaries. The window didn't  get
  192.      activated. Why? Just increase the threshold and do it again.  The
  193.      window got activated, if the threshold was big  enough,  but  you
  194.      may have noticed this ugly "jumping" of the mouse pointer. On  my
  195.      A3000 I prefer a threshold of 1.
  196.  
  197.      Reactivate windows after:
  198.  
  199.      The second slider determines the time, after which SMaus tests if
  200.      the window under the mouse pointer is  still  active.  If  it  is
  201.      inactive, it will be reactivated. This  timeout  is  measured  in
  202.      1/10  seconds.  0/10  disables  this  feature.  Default  is  5/10
  203.      seconds, what means half a second. Increasing  this  value  saves
  204.      CPU time. If you use the option "Keypress", too, you may increase
  205.      this value without any disadvantages.
  206.  
  207.      Don't deactivate this windows:
  208.  
  209.      In this string gadget you can specify titles  of  windows,  which
  210.      are not to be deactivated. You may use normal AmigaOS  wildcards.
  211.      Example: Arq#? doesn't disable windows with a title  that  starts
  212.      with  Arq.  For  further  information  read  the  chapter   about
  213.      wildcards  in  your  AmigaDOS  manual.  Please  note,  that   the
  214.      comparison is case dependant. Some more examples:
  215.  
  216.      (Arq#?|#?estion#?)  -  all  titles  beginning   with   "Arq"   or
  217.      containing "estion", e.q. question.
  218.  
  219.      (#?[Rr]equest|Arq#?|#?[Mm]essage|Choose #?) -  all  titles,  that
  220.      end with "Request" or "request", or start with "Arq" or "Choose".
  221.  
  222.      If the pattern is  not  syntactically  correct,  e.g.  a  bracket
  223.      misses, SMaus will tell you this.
  224.  
  225.      Do nothing on these screens:
  226.  
  227.      In  this  string  gadget  you  specify  titles  of  screens,  with
  228.      wildcards, as above.  If the title of the frontmost screen matches
  229.      the contents of this stringgadget, SMaus does absolutely nothing.
  230.  
  231.      Hotkey to open this window:
  232.  
  233.      In this string gadget you put a description of the hotkey,  which
  234.      shall open SMaus's window. Examples:
  235.  
  236.      lcommand f1 - open window on left Amiga + F1
  237.      ctrl help   - open window on ctrl + help key
  238.  
  239.      SMaus uses commodities.library's input description strings:
  240.  
  241.                          Input description strings
  242.  
  243.      With input description strings you can specify almost  any  input
  244.      action, for example the action lshift f1, that is  pressing  the
  245.      left shift and the f1 key together.
  246.  
  247.      Input description strings have the following template:
  248.  
  249.          [class] (([-]qual)|syn)* [[-]upstroke] [highmap|ANSIcode]
  250.  
  251.      (* means: zero or more occurances of the expression in brackets)
  252.  
  253.      class   is one of the following strings:
  254.              rawkey, rawmouse, event, pointerpos, timer, newprefs,
  255.              diskremoved, diskinserted.
  256.              If not specified, the class is supposed to be "rawkey".
  257.  
  258.      qual    is one of the strings:
  259.              lshift, rshift, capslock, control, lalt, ralt, lcommand,
  260.              rcommand, numericpad, repeat, midbutton, rbutton,
  261.              leftbutton, relativemouse
  262.              A preceding '-' means that the value of the corresponding
  263.              qualifier is to be considered irrelevant.
  264.  
  265.      syn     (synonym) is one of the strings: shift, caps, alt
  266.              shift means "left or right shift"
  267.              caps means "shift or capslock"
  268.              alt means "either alt key"
  269.  
  270.      upstroke (literally "upstroke")
  271.              if this token is absent, only downstrokes are considered
  272.              for rawmouse (mousebuttons) and rawkey events.  If only
  273.              this is present, only upstrokes count.  If it is preceded
  274.              by '-'  both, up and down strokes, are included.
  275.  
  276.      highmap one of the strings:
  277.              comma, space, backspace, tab, enter, return, esc, del, up,
  278.              down, right, left, help, f1, f2, f3, f4, f5, f6, f7, f8,
  279.              f9, f10, 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, (, ), /, *, -, +
  280.  
  281.      ansicode a single character token is interpreted as a character
  282.              code, which is looked up in the system default keymap.
  283.  
  284.      The names of the keywords above may vary  in  other  versions  of
  285.      AmigaOS or new descriptors may be added.  SMaus  will  unterstand
  286.      them. Please consult your AmigaOS documentation.
  287.  
  288.      Activate by mouse:
  289.  
  290.      With this cycle  gadget  you  select  if  mouse  movements  shall
  291.      activate the window under the pointer at  all  and  wether  mouse
  292.      movements shall activate normally or  always.  "Normally"  means:
  293.      activate,  if  not  the  options  "WindowNot"  or  "StringGadNot"
  294.      prohibit the activation. E.g. if a string gadget  is  active,  no
  295.      window will be activated. "Always" means activate really always.
  296.  
  297.      Activate by key:
  298.  
  299.      When this option is enabled, SMaus activates the window under the
  300.      mouse pointer if you press any key of the keyboard.
  301.  
  302.      Don't deactivate windows with active string gadget:
  303.  
  304.      If you enable this, SMaus won't deactivate  windows  with  active
  305.      string gadgets. Please notice, that this will not work  correctly
  306.      if you specify a too small timeout for reactivation  of  windows,
  307.      because a program  might  open  a  window  and  before  it  could
  308.      activate the string gadget, SMaus may  already  have  deactivated
  309.      its window.
  310.  
  311.  
  312.                                Other gadgets
  313.  
  314.      Hide:
  315.  
  316.      This button or the close gadget or  the  ESC  key  close  SMaus's
  317.      window without quitting.
  318.  
  319.      About:
  320.  
  321.      This shows you some information about the program.
  322.  
  323.      Quit:
  324.  
  325.      This button removes SMaus completely.
  326.  
  327.  
  328.                                    Menu
  329.  
  330.      Configuration open/save:
  331.  
  332.      With this two menu items you can save all your prefered  settings
  333.      in a  selectable  config  file  or  load  a   previously   saved
  334.      configuration.
  335.  
  336.  
  337.                                Installation
  338.  
  339.      If you want to start SMaus any time you boot   your  Amiga,  just
  340.      drag SMaus's icon to your WBStartup drawer. If you'd  like  SMaus
  341.      to use other languages, e.g.  german,  please  read  the  chapter
  342.      "languages".
  343.      If you want to start SMaus in your User-Startup, add the line
  344.  
  345.                       Run >NIL: <path>SMaus <otions>
  346.  
  347.      to it,  after  replacing  <path>  with  the  path  to  the  SMaus
  348.      executable and <options> with your prefered options. Example:
  349.  
  350.                Run >NIL: SYS:Tools/SMaus from s:SMaus.config
  351.  
  352.  
  353.                                 Tool Types
  354.  
  355.     You may add the following tooltypes  to  its  icon  to  configure
  356.     SMaus:
  357.  
  358.      From=<filename>         The name of a configfile to load.
  359.                              The configfile will be read before
  360.                              other tool types are parsed. So
  361.                              tool types will overrule the same
  362.                              options of the configfile.
  363.  
  364.      CX_Priority=<num>       The priority of SMaus in the list of
  365.                              commodities.
  366.  
  367.      CX_Popkey=<string>      The input description string for the
  368.                              hotkey.
  369.  
  370.      CX_Popup                If Smaus finds this tool type, it will
  371.                              immediately open its window.
  372.  
  373.      Timeout=<num>           The prefered timeout for window
  374.                              reactivation.
  375.  
  376.      Threshold=<num>         Threshold in pixel/event below which
  377.                              windows get activated immediately by
  378.                              mouse movement.
  379.  
  380.      Priority=<num>          The priority of the SMaus process.
  381.                              If you use the option "keypress", the
  382.                              priority gets automatically raised to
  383.                              21.
  384.  
  385.      WindowNot=<string>      The pattern describing windows which
  386.                              are not to be deactivated.
  387.  
  388.      ScreenNot=<String>      The pattern describing the screens on
  389.                              which SMaus mustn't do anything.
  390.  
  391.      Keypress                Turn on activation by keypress.
  392.  
  393.      MouseNever              Turn off activation by mouse.
  394.  
  395.      MouseAlways             Mouse movements activate always.
  396.  
  397.      NoStringGad             Don't deactivate windows with active
  398.                              string gadgetgs
  399.  
  400.      Here's the template if you want to start SMaus from Shell:
  401.  
  402.      CX_Priority/K/N,CX_Popkey/K,CX_Popup/S,Timeout/K/N,Threshold/K/N,
  403.      Priority/K/N,ScreenNot/K,WindowNot/K,Keypress/S,MouseNever/S,
  404.      MouseAlways/S,NoStringGad/S,From/K
  405.  
  406.      As you see these options are the same as the tool types. Please
  407.      notice that you have to put double quotes around options,
  408.      which contain a blank. Example:
  409.  
  410.                             cx_popkey "ctrl f1"
  411.  
  412.  
  413.                                 Config file
  414.  
  415.      SMaus's config file is an ASCII file, that means, you may  create
  416.      and change this file with your prefered editor. Every line in the
  417.      configfile has to look like the options part if you  start  SMaus
  418.      from a Shell. Lines starting with ";" are treated as comments.
  419.      Example of a configfile:
  420.  
  421.           ---- beginning of file ----
  422.           ; Comment
  423.           KeyPress NoStringGad
  424.           MouseAlways
  425.           Threshold 1
  426.           Timeout 10
  427.           ScreenNot "Post#?"
  428.           WindowNot "(Arq#?|#?equest #?|#?essage#?|System#?)"
  429.           CX_Popkey "lcommand control f2"
  430.           ---- end of file ----
  431.  
  432.      Please  notice  again  the  double  quotes  around  options  line
  433.      WindowNot. Please notice  also,  that  saving  the  configuration
  434.      within SMaus creates a completly new config file. Comments in the
  435.      old config file will be lost.
  436.  
  437.  
  438.                                 SMaus_nowin
  439.  
  440.      SMaus_nowin is a special version of  SMaus  without  a  graphical
  441.      user interface and without a window. If you're short  on  memory,
  442.      this version saves you some of it.
  443.  
  444.  
  445.                                  Languages
  446.  
  447.      If you use Workbench V2.1 or higher, you have  a  library  called
  448.      "locale.library". This library  allows  programs  easy  usage  of
  449.      message catalogs in different  languages.  SMaus  plus  a  german
  450.      message catalog makes a  SMaus with a german user interface, with
  451.      german error messages etc. If you've got a  message  catalog  for
  452.      SMaus in your native language, you  can  have  SMaus  using  your
  453.      language. But these message catalogs must be created  exclusively
  454.      for every  program.  The  message  catalog  for  SMaus  is  named
  455.      SMaus.catalog.  Unfortunately  I  only  speak  German  and   some
  456.      English, so I can only provide you with a German message  catalog
  457.      (the English message catalog is built in). But you may  create  a
  458.      message catalog for SMaus in your native language if you  have  a
  459.      software developing tool called "CatComp" by Commodore:
  460.  
  461.      First create a directory Catalogs/<language> in SMaus's  catalogs
  462.      directory. With
  463.  
  464.            CatComp SMaus.cd CTFILE Catalogs/<language>/SMaus.ct
  465.  
  466.      you make  an empty  translation file. Fill up the empty lines  in
  467.      this file with the translation of the english messages below  the
  468.      empty line. After this insert  "SMaus.catalog"  and  the  version
  469.      number 1.0 in the first line. In  the  third  line  you  have  to
  470.      insert the name of the language, as you  can  select  it  in  the
  471.      prefs editor "Locale", e.g. français. With
  472.  
  473.            CatComp SMaus.cd Catalogs/<language>/SMaus.ct CATALOG
  474.                    catalogs/<language>/SMaus.catalog"
  475.  
  476.      you create the message catalog for <language>.
  477.  
  478.      If you have a message catalog for SMaus in a language you want,
  479.      you have to do this to make SMaus use this catalog.
  480.  
  481.      First, you have to choose the language as the prefered language
  482.      in the preferences editor Locale.
  483.  
  484.      Second,  locale.library  must  be   able   to   find   the   file
  485.      SMaus.catalog.  locale.library  tries  to  open  the  catalog  as
  486.      Catalogs/<language>/SMaus.catalog in  the  directory,  where  the
  487.      SMaus executable resides. If it can't find it there, it tries  to
  488.      open Locale:catalogs/<language>/SMaus.catalog.
  489.  
  490.      Now you may copy SMaus.catalog to  Locale:catalogs/<language>  or
  491.      create a subdirectory catalogs/<language> in the directory, where
  492.      the SMaus executable resides and copy SMaus.catalog there.
  493.  
  494.      PLEASE send me  the translation files if you translate SMaus into
  495.      your native language. Thank you!
  496.  
  497.  
  498.                                   History
  499.  
  500.      V1.15   first international version of SMaus
  501.      V1.16   not released
  502.      V1.17   changed small bug in the code which reads the config file
  503.              which could lead to loosing some bytes (140 or so);
  504.              checkmark gadgets are now scaled;
  505.              recompiled with SAS/C 6.2
  506.      V1.22   if no window was active, no window got ever activated
  507.              (found by Andreas M. Kirchwitz);
  508.              the loadconfig-filerequester had a wrong title (found by
  509.              Mikael Silfver); now a svenska catalog file done by
  510.              Mikael Silfver is supplied; recompiled with SAS/C 6.3;
  511.              some internal changes
  512.      V1.24   SMaus crashed on some machines when adjusting the timeout
  513.              slider; with the help of Mikael Silfver (he provided a
  514.              concrete example how to produce this crash and tested
  515.              new versions; nevertheless the crash never showed up on my
  516.              two machines, but I could figure out what might go wrong)
  517.              I could fix this.
  518.  
  519.  
  520.                                   Support
  521.  
  522.      If you have any suggestions,  bug  reports  etc.,  feel  free  to
  523.      contact the author of SMaus at the below address.
  524.  
  525.  
  526.          Stefan Sticht
  527.          Bibereckerweg 40a
  528.          D-94036 Passau
  529.          Germany
  530.  
  531.          EMail:
  532.          Internet: sticht@edith.deg.sub.org
  533.          Fido: Stefan Sticht (2:246/200.4)
  534.  
  535.  
  536.      T h a n k  y o u  f o r  r e g i s t e r i n g!
  537.  
  538.      Greetings, Stefan Sticht
  539.