home *** CD-ROM | disk | FTP | other *** search
/ Groovy Bytes: Behind the Moon / groovybytes.iso / GROOVY / SND_TOOL / WM10.ZIP / DOC.DAT / fnkeys.txt < prev    next >
Encoding:
Text File  |  1995-08-30  |  8.8 KB  |  158 lines
  1.  Function Keys
  2.  ─────────────
  3.  
  4.  WMmain, WMmenu, WM Read, WM WAView and WM PRGed all give you access to ten 
  5.  programmable Function keys (F1 to F10). In addition, many WM application 
  6.  programs change the contents of WAVmaker's public Function key file (see 
  7.  below), allowing new Function key values to be inherited by other WM 
  8.  applications (this is actually the ONLY mechanism available for changing 
  9.  Function key values in WMmain and in WMmenu!).
  10.  
  11.  Details about Function key operations in individual programs can be found in
  12.  the respective Help entries. See in particular {menuCmnd}, {Read}, {WAView}
  13.  and {PRGed}.
  14.  
  15.  This document explains the generic mechanisms behind WAVmaker's Function key
  16.  operations.
  17.  
  18.  Contents:   ■ Titles and Values            {FnKeys  24}
  19.  ────────    ■ Private Function key files   {FnKeys  41}
  20.              ■ The Public function key file {FnKeys  77}
  21.              ■ Is this a kludge or what?!?  {FnKeys 140} (want to speed it up?)
  22.  
  23.  
  24. ─── Titles and Values ──────────────────────────────────────────────────────────
  25.  
  26.  At runtime, all WAVmaker applications supporting Function keys keep their own
  27.  private record of current Function key titles and values. These are strings 
  28.  comprised of up to 15 characters each (reflecting the length of the standard 
  29.  DOS keyboard buffer).
  30.  
  31.  ■ Titles are labels, preferably mnemonic ones. Typical titles are "File #1", 
  32.    "Start time" or, when greater flexibility is called for, "Parameter #1". 
  33.    There is nothing to keep you from assigning a time value to a Function
  34.    entitled "File #1", but if you can refrain from doing so, you probably 
  35.    should!
  36.  
  37.  ■ Values are what gets actually written to the keyboard buffer when you press 
  38.    a Function key.
  39.  
  40.  
  41. ─── Private Function key files ─────────────────────────────────────────────────
  42.  
  43.  Some WAVmaker programs keep private files where they store current Function 
  44.  key titles and values upon exit. The next time such a program is called, the 
  45.  file is read back in and the Function key assignments are updated accordingly.
  46.  WMmain and WMmenu do this, for instance, allowing you to switch back and forth
  47.  between menus and have a different set of Function key assignments for each 
  48.  one of them (WMmenu maintains a separate file for each menu it manages, so 
  49.  there is no risk of interference between Function key assignment for e.g. 
  50.  the File and the PRG menus - but see the explanation of inheritance, below
  51.  {FnKeys 77}).
  52.  
  53.  If you take a look at WM.BAT, you will see that WMmain is started with the
  54.  option "/TD <directory>"; "TD" stands for "Temporary Directory", <directory> 
  55.  denotes the directory where all private Function key files (among other 
  56.  things) are kept during a WAVmaker session. WAVmaker applications which use 
  57.  such files should be provided with a "/TD <directory>" command line pair by 
  58.  the caller. WMmain and WMmenu take care of this automagically by prefixing 
  59.  the user-supplied command line with the correct "/TD <directory>" pair before 
  60.  launching an application requiring it, making the process transparent to the 
  61.  user. For details on how to tell WMmain and WMmenu when such special treatment 
  62.  is required, see {Customiz}.
  63.  
  64.  If a WAVmaker application requiring a "/TD <directory>" command line pair is
  65.  started up without one, it will neither read from nor write to the public 
  66.  Function key file. The only exceptions are WMmain and WMmenu, which default 
  67.  to "/TD Temp\". Since the <directory> fed to WMmain is propagated down to all 
  68.  other WAVmaker applications (WMmain calls WMmenu with the "/TD <directory>" 
  69.  option, too!), starting WMmain without a "/TD <directory>" pair will cause all 
  70.  WAVmaker applications to use the Temp\ directory for their private Function 
  71.  key files (and for other things, too). The <directory> propagated to other 
  72.  programs by WMmain and WMmenu is actually a fully expanded path, complete with
  73.  disk drive, so there is no risk of errors if the program works somewhere else
  74.  than in WAVmaker's main directory.
  75.  
  76.  
  77. ─── The Public Function key file ───────────────────────────────────────────────
  78.  
  79.  If there were only runtime memory records and private files of Function key
  80.  assignments, the assignments for each WAVmaker application would be totally 
  81.  isolated from those for all others. In practice, the main purpose of Function
  82.  keys in WAVmaker is not so much to aid your memory (and typing) as to provide 
  83.  a simple means for inter-application communication (now THAT came out sounding 
  84.  quite impressive, didn't it?). 
  85.  
  86.  When WMmain and WMmenu are instructed to pass the "/TD <directory>" command 
  87.  line pair described above {FnKeys 53}, they also assume that the program 
  88.  being lauched may need to know some (or all) current Function key values, 
  89.  and to return new ones upon termination. All WAVmaker applications which 
  90.  import and export Function key assignments do so by reading from and writing 
  91.  to the public Function key file (FnDelta.TXT, residing in whichever directory 
  92.  is specified by the /TD option). Thus, when WMmain and WMmenu are instructed
  93.  to call a program requiring a "/TD <directory>" pair, they write all their 
  94.  current Function key assignments to the public Function key file before
  95.  executing the call. It is then up to the program being launched to read from
  96.  the file (if needed), and (optionally) to modify the same file upon 
  97.  termination.
  98.  
  99.  The actual contents of the public Function key file is always a number of 
  100.  title:value pairs; first a line specifying a title (e.g. "File #1"), then a 
  101.  line specifying a value (e.g. "TEST.MID").
  102.  
  103.  When control is returned to WMmain or WMmenu after a call to a program
  104.  requiring a "/TD <directory>" pair, the public Function key file is read,
  105.  and the values of Function keys with matching titles are updated. What counts
  106.  here is TITLES, not key numbers; the latter are not even exported, i.e. there
  107.  is no way to tell which Function key was assigned a certain title:value by
  108.  reading the public Function key file. Most WAVmaker applications import 
  109.  Function key values by running through the file and comparing titles with
  110.  those currently assigned to the Function keys. When a match is found, the
  111.  new value is read in. (WM Read is an exception to this rule: it reads in
  112.  all it finds, in the order it's found, both titles and values, thus inheriting
  113.  the exact Function key map written to the public Function key file by the
  114.  caller).
  115.  
  116.  Note:    WMmenu always reads the public Function key file upon startup, and
  117.           it always dumps its current Function key map back into the public 
  118.           Function key file upon termination. The public file is read after the 
  119.           private one, so new values inherited from WMmain override old ones 
  120.           saved to the private file during earlier runs. 
  121.           
  122.           To WMmain, WMmenu is just another application requiring a 
  123.           "/TD <directory>" pair. Upon return from WMmenu, WMmain will 
  124.           therefore scan the public Function key file for matching titles
  125.           and update its own Function key values according to the above
  126.           description {FnKeys 103}: in this case, communication works both 
  127.           ways.
  128.           
  129.           In other words, if your main menu has a Function key entitled 
  130.           "File #1", and you enter a submenu with a Function key having the 
  131.           same title, hitting that key should always give the same result in 
  132.           both menus.
  133.  
  134.  WARNING: CASE MATTERS ("File #1" is NOT the same as "FILE #1"). Be careful 
  135.           when you assign Function key titles, or you may end up having 
  136.           apparently mysterious errors with Function keys refusing to inherit 
  137.           new values!
  138.  
  139.  
  140. ─── Is this a kludge or what?!? ────────────────────────────────────────────────
  141.  
  142.  In a way, it is. Passing values over a disk file is not very elegant, and
  143.  it can be slow. If you are a programmer, you're probably wondering why 
  144.  WAVmaker does not use a common memory area for its "clipboard". The reason
  145.  is very simple: WAVmaker is meant to be easily extended, by anyone, by any 
  146.  means. Reading and writing text files is as easy as it gets; even a BAT will 
  147.  manage that. Passing a memory address between applications is easy too, but 
  148.  it takes an experienced programmer to put such an address to good use, and 
  149.  BATs will no longer do - you'll need a compiler.
  150.  
  151.  Actually, with a fast hard disk (and especially with a good disk cache) the 
  152.  time spent reading and writing Function key files is barely noticeable. 
  153.  Should you nevertheless be bothered by a slight delay when switching menus, 
  154.  try putting your /TD directory on a RAM disk (since the files are quite small,
  155.  a minimal RAM disk will do - 10 kB or so should be fine). This in combination 
  156.  with XMS swapping should make your menus switch like greased lightning! See 
  157.  {Customiz} for details.
  158.