home *** CD-ROM | disk | FTP | other *** search
/ Frozen Fish 2: PC / frozenfish_august_1995.bin / bbs / d09xx / d0938.lha / Angie / Angie.doc < prev    next >
Text File  |  1993-12-20  |  38KB  |  918 lines
  1.  
  2.               ----------------------------------------------
  3.               Angie 1.6 (4.11.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: 2:2476/506.18
  14.  
  15.              GUI created with assistance of GadToolsBox 37.300
  16.  
  17.           Since Angie is Giftware you are encouraged to send the
  18.          author a present, money, a postcard, etc. if you use it.
  19.  
  20.  
  21.  
  22.                              table of contents
  23.                              -----------------
  24.  
  25.                                   preface
  26.  
  27.            ATTN. lazy boys and girls - WHAT EVERYONE SHOULD KNOW
  28.  
  29.                          concepts, program design
  30.  
  31.                         the installation procedure
  32.  
  33.       the interactive user interface & the arguments passed on startup
  34.  
  35.                           how to define a hotkey
  36.  
  37.                         The various hotkey actions
  38.  
  39.                  programming info, implementation details
  40.  
  41.                               program history
  42.                               
  43.                                 final notes
  44.  
  45.                            contacting the author
  46.  
  47.                                   credits
  48.                                   
  49.  
  50.                                   preface
  51.                                   -------
  52.  
  53. Angie is a nice name as well as a terrific song by the Rolling Stones.
  54. From now on, this name is to be remembered in the Amiga community as well:
  55. Angie, i.e. this software's name is an acronym for
  56.  
  57.                     ANother  Great  Intuition  Enhancer
  58.  
  59.  
  60.  
  61.  
  62.            ATTN. lazy boys and girls - WHAT EVERYONE SHOULD KNOW
  63.            -----------------------------------------------------
  64.  
  65. If you have other commodities than Angie shuffle screens on hotkeys,
  66. you ought to define pseudo hotkeys with action 'NoKeyActivate' for
  67. those hotkeys.  These pseudo hotkey definitions keep Angie from getting
  68. mixed up when shuffling screens with these hotkeys consecutively if the
  69. global Angie switch 'Key screen activation' is on.  Note however that
  70. these pseudo hotkey definitions need commodities.library V38 (=WB2.1)
  71. or higher to work.  For Intuition screen shuffling with lcommand m/n,
  72. the two necessary pseudo hotkey definitions are:
  73.          'lcommand -repeat -shift -alt -control -capslock m' &
  74.           'lcommand -repeat -shift -alt -control -capslock n'
  75.                       (action = 'NoKeyActivate')
  76.  
  77. You ought to set the 'NoScrAct' attribute for all of your hotkey
  78. definitions that shuffle screens or retrieve windows like the 
  79. 'HuntWindow', 'LastActive', 'LastActiveScr' actions.
  80.  
  81. Note for users upgrading from versions older than 1.4:  There exists
  82. A NEW 'Custom' BASE ACTION that can be used to EXECUTE DOS COMMANDS
  83. and to INSERT INPUT EVENTS into the input stream.
  84.  
  85. The STRING GADGETS of Angie have SPECIAL EDITING FEATURES:  'ESC'
  86. cancels the editing operation, and for the 'Edit Hotkeys' & 'Action'
  87. gadgets, the CURSOR UP/DOWN KEYS have a special functionality.
  88.  
  89. If you start Angie from shell, all arguments that have values
  90. assigned need to be surrounded by quotes, e.g.  "CX_PRIORITY=127"
  91. instead of just CX_PRIORITY=127
  92.  
  93.  
  94.  
  95.  
  96.  
  97.                          concepts, program design
  98.                          ------------------------
  99.  
  100. In fact, the Angie commodity enhances Amiga's unique Intuition
  101. graphical user interface in many ways.  But what is even better:  It
  102. is thoroughly customizable by the user - i.e.  YOU; thus you have
  103. the ability to adapt it to your personal taste and likes in almost
  104. any way whatsoever.  This is accomplished by providing you with
  105. complete user control of almost all of Angie's significant
  106. characteristics from within a nitfy graphical user interface (and
  107. save them for later retrieval from there, of course)
  108.  
  109. Amongst Angie's capabilities there are automatic window hunting
  110. (i.e.  active screen and active window to front, adjusting the
  111. display of over-sized autoscroll screens) as provided by J÷rg
  112. Bublath's HuntWindow, retrieval of the last active window & the last
  113. active screen on hotkey, remembering & retrieval the last active
  114. window of all screens (similar to Tron's TWA), and a hitherto unique
  115. 'Key screen activation' feature that activates the last window
  116. remembered (or the window under the mouse, or the screen's frontmost
  117. window if none is remembered) *if, and only if* the active window is
  118. not placed in one of the at least partially visible screens and a
  119. key downstroke event is rushing in from the input device.  This
  120. feature has proved *very* ergonomic and nifty (in deed, it was
  121. actually the motivation for me to embark on this project;-))
  122. Moreover, Angie can automatically raise the priority of the task
  123. that owns the currently active window (and restore it when the
  124. window becomes inactive, of course) However, the best is that Angie
  125. (don't you forget the triad:  the nice name, the terrific Rolling
  126. Stones song and the neat commodity we are talking about...) offers
  127. you about sixty actions that may be triggered by any number of
  128. arbitrary commodities input descriptions!  In conjunction with the
  129. possible 'Window To Front' attribute that may be bound to any hotkey
  130. and that affects all hotkey operations with windows involved (except
  131. 'Hunt', 'ToFront' & 'ToBack') of course) and in combination with the
  132. 'Hunt on wintofront hotkeys' you get roughly one hundred and thirty
  133. different actions you may map to any input event the version of
  134. commodities.library you have installed in your system can process.
  135. These actions include execution of arbitrary dos command lines and
  136. insertion of arbitrary input events with arbitrary delay times
  137. between inserting two events.
  138.  
  139. Angie can take advantage of several V39 Intuition / GadTools and V38
  140. Commodities features but operates well with V37 Intuition/ GadTools/
  141. Commodities, too.
  142.  
  143.  
  144.  
  145.                         the installation procedure
  146.                         --------------------------
  147.  
  148. What installation procedure?  - Just copy Angie and its icon to your
  149. SYS:WBStartup directory.
  150.  
  151.  
  152.  
  153.      the interactive user interface & the arguments passed on startup
  154.      ----------------------------------------------------------------
  155.  
  156. The GUI conforms to Commodore's User Interface Style Guide, thus it should
  157. be mostly intuitive and self-explanatory to the User who is familiar with
  158. Commodore's commodities and preferences editors supplied with the operating
  159. system.  The usual commodities arguments 'CX_PRIORITY, CX_POPUP & CX_POPKEY
  160. are supported.
  161.  
  162. Notez-bien: If you start Angie from shell, all arguments that have values
  163. assigned need to be surrounded by quotes, e.g. 
  164. "CX_PRIORITY=127" instead of just CX_PRIORITY=127
  165.  
  166.  
  167. Following now is a brief description of the GUI elements and Angie's
  168. arguments:
  169.  
  170.  
  171. The checkbox toggle gadgets:
  172.   
  173.   'Hunt always' - decides on whether or not Angie shall automatically hunt
  174.     (i.e.  bring the active window & the active screen to front & adapt
  175.     the active screen's position so that as much of the active window as
  176.     possible is visible.  This screen position adapting is performed
  177.     whenever the active window changes or its position or size changes.
  178.     It is done in a way that minimum screen move takes place.  In case the
  179.     window is too large to fit in the actual display, the screen is moved
  180.     so that the left/top edge of the window is displayed in the left/top
  181.     edge of the visible portion of the screen - except for backdrop windows,
  182.     where it is only ensured that the screen's display clip is completely
  183.     filled with the screen's data (i.e. if the screen is dragged down, it
  184.     will reposition, otherwise not). This action is deferred until the
  185.     left mouse button and its keyboard equivalent (lalt amiga) are released.
  186.     The argument for this toggle is 'HUNTMODEALWAYS', it defaults to 'YES'
  187.  
  188.   'Hunt on wintofront hotkeys' - if enabled, Angie performs an automatic
  189.     hunt (see above) operation whenever it issues a hotkey-bound
  190.     Window_To_Front.
  191.     The corresponding argument is 'HUNTMODEWFRONT' and defaults to 'YES' 
  192.     
  193.   'Hunt: set default public screen' - toggles the automatic declaration of
  194.     the active window's screen as the system's default public screen
  195.     whenever a hunt (see above) operation is done. If the active screen
  196.     is no public screen, the Workbench screen is set as default public
  197.     screen.
  198.     The argument for this toggle is 'HUNTMODESETDEFPUBSCR' and defaults to  
  199.     'NO'
  200.     
  201.   'Key screen activation' - (de)activates a nifty, hitherto unique
  202.     feature that activates the last active window of the screen under 
  203.     the mouse remembered (or the window under the mouse, or the
  204.     screen's frontmost window if none is remembered) *if, and only
  205.     if* the active window is not placed in one of the at least
  206.     partially visible screens and a key downstroke event rushes in from
  207.     the input.device.  This feature has proved very ergonomic and nifty,
  208.     especially if immediate activation after screen shuffling is not
  209.     appropriate (indeed, this feature was actually the motivation for me to
  210.     embark on this project;-))
  211.     'KEYACTIVATE' is the argument for this, and defaults to 'YES'
  212.   
  213.   'Raise Active WinTask's Pri' - determines whether Angie should always
  214.     raise the priority of the task, the active window is associated with,
  215.     by one, and restore the old priority on deactivation if the priority
  216.     hasn't been changed by someone else in the meantime.
  217.     The correct argument is 'RAISEWINTASKPRI', default is 'YES'
  218.  
  219.   'Shuffle backdrop windows' - decides whether backdrop windows should be
  220.     considered when performing hotkey-bound window-shuffling or not.
  221.     The default is 'NO', the argument is named 'SHUFFLEBACKDROP'.
  222.     
  223.   'Pop GUI on startup' - if you want Angie's GUI window to pop open when
  224.     Angie is launched, set this toggle, otherwise switch it off.
  225.     The appertaining argument is 'CX_POPUP' and defaults to 'YES'.
  226.     
  227.     
  228. The sliders have the following significance:
  229.   
  230.   'Stable time' - this one is used to adjust the time in milliseconds, the
  231.     snoop task expects the active window, the active screen, the active  
  232.     window's size and its dimensions to remain unchanged until it signals a
  233.     'change' operation to the main task. The valid range is -1 up to 1000,
  234.     where -1 is a magic value that signifies that whenever the snoop task
  235.     detects a change, it immediately signals the main task. All positive
  236.     values including 0 require the snapshot data to remain unchanged for at
  237.     least two snoops and a minimum of 'Stable time' milliseconds.
  238.     The argument for this characteristic is called 'STABLETIME' and defaults
  239.     to 20.
  240.  
  241.   'Snoop delay' - this is the delay time in milliseconds, the SnoopTask
  242.     should wait before two snoops.  The valid range is 10..1000.  Note that
  243.     the accuracy of this delay is bound to the frequency of the vertical
  244.     blanking interrupt, which is usually 50Hz PAL, 60Hz NTSC, 70Hz
  245.     EURO36/EURO72/SUPER72, that means, you'll never get more than 50 snoops
  246.     per second for PAL, never more than 60 snoops per second for NTSC and
  247.     never more than 70 snoops per second for EURO36/EURO72/SUPER72. 
  248.     Note that allocating a CIA timer for this job to gain accuracy would
  249.     be IMHO a waste of system resources. Huge values for this characteristic
  250.     yearn for a '-1' 'Stable time' setting.
  251.     The argument name for this value is 'SNOOPDELAY' and defaults to 30.
  252.   
  253.   'Screen steps' - use this slider to set the quantity a screen should be
  254.     moved with the 'MoveScrXXX' hotkey actions.  The quantity is provided
  255.     as the 'Screen steps'-th part of the display clip of the active screen.
  256.     The range for this quantity is 1..50
  257.     This argument defaults to '5', its name is 'SCRMOVESTEPS'
  258.  
  259.   'Window steps' - this is the same as above except that this value is
  260.     applied for window moving and dimensioning via the 'MoveXXX',
  261.     'ExpandXXX' and 'ShrinkXXX' hotkey actions. The range is 1..50,
  262.     too.
  263.     The corresponding argument is named 'WINMOVESTEPS' and defaults to 5
  264.      
  265.   'CX priority' - use this to set Angie's commodity broker's priority.
  266.     Note well that this action takes effect immediately - the effort to
  267.     achieve this in a documented way was quite high, by the way.
  268.     The argument for this is called 'CX_PRIORITY' and defaults to 0
  269.     
  270.  
  271. There's one separate text entry gadget, named 'Window shuffle pattern'
  272.     where you can enter the pattern to be applied to windows' names when
  273.     doing a window shuffle ('ActivateNext' / 'ActivatePrev') hotkey action.
  274.     Windows whose titles don't match to the pattern are skipped.
  275.     The argument name for this setting is 'SHUFFLEPAT' and defaults to '#?'
  276.     (which matches all names, incl. an empty name)
  277.     
  278.  
  279. The other gadgets form a system to maintain the action hotkey list of
  280. Angie:
  281.  
  282.   Use the 'ADD' gadget to add new hotkeys to the list, the 'DEL' gadget
  283.   to delete hotkeys from the list, the 'UP' gadget to move an entry up
  284.   in the list, the 'DOWN' gadget to move an entry down in the list,
  285.   use the listview to browse through the hotkey list and to select the
  286.   active hotkey, the change operations will affect.  The change
  287.   operations consist of selecting the 'Action' gadget, where you can
  288.   select the desired base action for the hotkey. This text entry gadget
  289.   has some special editing functions: You can use the cursor up/down
  290.   keys to browse through the different base actions. If the contents
  291.   of the gadget do not reflect an exact, case-insensitive match with
  292.   a valid base action type, the 'Custom' type is considered to be
  293.   active. If not preceded by a '#' or '~' character, the contents
  294.   of the gadget signify a dos command line that shall be executed
  295.   when the hotkey is triggered. If the text's first character consists
  296.   either of '#' or '~', the following text is considered as an input
  297.   events description sequence that shall be inserted into the system's
  298.   input stream when the hotkey is triggered. You can select the
  299.   desired base action by selecting the respective entry in the
  300.   'Edit╖Hotkey╖Type', too, because shuffling through approx.  sixty
  301.   entries might be irksome, IMHO.  Another change operation is the
  302.   selection of the 'Attrs' gadget.  You can assign several attributes to
  303.   the hotkey entry with this gadget:  If the 'WinFront' attribute
  304.   is enabled, the hotkey action will cause an automatic WindowToFront()
  305.   of the processed window, if a window is affected by the hotkey action,
  306.   and the base action is not 'ToBack'.  This attribute is always
  307.   considered to be on for the 'Hunt', 'ToFront' and 'CX_POPKEY' base
  308.   actions.  The second attribute is 'Repeatbl' and means that matching
  309.   rawkey events with the 'repeat' qualifier set shall be normally
  310.   processed rather than just being filtered, which is the default.  This
  311.   attribute is always considered to be on for the 'Filter' and
  312.   'NoKeyActivate' base actions.  The last attribute is the 'NoScrAct'
  313.   attribute and inhibits the hotkey from triggering an automatic 
  314.   'Key screen activation' action (see above).  This attribute
  315.   is enforced for the 'NoKeyActivate' base action.  It is extremely
  316.   useful for simple screen shuffling action hotkeys where otherwise the
  317.   next shuffle event would cause Angie's Hunt (see above) driver to mix
  318.   up screens.  For the 'HuntWindow' base action it is recommended to set
  319.   this flag in all predictable cases, too.  Apart from that, it may be
  320.   useful to set this flag e.g.  for the 'LastActive' and 'LastActiveScr'
  321.   base actions.  Note that the 'Attrs' gadget does not always reflect
  322.   the actual attributes, since Angie's enforced settings (see above) are
  323.   not taken into account after cycling the Attrs gadget.  However, they
  324.   are always correctly displayed in the 'Edit╖Hotkey╖Type->Attributes'
  325.   submenu, which can be used to set the attributes, too.  The most
  326.   important change operation however is the listview's string gadget
  327.   where you can modify the commodities input description for the hotkey.
  328.   If you enter an invalid input description, the former description is
  329.   reused instead of the one you entered. Note that you can leave the
  330.   string gadget by pressing cursor up/down, too: The cursor up/down keys
  331.   are equivalent to pressing return within the string gadget and right
  332.   afterwards pressing cursor up/down.
  333.  
  334.  
  335. The Project menu is intuitive:
  336.  
  337.   -Save╖Settings  saves the current settings into the PROGDIR:Angie icon
  338.   
  339.   -About brings up a requester with information about Angie. Note that
  340.    while the About requester is displayed, Angie is in inactive state.
  341.   
  342.   -Hide closes the GUI window
  343.   
  344.   -Quit causes Angie to shut completely down
  345.   
  346. The underscored character of the gadget text signifies the key shortcut for
  347. selecting the respective gadget, additionally the cursor up / down keys are
  348. used to scroll through the hotkeys in the listview, the DEL key is used to
  349. delete the current entry in the listview, the ESCape key or the close
  350. gadget is used to close Angie's GUI window, and the 'Z' key or the Zoom
  351. gadget is used to (un-)iconify the GUI window.
  352.   
  353. There exists one common non-standard editing feature of all of Angie's
  354. text entry gadgets: Pressing 'ESC' leaves the gadget by discarding
  355. all changes made to it, i.e. a sort of 'CANCEL' operation.
  356.  
  357.  
  358.  
  359.                           how to define a hotkey
  360.                           ----------------------
  361.  
  362. The following text is courtesy Stefan Becker and describes the structure of
  363. the currently defined commodities input descriptions:
  364.  
  365. How to define a Hot Key
  366. ************************
  367.  
  368.    This chapter describes how to define a Hot Key as an Input
  369. Description String, which is then parsed by Commodities. Each time a
  370. Hot Key is activated Commodities generates an event which is used by
  371. ToolManager to activate Exec objects or to toggle Dock objects. A
  372. description string has the following syntax:
  373.  
  374.      [<class>] {[-][<qualifier>]} [-][upstroke] [<key code>]
  375.  
  376.    All keywords are case insensitive.
  377.  
  378.    `class' describes the InputEvent class. This parameter is optional
  379. and if it is missing the default `rawkey' is used. See InputEvent
  380. classes.
  381.  
  382.    Qualifiers are "signals" that must be set or cleared by the time the
  383. Hot Key is activated; otherwise no event will be generated. For each
  384. qualifier that must be set you supply its keyword. All other qualifiers
  385. are expected to be cleared by default. If you want to ignore a
  386. qualifier, just set a `-' before its keyword. See Qualifiers.
  387.  
  388.    Normally a Hot Key event is generated when a key is pressed. If the
  389. event should be generated when the key is released, supply the keyword
  390. `upstroke'. When both press and release of the key should generate an
  391. event, use `-upstroke'.
  392.  
  393.    The key code is depending on the InputEvent class. See Key codes.
  394.  
  395.    Note: Choose your hot keys *carefully*, because Commodities has a
  396. high priority in the InputEvent handler chain (i.e. will override
  397. existing definitions).
  398.  
  399.  
  400. InputEvent classes
  401. ===================
  402.  
  403.    Commodities supports most of the InputEvent classes that are
  404. generated by the input.device. This section describes those classes
  405. that are most useful for ToolManager Hot Keys.
  406.  
  407. `rawkey'
  408.      This is the default class and covers all keyboard events. For
  409.      example `rawkey a' or `a' creates an event every time when the key
  410.      "a" is pressed. You must specify a key code for this class. See
  411.      rawkey key codes.
  412.  
  413. `rawmouse'
  414.      This class describes all mouse button events. You must specify a
  415.      key code for this class. See rawmouse key codes.
  416.  
  417. `diskinserted'
  418.      Events of this class are generated when a disk is inserted in a
  419.      drive. This class has no key codes.
  420.  
  421. `diskremoved'
  422.      Events of this class are generated when a disk is removed from a
  423.      drive. This class has no key codes.
  424.  
  425.  
  426. Qualifiers
  427. ===========
  428.  
  429.    Some keyword synonyms were added to Commodities V38. These are
  430. marked with an `*'.
  431.  
  432. `lshift', `left_shift' *
  433.      Left shift key.
  434.  
  435. `rshift', `right_shift' *
  436.      Right shift key.
  437.  
  438. `shift'
  439.      Either shift key.
  440.  
  441. `capslock', `caps_lock' *
  442.      Caps lock key.
  443.  
  444. `caps'
  445.      Either shift key or caps lock key.
  446.  
  447. `control', `ctrl' *
  448.      Control key.
  449.  
  450. `lalt', `left_alt' *
  451.      Left alt key.
  452.  
  453. `ralt', `right_alt' *
  454.      Right alt key.
  455.  
  456. `alt'
  457.      Either alt key.
  458.  
  459. `lcommand', `lamiga' *, `left_amiga' *, `left_command' *
  460.      Left Amiga/Command key.
  461.  
  462. `rcommand', `ramiga' *, `right_amiga' *, `right_command' *
  463.      Right Amiga/Command key.
  464.  
  465. `numericpad', `numpad' *, `num_pad' *, `numeric_pad' *
  466.      This keyword *must* be used for any key on the numeric pad.
  467.  
  468. `leftbutton', `lbutton' *, `left_button' *
  469.      Left mouse button. See note below.
  470.  
  471. `midbutton', `mbutton' *, `middlebutton' *, `middle_button' *
  472.      Middle mouse button. See note below.
  473.  
  474. `rbutton', `rightbutton' *, `right_button' *
  475.      Right mouse button. See note below.
  476.  
  477. `repeat'
  478.      This qualifier is set when the keyboard repeat is active. Only
  479.      useful for InputEvent class `rawkey'.
  480.  
  481.    Note: Commodities V37 has a bug which prevents the use of
  482. `leftbutton', `midbutton' and `rbutton' as qualifiers. This bug is
  483. fixed in V38.
  484.  
  485.  
  486. Key codes
  487. ==========
  488.  
  489.    Each InputEvent class has its own key codes:
  490.  
  491.  
  492. Key codes for InputEvent class `rawkey'
  493. ----------------------------------------
  494.  
  495.    Some keywords and synonyms were added to Commodities V38. These are
  496. marked with an `*'.
  497.  
  498. `a'-`z', `0'-`9', ...
  499.      ASCII characters.
  500.  
  501. `f1', `f2', ..., `f10', `f11' *, `f12' *
  502.      Function keys.
  503.  
  504. `up', `cursor_up' *, `down', `cursor_down' *
  505. `left', `cursor_left' *, `right', `cursor_right' *
  506.      Cursor keys.
  507.  
  508. `esc', `escape' *, `backspace', `del', `help'
  509. `tab', `comma', `return', `space', `spacebar' *
  510.      Special keys.
  511.  
  512. `enter', `insert' *, `delete' *
  513. `page_up' *, `page_down' *, `home' *, `end' *
  514.      Numeric Pad keys. Each of these key codes *must* be used with the
  515.      `numericpad' qualifier keyword!
  516.  
  517.  
  518. Key codes for InputEvent class `rawmouse'
  519. ------------------------------------------
  520.  
  521.    These keywords were added to Commodities V38. They are not available
  522. in V37.
  523.  
  524. `mouse_leftpress'
  525.      Press left mouse button.
  526.  
  527. `mouse_middlepress'
  528.      Press middle mouse button.
  529.  
  530. `mouse_rightpress'
  531.      Press right mouse button.
  532.  
  533.    Note: To use one of these key codes, you must also set the
  534. corresponding qualifier keyword, e.g.
  535.  
  536.      rawmouse leftbutton mouse_leftpress
  537.  
  538.  
  539. Examples for Hot Keys
  540. ======================
  541.  
  542. `ralt t'
  543.      Hold right Alt key and press "t"
  544.  
  545. `ralt lalt t'
  546.      Hold left *and* right Alt key and press "t"
  547.  
  548. `alt t'
  549.      Hold either Alt key and press "t"
  550.  
  551. `rcommand f2'
  552.      Hold right Amiga key and press the second function key
  553.  
  554. `numericpad enter'
  555.      Press the Enter key on the numeric pad
  556.  
  557. `rawmouse midbutton leftbutton mouse_leftpress'
  558.      Hold middle mouse button and press the the left mouse button
  559.  
  560. `diskinserted'
  561.      Insert a disk in any drive.
  562.  
  563. ************ end of Stefan Becker's text *****************************
  564.  
  565.  
  566.                         The various hotkey actions
  567.                         --------------------------
  568.  
  569.  
  570. Now, let's discuss the various hotkey actions:
  571.  
  572.  
  573. CX_POPKEY: 
  574.   Pop Angie's GUI window open, activate and hunt it if it is already open.
  575.   
  576. HuntWindow:
  577.   Perform a hunt action (see above) right now.
  578.   
  579. Activate:
  580.   Activate the window under the mouse  
  581.  
  582. ActivateNext:  
  583.   Shuffle forward through the current active screen's window list
  584.   
  585. ActivatePrev:  
  586.   Shuffle backward through the current active screen's window list
  587.  
  588. ActivateBackdrop:
  589.   Activate the active screen's first backdrop window
  590.  
  591. ActivateFrontScr:
  592.   Activate the frontmost window on the frontmost screen.
  593.   
  594. LastActive:
  595.   Activate the window that was active right before the current active  
  596.   window if it still exists, In case it doesn't exist any more, but
  597.   it was opened on another screen that still exists, this action 
  598.   activates that screen's frontmost window.
  599.  
  600. LastActiveScreen:
  601.   Activate the last active window of the last active screen, if it still
  602.   exists.  If it doesn't exist anymore, but the screen on which it was open
  603.   still exists, then activate the frontmost window on that screen.
  604.   
  605. ToFront:
  606.   Pops the currently active window to front
  607.  
  608. ToBack:
  609.   Moves the currently active window to the back  
  610.   
  611. AdaptWindow:
  612.   This is something like an 'inverted hunt' action:  the active window is
  613.   (if necessary) moved and shrunk in a way that it fits into the currently
  614.   displayed portion of its screen.
  615.   
  616. CenterWindow:
  617.   The active window is centered within the currently displayed portion of
  618.   its screen.
  619.   
  620. Zip:
  621.   The active window is zipped (equivalent to selecting the Zoom gadget)
  622.   
  623. Close:
  624.   A selection of the active window's close gadget is emulated
  625.  
  626. Max:
  627.   The active window's position and size are changed to exactly fill the 
  628.   screen's visible portion.
  629.   
  630. MaxWidth:
  631.   The same as for above, but only horizontally, and if at least a part of  
  632.   the window would be visible in the screens display portion with
  633.   consideration to the vertical window position & dimension.
  634.   
  635. MaxHeight:  
  636.   Like MaxWidth, but now vertically.
  637.   
  638. MinWin:
  639.   The active window is shrunk to its minimum dimensions and moved into the
  640.   lower right edge of the screen's visible portion
  641.  
  642. MoveLeft / MoveRight / MoveUp / MoveDown:
  643.   Move the active window in the respective direction, the move quantity is
  644.   derived from the 'Window steps' setting.
  645.  
  646. UpperLeft / LowerLeft / UpperRight /  LowerRight:
  647.   Place the  active window in the respective edge of the screen's visible
  648.   portion
  649.   
  650. ExpandWidth / ExpandHeight / ShrinkWidth / ShrinkHeight:
  651.   Expand / shrink the active window's width / height. The quantity
  652.   to expand /shrink is derived from the 'Window steps' setting.
  653.  
  654. DoubleWidth / DoubleHeight / HalveWidth / HalveHeight:
  655.   Double / halve the active window's width / height
  656.   
  657. ActivateNextScreen / ActivatePrevScreen / ActivateWBenchScreen /
  658. ActivateDefPubScreen: 
  659. Shuffles the screen list forward / backward, resp. pops the Workbench
  660. screen / default public screen to the front and activates the last
  661. active window of the new front screen or the frontmost window of the
  662. screen instead.  If the 'Hunt:  set default public screen' toggle is
  663. set and either the 'Hunt always' toggle is set, or both, the 'Hunt on
  664. wintofront hotkeys' toggle is set and the 'window to front' attribute
  665. is set for the hotkey, it will also make the new front screen the
  666. default public screen even if no windows are open on it.
  667.   
  668. NextScreen / PrevScreen / WBenchScreen / DefPubScreen:
  669.   the same as for the corresponding ActivateXXXXScreen entries except
  670.   that no window activation and no default public screen definition
  671.   magic takes place.
  672.   
  673. ScrollScrLeft / ScrollScrRight / ScrollScrUp / ScrollScrDown:
  674.   scrolls the active screen in the respective direction. The scroll
  675.   quantity is derived from the 'Screen steps' setting.
  676.    
  677. UpperLeftScr / LowerLeftScr / UpperRightScr / LowerRightScr / 
  678. ShowScrCenter:
  679.   makes the respective portion of the active screen visible in its
  680.   display clip.
  681.  
  682. ScreenTop:
  683.   aligns the top edge of the active screen with the top edge of its
  684.   display clip
  685.  
  686. SetDefPubScreen:
  687.   makes the active screen the default public screen. If the frontmost
  688.   screen is a screen with no windows open, and the active screen is
  689.   completely invisible, the frontmost screen is used instead for this
  690.   operation. If the screen is not a public screen, the Workbench screen
  691.   is set as the new default public screen.
  692.  
  693. Filter:
  694.   This is a real nop operation: It does nothing at all. Thus, the
  695.   only job of this action is to filter the respective input 
  696.   sequences out of the input stream.
  697.  
  698. NoKeyActivate:
  699.   This action only works if your system runs commodities.library
  700.   V38 or better - for V37 commodities.library it does nothing at all.
  701.   All input events matching this action's input description are excluded
  702.   from triggering 'Key screen activation' (see above). This is useful to
  703.   keep other commodities / input handlers that shuffle screens (e.g. for
  704.   Intuition / KCommodity: 
  705.          'lcommand -shift -control -alt -repeat -capslock [m|n]')
  706.   from fooling Angie's snoop code in some cases when screens are 
  707.   consecutively shuffled.
  708.   
  709.  
  710. ** Starting from Angie 1.4 (28.10.93), Angie has another mighty base **
  711. **   action for executing Dos commands and inserting input events:   **
  712.  
  713. Custom:
  714.   This action is very versatile:  If the first character of the action
  715.   string is either '#' or '~', the following contents of the 'Action'
  716.   gadget are considered to be INPUT DESCRIPTION DATA.  In case of the '#'
  717.   introducer, a positive (incl.  0) number may be provided right after
  718.   the '#' introducer.  This number ends either with the last digit or
  719.   with one of the ' ' / '~' delimiters.  It is normalized into the range
  720.   0..999 and signifies the time in milliseconds to delay after inserting
  721.   each of the generated input events.  In case of the '#' introducer,
  722.   this delay defaults to 50 milliseconds.  For the '~' introducer, this
  723.   delay is always considered 0.  The input description data consist of
  724.   ordinary plain ASCII text that may furthermore contain the following
  725.   ESCape codes:
  726.           \n   -  linefeed (inserted  as carriage return)
  727.           \r   -  carriage return
  728.           \0   -  nul
  729.           \t   -  horizontal tab 
  730.           \f   -  formfeed
  731.           \xff -  ASCII code 0xff (f represents an arbitrary hex nibble)
  732.           \'   -  apostrophe
  733.           \"   -  quotation mark
  734.           \<   -  left angled bracket '<'
  735.           \\   -  backslash '\'
  736.   Moreover, separate input events may be specified according to Commodities'
  737.   ParseIX() syntax within angled brackets.  The line 
  738.   '<lcommand a><tab>Hello!<alt -capslock numericpad enter>\x06\t\5*x\<12\n'',
  739.   for example, represents valid input description data.
  740.   Plain Linefeeds (0x0a) are automatically converted into carriage returns.
  741.   In addition to this, carriage returns are inserted as key presses of the
  742.   plain, simple carriage return rawkey unless the system default keymap
  743.   doesn't map that rawkey to carriage return.
  744.  
  745.   In case the first character of the 'Action' data contents is none of the  
  746.   input description sequence introducers ('~', '#'), the whole text
  747.   represents a DOS COMMAND LINE that is executed asynchronously whenever
  748.   this custom hotkey is triggered. The priority of the launched task will
  749.   be the same as the priority, Angie was started with - the same goes for
  750.   the stack size, current directory and the dos command search path.
  751.   Input and Output are set to an interactive console window with the
  752.   WAIT/AUTO/CLOSE attributes, its position and alternative ('zoom') 
  753.   position are optimized for the currently displayed portion of the default
  754.   public screen. The console will open on the default public screen at
  755.   the very moment when the first input/output operation takes place.
  756.   If you set the 'WinFront' attribute for the hotkey, the default public
  757.   screen pops to front immediately when triggering the hotkey.
  758.  
  759.  
  760. Well, that's it - all the actions are described now;-)  
  761.   
  762.  
  763.  
  764.                  programming info, implementation details
  765.                  ----------------------------------------
  766.  
  767. Angie is completely written in Amiga-Oberon, a superset of a powerful
  768. object-oriented language by Nicolaus Wirth, that offers all the flexibility
  769. and excellent code generation that is needed for Amiga system and
  770. application programming.  I tried hard to make Angie conforming with the
  771. User Interface Style Guide, and to make it really free of bugs.  I can tell
  772. you that despite having used Oberon runtime checking code (which is
  773. disabled in this official release), Enforcer and Mungwall, this release has
  774. been proved free of any bugs (however, don't blame me if you find one
  775. though:  you know Murphy rules...;-^) Especially, I always tried to ensure
  776. that all accesses to system data are protected by the respective official
  777. CBM protocols.  Since within interrupts there is no such protocol for
  778. Intuition data structures available, I placed the snooping code for window
  779. hunting, raising of the active window task's priority, remembering of the
  780. last window and all the last windows of a screen, in a child task rather
  781. than within interrupt code.
  782.  
  783. If you find any bugs or you have any suggestions for improving Angie or
  784. extending its functionality, or if you just want its source code,
  785. you are encouraged to contact the author via electronic mail (preferred)
  786. or snail mail.
  787.  
  788.  
  789. If you own a 68000 you may wonder why Angie's snoop task uses quite more
  790. CPU time than you thought it uses (Note however that only Xoper2.4 gives
  791. you reliable information.  Former versions of Xoper display much too much
  792. CPU time usage of tasks that are both, frequently switched and don't hold
  793. the CPU for a long time).  Well, the solution is as follows:  I decided to
  794. make Angie as system-friendly as possible.  Angie has to snoop not only the
  795. IntuitionBase->ActiveWindow, but also elements like
  796. TopEdge/LeftEdge/Width/Height/WScreen of the ActiveWindow itself.  In a
  797. consistent way, this is only possible within tasks, not interrupts, in
  798. conjunction with the (Un)LockIBase() protocol.  However, task switching,
  799. the timer request for delaying, and especially the (Un)LockIBase() protocol
  800. produce an enormous overhead of CPU usage:  I measured (on a 68030, OS3.0)
  801. that the snoop code itself only consumes 15% (fifteen) percent of the snoop
  802. task's total CPU usage (total CPU usage is less than 1% @ 30 ms snoopdelay
  803. on 68030, 25Mhz, OS3.0).  With the snoop code removed, only the timer IO
  804. and (Un)LockIBase() stub left, the CPU usage of the snoop task was still at
  805. 85% of the original CPU usage.  With (Un)LockIBase() removed, the snoop
  806. task's CPU usage was at about 45% of the original CPU usage.
  807.  
  808.  
  809.  
  810.  
  811.  
  812.                               program history
  813.                               ---------------
  814.   v1.0 20.10.93 [fSchwarz]
  815.   v1.1 22.10.93 [fSchwarz] improved setDefPubScreen action
  816.     fixed ActivateXXXXScreen, fixed Menu Attrs selection
  817.   v1.2 23.10.93 [fSchwarz] doesn't send any closeWindow
  818.     event on Close action when window is blocked by
  819.     requesters.
  820.   v1.3 24.10.93 [fSchwarz] added Edithook for hotkey
  821.     definition gadget
  822.   v1.4a 29.10.93 [fSchwarz] major code cleanup, now
  823.     supports dos command and inputevent insertion type
  824.   v1.5a 4.11.93 [fSchwarz] now really uses the frontmost
  825.     window of screens instead of just screen.firstWindow;
  826.     improved Key Screen Activation handling for screens
  827.     without windows
  828.   v1.6 4.11.93 [fSchwarz] removed last Intuition stuff from
  829.     cxcustom inputhandler - now all accesses to Intuition
  830.     structures are safeguarded by official CBM protocols;
  831.     enhanced Intuition/GadTools V37 GUI
  832.  
  833.  
  834.  
  835.                                 final notes
  836.                                 -----------
  837.  
  838. Known Bugs:  Currently, no known bugs exist.  However, due to the extent of
  839. this project, it is possible that a few bugs are in the code that haven't
  840. turned out yet.
  841.  
  842.  
  843. Angie is Giftware. In other words, I strongly encourage you to
  844. send me a small present, a donation, a nice postcard, and so on, if
  845. you appreciate this program and you use it.
  846. Suggestions, comments, bug reports, criticism, praise, etc.  are
  847. welcomed, too!
  848.  
  849. If you want to translate this documentation into other languages, feel 
  850. free to do so, add the translation to this archive, and send it to the
  851. author (that is me;-))
  852.  
  853.  
  854. Angie is copyrighted and protected by copyright laws all over
  855. the world. Copyright ⌐ 1993 Franz Schwarz.
  856.  
  857.  
  858. The author can't be hold liable for any harm that stems from the
  859. usage of this program, no matter whether direct harm or indirect harm.
  860.  
  861. Angie is freely distributable; it may be published in the Fred Fish
  862. & Amok software collections and in other non-commercial software
  863. collections, including CD-ROM versions of them. Moreover, it may be
  864. spread via electronic data transfer.
  865.  
  866. Angie may only be distributed in this archive as a whole.  It may 
  867. be only distributed if the distributor does not claim any copyright on
  868. the Angie archive nor on any files that are compulsorily distributed
  869. with it (i.e. the distributor claims that this archive may not be
  870. distributed separately without those files). Inquiries on exceptions
  871. from these limitations may be submitted to the author.
  872.  
  873.  
  874.                            contacting the author
  875.                            ---------------------
  876.  
  877.                                Franz Schwarz
  878.                               Mⁿhlenstra▀e 2
  879.                        D-78591 Durchhausen, Germany
  880.                     Uucp: Franz_Schwarz@mil.ka.sub.org
  881.                             Fido: 2:2476/506.18
  882.                          Bank account 951.207 at 
  883.              KSK Trossingen, Germany, bank ZIP code 643 500 70
  884.  
  885.  
  886.  
  887.  
  888.                                   Credits
  889.                                   -------
  890.  
  891. The interactive graphical user interface was created with assistance of
  892. GadToolsBox 37.300 by Jan van der Baard and its Oberon source generator
  893. OG 38.02 by Stefan Kurtz, Thomas Igracki & Kai Bolay.
  894.  
  895.  
  896.  
  897.  
  898. Have fun, and don't you forget:
  899.  
  900. Angie is a nice name as well as a terrific song by the Rolling Stones.
  901. From now on, this name is to be remembered in the Amiga community as well:
  902. Angie, i.e. this software's name is an acronym for
  903.  
  904.                     ANother  Great  Intuition  Enhancer
  905.  
  906.  
  907.   Franz 'Blacky' Schwarz
  908.  
  909.                - Girlfriend Is Better - Talking Heads -
  910.  
  911.  
  912.  
  913. PS:  This documentation was written in one go in a few hours and has not
  914. been completely checked for mistakes yet- so don't blame me if you find
  915. many mistakes...
  916.  
  917.  
  918.