home *** CD-ROM | disk | FTP | other *** search
/ Amiga Format 106 / af106a.adf / archives / serious.lzx / ARQ / Arq.doc < prev    next >
Encoding:
Text File  |  1997-02-28  |  13.6 KB  |  498 lines
  1.  
  2.  
  3.      Page 1                      Arq 1.83                       Page 1
  4.  
  5.  
  6.  
  7.  
  8.  
  9.  
  10.  
  11.  
  12.  
  13.  
  14.  
  15.  
  16.  
  17.  
  18.  
  19.  
  20.  
  21.                             Arq's Documentation
  22.                    Copyright © 1990-94 by Martin Laubach
  23.                             All rights reserved
  24.  
  25.                                     Arq
  26.                    Copyright © 1990-94 by Martin Laubach
  27.                             All rights reserved
  28.  
  29.  
  30.  
  31.  
  32.  
  33.  
  34.  
  35.  
  36.  
  37.  
  38.  
  39.  
  40.  
  41.  
  42.  
  43.  
  44.  
  45.  
  46.  
  47.  
  48.  
  49.  
  50.  
  51.  
  52.  
  53.  
  54.  
  55.  
  56.  
  57.  
  58.  
  59.  
  60.  
  61.  
  62.  
  63.  
  64.  
  65.      Page 2                      Arq 1.83                       Page 2
  66.  
  67.  
  68.  
  69.   1. Introduction      
  70.  
  71.        Arghh! There it is again... Your favorite application just
  72.      wanted to inform you of some important event. And there it
  73.      appears, the much-hated standard system requester, that
  74.      itty-bitty window that seems glued forever to the upper left
  75.      edge of the screen, a requester that can only be acknoledged
  76.      using the mouse or some much too cryptic key combination (Hmm,
  77.      I've been reading too many bad novels lately...?) 
  78.  
  79.  
  80.   2. Who and why    
  81.  
  82.        Especially Peter was very unhappy with the new style
  83.      requesters in 2.0 (he didn't like the 1.3 version either) --
  84.      "They have redone Workbench, it now looks slick and shiny, but
  85.      those requesters are about as ugly as they could be", and "the
  86.      design of the new requesters has already improved quite a bit --
  87.      compared to Kickstart 1.3. But yet they are not yet
  88.      state-of-the-art".  
  89.  
  90.        Having seen one of my (mjl's) earlier tools, "CR", that
  91.      remapped the requesters under 1.3 to something a bit more
  92.      appealing to the eye (and IMHO, kinda much more user friendly),
  93.      he came up with the idea of redesigning those dialog boxes.  
  94.  
  95.        In the beginning, I was not quite happy about rewriting my
  96.      code to suit his rather perfectionist ideas ("now leave two
  97.      pixels here, and don't forget that line of gray to the
  98.      right...") -- no idea how he's done it, but he finally got me to
  99.      the point to do him the favor.  
  100.  
  101.        So here's the result. Note that it is trimmed to fit the "new
  102.      look" of Workbench 2.0 (hires interlace -- any other resolution
  103.      will make it look a bit weird).  
  104.  
  105.  
  106.   3. What      
  107.  
  108.        Arq, abreviation for -- well, I forgot --, is a little utility
  109.      to improve the look and feel of system requesters under AmigaOS
  110.      2.0. I won't say more... Or, as Peter put it: 
  111.  
  112.        "If you were ever used to those really professional
  113.      Custom-Requesters for KS 1.3 from mjl, you were missing those
  114.      under AmigaOS-2. Well -- here they are!" 
  115.  
  116.        Since 1.57, Arq features a sound interface -- any appearing
  117.      requester now may be accompagnied by some user-definable sound.
  118.      Please refer to the respective chapter for more information
  119.      about the sound interface.  
  120.  
  121.        Arq wedges into Intuition's AutoRequest(), EasyRequest() and
  122.  
  123.  
  124.      What
  125.  
  126.  
  127.      Page 3                      Arq 1.83                       Page 3
  128.  
  129.  
  130.      DisplayBeep() vectors (as well as CloseScreen(), but you won't
  131.      notice that one), and replaces each of those routines by our
  132.      artist's idea of a requester, which is much more flexible and
  133.      user friendly than the system's standard requester.  
  134.  
  135.        Note that the graphics are stored in fax-like compression
  136.      format. This means that you (a) won't be able to compress it
  137.      much further, (b) having several Arq requesters open on a plain
  138.      vanilla 68000 will slow down the system a bit.  
  139.  
  140.  
  141.        This archive should contain 
  142.             Arq ......... The executable
  143.             Arq.doc ..... What you are reading now
  144.             Arq.h ....... Include file for special features
  145.             upd ......... The ARexx sound player daemon
  146.             upd.doc ..... And its accompanying documentation
  147.  
  148.   4. How to     
  149.  
  150.        Just "run arq" and enjoy the improved system messages. To stop
  151.      it, just send it a ^C via the "break" command (though I doubt
  152.      you'll ever want to quit it).  
  153.  
  154.        Under 2.0, you can control Arq with the Commodities Exchange
  155.      tool. You may freely enable, disable, or kill Arq. Also,
  156.      starting Arq a second time, will remove itself from the system.  
  157.  
  158.        The main advantage of those requesters is (apart their look),
  159.      that we moved the strange combination of Left-Amiga-V and
  160.      Left-Amiga-B (of course those are working too, special favor to
  161.      Andy Finkel) to the ESC and RETURN key, which makes life quite a
  162.      lot easier (no more knots in your fingers).  
  163.  
  164.        Another possibility is to use the function keys, where F1
  165.      corresponds to the leftmost, F2 to the second, and so forth,
  166.      gadget -- that way you can answer requesters with more than two
  167.      buttons, like IconEdit's.  
  168.  
  169.        Though written with 2.0 in mind, Arq does work under 1.3 as
  170.      well -- but the layout will look a bit stretched in
  171.      non-interlace mode. Sorry about that -- it really doesn't look
  172.      all that bad...  
  173.  
  174.        Please also note that this command replaces some of the
  175.      library vectors in intuition.library -- restoring them is per
  176.      definitionem not a safe operation.  While this works most of the
  177.      time, you may witness wonderful things happening when there is
  178.      another tool (like srt) wedged in after Arq.  So please be
  179.      careful.  
  180.  
  181.        A favorite seems to install AssignX in conjunction with Arq --
  182.      please note that when using a bigger system font, Arq will find
  183.      the so changed requester too big to be opened, and use the
  184.  
  185.  
  186.      How to
  187.  
  188.  
  189.      Page 4                      Arq 1.83                       Page 4
  190.  
  191.  
  192.      original system requester instead. THIS IS NOT A BUG, but an
  193.      intended feature.  
  194.  
  195.  
  196.   5. Sounding away     
  197.  
  198.        Instead of building the sound capability into Arq itself, we
  199.      chose to implement it following the client-server model:  a
  200.      sound playing server, as, for example the "upd" sound daemon by
  201.      Jonas Petersson will do all the hard work, giving you the
  202.      additional bonus of being able to play your favorite tunes from
  203.      your ARexx programs...  
  204.  
  205.        The following sound IDs are used, for the corresponding
  206.      requesters and DisplayBeep -- please refer to upd's
  207.      documentation how these work.  
  208.  
  209.           · warn_write_protected
  210.           · warn_insert_volume
  211.           · warn_delete
  212.           · warn_printer
  213.           · error_task_held
  214.           · error_read_write
  215.           · error_general
  216.           · warn_general
  217.           · query_general
  218.           · beep
  219.  
  220.  
  221.   6. Programmabilities      
  222.  
  223.        Often some application would display a requester e.g. in a
  224.      different language, thus Arq was unable to choose the correct
  225.      graphics to display.  To circumvent this problem, Arq features
  226.      third-party programmable animations and images since version
  227.      1.64.  
  228.  
  229.        The problem was how to extend the usual EasyStruct without
  230.      disturbing the correct working on machines without Arq installed
  231.      or with an older version of Arq. Our (yes, it's strange)
  232.      solution is to stick a non-breaking space (0xA0) in
  233.      easy.es_Title.  
  234.  
  235.  
  236.  
  237.  
  238.  
  239.  
  240.  
  241.  
  242.  
  243.  
  244.  
  245.  
  246.  
  247.  
  248.      Programmabilities
  249.  
  250.  
  251.      Page 5                      Arq 1.83                       Page 5
  252.  
  253.  
  254.        The extended EasyStruct looks like this (and can be found in
  255.      arq.h): 
  256.  
  257.             struct ExtEasyStruct
  258.                     {
  259.                     struct Image *Image;
  260.                     char *Sound;
  261.                     WORD AnimID;
  262.                     UWORD Flags;
  263.                     ULONG Magic;
  264.                     ULONG Reserved[3];
  265.                     struct EasyStruct Easy;
  266.                     };
  267.  
  268.        To trigger the recognition of an extended structure, you have
  269.      to put a non-breaking space in easy.Easy.es_Title, and fill
  270.      easy.Magic with the value ARQ_MAGIC.  
  271.  
  272.        Only then Arq will look at the extra fields to determine which
  273.      imagery should be displayed.  
  274.  
  275.        You have the following possibilities: 
  276.  
  277.        One: Put the ID of the scene you want to appear into
  278.      easy.AnimID -- Arq will display the animation of your choice.
  279.      For example, stuff ARQ_ID_GURU in that field (see the include
  280.      file arq.h for more ID names), and no matter what the requester
  281.      text is, you will always get the guru graphics.  
  282.  
  283.        Two: Put ARQ_ID_IMAGE into easy.AnimID, and a pointer to a
  284.      struct Image into easy.Image. Arq will then display the (static)
  285.      image you provided instead of any built-in imagery. If
  286.      easy.Sound is non-NULL, Arq will also attempt to play the sound
  287.      with the given name (please refer to the chapter about "upd" and
  288.      sounds for more details).  
  289.  
  290.        After having filled out the ExtEasyStruct structure, submit it
  291.      to the EasyRequest() routine, like this: 
  292.  
  293.             EasyRequest(&MyExtEasyStruct->Easy) 
  294.  
  295.  
  296.   7. Recent changes     
  297.  
  298.        In version 1.61, people complained that, if Arq opened its
  299.      requester while some screen obscures the active screen, they
  300.      would not notice the requester. So this was changed to the first
  301.      screen in 1.66. Now people are actually complaining it opening
  302.      on the first screen. I've changed it back to the active screen.
  303.      Oh well.  
  304.  
  305.        The buttons have a visual feedback for keyboard operation
  306.      since 1.66.  
  307.  
  308.  
  309.  
  310.      Recent changes
  311.  
  312.  
  313.      Page 6                      Arq 1.83                       Page 6
  314.  
  315.  
  316.        For 1.83, I incorporated much of the enhancements suggested
  317.      that I could fit in my rather tight spare time. I'm afraid, some
  318.      of the things I wanted to add are still outstanding, but I felt
  319.      a new release tackling known problem areas were more important
  320.      right now. Rest assured I have not forgotten your enhancement
  321.      request...  
  322.  
  323.  
  324.   8. License      
  325.  
  326.        This material is © Copyright 1990-94 by Martin J. Laubach. All
  327.      rights reserved. Graphics are © Copyright 1990-91 by Peter
  328.      Wlcek.  
  329.  
  330.        It may be distributed freely as long as the following
  331.      restrictions are met: 
  332.  
  333.        The distributor may charge a fee to recover distribution
  334.      costs. The fee for diskette distribution should not be more than
  335.      the cost to obtain the same diskette from Fred Fish.  
  336.  
  337.        The distributor agrees to cease distributing the programs and
  338.      data involved if requested to do so by the authors.  
  339.  
  340.        You may copy and distribute verbatim copies of the program's
  341.      executable code and documentation as you receive it, in any
  342.      medium, provided that you conspicuously and appropriately
  343.      publish only the original, unmodified program, with all
  344.      copyright notices and disclaimers of warranty intact and
  345.      including all the accompanying documentation, example files and
  346.      anything else that came with the original.  
  347.  
  348.        The author will not be liable for any damage arising from the
  349.      failure of this program to perform as described, or any
  350.      destruction of other programs or data residing on a system
  351.      attempting to run the program.  While I know of no damaging
  352.      errors, the user of this program uses it at her or his own
  353.      risk.  
  354.  
  355.  
  356.  
  357.  
  358.  
  359.  
  360.  
  361.  
  362.  
  363.  
  364.  
  365.  
  366.  
  367.  
  368.  
  369.  
  370.  
  371.  
  372.      License
  373.  
  374.  
  375.      Page 7                      Arq 1.83                       Page 7
  376.  
  377.  
  378.   9. Acks and Naks    
  379.  
  380.           Additional code by René Hexel.
  381.           Amiga and AmigaDOS are trademarks of Commodore-Amiga, Inc.
  382.           ARexx by William S. Hawes.
  383.           Graphics inspired by Michael Karlsson
  384.           Nagging by ZZA (next version, I promise!)
  385.           Perfectionism by Peter Wlcek.
  386.           Teasing by MCP on #amigager.
  387.           upd by Jonas Petersson.
  388.           Window centering code by Holger Gzella, with additional
  389.                    comments by Peter Cherna.
  390.  
  391.  
  392.   10. Postscript      
  393.  
  394.         We are not really happy yet with the graphics for "?" and
  395.      "!". Should you have "THE" idea, please get in touch with any of
  396.      us...  
  397.  
  398.        Also, don't hesitate to yell when you've got graphics you'd
  399.      like to see in the next version. As of version 1.66 I've heard
  400.      very little "direct" response -- I was able to catch a few
  401.      comments in some newsgroups, but that's it basically. Remember,
  402.      if you don't tell me (me, and not some unrelated, innocent
  403.      people in some newsgroup/usergroup/echomail conference) what
  404.      problems or ideas you have, chances are good you won't find them
  405.      realised in future versions.  
  406.  
  407.  
  408.   11. Reactions      
  409.  
  410.        If you have any comments, ideas what could or should be
  411.      improved, bug reports or just like to chat a bit, please feel
  412.      free to contact me at one of the following addresses... I just
  413.      *love* receiving mail! 
  414.  
  415.        FidoNet: 2:310/3.14 
  416.        Usenet:  mjl@alison.co.at (home) 
  417.                                mjl@auto.tuwien.ac.at (work) 
  418.  
  419.        Peter, the graphics and animation wizard, can be reached
  420.      2:310/42 in FidoNet.  
  421.  
  422.        Looking forward to reading from you, 
  423.  
  424.              mjl 
  425.  
  426.  
  427.  
  428.  
  429.  
  430.  
  431.  
  432.  
  433.  
  434.      Reactions
  435.  
  436.  
  437.      Page 8                      Arq 1.83                       Page 8
  438.  
  439.  
  440.   12. Road Map    
  441.  
  442.  
  443.  
  444.         1. Introduction     ....................................    2
  445.         2. Who and why   .......................................    2
  446.         3. What     ............................................    2
  447.         4. How to    ...........................................    3
  448.         5. Sounding away    ....................................    4
  449.         6. Programmabilities     ...............................    4
  450.         7. Recent changes    ...................................    5
  451.         8. License     .........................................    6
  452.         9. Acks and Naks   .....................................    7
  453.         10. Postscript     .....................................    7
  454.         11. Reactions     ......................................    7
  455.         12. Road Map    ........................................    8
  456.  
  457.  
  458.  
  459.  
  460.  
  461.  
  462.  
  463.  
  464.  
  465.  
  466.  
  467.  
  468.  
  469.  
  470.  
  471.  
  472.  
  473.  
  474.  
  475.  
  476.  
  477.  
  478.  
  479.  
  480.  
  481.  
  482.  
  483.  
  484.  
  485.  
  486.  
  487.  
  488.  
  489.  
  490.  
  491.  
  492.  
  493.  
  494.  
  495.  
  496.      Road Map
  497.  
  498.