home *** CD-ROM | disk | FTP | other *** search
/ Frozen Fish 2: PC / frozenfish_august_1995.bin / bbs / d09xx / d0964.lha / Angie / Angie.doc < prev    next >
Text File  |  1993-12-03  |  71KB  |  1,648 lines
  1.  
  2.               ----------------------------------------------
  3.               Angie 3.6 (3.12.93) ⌐ Franz Schwarz - Giftware
  4.               ----------------------------------------------
  5.  
  6.                ANother Great Intuition Enhancer - Commodity
  7.  
  8.                             Written & ⌐ 1993 by
  9.                                Franz Schwarz
  10.                               Mⁿhlenstra▀e 2
  11.                        D-78591 Durchhausen, Germany
  12.                     Uucp: Franz_Schwarz@mil.ka.sub.org
  13.                         Fido Classic: 2:2476/506.18
  14.  
  15.              GUI created with assistance of GadToolsBox 37.300
  16.  
  17.          Due to Angie being GIFTWARE, thou shalt send the author a
  18.         nice present, cash, or AT LEAST a postcard, if you use it.
  19.  
  20.        Gifts, the author appreciates very much include music tapes,
  21.            CDs & LPs of pop/rock/indie/blues/soul music. So, if
  22.                  you have any music volumes you can spare,
  23.                don't hesitate and send them to the author;-)
  24.  
  25.  
  26.                      Moreover, Angie is TOLERANCEWARE.
  27.          In other words, it is strictly forbidden for persons that
  28.          support or approve acts of violence against other people
  29.         because of their race, descent, skin color, gender, sexual
  30.           orientation, religion or handicap to use or take profit
  31.               of this software package in any way whatsoever.
  32.  
  33.  
  34.                              table of contents
  35.                              -----------------
  36.  
  37.                                   preface
  38.  
  39.                          concepts, program design
  40.  
  41.            ATTN. lazy boys and girls - WHAT EVERYONE SHOULD KNOW
  42.  
  43.                         the installation procedure
  44.  
  45.      the interactive user interface & the arguments passed on startup
  46.  
  47.                     the various Angie Intuition actions
  48.  
  49.                        the syntax of AngieSequences
  50.                        
  51.                             the arexx interface
  52.  
  53.                  programming info, implementation details
  54.  
  55.                               program history
  56.                               
  57.                                 final notes
  58.  
  59.                            contacting the author
  60.  
  61.                                   credits
  62.                                   
  63.                      appendix: how to define a hotkey
  64.  
  65.              appendix: tutorial / the supplied hotkey mapping
  66.  
  67.                                   
  68.  
  69.                                   preface
  70.                                   -------
  71.  
  72. Angie is a nice name as well as a terrific song by the Rolling Stones.
  73. From now on, this name is to be remembered in the Amiga community as well:
  74. Angie, i.e. this software's name is an acronym for
  75.  
  76.                     ANother  Great  Intuition  Enhancer 
  77.  
  78.  
  79.  
  80. The Angie commodity is dedicated to all Amiga users that are tired of using
  81. the many utilities that use dirty hacks and don't care about offical CBM
  82. access protocols.  Angie was written with the aim to provide you with a
  83. commodity that avoids illegal memory access and unsecured or undocumented
  84. access to global system shared data in all cases and by all means.
  85.  
  86.  
  87.  
  88.  
  89.  
  90.  
  91.                          concepts, program design
  92.                          ------------------------
  93.  
  94. In fact, the Angie commodity enhances Amiga's unique Intuition
  95. graphical user interface in many ways.  But what is even better:  It
  96. is thoroughly customizable by the user - i.e.  YOU; thus you have
  97. the ability to adapt it to your personal taste and likes in almost
  98. any way whatsoever.  This is accomplished by providing you with
  99. complete user control of almost all of Angie's significant
  100. characteristics from within a nitfy graphical user interface (and
  101. save them for later retrieval from there, of course)
  102.  
  103. Amongst Angie's capabilities there are automatic window hunting (i.e.
  104. active screen and active window to front, adjusting the display of
  105. over-sized autoscroll screens) as provided by J÷rg Bublath's HuntWindow,
  106. retrieval of the last active window & the last active screen on hotkey,
  107. remembering & retrieval the last active window of all screens (similar to
  108. Tron's TWA), and a hitherto unique 'Key screen activation' feature that
  109. activates the last window remembered (or the window under the mouse, or the
  110. screen's frontmost window if none is remembered) of the screen under the
  111. mouse *if, and only if* the active window is not placed in one of the at
  112. least partially visible screens and a key downstroke event is rushing in
  113. from the input device.  This feature has proved *very* ergonomic and nifty
  114. (in deed, it was actually the motivation for me to embark on this
  115. project;-)) Moreover, Angie can automatically raise the priority of the
  116. task that owns the currently active window (and restore it when the window
  117. becomes inactive, of course) However, the best is that Angie (don't you
  118. forget the triad:  the nice name, the terrific Rolling Stones song and the
  119. neat commodity we are talking about...) provides you with the ability to
  120. map arbitrary 'AngieSequences' to any number of arbitrary trigger input
  121. events.  'AngieSequences' may consist of Angie's sixty Intuition actions,
  122. arbitrary async / sync dos commands, raw ascii text and commodities input
  123. descriptions with arbitrary delays between each of the elements.  You may
  124. even choose whether the input event that triggers the respective operation
  125. shall be filtered or propagated to the other commodities objects.  Starting
  126. from version 3.5, you can feed Angie with AngieSequences via its ARexx
  127. port, too.
  128.  
  129.  
  130. Angie can take advantage of several V39 Intuition / GadTools and V38
  131. Commodities features but operates well with V37 Intuition/ GadTools/
  132. Commodities, too.
  133.  
  134.  
  135.  
  136.  
  137.            ATTN. lazy boys and girls - WHAT EVERYONE SHOULD KNOW
  138.            -----------------------------------------------------
  139.  
  140. EVERYONE should know that Angie is GIFTWARE - thus you shouldn't hesitate
  141. to send the author a gift, a small donation or AT LEAST a nice postcard if
  142. you use it.
  143.  
  144.  
  145. AS OF ANGIE 3.6 (the final version for 1993!), you can use the '╢'
  146. character (usually <alt p>) as a substitute for the linefeed character
  147. within dos_command_sequences.
  148.  
  149. AS OF ANGIE 3.6 you can use the configuration that is stored in the
  150. 'PROGDIR:Angie' icon by not supplying any arguments if you start Angie from
  151. the shell
  152.  
  153. AS OF ANGIE 3.5, Angie has an AREXX PORT named 'ANGIEREXX' that processes
  154. arbitrary AngieSequences you send to it.
  155.  
  156. AS OF ANGIE 3.3, hotkey list browsing has been highly optimized - this is
  157. especially of interest for all poor 68000/68010 users as this action has
  158. turned out to be very sluggish in former Angie versions on their machines.
  159. Angie's GUI now works great even with the most excentric proportional
  160. fonts.  In addition to this, AngieSequence execution backlogging is avoided
  161. and the user always gets an immediate feedback for GUI window inputs, no
  162. matter whether thousands of AngieSequences or auto hunts are waiting for
  163. execution.
  164.  
  165. AS OF ANGIE 3.1, three very useful utilities for the use in AngieSequences
  166. are supplied:  SetActiveWin, MagicPubName & RawInsert.  All are written and
  167. copyrighted by the author of Angie.  Have close look at their
  168. documentations for more details about them - have a VERY close look at
  169. the example AngieSequences in the documentation of SetActiveWin.
  170.  
  171. AS OF ANGIE 3.1, SyncDosSequences are executed differently:  NO CONSOLE is
  172. opened for them, and they run with the current task priority of Angie
  173. instead of the priority, Angie was started with.
  174.  
  175.  
  176.  
  177.                         NEW FEATURES OF ANGIE 3.0:
  178.  
  179. Angie 3.0 drops the restrictions of commodities.library V37-V40 in terms of
  180. parsing input descriptions:  For V37, the rawmouse keycodes
  181. 'MOUSE_LEFTPRESS', 'MOUSE_MIDDLEPRESS' & 'MOUSE_RIGHTPRESS' that are
  182. usually only available in commodities.library V38 or higher are supported.
  183. As of V40, commodities.library doesn't support keycodes for the keyboard
  184. qualifiers.  Angie allows you to use the rawkey keycodes 'CONTROL_PRESS',
  185. 'CAPS_PRESS', 'LSHIFT_PRESS', 'RSHIFT_PRESS', 'LALT_PRESS', 'RALT_PRESS',
  186. 'LAMIGA_PRESS' & 'RAMIGA_PRESS'.  These parsing extensions are made in a
  187. highly compatible manner, of course - they are likely to work in all
  188. future versions of commodities.library.  
  189. You should keep in mind that the inability of commodities.library V37 to
  190. apply the 'leftbutton', 'midbutton' & 'rbutton' qualifiers correctly is NOT
  191. affected by these internal enhancements of Angie.
  192.  
  193. IT IS MOST IMPORTANT FOR USERS UPGRADING FROM FORMER VERSIONS OF ANGIE TO
  194. KNOW THAT AS OF ANGIE 3.0, YOU ASSIGN 'ANGIESEQUENCES' TO YOUR HOTKEYS.  An
  195. 'AngieSequence' consists of ANY NUMBER of Angie's Intuition-related
  196. actions, arbitrary async or sync dos command sequences, raw ascii text
  197. sequences and commodities input descriptions, with arbitrary delays between
  198. each of the elements.  Thus, programming Angie is now much easier than in
  199. former versions (In translator terminology, you would say 'Angie 2.0
  200. ENABLED Angie programming, whereas Angie 3.0 SUPPORTS Angie programming').
  201. In other words, as of Angie 3.0, you can VERY EASILY ASSIGN MULTIPLE
  202. VARIOUS ACTIONS TO ONE SINGLE HOTKEY.  As a consequence of this
  203. trailblazing new concept, Angie 3.0 has now a different tooltypes format,
  204. whilst it is still capable of reading the old prefs format.
  205.  
  206. Another new feature of Angie 3.0 is the new 'NoFilter' attribute which
  207. replaces the old 'ToFront' attribute (that may now be specified separately
  208. for each element of an 'AngieSequence').  It has the effect that the
  209. respective input event that triggers the execution of the appertaining
  210. AngieSequence is left in the input stream rather than filtering it, which
  211. is the default.
  212.  
  213. Angie 3.0 has a new default auto hunt mode, called 'CapsLock1'.  The old
  214. 'CapsLock' mode of Angie 2.0 is optionally still available as 'CapsLock2'.
  215.  
  216. In the CapsLock* auto hunt modes, the CapsLock qualifier is alienated as a
  217. 'Hunt Always' toggle to change the mode on the fly.  For the CapsLock2
  218. mode, all CapsLock events along with the CapsLock qualifier are filtered by
  219. Angie (so they don't affect neither the hotkeys you defined within Angie
  220. nor any other brokers that are linked into the commodities network after
  221. Angie's broker).
  222.  
  223. UNTIL ANGIE 1.7, rawkey hotkeys inside and outside Angie that shuffled
  224. screens didn't work correctly in connection with an active Key Screen
  225. Activation feature if you neglected to specify the NoScrAct attribute for
  226. hotkeys inside Angie resp.  if you neglected to define NoKeyActivate pseudo
  227. hotkeys for foreign hotkeys.  Note that STARTING FROM ANGIE 2.0, this
  228. effect has vanished, as Angie now uses another, more complex -yet very
  229. compatible- method for its key screen activation action.  Unfortunately,
  230. UNTIL ANGIE 3.2, the documentation still reflected the ANGIE 1.7 state.
  231.  
  232.  
  233.  
  234.                               GENERAL ISSUES
  235.  
  236.  
  237. When does an auto hunt action happen????
  238.     An auto hunt action does not necessarily take place immediately when
  239.     a change is detected: If one or both of the left mouse button
  240.     and its keyboard equivalent (lalt amiga) are pressed, this action is
  241.     deferred until at least one of them is released. Furthermore, pressing
  242.     the right mouse button or keeping it pressed does always cancel resp.
  243.     inhibit any auto hunt action that is due. For the 'CapsLock*' auto hunt
  244.     modes, the same goes for an active (illuminated) capslock key, too.    
  245.  
  246.  
  247. You are advised to set the 'NoScrAct' attribute for all your rawkey hotkeys
  248. that shuffle screens and don't activate a window on the new frontmost
  249. screen and for your rawkey hotkeys that retrieve windows (i.e.  hotkeys
  250. mapped to actions like 'NextScreen', 'PrevScreen', 'WBenchScreen',
  251. 'HuntWindow', 'LastActive' or 'LastActiveScr') This keeps the respective
  252. rawkey events from triggering a key screen activation action (such an
  253. action is usually undesirable in these cases).
  254.  
  255. As for other commodities' / Intuition's rawkey hotkeys that perform such
  256. actions, key screen activation is usually undesirable, too, you can exclude
  257. those foreign hotkeys from triggering key screen activation action by
  258. defining NoKeyActivate pseudo hotkeys inside Angie for them.  These
  259. NoKeyActivate pseudo hotkeys have the only effect that Angie doesn't
  260. trigger key screen activation action for the respective rawkey input
  261. events.  E.g, you may exclude standard Intuition lcommand m/n screen
  262. shuffling from triggering a key screen activation action:
  263.                 'lcommand -repeat -caps -alt -control m' &
  264.                 'lcommand -repeat -caps -alt -control n' &
  265.                           'lcommand lamiga_press'
  266.                 (pseudo action from menu: 'NoKeyActivate')
  267.  
  268.  
  269.  
  270.  
  271. The STRING GADGETS of Angie have SPECIAL EDITING FEATURES:  'ESC'
  272. cancels the editing operation, and for the 'Edit Hotkeys' & 'Action'
  273. gadgets, the CURSOR UP/DOWN KEYS have a special functionality.
  274.  
  275. Pressing 'ESC' outside the string gadgets closes Angie's GUI window,
  276. pressing 'Z' zips the GUI window, and the cursor up/down keys can be used
  277. to browse through the hotkey list.
  278.  
  279.  
  280. All shell command line arguments that have values assigned need to be
  281. surrounded by quotes, e.g.  "CX_PRIORITY=127" instead of just
  282. CX_PRIORITY=127.
  283.  
  284.  
  285. As of version 2.0, Angie's support for the 'active screen yet no active
  286. window present' case has greatly improved:  Three of the consequences
  287. (there are many more):  
  288. 1.  The hotkey action 'HuntWindow' now hunts the active screen if no active
  289. window exists.
  290. 2. If key screen activation is selected
  291. and a (partially) visible screen is active along with no active window, a
  292. key screen activation action is issued (the preferred window for that
  293. specific action is the last active window of the active screen). 
  294. 3.  All hotkey actions based on windows cause a 'Key screen activation'
  295. action with a Hunt or WindowToFront() of the resulting window according to
  296. the hotkey's attributes if no active window exists.
  297.  
  298.  
  299.  
  300.                         the installation procedure
  301.                         --------------------------
  302.  
  303. The installation is done by the supplied 'InstallAngie' script.
  304.  
  305.  
  306.  
  307.      the interactive user interface & the arguments passed on startup
  308.      ----------------------------------------------------------------
  309.  
  310. The GUI conforms to Commodore's User Interface Style Guide, thus it should
  311. be mostly intuitive and self-explanatory to the User who is familiar with
  312. Commodore's commodities and preferences editors supplied with the operating
  313. system.  The usual commodities arguments 'CX_PRIORITY, CX_POPUP & CX_POPKEY
  314. are supported.
  315.  
  316. Notez-bien: If you start Angie from shell, all arguments that have values
  317. assigned need to be surrounded by quotes, e.g. 
  318. "CX_PRIORITY=127" instead of just CX_PRIORITY=127
  319.  
  320. You can use the configuration stored in the 'PROGDIR:Angie' icon if you
  321. specify the 'DEFAULTPREFS' argument or if you launch Angie from shell and
  322. don't specify any arguments at all.
  323.  
  324.  
  325. Following now is a brief description of the GUI elements and Angie's
  326. arguments:
  327.  
  328.  
  329. The 'Auto hunt mode' cycle gadget:
  330.     With this cycle gadget you can control Angie's automatic hunt feature.
  331.     This feature controls whether or not Angie shall automatically hunt,
  332.     A Hunt action consists of popping the active window & the active screen
  333.     to front & adapting the active screen's position so that as much of the
  334.     active window as possible is visible. It is done in a way that minimum
  335.     screen move takes place.  In case the window is too large to fit in the
  336.     actual display, the screen is moved so that the left/top edge of the
  337.     window is displayed in the left/top edge of the visible portion of the
  338.     screen - except for backdrop windows, where it is only ensured that the
  339.     screen's display clip is completely filled with the screen's data (i.e.
  340.     if the screen is dragged down, it will reposition, otherwise not). 
  341.     If the automatic hunt feature of Angie is active, a hunt operation is
  342.     issued whenever the active screen or the active window or the active
  343.     window's position or size have changed.
  344.  
  345.     An auto hunt action does not necessarily take place immediately when
  346.     a change is detected: If one or both of the left mouse button
  347.     and its keyboard equivalent (lalt amiga) are pressed, this action is
  348.     deferred until at least one of them is released. Furthermore, pressing
  349.     the right mouse button or keeping it pressed does always cancel resp.
  350.     inhibit any auto hunt action that is due. For the 'CapsLock*' auto hunt
  351.     modes, the same goes for an active (illuminated) CapsLock key, too.    
  352.  
  353.     There are four different cycle states for this gadget:
  354.     A: 'CapsLock1':  In this mode, Angie's auto hunt is always considered
  355.     to be on unless the CapsLock key is active (illuminated). The CapsLock
  356.     key is alienated as a 'Hunt Always' toggle to change the mode on the
  357.     fly. This mode is the default mode 
  358.     B: 'CapsLock2':  same as 'CapsLock1'. Additionally, all CapsLock events
  359.     and the CapsLock qualifier are swallowed by Angie and thus don't affect
  360.     Angie's hotkey definitions nor any brokers that are linked into the
  361.     commodities network after Angie's broker.
  362.     C: 'Always': In this mode, auto hunt is always on - no special CapsLock
  363.     magic takes place
  364.     D: 'Off': This selection turns auto window hunting permanently off.
  365.  
  366.     The argument for this toggle is 'AUTOHUNTMODE', it defaults to 
  367.     'CAPSLOCK1'
  368.  
  369.  
  370. The checkbox toggle gadgets:
  371.   
  372.   'Hunt on wintofront hotkeys' - if enabled, Angie performs an automatic
  373.     hunt (see above) operation whenever it issues a hotkey-bound
  374.     Window_To_Front.
  375.     The corresponding argument is 'HUNTMODEWFRONT' and defaults to 'YES' 
  376.     
  377.   'Hunt: set default public screen' - toggles the automatic declaration of
  378.     the active window's screen as the system's default public screen
  379.     whenever a hunt (see above) operation is done. If the active screen
  380.     is no public screen, the Workbench screen is set as default public
  381.     screen.
  382.     The argument for this toggle is 'HUNTMODESETDEFPUBSCR' and defaults to  
  383.     'NO'
  384.     
  385.   'Key screen activation' - (de)activates a nifty, hitherto unique
  386.     feature that activates the last active window of the screen under 
  387.     the mouse (or the window under the mouse, or the screen's frontmost
  388.     window if none is remembered) *if, and only if* the active window
  389.     is not placed in one of the at least partially visible screens and
  390.     a key downstroke event rushes in from the input.device.  This
  391.     feature has proved very ergonomic and nifty, especially if
  392.     immediate activation after screen shuffling is not appropriate
  393.     (indeed, this feature was actually the motivation for me to
  394.     embark on this project;-))
  395.     'KEYACTIVATE' is the argument for this, and defaults to 'YES'
  396.   
  397.   'Raise Active WinTask's Pri' - determines whether Angie should always
  398.     raise the priority of the task, the active window is associated with,
  399.     by one, and restore the old priority on deactivation if the priority
  400.     hasn't been changed by someone else in the meantime.
  401.     The correct argument is 'RAISEWINTASKPRI', default is 'YES'
  402.  
  403.   'Shuffle backdrop windows' - decides whether backdrop windows should be
  404.     considered when performing AngieSequence-bound window-shuffling or not.
  405.     The default is 'NO', the argument is named 'SHUFFLEBACKDROP'.
  406.     
  407.   'Pop GUI on startup' - if you want Angie's GUI window to pop open when
  408.     Angie is launched, set this toggle, otherwise switch it off.
  409.     The appertaining argument is 'CX_POPUP' and defaults to 'YES'.
  410.     
  411.     
  412. The sliders have the following significance:
  413.   
  414.   'Stable time' - this one is used to adjust the time in milliseconds, the
  415.     snoop task expects the active window, the active screen, the active  
  416.     window's size and its position to remain unchanged until it signals a
  417.     change to the main task. The valid range is -1 up to 1000, where -1 is
  418.     a magic value that signifies that whenever the snoop task detects
  419.     a change, it immediately signals the main task. All positive values 
  420.     including 0 require the snapshot data to remain unchanged for at
  421.     least two snoops and a minimum of 'Stable time' milliseconds before
  422.     the main task is signalled.
  423.     The argument for this characteristic is called 'STABLETIME' and defaults
  424.     to 20.
  425.  
  426.   'Snoop delay' - this is the delay time in milliseconds, the SnoopTask
  427.     should wait between two snoops.  The valid range is 10..1000.  Note that
  428.     the accuracy of this delay is bound to the frequency of the vertical
  429.     blanking interrupt, which is usually 50Hz PAL, 60Hz NTSC, 70Hz
  430.     EURO36/EURO72/SUPER72, that means, you'll never get more than 50 snoops
  431.     per second for PAL, never more than 60 snoops per second for NTSC and
  432.     never more than 70 snoops per second for EURO36/EURO72/SUPER72. 
  433.     Note that allocating a CIA timer for this job to gain accuracy would
  434.     be IMHO a waste of system resources. Huge values for this characteristic
  435.     yearn for a '-1' 'Stable time' setting.
  436.     The argument name for this value is 'SNOOPDELAY' and defaults to 30.
  437.   
  438.   'Screen steps' - use this slider to set the quantity a screen should be
  439.     moved with the 'MoveScrXXX' hotkey actions.  The quantity is provided
  440.     as the 'Screen steps'-th part of the display clip of the active screen.
  441.     The range for this quantity is 1..50
  442.     This argument defaults to '5', its name is 'SCRMOVESTEPS'
  443.  
  444.   'Window steps' - this is the same as above except that this value is
  445.     applied for window moving and dimensioning via the 'MoveXXX',
  446.     'ExpandXXX' and 'ShrinkXXX' hotkey actions. The range is 1..50,
  447.     too.
  448.     The corresponding argument is named 'WINMOVESTEPS' and defaults to 5
  449.      
  450.   'CX priority' - use this to set Angie's commodity broker's priority.
  451.     Note well that this action takes effect immediately - the effort to
  452.     achieve this in a documented way was quite high, by the way.
  453.     The argument for this is called 'CX_PRIORITY' and defaults to 0
  454.     
  455.  
  456. There's one separate text entry gadget, named 'Window shuffle pattern'
  457.     where you can enter the pattern to be applied to windows' names when
  458.     doing a window shuffle ('ActivateNext' / 'ActivatePrev') hotkey action.
  459.     Windows whose titles don't match to the pattern are skipped.
  460.     The argument name for this setting is 'SHUFFLEPAT' and defaults to '#?'
  461.     (which matches all names, incl. an empty name)
  462.     
  463.  
  464. The other gadgets form a system to maintain the action hotkey list of
  465. Angie:
  466.  
  467. Use the 'ADD' gadget to add new hotkeys to the list, the 'DEL' gadget to
  468. delete hotkeys from the list, the 'UP' gadget to move an entry up in the
  469. list, the 'DOWN' gadget to move an entry down in the list, use the
  470. listview to browse through the hotkey list and to select the active
  471. hotkey, the change operations will affect.  
  472.  
  473.  
  474. The 'Action' text entry gadget is one of these change operation gadgets:
  475. You can enter an arbitrary 'AngieSequence' with up to 255 characters in
  476. this gadget that is to be executed when the hotkey is triggered.  Plain
  477. text outside brackets is considered as ascii text that is to be inserted
  478. into the input stream, text in angled brackets like '<lshift lshift_press>'
  479. represents a commodities input description, text in normal brackets like
  480. '(^ActivateNextScreen)' represents an Angie Intuition related action (or if
  481. it doesn't match an Angie Intuition action it is considered to be an async
  482. dos command sequence), text in '[]' brackets like 
  483. '[^cd ram:<CTRL-J>newshell *]' represents a dos command sequence that shall
  484. be launched asynchronously, whereas text in '{}' brackets like
  485. {magicpubname q tofront CygnusEdScreen1} represents a dos command sequence
  486. that shall be executed synchronously.  '#n' specifies the delay to wait
  487. between processing two elements of an AngieSequence / inserting each char
  488. of plain text and '~n' stands for a one-time delay (the valid range for n
  489. is 0..999 milliseconds).  As the very first character of the AngieSequence
  490. or as the character following immediately after the opening bracket in case
  491. of '()'/'[]'/'{}'- bracketed elements, a '^' - ToFront attribute may be 
  492. specified.  It has the effect, that either the window involved in the
  493. operation, or if no window but a screen is involved, the involved screen, 
  494. is popped to the front. To give you a rough idea about AngieSequences, e.g.
  495. '{magicpubname q tofront ShellScr}(^ActivateFrontScr)<control x>~200 list '
  496. is a valid AngieSequence.
  497.  
  498. Within the 'Action' gadget, the cursor up/down keys have some special
  499. functionality.  If the cursor is within a bracketed element, or on a
  500. space character, these cursor key presses have the effect that this element
  501. is replaced by either the first or last action of the actions in Angie's
  502. Angie Intuition action list.  Otherwise, if the cursor is not within a
  503. bracketed element or over a space character, the respective Angie Intuition
  504. action is inserted at the cursor position. Any following, consecutive cursor
  505. up/down presses simply shuffle through Angie's Intuition action list.
  506. Pressing ESCape quits the gadget by discarding all changes that have been made.
  507.  
  508. An additional way of modifying the contents of the 'Action' gadget is
  509. selecting the respective Angie Intuition action in the 'Edit╖Hotkey╖Type'
  510. menu.  This replaces the WHOLE contents of the action gadget with the
  511. selected action.
  512.  
  513.  
  514.  
  515. Another change operation is the selection of the 'Attrs' gadget.  You can
  516. assign three different attributes to the hotkey entry with this gadget:
  517.  
  518. 1.  'NoFilter':  If this attribute is enabled, an input event that matches
  519. the hotkey is propagated to the other commodities objects rather than being
  520. filtered which is the default.
  521.  
  522. 2.  'NoScrAct':  This attribute inhibits a rawkey hotkey from triggering an
  523. automatic 'Key screen activation' action (see above).  This attribute is
  524. enforced for the 'NoKeyActivate' pseudo action.  It should be generally
  525. used for hotkeys with actions that shuffle screens without activating a
  526. window on the new frontmost screen or for hotkeys with actions that hunt or
  527. retrieve windows like 'HuntWindow', 'LastActive' or 'LastActiveScr'.
  528.  
  529. 3.  'Repeatbl':  This attribute signifies that matching rawkey events
  530. with the 'repeat' qualifier set shall be normally processed rather than
  531. just being filtered, which is the default.  It is of no use at all to
  532. apply this attribute to a hotkey that has both, no '-repeat' 
  533. maybe-qualifier and no 'repeat' qualifier set in its definition.
  534.  
  535.  
  536. Furthermore, you can toggle the different attributes by using the
  537. 'Edit╖Hotkey╖Type->Attributes' submenu toggle items.
  538.  
  539.  
  540.  
  541. However, the most important change operation gadget is the listview's
  542. string gadget where you can modify the commodities input description for
  543. the hotkey.  If you enter an invalid input description, the former
  544. description is reused instead of the one you entered.  Note that you can
  545. leave the string gadget by pressing cursor up/down, too:  The cursor
  546. up/down keys are equivalent to pressing return within the string gadget and
  547. right afterwards pressing cursor up/down.  As all other Angie string
  548. gadgets, this string gadget can be quit by pressing ESC, which has the
  549. effect that the gadget's contents are discarded and the gadget is
  550. refreshed.
  551.  
  552.  
  553. The Project menu is intuitive:
  554.  
  555.   -New resets Angie to the default configuration
  556.   
  557.   -Read╖Settings reads the configuration that are currently stored in the
  558.    PROGDIR:Angie icon.
  559.    
  560.   -Restore╖Settings restores the settings to the latest arguments that
  561.    were read either at startup or after selecting the Read╖Settings menu
  562.    item.
  563.  
  564.   -Save╖Settings saves the current configuration into the PROGDIR:Angie
  565.    icon
  566.   
  567.   -About brings up a requester with information about Angie. Note that
  568.    while the About requester is displayed, Angie is in inactive state.
  569.   
  570.   -Hide closes the GUI window
  571.   
  572.   -Quit causes Angie to shut completely down
  573.   
  574.  
  575.  
  576. The underscored character of a gadget's text signifies the key shortcut for
  577. selecting the respective gadget, additionally the cursor up / down keys are
  578. used to scroll through the hotkeys in the listview, the DEL key is used to
  579. delete the current entry in the listview, the ESCape key or the close
  580. gadget is used to close Angie's GUI window, and the 'Z' key or the Zoom
  581. gadget is used to (un-)iconify the GUI window.
  582.   
  583. There exists one common non-standard editing feature of all of Angie's
  584. text entry gadgets: Pressing 'ESC' leaves the gadget by discarding
  585. all changes made to it, i.e. a sort of 'CANCEL' operation.
  586.  
  587.  
  588.  
  589.                     the various Angie Intuition actions
  590.                     -----------------------------------
  591.  
  592.  
  593. Now, let's discuss the various Angie Intuition actions:
  594.  
  595.  
  596. CX_POPKEY: 
  597.   Pop Angie's GUI window open, activate and hunt it if it is already open.
  598.   
  599. HuntWindow:
  600.   Perform a hunt action (see above) right now.
  601.   
  602. Activate:
  603.   Activate the window under the mouse  
  604.  
  605. ActivateNext:  
  606.   Shuffle forward through the current active screen's window list
  607.   
  608. ActivatePrev:  
  609.   Shuffle backward through the current active screen's window list
  610.  
  611. ActivateBackdrop:
  612.   Activate the active screen's first backdrop window
  613.  
  614. ActivateFrontScr:
  615.   Activate the frontmost window on the frontmost screen.
  616.   
  617. LastActive:
  618.   Activate the window that was active right before the current active  
  619.   window if it still exists, In case it doesn't exist any more, but
  620.   it was opened on another screen that still exists, this action 
  621.   activates that screen's frontmost window.
  622.  
  623. LastActiveScreen:
  624.   Activate the last active window of the last active screen, if it still
  625.   exists.  If it doesn't exist anymore, but the screen on which it was open
  626.   still exists, then activate the frontmost window on that screen.
  627.   
  628. ToFront:
  629.   Pops the currently active window to front
  630.  
  631. ToBack:
  632.   Moves the currently active window to the back  
  633.   
  634. AdaptWindow:
  635.   This is something like an 'inverted hunt' action:  the active window is
  636.   (if necessary) moved and shrunk in a way that it fits into the currently
  637.   displayed portion of its screen.
  638.   
  639. CenterWindow:
  640.   The active window is centered within the currently displayed portion of
  641.   its screen.
  642.   
  643. Zip:
  644.   The active window is zipped (equivalent to selecting the Zoom gadget)
  645.   
  646. Close:
  647.   A selection of the active window's close gadget is emulated
  648.  
  649. Max:
  650.   The active window's position and size are changed to exactly fill the 
  651.   screen's visible portion.
  652.   
  653. MaxWidth:
  654.   The same as for above, but only horizontally, and if at least a part of  
  655.   the window would be visible in the screens display portion with
  656.   consideration to the vertical window position & dimension.
  657.   
  658. MaxHeight:  
  659.   Like MaxWidth, but now vertically.
  660.   
  661. MinWin:
  662.   The active window is shrunk to its minimum dimensions and moved into the
  663.   lower right edge of the screen's visible portion
  664.  
  665. MoveLeft / MoveRight / MoveUp / MoveDown:
  666.   Move the active window in the respective direction, the move quantity is
  667.   derived from the 'Window steps' setting.
  668.  
  669. UpperLeft / LowerLeft / UpperRight /  LowerRight:
  670.   Place the  active window in the respective edge of the screen's visible
  671.   portion
  672.   
  673. ExpandWidth / ExpandHeight / ShrinkWidth / ShrinkHeight:
  674.   Expand / shrink the active window's width / height. The quantity
  675.   to expand /shrink is derived from the 'Window steps' setting.
  676.  
  677. DoubleWidth / DoubleHeight / HalveWidth / HalveHeight:
  678.   Double / halve the active window's width / height
  679.   
  680. ActivateNextScreen / ActivatePrevScreen / ActivateWBenchScreen /
  681. ActivateDefPubScreen: 
  682. Shuffles the screen list forward / backward, resp. pops the Workbench
  683. screen / default public screen to the front and activates the last
  684. active window of the new front screen or the frontmost window of the
  685. screen instead.  If the 'Hunt:  set default public screen' toggle is
  686. set and either the 'Hunt always' toggle is set, or both, the 'Hunt on
  687. wintofront hotkeys' toggle is set and the 'window to front' attribute
  688. is set for the hotkey, it will also make the new front screen the
  689. default public screen even if no windows are open on it.
  690.   
  691. NextScreen / PrevScreen / WBenchScreen / DefPubScreen:
  692.   the same as for the corresponding ActivateXXXXScreen entries except
  693.   that no window activation and no default public screen definition
  694.   magic takes place.
  695.   
  696. ScrollScrLeft / ScrollScrRight / ScrollScrUp / ScrollScrDown:
  697.   scrolls the active screen in the respective direction. The scroll
  698.   quantity is derived from the 'Screen steps' setting.
  699.    
  700. UpperLeftScr / LowerLeftScr / UpperRightScr / LowerRightScr / 
  701. ShowScrCenter:
  702.   makes the respective portion of the active screen visible in its
  703.   display clip.
  704.  
  705. ScreenTop:
  706.   aligns the top edge of the active screen with the top edge of its
  707.   display clip
  708.  
  709. SetDefPubScreen:
  710.   makes the active screen the default public screen. If the frontmost
  711.   screen is a screen with no windows open, and the active screen is
  712.   completely invisible, the frontmost screen is used instead for this
  713.   operation. If the screen is not a public screen, the Workbench screen
  714.   is set as the new default public screen.
  715.  
  716. Filter: (** pseudo action - select this through the menu!! **)
  717.   This is a real nop operation: It does nothing at all. Thus, the
  718.   only job of this action is to filter the respective hotkey input 
  719.   events out of the input stream.
  720.  
  721. NoKeyActivate: (** pseudo action - select this through the menu!! **)
  722.   All (rawkey) input events matching this hotkey's input description are
  723.   excluded from triggering 'Key screen activation' (see above). This is
  724.   useful to keep other commodities' / input handlers' rawkey hotkeys from
  725.   triggering key screen activation action. You may want that for foreign
  726.   rawkey hotkeys that shuffle screens and don't activate a window on the
  727.   new frontmost screen (like Intuition lcommand m/n).
  728.   
  729.  
  730.  
  731.                        the syntax of AngieSequences
  732.                        -----------------------------
  733.  
  734. In the following definition, terms surrounded by '[]' brackets may be
  735. omitted.  The same goes for terms surrounded by '{}' brackets, except that
  736. these terms may be even repeated any times you want.
  737.  
  738. AngieSequence := [ ToFrontAttr ] AngieSequence1
  739.  
  740. AngieSequence1 := { IntuitionSequence | AsyncDosSequence | SyncDosSequence |
  741.                     CxInputSequence | AsciiChar | DelaySequence | 
  742.                     OneDelaySequence }
  743.  
  744. IntuitionSequence := '(' [ ToFrontAttr ] Angie_Intuition_action_string ')'
  745.  
  746. Angie_Intuition_action_string := Angie_Intuition_action | 
  747.                                  async_dos_command_sequence
  748.  
  749. Angie_Intuition_action := "any of Angie's valid Intuition action names as
  750.                            displayed in the Edit╖Hotkey╖Type menu,
  751.                            except a pseudo_action_name"
  752.                            
  753. pseudo_action_name := 'Filter' | 'NoKeyActivate' | 'Custom'
  754.                            
  755. AsyncDosSequence := '[' [ ToFrontAttr ] async_dos_command_sequence ']'
  756.  
  757. SyncDosSequence := '{' [ ToFrontAttr ] sync_dos_command_sequence '}'
  758.  
  759. async_dos_command_sequence := dos_command_sequence 
  760.  
  761. sync_dos_command_sequence := dos_command_sequence 
  762.  
  763. dos_command_sequence := [ linefeed | dos_command_line ] 
  764.                         [ linefeed dos_command_sequence ]
  765.  
  766. linefeed := '<control-j>' | '╢'          ; '╢' = <alt p>
  767.  
  768. dos_command_line := "a line of ascii text that is executed 
  769.                      as a dos command line"
  770.  
  771. CxInputSequence := '<' input_description '>'
  772.  
  773. input_description := "a description string for an input event 
  774.                       respectively for an IX according to 
  775.                       commodities.library."
  776.  
  777. AsciiChar := esc_sequence | valid_ascii ; short circuit evaluation here!
  778.  
  779. esc_sequence := '\' esc_desc
  780.  
  781. esc_desc := [ 'n' | 'r' | '0' | 't' | 'f' | ''' | '"' | 
  782.               '<' | '(' | '[' | '{' | '\' | 'x' hex_value ]
  783.  
  784. valid_ascii := "any ASCII characters except an invalid_ascii character"
  785.              
  786. invalid_ascii := '<' | '(' | '[' | '{'
  787.  
  788. hex_value := hex_nibble [ hex_nibble ]
  789.  
  790. hex_nibble := '0' | '1' | '2' | '3' | '4' | '5' | '6' | '7' | '8' |
  791.               '9' | '0' | 'a' | 'b' | 'c' | 'd' | 'e' | 'f'
  792.  
  793. DelaySequence := '#' [delay_value] [ ' ' ] 
  794.  
  795. OneDelaySequence := '~' [delay_value] [ ' ' ]
  796.  
  797. delay_value := "decimal digits representation of time in milliseconds to
  798.                 delay, range 0..999" 
  799.  
  800. ToFrontAttr := '^';
  801.  
  802. NOTE:  
  803. -Whereever the ToFrontAttr may be specified, and a '\^' sequence
  804.  follows immediately after that position, the '\^' sequence is replaced
  805.  by a simple '^' character. 
  806.  
  807. -Moreover, inside bracketed AngieSequence1 
  808.  elements, the closing bracket may be specified as a normal character of
  809.  that element by prepending a '\' to the closing bracket.
  810.  e.g. '[echo "[Hello\]"]' is a valid async_dos_command_sequence
  811.  
  812.  
  813.  
  814. Most of the formal stuff should be self-explanatory.  However, some things
  815. deserve a verbose discussion:  
  816.  
  817. The dalay_value of DelaySequence & OneDelaySequence defaults to 50 if it 
  818. is not specified.
  819.  
  820. The effects of the ToFrontAttr element:
  821.  
  822. -as the first element of the AngieSequence, it originates a 'ToFront'
  823.  Angie_Intuition_action before the rest of the AngieSequence is processed.
  824.  
  825. -for dos_command_sequences, it causes the default public screen to be popped
  826.  to the front before the dos_command_sequence is launched
  827.  
  828. -for Angie_Intuition_actions, its effect depends on the action itself:  if a
  829.  window is affected by the action, that window is popped to the front.
  830.  Otherwise, if no window at all, but a screen is involved in the action,
  831.  that screen is popped to the front.  BTW:  For the 'ToBack' action, it has
  832.  no effect at all, of course;-)
  833.  
  834.  
  835. The esc_sequence character translation:
  836.  
  837.           \n   -  linefeed (inserted  as carriage return)
  838.           \r   -  carriage return
  839.           \0   -  nul
  840.           \t   -  horizontal tab 
  841.           \f   -  formfeed
  842.           \xff -  ASCII code 0xff (f represents an arbitrary hex nibble)
  843.           \'   -  apostrophe
  844.           \"   -  quotation mark
  845.           \\   -  backslash '\'
  846.           \<   -  '<' opening bracket
  847.           \(   -  '(' opening bracket
  848.           \[   -  '[' opening bracket
  849.           \{   -  '{' opening bracket
  850.  
  851.  
  852.  
  853. NOTEZ-BIEN!!!
  854.   sync_dos_command_sequences are rather dangerous since during their
  855.   execution Angie is BLOCKED for any other action. So please only use 
  856.   sync_dos_command_sequences in AngieSequences like
  857.   '{magicpubname q tofront CygnusEdScreen1}(^ActivateFrontScr)' where the
  858.   dos_command_sequence really  has to be executed synchronously, and
  859.   where its execution doesn't take much time.  NEVER launch interactive
  860.   applications / tools or similar things synchronously!!!
  861.  
  862.  
  863. The launching parameters for async_dos_command_sequence execution:
  864.   The priority of the launched task will
  865.   be the same as the priority, Angie was started with - the same goes for
  866.   the stack size, current directory and the dos command search path.
  867.   Input and Output are set to an interactive console window with the
  868.   WAIT/AUTO/CLOSE attributes, its position and alternative ('zoom') 
  869.   position are optimized for the currently displayed portion of the default
  870.   public screen. The console will open on the default public screen at
  871.   the very moment when the first input/output operation takes place.
  872.  
  873. For sync_dos_command_sequence execution, the only two differences are that
  874. no console is opened for them, and they run with the current task priority
  875. of Angie.
  876.  
  877.  
  878.                             the arexx interface
  879.                             -------------------
  880.  
  881. Angie offers an Arexx interface in order to provide you with the ability to
  882. make Angie execute arbitrary AngieSequences from ARexx scripts or any other
  883. source.  For this purpose, Angie maintains a public Arexx port named
  884. 'ANGIEREXX'.
  885.  
  886. A simple example for an ARexx script:
  887.  
  888.   options results
  889.   address command 'SetActiveWin tpat (%|#?/|#:)Clock'
  890.   if rc = 0 then address 'ANGIEREXX' '(HuntWindow)'
  891.   else address command 'run <nil: <nil: sys:utilities/clock'
  892.  
  893. Apart from that, you can quit Angie by sending the 'QUIT' command to
  894. Angie's ARexx port.
  895.  
  896.  
  897.  
  898.                  programming info, implementation details
  899.                  ----------------------------------------
  900.  
  901. Angie is completely written in Amiga-Oberon, a superset of a powerful
  902. object-oriented language by Nicolaus Wirth, that offers all the flexibility
  903. and excellent code generation that is needed for Amiga system and
  904. application programming.  I tried hard to make Angie conforming with the
  905. User Interface Style Guide, and to make it really free of bugs.  I can tell
  906. you that despite having used Oberon runtime checking code (which is
  907. disabled in this official release), Enforcer and Mungwall, this release has
  908. been proved free of any bugs (however, don't blame me if you find one
  909. though:  you know Murphy rules...;-^) Especially, I always tried to ensure
  910. that all accesses to system data are protected by the respective official
  911. CBM protocols.  Since within interrupts there is no such protocol for
  912. Intuition data structures available, I placed the snooping code for window
  913. hunting, raising of the active window task's priority, remembering of the
  914. last window and all the last windows of a screen, in a child task rather
  915. than within interrupt code.
  916.  
  917. If you find any bugs or you have any suggestions for improving Angie or
  918. extending its functionality, or if you just want its source code,
  919. you are encouraged to contact the author via electronic mail (preferred)
  920. or snail mail.
  921.  
  922.  
  923. If you own a 68000 you may wonder why Angie's snoop task uses quite more
  924. CPU time than you thought it uses (Note however that only Xoper2.4 gives
  925. you reliable information.  Former versions of Xoper display much too much
  926. CPU time usage of tasks that are both, frequently switched and don't hold
  927. the CPU for a long time).  Well, the solution is as follows:  I decided to
  928. make Angie as system-friendly as possible.  Angie has to snoop not only the
  929. IntuitionBase->ActiveWindow, but also elements like
  930. TopEdge/LeftEdge/Width/Height/WScreen of the ActiveWindow itself.  In a
  931. consistent way, this is only possible within tasks, not interrupts, in
  932. conjunction with the (Un)LockIBase() protocol.  However, task switching,
  933. the timer request for delaying, and especially the (Un)LockIBase() protocol
  934. produce an enormous overhead of CPU usage:  I measured (on a 68030, OS3.0)
  935. that the snoop code itself only consumes 15% (fifteen) percent of the snoop
  936. task's total CPU usage (total CPU usage is less than 1% @ 30 ms snoopdelay
  937. on 68030, 25Mhz, OS3.0).  With the snoop code removed, only the timer IO
  938. and (Un)LockIBase() stub left, the CPU usage of the snoop task was still at
  939. 85% of the original CPU usage.  With (Un)LockIBase() removed, the snoop
  940. task's CPU usage was at about 45% of the original CPU usage.
  941.  
  942.  
  943.  
  944.  
  945.  
  946.                               program history
  947.                               ---------------
  948.  
  949.  
  950.   v1.0 20.10.93 [fSchwarz]
  951.  
  952.   v1.1 22.10.93 [fSchwarz] improved setDefPubScreen action
  953.     fixed ActivateXXXXScreen; fixed Menu Attrs selection
  954.  
  955.   v1.2 23.10.93 [fSchwarz] doesn't send any closeWindow
  956.     event on Close action when window is blocked by
  957.     requesters.
  958.  
  959.   v1.3 24.10.93 [fSchwarz] added Edithook for hotkey
  960.     definition gadget
  961.  
  962.   v1.4a 29.10.93 [fSchwarz] major code cleanup; now
  963.     supports dos command and inputevent insertion type
  964.  
  965.   v1.5 4.11.93 [fSchwarz] now really uses the frontmost
  966.     window of screens instead of just screen.firstWindow;
  967.     improved Key Screen Activation handling for screens
  968.     without windows
  969.  
  970.   v1.6 4.11.93 [fSchwarz] removed last Intuition stuff from
  971.     cxcustom inputhandler - now all accesses to Intuition
  972.     structures are safeguarded by official CBM protocols;
  973.     enhanced Intuition/GadTools V37 GUI
  974.  
  975.   v1.7 7.11.93 [fSchwarz] now accounts the fact that
  976.     ViewPortExtra.displayClip is volatile and dependent on
  977.     the displayids of both, the affected screen & the front
  978.     screen; improved timing in msghandler (results in faster
  979.     Auto-Hunts when receiving many CxMsgs consecutively
  980.     and in better hotkey recursion capabilities); now
  981.     needs BlackMagic 1.14; fixed nasty Enforcer hit in
  982.     DefinitionProc() that turned out very rarely and was
  983.     due to use of post-freed memory (which was usually
  984.     immediately reallocated, so Enforcer/Mungwall hardly
  985.     ever noticed it); improved Intuition left mouse button
  986.     effective detection
  987.  
  988.   v2.0 11.11.93 [fSchwarz] Angie is now completely localized;
  989.     fixed rare timing problems that were due to rearranging
  990.     Intuition related KeyScreenActivation stuff from the
  991.     the cxcustom handler to the main task; changed again
  992.     KeyScreenActivation handling; complete code heavily
  993.     revised & updated to ensure optimal ergonomics when
  994.     there's no current active window, yet an active screen;
  995.     now right mouse button blocks all Auto-Hunt (it doesn't
  996.     block hotkey-(attribute)-based hunts, though!);
  997.     former WinToFront attribute changed to 'ToFront': *If
  998.     and only if* the hotkey action doesn't involve a window,
  999.     but a screen, the attribute causes a ScreenToFront()
  1000.     instead of a simple WindowToFront(). HuntWindow action
  1001.     now hunts the active screen if no active window exists;
  1002.     the KeyScreenActivation considers that case, too.
  1003.     Most window-related hotkey-actions (except Hunt) now
  1004.     simply activate the BestWindow() if there exists no
  1005.     active window (ToFront/Hunt according to the hotkey
  1006.     attrs); optimized LastActive-Action (now activates the
  1007.     frontmost window of the last window's screen if the
  1008.     last window doesn't exist any more, but the screen it
  1009.     was opened on, and that screen differs from the active
  1010.     one). Added Capslock-AutoHunt-mode (default!): capslock
  1011.     is alienated as an inverse Auto-Hunt toggle switch, all
  1012.     capslock events & capslock qualifier in inputevents
  1013.     are eliminated.; Now cxcustom handler code runs at
  1014.     three different priorities. Moved some IntuitionBase
  1015.     related window code to own module. Angie's minimum
  1016.     taskpri is now 5; wintask priority increment only
  1017.     happens if resulting priority isn't greater than
  1018.     Angie's taskpri. Added 'New', 'Read Settings' &
  1019.     'Restore settings' to the project menu; remembers also
  1020.     the second last window/screen for LastActive/
  1021.     LastActiveScr actions; general changes in the code to
  1022.     obtain better ergonomics in many places; added
  1023.     'DEFAULTPREFS' argument (especially for CLI): loads
  1024.     the configuration stored in PROGDIR:Angie.info.
  1025.     Angie now requires CxLib V1.1 with ArgArrayDiskObj().
  1026.     All tooltypes longer than 128 chars (the official
  1027.     length limit as of the RKMs) are now split by Angie
  1028.     for the icon writing (fixes problems with Workbench's
  1029.     Icon->Information menu item that prunes all longer
  1030.     tooltypes). Main module is now split into three modules.
  1031.     Plus several changes I forgot to mention here.
  1032.  
  1033.   v3.0 19.11.93 [fSchwarz] COMPLETELY NEW CONCEPT: Angie-
  1034.     Sequences, consisting of multiple Angie actions, ascii
  1035.     text, commodities input descriptions, & async / sync
  1036.     dos command sequences are now assigned to the hotkeys.
  1037.     The ToFront attribute is now replaced by a 'NoFilter'
  1038.     attribute (the ToFront attribute may now be specified
  1039.     separately for each item of an AngieSequence). Angie
  1040.     parses now qualifier keystrokes like 'LALT_PRESS' in
  1041.     input descriptions - along with mouse button keystrokes
  1042.     in input descriptions even for V37 commodities users;
  1043.     simple NoScrActivate pseudo hotkeys now work for V37,
  1044.     too (own ParseIX() extension, own V37 MatchIX()).
  1045.     fixed NewMenu array size of the edit menu. For
  1046.     proportional fonts, gimmeZeroZero windows are used in
  1047.     conjunction with other slLevelFormat - this fixes V37
  1048.     level display problems and keeps the window borders
  1049.     from messing up in those rare cases where the nominal
  1050.     proportional font's width is utterly misleading.
  1051.     Invocation of WindowToFront() is now omitted if the
  1052.     respective window is already the screen's frontmost
  1053.     window (results in much better performance for
  1054.     gimmeZeroZero windows). GetBestWin() now accounts that
  1055.     visible screens may follow after invisible screens in
  1056.     the IntuitionBase screen list. cx_pri slider step is
  1057.     now level-adaptive (like snoopdelay/stabletime sliders)
  1058.     A new tooltype format for hotkeys is now used - old
  1059.     format can still be read. Another new (default!)
  1060.     auto hunt mode is provided: CapsLock1 (functionality
  1061.     is the same as for the old CapsLock mode which is now
  1062.     called CapsLock2, except that capslock keystrokes & the
  1063.     capslock qualifier in the ievents are left untouched).
  1064.  
  1065.   v3.1 22.11.93 [fSchwarz] removed all code where
  1066.     LockLayerInfo() is called directly or indirectly with
  1067.     a locked IntuitionBase due to very unlikely deadlock
  1068.     situations that may arise from LockLayerInfo() when
  1069.     IBase is locked. Other protocol to avoid illegal
  1070.     mem access & to ensure valid window pointer is used
  1071.     instead. Distribution now includes my SetActiveWin
  1072.     and MagicPubName shell utilities that can be perfectly
  1073.     used in SyncDosSequences. In order to disencourage
  1074.     you from abusing SyncDosSequences for launching
  1075.     interactive stuff, etc, and in order to improve
  1076.     performance, SyncDosSequences are now executed without
  1077.     new I/O channels & with the same priority Angie is
  1078.     running. Fixed bug that kept Angie from activating
  1079.     the BestWindow for most Intuition actions in case
  1080.     no active window exists (bug was due to the severe
  1081.     code changes that were necessary for inventing the
  1082.     AngieSequence concept)
  1083.  
  1084.   v3.2 23.11.93 [fSchwarz] all CxMsgs of cxmIEvent type
  1085.     that are older than 2.5 seconds are discarded by the
  1086.     msghandler now; rearranged msghandler code - this
  1087.     fixes all backlog problems and makes the GUI accessable
  1088.     even when Angie is busy with CxMsgs & AutoHunt. Support
  1089.     for proportional fonts has now greatly improved: all
  1090.     strings in Angie's window are now accounted for
  1091.     calculating the window width - even for the most
  1092.     excentric proportional fonts, display won't mess up.
  1093.     The distribution now includes full-featured German
  1094.     docs, another utility (RawInsert) for DosSequences
  1095.     and SetActiveWin 1.1 (V1.0 could cause Intuition 
  1096.     deadlocks!)
  1097.  
  1098.  
  1099.   v3.3 24.11.93 [fSchwarz] Strangely, AddIEvents() doesn't
  1100.     set the timeStamp of the InputEvents as opposed to
  1101.     the v37 input device writeEvent command - this caused
  1102.     problems in conjunction with the anti backlog handling
  1103.     that was invented in Angie 3.2, so Angie itself now
  1104.     sets the TimeStamp. The same problem was present in the
  1105.     RawInsert utility - now fixed in RawInsert 1.1;
  1106.     improved performance & minimized gadget/menu refresh
  1107.     for hotkey list browsing.
  1108.  
  1109.   v3.3a 25.11.93 [fSchwarz] fixed another small bug that
  1110.     was due to the code changes for the AngieSequence
  1111.     concept (scrActivateMagic const had to be set to a
  1112.     unique value outside the range of AngieSequence ids)
  1113.  
  1114.   v3.5 1.12.93 [fSchwarz] added AREXX interface for
  1115.     executing AngieSequences from outside Angie. Fixed
  1116.     bug in the SetActiveWin utility that frustrated
  1117.     activation of windows on non-public screens (V1.2)
  1118.  
  1119.   v3.6 3.12.93 [fSchwarz] adapted to Amiga-Oberon 3.10,
  1120.     fixed active/inactive state handling (now arexx works
  1121.     great even if Angie is in inactive state); fixed error
  1122.     exit code; introduced '╢'-lineFeedMagic as a linefeed
  1123.     substitute within dos_command_sequences.
  1124.     !!! THIS IS the last revision for 1993 !!!
  1125.  
  1126.  
  1127.  
  1128.                                 final notes
  1129.                                 -----------
  1130.  
  1131. Known Bugs:  Currently, no known bugs exist.  However, due to the extent of
  1132. this project, it is possible that a few bugs are in the code that haven't
  1133. turned out yet.
  1134.  
  1135.  
  1136. Angie is GIFTWARE.  In other words THOU SHALT send the author a nice
  1137. present, cash, or AT LEAST a postcard, if you use it.
  1138.  
  1139. Suggestions, comments, bug reports, criticism, praise, etc.  are welcomed,
  1140. too!
  1141.  
  1142. If you want to translate this documentation into other languages, feel free
  1143. to do so, add the translation to this archive, and send it to the author
  1144. (that is me;-)) The same goes for catalog translation files and catalogs.
  1145.  
  1146.  
  1147. Angie is copyrighted and protected by copyright laws all over the world.
  1148. Copyright ⌐ 1993 Franz Schwarz.
  1149.  
  1150.  
  1151. The author can't be hold liable for any harm that stems from the
  1152. usage of this program, no matter whether direct harm or indirect harm.
  1153.  
  1154. Angie is freely distributable; it may be published in the Fred Fish
  1155. & Amok software collections and in other non-commercial software
  1156. collections, including CD-ROM versions of them. Moreover, it may be
  1157. spread via electronic data transfer.
  1158.  
  1159. Angie may only be distributed in this archive as a whole.  The only
  1160. exception from this:  if this archive contains the source code of Angie,
  1161. you may distribute a modified archive where _ONLY_ the complete 'txt' &
  1162. 'Locale' drawers with the respective icons may be removed.
  1163.  
  1164. Angie may be only distributed if the distributor does not claim any
  1165. copyright on the Angie archive nor on any files that are compulsorily
  1166. distributed with it (i.e.  the distributor claims that this archive may not
  1167. be distributed separately without those files).  Inquiries on exceptions
  1168. from these limitations may be submitted to the author.
  1169.  
  1170.  
  1171.                            contacting the author
  1172.                            ---------------------
  1173.  
  1174.                                Franz Schwarz
  1175.                               Mⁿhlenstra▀e 2
  1176.                        D-78591 Durchhausen, Germany
  1177.                     Uucp: Franz_Schwarz@mil.ka.sub.org
  1178.                         Fido Classic: 2:2476/506.18
  1179.                           Bank account 951.207 at
  1180.              KSK Trossingen, Germany, bank ZIP code 643 500 70
  1181.  
  1182.  
  1183.  
  1184.  
  1185.                                   Credits
  1186.                                   -------
  1187.  
  1188. The interactive graphical user interface was created with assistance of
  1189. GadToolsBox 37.300 by Jan van der Baard and its Oberon source generator
  1190. OG 38.02 by Stefan Kurtz, Thomas Igracki & Kai Bolay.
  1191.  
  1192.  
  1193.  
  1194.  
  1195. Have fun, and don't you forget:
  1196.  
  1197. Angie is a nice name as well as a terrific song by the Rolling Stones.
  1198. From now on, this name is to be remembered in the Amiga community as well:
  1199. Angie, i.e. this software's name is an acronym for
  1200.  
  1201.                     ANother  Great  Intuition  Enhancer
  1202.  
  1203.  
  1204.   Franz 'Blacky' Schwarz
  1205.  
  1206.                - Girlfriend Is Better - Talking Heads -
  1207.  
  1208.  
  1209.  
  1210.  
  1211.                     appendix: how to define a hotkey
  1212.                     --------------------------------
  1213.  
  1214. Angie 3.0 drops the restrictions of commodities.library V37-V40 in terms of
  1215. parsing input descriptions:  For V37, the rawmouse keycodes
  1216. 'MOUSE_LEFTPRESS', 'MOUSE_MIDDLEPRESS' & 'MOUSE_RIGHTPRESS' that are
  1217. usually only available in commodities.library V38 or higher are supported.
  1218. As of V40, commodities.library doesn't support keycodes for the keyboard
  1219. qualifiers.  Angie allows you to use the rawkey keycodes 'CONTROL_PRESS',
  1220. 'CAPS_PRESS', 'LSHIFT_PRESS', 'RSHIFT_PRESS', 'LALT_PRESS', 'RALT_PRESS',
  1221. 'LAMIGA_PRESS' & 'RAMIGA_PRESS'.  These parsing extensions are made in a
  1222. highly compatible manner, of course - they will very probably work in all
  1223. future versions of commodities.library.
  1224.  
  1225. Within Angie, valid input description strings are for ALL VERSIONS OF
  1226. commodities.library:
  1227. 'rawmouse leftbutton mouse_leftpress'
  1228. 'rawmouse -capslock upstroke mouse_middlepress'
  1229. 'lshift -capslock -control -alt lshift_press'
  1230. '-capslock -upstroke caps_press'
  1231. etc.
  1232.  
  1233. THESE facts are NOT ACCOUNTED in the following text!!
  1234.  
  1235. The following text is courtesy Stefan Becker and describes the structure of
  1236. the currently defined commodities input descriptions:
  1237.  
  1238. How to define a Hot Key
  1239. ************************
  1240.  
  1241.    This chapter describes how to define a Hot Key as an Input
  1242. Description String, which is then parsed by Commodities. Each time a
  1243. Hot Key is activated Commodities generates an event which is used by
  1244. ToolManager to activate Exec objects or to toggle Dock objects. A
  1245. description string has the following syntax:
  1246.  
  1247.      [<class>] {[-][<qualifier>]} [-][upstroke] [<key code>]
  1248.  
  1249.    All keywords are case insensitive.
  1250.  
  1251.    `class' describes the InputEvent class. This parameter is optional
  1252. and if it is missing the default `rawkey' is used. See InputEvent
  1253. classes.
  1254.  
  1255.    Qualifiers are "signals" that must be set or cleared by the time the
  1256. Hot Key is activated; otherwise no event will be generated. For each
  1257. qualifier that must be set you supply its keyword. All other qualifiers
  1258. are expected to be cleared by default. If you want to ignore a
  1259. qualifier, just set a `-' before its keyword. See Qualifiers.
  1260.  
  1261.    Normally a Hot Key event is generated when a key is pressed. If the
  1262. event should be generated when the key is released, supply the keyword
  1263. `upstroke'. When both press and release of the key should generate an
  1264. event, use `-upstroke'.
  1265.  
  1266.    The key code is depending on the InputEvent class. See Key codes.
  1267.  
  1268.    Note: Choose your hot keys *carefully*, because Commodities has a
  1269. high priority in the InputEvent handler chain (i.e. will override
  1270. existing definitions).
  1271.  
  1272.  
  1273. InputEvent classes
  1274. ===================
  1275.  
  1276.    Commodities supports most of the InputEvent classes that are
  1277. generated by the input.device. This section describes those classes
  1278. that are most useful for ToolManager Hot Keys.
  1279.  
  1280. `rawkey'
  1281.      This is the default class and covers all keyboard events. For
  1282.      example `rawkey a' or `a' creates an event every time when the key
  1283.      "a" is pressed. You must specify a key code for this class. See
  1284.      rawkey key codes.
  1285.  
  1286. `rawmouse'
  1287.      This class describes all mouse button events. You must specify a
  1288.      key code for this class. See rawmouse key codes.
  1289.  
  1290. `diskinserted'
  1291.      Events of this class are generated when a disk is inserted in a
  1292.      drive. This class has no key codes.
  1293.  
  1294. `diskremoved'
  1295.      Events of this class are generated when a disk is removed from a
  1296.      drive. This class has no key codes.
  1297.  
  1298.  
  1299. Qualifiers
  1300. ===========
  1301.  
  1302.    Some keyword synonyms were added to Commodities V38. These are
  1303. marked with an `*'.
  1304.  
  1305. `lshift', `left_shift' *
  1306.      Left shift key.
  1307.  
  1308. `rshift', `right_shift' *
  1309.      Right shift key.
  1310.  
  1311. `shift'
  1312.      Either shift key.
  1313.  
  1314. `capslock', `caps_lock' *
  1315.      Caps lock key.
  1316.  
  1317. `caps'
  1318.      Either shift key or caps lock key.
  1319.  
  1320. `control', `ctrl' *
  1321.      Control key.
  1322.  
  1323. `lalt', `left_alt' *
  1324.      Left alt key.
  1325.  
  1326. `ralt', `right_alt' *
  1327.      Right alt key.
  1328.  
  1329. `alt'
  1330.      Either alt key.
  1331.  
  1332. `lcommand', `lamiga' *, `left_amiga' *, `left_command' *
  1333.      Left Amiga/Command key.
  1334.  
  1335. `rcommand', `ramiga' *, `right_amiga' *, `right_command' *
  1336.      Right Amiga/Command key.
  1337.  
  1338. `numericpad', `numpad' *, `num_pad' *, `numeric_pad' *
  1339.      This keyword *must* be used for any key on the numeric pad.
  1340.  
  1341. `leftbutton', `lbutton' *, `left_button' *
  1342.      Left mouse button. See note below.
  1343.  
  1344. `midbutton', `mbutton' *, `middlebutton' *, `middle_button' *
  1345.      Middle mouse button. See note below.
  1346.  
  1347. `rbutton', `rightbutton' *, `right_button' *
  1348.      Right mouse button. See note below.
  1349.  
  1350. `repeat'
  1351.      This qualifier is set when the keyboard repeat is active. Only
  1352.      useful for InputEvent class `rawkey'.
  1353.  
  1354.    Note: Commodities V37 has a bug which prevents the use of
  1355. `leftbutton', `midbutton' and `rbutton' as qualifiers. This bug is
  1356. fixed in V38.
  1357.  
  1358.  
  1359. Key codes
  1360. ==========
  1361.  
  1362.    Each InputEvent class has its own key codes:
  1363.  
  1364.  
  1365. Key codes for InputEvent class `rawkey'
  1366. ----------------------------------------
  1367.  
  1368.    Some keywords and synonyms were added to Commodities V38. These are
  1369. marked with an `*'.
  1370.  
  1371. `a'-`z', `0'-`9', ...
  1372.      ASCII characters.
  1373.  
  1374. `f1', `f2', ..., `f10', `f11' *, `f12' *
  1375.      Function keys.
  1376.  
  1377. `up', `cursor_up' *, `down', `cursor_down' *
  1378. `left', `cursor_left' *, `right', `cursor_right' *
  1379.      Cursor keys.
  1380.  
  1381. `esc', `escape' *, `backspace', `del', `help'
  1382. `tab', `comma', `return', `space', `spacebar' *
  1383.      Special keys.
  1384.  
  1385. `enter', `insert' *, `delete' *
  1386. `page_up' *, `page_down' *, `home' *, `end' *
  1387.      Numeric Pad keys. Each of these key codes *must* be used with the
  1388.      `numericpad' qualifier keyword!
  1389.  
  1390.  
  1391. Key codes for InputEvent class `rawmouse'
  1392. ------------------------------------------
  1393.  
  1394.    These keywords were added to Commodities V38. They are not available
  1395. in V37.
  1396.  
  1397. `mouse_leftpress'
  1398.      Press left mouse button.
  1399.  
  1400. `mouse_middlepress'
  1401.      Press middle mouse button.
  1402.  
  1403. `mouse_rightpress'
  1404.      Press right mouse button.
  1405.  
  1406.    Note: To use one of these key codes, you must also set the
  1407. corresponding qualifier keyword, e.g.
  1408.  
  1409.      rawmouse leftbutton mouse_leftpress
  1410.  
  1411.  
  1412. Examples for Hot Keys
  1413. ======================
  1414.  
  1415. `ralt t'
  1416.      Hold right Alt key and press "t"
  1417.  
  1418. `ralt lalt t'
  1419.      Hold left *and* right Alt key and press "t"
  1420.  
  1421. `alt t'
  1422.      Hold either Alt key and press "t"
  1423.  
  1424. `rcommand f2'
  1425.      Hold right Amiga key and press the second function key
  1426.  
  1427. `numericpad enter'
  1428.      Press the Enter key on the numeric pad
  1429.  
  1430. `rawmouse midbutton leftbutton mouse_leftpress'
  1431.      Hold middle mouse button and press the left mouse button
  1432.  
  1433. `diskinserted'
  1434.      Insert a disk in any drive.
  1435.  
  1436.  
  1437. ************ end of Stefan Becker's text *****************************
  1438.  
  1439.  
  1440.  
  1441.  
  1442.              appendix: tutorial / the supplied hotkey mapping
  1443.              ------------------------------------------------
  1444.  
  1445. It is quite important for you to have a close look on the supplied example
  1446. hotkey mapping of Angie, because only if you understand all of its hotkey
  1447. definitions, you can be sure to know all the power of Angie and become
  1448. familiar with the different commodities input descriptions you can use for
  1449. your very personal Angie configuration.
  1450.  
  1451.  
  1452. examples of the supplied mapping:
  1453.  
  1454. ***
  1455.  
  1456. 'lcommand esc' is mapped to '[^cd ram:╢newshell *]'
  1457.  
  1458. I.e.  every time you press the left amiga key plus the ESCape key, Angie
  1459. starts a shell with the stack size Angie was started with, the task
  1460. priority Angie was started with, the command path Angie was started with,
  1461. the current directory assigned to 'ram:' and with the console Angie opened
  1462. for the asynchronously launched process (the console window opens with
  1463. optimized size and position on the default public screen).  As the ToFront
  1464. attribute ('^') is set for the AsyncDosSequence, the default public
  1465. screen is immediately popped to the front.
  1466.  
  1467. ***
  1468.  
  1469. 'f7' is mapped to '^<control x>~80list   lformat "%s%s"<left>\
  1470. <left><left><left><left><left><left><left><left><left><left><left><left>\
  1471. <left><left><left>'
  1472.  
  1473. This definition already shows how to assign multiple actions to one single
  1474. hotkey.  It may be used in a shell:  if you press f7, the active shell
  1475. window is popped to front, any text that may be already typed in the
  1476. command line is deleted (that's the effect of <control x>), then after a
  1477. short delay of 80 milliseconds, the text 'list lformat "%s%s"' is inserted,
  1478. and the cursor is positioned on the second space character after 'list'.
  1479.  
  1480. Why that delay, you may wonder.  The answer is as follows:  The console is
  1481. usually able to accept input events without any delay between them, yet
  1482. there's the special <control x> case, where the console needs some dozens
  1483. of milliseconds to recover, and all events that were inserted during this
  1484. blackout are lost forever.
  1485.  
  1486. ***
  1487.  
  1488. 'f8' is mapped to '#200 <rawmouse leftbutton mouse_leftpress>\
  1489. <rawmouse upstroke mouse_leftpress>'
  1490.  
  1491. If you press the function key f8, two rawmouse input events are inserted
  1492. into the input stream, with a 200ms delay between the insertions.  The two
  1493. events emulate a click on the left mouse button, with a click duration of
  1494. 200 milliseconds:  The first event is inserted for the downstroke event of
  1495. the left mouse button whilst the second event signifies the upstroke event
  1496. for the left mouse button.
  1497.  
  1498. ***
  1499.  
  1500. 'diskinserted' is mapped to '[if exists sys:utilities/say╢\
  1501. sys:utilities/say "You've inserted a disk right now"╢endif]'
  1502. with the NoFilter attribute set
  1503.  
  1504. This definition has the effect that every time you insert a disk in one of
  1505. your disk drives, and you have the 'sys:utilities/say' program of Workbench
  1506. 2.04 along with the LIBS:translator.library & DEVS:narrator.device files
  1507. installed, your Amiga tells you that you've just inserted a disk' The
  1508. NoFilter attribute is set in order to supply all other commodities objects
  1509. that are linked into the commodities network after this definition's object
  1510. with the diskinserted event, too - otherwise all diskinserted events would
  1511. be swallowed by this definition's commodities object.
  1512.  
  1513. ***
  1514.  
  1515. 'rawmouse leftbutton rightbutton mouse_rightpress' is mapped to
  1516. '#100<rawmouse upstroke mouse_leftpress><lcommand shift l>' and
  1517. 'lcommand shift -repeat l' is mapped to the '(ToBack)' action.
  1518.  
  1519. NOTE:  This definition only works if you have Workbench 2.1 or higher.  The
  1520. reason is as follows:  Due to a bug, the commodities.library V37 of
  1521. Workbench 2.04 ignores all 'leftbutton', 'midbutton' & 'rbutton' qualifiers
  1522. when it searches for a matching input event.  As a result, this hotkey
  1523. would be triggered for every click on the right mouse button.  However,
  1524. this is intolerable.  So, in the above definition the 'rbutton' qualifier
  1525. has been replaced by the 'rightbutton' qualifier, which commodities.library
  1526. V37 cannot parse.  Thus this hotkey definition is ignored by Angie for
  1527. Workbench 2.04 systems.
  1528.  
  1529. The first definition is a magic to bring a window to back by pressing the
  1530. left mouse button, and while keeping the left mouse button pressed,
  1531. clicking the right mouse button.  THIS DEFINITION EVEN WORKS IF YOU HAVE
  1532. THE AUTO HUNT ENABLED, if you have small 'Stable time' and 'Snoop delay'
  1533. values (Otherwise just replace the '#100' by '#200' etc).  Have a close
  1534. look at this definition, especially at the <rawmouse upstroke
  1535. mouse_leftpress> event!  Every time you have a rawmouse hotkey where the
  1536. leftbutton qualifier is specified without the mouse_leftpress keycode, and
  1537. you want to assign an Intuition window action to that hotkey, you are
  1538. advised to do it like here:  Map two input events (or solely the above
  1539. mentioned <rawmouse upstroke mouse_leftpress>-Event plus a short delay plus
  1540. the other actions) to the hotkey, with the first event inserted the
  1541. <rawmouse upstroke mouse_leftpress> event, and the second one an event that
  1542. Angie has assigned to the Intuition action itself.  This is because
  1543. otherwise, WORKBENCH windows react in a very sluggish way to such a hotkey.
  1544. This is in no way due to Angie, but thoroughly to Intuition.  The 100 ms
  1545. delay in this particular definition is for evading problems with Angie's
  1546. Auto-Hunt device and is usually not needed.
  1547.  
  1548. The second definition ('lcommand shift -repeat l') shows how to define
  1549. normal rawkey hotkeys within Angie: If you press the left amiga key,
  1550. shift and 'l', the active window is brought to the back of its screen.
  1551.  
  1552. ***
  1553.  
  1554. 'lcommand shift -repeat z' is mapped to the '(Zip)' action &
  1555. 'lcommand -repeat z' is mapped to the '(^Zip)' action.
  1556.  
  1557.  
  1558. These definitions are two normal rawkey type definitions that both cause
  1559. the active window to zip its position.  For the second definition, the
  1560. active window also immediately pops to the front (and is hunted, if the
  1561. global 'Hunt on wintofront hotkeys' feature is selected), as the ToFront
  1562. attribute is set.  If you have the global 'Hunt always' switch turned on
  1563. however, the active window is always popped and hunted, even if you press
  1564. the first hotkey.
  1565.  
  1566. Note the specified '-repeat' qualifier in the definition.  It has the
  1567. effect that if you keep the 'z' key pressed, the repeated presses are also
  1568. included in the hotkey definition.  'BUT', you may complain, 'I only get a
  1569. Zip action ONCE even if I keep the 'z' key pressed.' Cool down, dude, this
  1570. is right, and is due to Angie:  By default, Angie swallows all hotkey
  1571. presses, that have the 'repeat' qualifier set.  In order to inhibit this
  1572. for one specific hotkey, just set the 'Repeatbl' attribute for that hotkey,
  1573. and all hotkey presses matching that hotkey's input description are
  1574. processed by Angie, even those that have the 'repeat' qualifier set.
  1575.  
  1576. ***
  1577.  
  1578. 'lcommand -shift -repeat help' is mapped to the '(^HuntWindow)' action with
  1579. the NoScrAct attribute set and
  1580. 'lcommand lamiga_press' is mapped to the 'NoKeyActivate' pseudo action with
  1581. the NoFilter, NoScrAct & Repeatbl attributes set. 
  1582.  
  1583. The first definition is a rawkey hotkey definition with an extraordinary
  1584. characteristic:  The NoScrAct attribute is set for this hotkey.  This has
  1585. the effect that even if the active window's screen is completely hidden,
  1586. and one or more other visible screens with windows exist, and the global
  1587. 'Key screen activation' function is active, triggering this hotkey does NOT
  1588. CAUSE A 'KEY SCREEN ACTIVATION' ACTION.  Thus, if you have an active window
  1589. on another screen, and that screen is completely invisible, you can press
  1590. lcommand help to hunt that active window.  Without the NoScrAct attribute,
  1591. pressing help would activate a new window on one of the visible screens and
  1592. hunt the new active window, which would be rubbish.  If the second hotkey
  1593. wasn't defined, the same nonsense operation would happen if you pressed the
  1594. lcommand qualifier key (see next example for more).
  1595.  
  1596. ***
  1597.  
  1598. 'lcommand lamiga_press' &
  1599. 'lcommand -repeat -caps -alt -control m' &
  1600. 'lcommand -repeat -caps -alt -control n' are all mapped to
  1601. the 'NoKeyActivate' pseudo action with the NoFilter, NoScrAct & Repeatbl
  1602. attributes set.
  1603.  
  1604. These definitions are special in several ways:  First, the 'NoKeyActivate'
  1605. action is a pseudo action, i.e.  it does not trigger any action.  Second,
  1606. the NoFilter, NoScrAct & Repeatbl attributes are enforced for this pseudo
  1607. action:  All matching input events are kept from triggering 'Key screen
  1608. activation' action, even if all conditions for that action are given (see
  1609. the last example for more).
  1610.  
  1611.  The last two input descriptions represent the normal Intuition hotkeys for
  1612. shuffling screens respectively for popping the Workbench screen to front.
  1613. Why should these events be kept from triggering 'Key screen activation'
  1614. action, you may ask, and the answer is as follows:  it is usually
  1615. undesirable to have a key screen activation action triggered for hotkeys
  1616. that shuffe screens without activating a window of the new frontmost
  1617. screen, no matter whether these hotkeys are defined inside (simply set the
  1618. NoScrAct attribute for the hotkey in that case) or outside Angie.
  1619.  
  1620.  The first description keeps all simple key presses of the left amiga key
  1621. from causing Key Screen Activation action.  This may be useful because most
  1622. hotkey definitions of the supplied Angie configuration (and the 'lcommand
  1623. m/n' Intuition screen shuflling hotkeys!) include the lcommand qualifier.
  1624. If you want to keep these hotkeys from triggering key screen activation by
  1625. setting the NoScrAct attribute, this would have no effect if the 'lcommand
  1626. lamiga_press' key was not mapped to the 'NoKeyActivate' pseudo action, as
  1627. pressing the left amiga key would originate the Key Screen Activation
  1628. action.
  1629.  
  1630. ***
  1631.  
  1632. Now, apprentice, go and create your very personal Intuition interface!;-)
  1633.  
  1634.  
  1635.  
  1636. FOR MORE HOTKEY EXAMPLES, IN CONNECTION WITH THE SETACTIVEWIN UTILITY &
  1637. SYNCDOSSEQUENCES, HAVE A LOOK AT THE DOCUMENTATION OF SETACTIVEWIN!!!
  1638.  
  1639.  
  1640.  
  1641.  
  1642. PS:  This documentation was written in a few hours and has not been
  1643. completely checked for typos & mistakes yet - so don't blame me if you find
  1644. many mistakes - keep in mind that English is not my native language;-)
  1645.  
  1646.  
  1647.  
  1648.