home *** CD-ROM | disk | FTP | other *** search
/ Club Amiga de Montreal - CAM / CAM_CD_1.iso / files / 632.lha / KCommodity_v1.63 / KCommodity.Doc.pp / KCommodity.Doc
Text File  |  1992-05-13  |  39KB  |  902 lines
  1.  
  2.  *****************************************************************************
  3.            K  K  CCCC  OOO  M     M M     M  OOO  DDDD  I TTTTT Y   Y
  4.            K K  C     O   O MM   MM MM   MM O   O D   D I   T    Y Y
  5.            KK   C     O   O M M M M M M M M O   O D   D I   T     Y
  6.            K K  C     O   O M  M  M M  M  M O   O D   D I   T     Y
  7.            K  K  CCCC  OOO  M     M M     M  OOO  DDDD  I   T     Y
  8.  *****************************************************************************
  9.  KCommodity V1.63,
  10.  a multifunctional commodity for the Amiga running under OS 2.0.
  11.  *****************************************************************************
  12.  
  13.  
  14.  *****************************************************************************
  15.  KCommodity V1.63 is ShareWare.
  16.  So   all   you   folks   out   there   who   like   my  program  and  use  it
  17.  frequently   please   send   a  little  donation  of  about  20.-DM  or  $20.
  18.  to the address given way down that document.
  19.  I  think  it`s  accurate,  since  I  included  the  whole  source,  which  in
  20.  fact  may  be   helpful  for  some  of  you.  The  advantage  of  paying  the
  21.  shareware   is   that  registered  users  of  KCommodity  will  automatically
  22.  receive   the  latest  versions  of  my  program  included  with  a  printout
  23.  of   this   document.   Maybe   it   will  then  be  set  with  TeX  and  put
  24.  together  to   a  nice  manual.  But  anyway,  anyone  who  wants  to  report
  25.  something   about   KCommodity   (like   Bugs,   further   enhancements  ...)
  26.  can contact me...
  27.  
  28.  Another word : I DO NOT TAKE ANY RESPONSIBILITY OF DAMAGES OCCURED
  29.                 DURING THE USAGE OF KCOMMODITY. THIS PROGRAM HAS
  30.                 BEEN TESTED AND I USE IT IN MY EVERY DAY WORK.
  31.                 ANYWAY, NO PROGRAMMER IS AWARE OF BUGS HE MIGHT
  32.                 PRODUCE. SO DON`T HARM ME IN THE CASE OF DAMAGE.
  33.                 (HARM MURPHY :-))
  34.  
  35.  All   you  guys  out  there  who  put  Public  Domain,  FreeWare,  ShareWare,
  36.  GiftWare  software  on  your  disks  and  request  more  than  10  DM  or the
  37.  same  amount  in  any  other  currency  leave your fingers off this program !
  38.  This   is   not   `quite`  helpfull  keeping  up  these  sorts  of  software.
  39.  
  40.  I  included  the  source  for  KCommodity.  This  one is written in Assembler
  41.  with  all  the  includes  you  need.  (I  was  too  lazy to put them into one
  42.  source file :-))
  43.  
  44.  You  can  spread  this  program  to  whoever  and  whereever you want as long
  45.  as  you  don`t  use  it  for  commercial  purposes  and  the  distribution is
  46.  kept as is.
  47.  
  48.  It  was  written  using  DevPac  version  3.01.  This  version  of KCommodity
  49.  can  only  be  assembled  under  DevPac  V3.01  or later versions since there
  50.  are some opcodes only known to DevPac V3.01.
  51.  *****************************************************************************
  52.  
  53.  
  54.  
  55.  
  56.  What the heck is KCommodity V1.63 ?
  57.  -----------------------------------
  58.  
  59.  It  unites  several  tiny  thingies  which  will  be  quite  helpfull in your
  60.  everyday use of your Amiga.
  61.  First  of  all  there  is  the  Window-Activator  of  KeyActivate (from which
  62.  KCommodity   derived),   which   does   more   than   the   usual  activators
  63.  like   AutoPoint   from   the   workbench.   These  activators  had  one  big
  64.  problem  :  They  always  deactivated  a  stringgadget  when the mousepointer
  65.  was  moved  out  of  the  window  containing  the  stringgadget.  That  was a
  66.  bug   I   really  was  crazy  about.  So  I  first  wrote  KeyActivate  which
  67.  activated   a   window   by  pressing  a  key  and  leaving  that  silly  bug
  68.  far, far behind.
  69.  Being  so  happy  about  what  I  had  achieved  on that new Operating System
  70.  I   continued   my   work   to   have   a  more  flexible,  short  commodity.
  71.  Since  I  have  plenty  of  tools  running  on  my  machine  I really thought
  72.  it  to  be  a  good  idea  if  all,  or  even some of the mostly used options
  73.  were  put  into  a  small  and  efficient  commodity,  so  that  I don`t have
  74.  to  start  dozens  of  tools  on  startup.  The  other  advantage  is that it
  75.  can  have  whatever   I  want  and  that  all  routines  could  be  coded  so
  76.  they  would  fit   my  needs  (not  to  forget  any  users  out  there  which
  77.  might   find   it  useful  too).  So  KCommodity  grew  and  grew  and  other
  78.  tools   running   got   less.   And   here   it   is   :   KCommodity   V1.63
  79.  
  80.  
  81.  Installation of KCommodity V1.63
  82.  --------------------------------
  83.  
  84.  Simply   copy   KCommodity   to   any  location  you  prefer  and  place  the
  85.  supplied   KCXPREFFILE   to  ENVARC:.  This  file  ist  configured  with  the
  86.  default values.
  87.  If  you  want  to  make  use  of  KCommodity`s  online help then copy the KCX
  88.  drawer to ENVARC:
  89.  
  90.  
  91.  Starting KCommodity V1.63
  92.  -------------------------
  93.  
  94.  - If  you  start  KCommodity  while  startup  of  your  system  (WBStartUp)
  95.    you  have  to  add  the  DONOTWAIT  tooltype  to  your  list  of tooltypes.
  96.    The  supplied  icon  has  all  the  known  tooltypes  in  it`s  list set to
  97.    the default values.
  98.  - You   have   to   Run/RunBack  KCommodity  when  started  from  CLI/SHELL
  99.  
  100.  No  matter   how  you  start  KCommodity  the  program  will  first  read  in
  101.  the  preferences  file  (if  it  exists)  and  then  examines  the ToolTypes.
  102.  This means the ToolTypes override your preferences.
  103.  If  the  NOICON  ToolType  is  not  set  KCommodity  will display an AppIcon.
  104.  When   clicked   onto   that   icon  KCommodity`s  main  window  will  popup.
  105.  Additionaly  there  is  a  new  MenuItem  (KCX Main-Window) in the Tools-Menu
  106.  with the same function.
  107.  
  108.  
  109.  
  110.  Terminating KCommodity
  111.  ----------------------
  112.  
  113.  There are several ways to terminate KCommodity.
  114.  - Using the QUIT gadget or the 'Q'-Key within the control window
  115.  - Starting KCommodity once again.
  116.  - Using the Exchange program.
  117.  
  118.  No  matter  which  way  you  choose  to  terminate  the  program it will take
  119.  a  short  amount  of  time,  since  there  may  be  some  IORequests pending.
  120.  
  121.  
  122.  
  123.  Actions KCommodity can perform
  124.  -------------------------------
  125.  
  126.  - Windowactivation -
  127.        Can be switched between KeyStroke and MouseMode and even turned off.
  128.  
  129.  - Clockdisplay -
  130.        Has several options.
  131.        Displaying the time with/without seconds,
  132.        Displaying a date in either american or german notation,
  133.        Displaying a weekday either full length or only three chars.
  134.        All options can be combined, but if you turn on the clock the time
  135.        (hour:minutes) will always be shown.
  136.        And an accumulated online time, so that you know how long you`ve
  137.        been online for a session.
  138.        By pressing the Page-HotKey (RALT HELP) you can change between
  139.        several display modes. (Time<->Memory)
  140.  
  141.  - Memory usage -
  142.        Displays the free Chip- and FastMemory, total free memory, or
  143.        graphical display of free memory.
  144.  
  145.  - Alarmfunction -
  146.        Alarmtime can be set with/without seconds but you must at least
  147.        enter hour and minutes of your requested alarmtime. Can also be
  148.        turned off.
  149.  
  150.  - Environment variables -
  151.       The current system time including day (full string), date either
  152.       american or german format and time are stored within three global
  153.       environment variables called DAY, DATE, TIME (what else)
  154.  
  155.  - Revision control system -
  156.       Keeps track of any changes made to a source (well you have to tell
  157.       the program what you`ve done) and adjusts revision numbers and
  158.       defines for use in "$VER" strings in C, Assembler and Pascal  source
  159.       codes.
  160.  
  161.  - Screen/Mouse Blanker -
  162.       The timeouts can be defined in a range from 1-999 seconds.
  163.       When a key is pressed the mousepointer is automatically blanked.
  164.  
  165.  - Window-Cycling -
  166.       This is for the easy moving of windows to the back/front of
  167.       other window without hitting the depth-gadget.
  168.       The left mousebutton in conjunction with the selected qualifier
  169.       brings the window underneith the mousepointer to front.
  170.       Using the right mousebutton in conjunction with the qualifier
  171.       brings the window behind all others.
  172.  
  173.  - KeyStroke-Clicker -
  174.       Like on professional keyboards a click is heard when a key is
  175.       pressed. Volume can be adjusted.
  176.  
  177.  - Telefone bill calculator -
  178.      Keeps track of your telefone costs due to heavy modem fun.
  179.  
  180.  - LeftyMouse option -
  181.      Activating this option will cause KCommodity to swap the left/right
  182.      mouse buttons.
  183.  
  184.  - ESC-WindowClose -
  185.      Windows with a CloseGadget can now be close using the ESC-Key.
  186.      Either with or without a qualifier. Any string gadgets that may be
  187.      active at this point are deactivated first.
  188.  
  189.  - HotKey Shell-Start -
  190.      Start a shell with your own parameters.
  191.      Default HotKey is : ALT SHIFT S
  192.  
  193.  - Mapping of german "Umlauts" -
  194.      This is usefull for the german "modem freaks" under you.
  195.      You know that german "Umlauts" are not allowed on international
  196.      EchoMail areas or even on some other german areas. So writing
  197.      a text which contains german "Umlauts" isn`t quite funny, since
  198.      you have to write two chars instead of only one.
  199.      This function maps the german "Umlauts" to "normal" chars.
  200.  
  201.  
  202.  How to deal with KCommodity ?
  203.  -----------------------------
  204.  
  205.  First  of  all  there  are  the  ToolTypes which are to be used when starting
  206.  from    Shell/CLI    the    same    way    as    started    from   WorkBench.
  207.  Here they are :
  208.  
  209.  ToolType             Description                Default
  210.  -----------------------------------------------------------------
  211.  CXPRIORITY=n         Priority of Broker         5
  212.  CXPOPKEY=s           PopUpKey for Window        LCOMMAND HELP
  213.  CXPOPUP=YES|NO       PopUp on startup           NO
  214.  PORTNAME=s           Set name for ARexx-Port    KComm.1
  215.  TOOLPRI=n            Priority of Program        21 (Must be > 21)
  216.  NOICON               Don`t display AppIcon      ---
  217.  
  218.  
  219.  
  220.  
  221.  Special infos about dealing with StringGadgets of KCommodity
  222.  ------------------------------------------------------------
  223.  
  224.  Each   window   of   KCommodity   (except  for  the  small StatusWindow and the
  225.  Logwindow) has a menu attached to it. Most (or even all) of the given menuitems
  226.  have a keyboard-shortcut. So while you`re in a StringGadget you normaly have to
  227.  deactivate the StringGadget first to get access to a  menu-shortcut.  Not  with
  228.  KCommodity.  Just  use  the  shortcut  you  like  and  KCommodity  will perform
  229.  the  action  you  wanted  it  to do :-) It will then reactivate the last gadget
  230.  again  if  needed.  The  two  MAGIC keystrokes RIGHT AMIGA X/Q which are mapped
  231.  with  edit  functions  within  StringGadgets  may  be needed for menu-shortcuts
  232.  sometimes.  To  have  these  two  executed  the  way  the  others  are executed
  233.  simply  press  the  shortcut  combined  with  any  SHIFT (eg. RAMIGA-SHIFT-Q to
  234.  quit KCommodity ... dare you).
  235.  There   are   more  functions  within  KCommodity  for  editing  StringGadgets.
  236.  
  237.  - The next available String/Integer-Gadget will be activated after a RETURN.
  238.  - The previous String/Integer-Gadget will be activated after a SHIFT-RETURN.
  239.  - Pressing ESC does the same as pressing HELP -> It escapes the String/
  240.    Integer-Gadget without activating the next one.
  241.  - As mentioned -> Menu-Shortcuts from within String/Integer-Gadgets.
  242.  - Using CURSOR UP/DOWN to get to the previous/next gadget.
  243.  - Using CONTROL CURSOR LEFT/RIGHT to get to the previous/next word.
  244.  
  245.  Standard editing modes are supported too :
  246.  
  247.  - TAB activates the next available String/Integer-Gadget
  248.  - SHIFT-TAB does the opposite
  249.  - HELP is used to escape String/Gadgets.
  250.  - RIGHT AMIGA-X clears the input buffer.
  251.  - RIGHT AMIGA-Q restores the previous input buffer.
  252.  
  253.  
  254.  
  255.  
  256.  Online-Help Function of KCommodity
  257.  ----------------------------------
  258.  
  259.  If  you  press HELP within  one of the following windows a small help text will
  260.  be shown describing the window`s purpose.
  261.  
  262.  Main   window,   Bill   window,   Preferences   window   and   HotKeys   window
  263.  
  264.  Since  these  windows  all  have  menus attached to themselves there is another
  265.  possibility to get Online-Help :
  266.  
  267.  Position  your  mouse  over  the  menu-item  you  want  help  for and press the
  268.  HELP-Key. The Help window openes up.
  269.  
  270.  Within  the  Help window  you can scroll through the help text using the gadget
  271.  on  the  right  or  your  cursor  keys. The cursor keys are mapped as follows :
  272.  
  273.  CUROSR UP         Move one line upward
  274.  CUROSR DOWN       Move one line downward
  275.  SHIFT-CURSOR UP   Move one page upward
  276.  SHIFT-CURSOR DOWN Move one page downward
  277.  
  278.  
  279.  Configurating KCommodity while runtime.
  280.  ---------------------------------------
  281.  
  282.  Just   press   your  PopUp-HotKey  (default  :  LCOMMAND  HELP),  select  the
  283.  AppIcon ,  the  "KCX Main-Window"  MenuItem  of  Tools-Menu,  or  select  the
  284.  SHOW  gadget  of  the  Exchange  program  of  your  WorkBench  and  a  window
  285.  will pop up displaying several gadgets.
  286.  
  287.  
  288.  - Window activate   Enable/Disable windowsctivation.
  289.  - MouseMode         Enable/Disable window activation via mouse.
  290.                      If unset a keystroke will activate windows.
  291.  - Display clock/mem Turn on display for clock/memory.
  292.  - Display in window Display clock/memory within a window
  293.  - Show secondz      Additionaly display seconds.
  294.  - Show date         Display date.
  295.  - American date     Display date in english notation.
  296.                      If unset it will be shown in german notation.
  297.  - Show day          Show name of current day.
  298.  - Short day string  Only three chars per day.
  299.  - Alarm on          Turn alarm on/off.
  300.  - Key-Click         Turn KeyStroke-Clicker on/off.
  301.  - Write environment Save day, date and time to environment variables
  302.                      called DAY, DATE and TIME (what else).
  303.  - Window cycling    Enable/Disable cycling of windows.
  304.  - WB to front       Enable/Disable pop to front of workbench, when
  305.                      KCommodity`s main window is opened.
  306.  - LeftyMouse        Activate LeftyMouse option.
  307.  - ESC WindowClose   Enable/Disable option for closing a window on
  308.                      Key-Stroke.
  309.  - Map "Umlauts"     Enable/Disable mapping of "Umlauts"
  310.  - Win Qualifier     Click on this gadget to change the qualifier for use
  311.                      with the window-cylce option. The shown qualifier will
  312.                      be the one to be used to bring a window to front/back.
  313.                      Use left button for popping a window to front and the
  314.                      right button for popping a window behind all others.
  315.  - ESC Qualifier     This one is to be used to change the qualifier for
  316.                      the ESC-Key to close windows. If a gadget is active
  317.                      on the current window this function is ineffective.
  318.                      NOTE ON CLI-WINDOWS : NEVER USE THIS FUNCTION WHILE
  319.                                            A PROGRAM IS RUNNING AND BLOCKING
  320.                                            THE CLI/SHELL.
  321.  - Alarm time        Change/Enter alarm time. You must at least enter
  322.                      hour:minutes (seconds are optional). Any errors
  323.                      in alarm time will be trapped and if one was found
  324.                      the time is reset to the previously used.
  325.  - User Shell        Lets you define the parameters for the new shell
  326.  - Screen time       You can enter a timeout value for the screen-blanking.
  327.                      1-999 seconds. If entered 0 the screenblanker will be
  328.                      disabled. Entering a negative value will also cause the
  329.                      previous value to be restored.
  330.  - Mouse time        Same as above, but for the timout value of
  331.                      mouse-blanking.
  332.  - Click vol         You can enter a new volume of the click sound.
  333.                      Illegal values ( < 0, > 64 ) will be ignored and the
  334.                      value is reset to the previous value.
  335.  - Telefone bill...  Pops up the window telling you how much the current
  336.                      call will cost. Changes on timezones and tariff can
  337.                      be made here.
  338.  - Telefone prefe .. Within this window you can customize the times for
  339.                      one unit and the cost of unit itself. You can also
  340.                      specify a new logfile the logs of each call should
  341.                      be written to. Finally you can retrieve the total
  342.                      cost of your calls.
  343.  - HotKeys...        Let the HotKeys window popup
  344.  - Load Prefs...     You guessed it : A FileRequester will pop up giving
  345.                      the possibility to select new preferences.
  346.  - Save Prefs...     This one`s easy. You can save the current settings
  347.                      to a file using a FileRequester.
  348.  - Enable            Enable KCommodity`s broker.
  349.  - Disable           Disable KCommodity`s broker (NOTE : All HotKeys are
  350.                      also disabled. You have to use Exchange, the AppIcon,
  351.                      or the MenuItem to pop up the window again.)
  352.  - Hide              Hide the window
  353.  - Quit              Leave KCommodity
  354.  - CLOSEGADGET       same as Hide.
  355.  
  356.  All gadgets can also be selected using a keystroke.
  357.  The  keystroke for a  gadget is marked by an underscore in the gadget`s text.
  358.  Alternatively   you   can   select   menu   items  or  use  their  ShortCuts.
  359.  
  360.  While   any  of  KCommodity`s  windows  is  present  and  moved  the  program
  361.  will  remember  it`s  positions  so  that  every  time  you pop up the window
  362.  again it will be located to it`s previous position.
  363.  
  364.  
  365.  The menus of KCommodity`s Main window
  366.  -------------------------------------
  367.  
  368.  - Project
  369.  
  370.    - Load Preferences...    Load new preferences for KCommodity
  371.    - Save Preferences       Save current preferences to file specified by
  372.                             "Save preferences as..." or to default :
  373.                             ENV:KCXPREFFILE. If you want to keep the
  374.                             prefs permanently then you will have to
  375.                             use "Save preferences as...".
  376.    - Save Preferences as... Specify a new name for preferences and write
  377.                             prefs to this file.
  378.    - Enable                 Same functions as mentiond above
  379.    - Disable
  380.    - Hide
  381.    - About...               Displays a short "about" and gives you the
  382.                             possibility to print out a registration
  383.                             form to PRT:
  384.    - Quit                   Guess what ???
  385.  
  386.  - Enable/Disable
  387.  
  388.    These are menu alternatives for the Gadget-ShortCuts. The have the
  389.    same ShortCuts as the ones for the Gadgets.
  390.  
  391.  - Other settings
  392.  
  393.    You can activate the StringGadgets via menu.
  394.  
  395.  - Windows
  396.  
  397.    Open the different windows KCommodity provides.
  398.  
  399.  
  400.  
  401.  
  402.  
  403.  The HotKeys window
  404.  ------------------
  405.  
  406.  Shown   are   6   string   gadgets   giving   the   possibility   to   change
  407.  KCommodity`s   HotKeys.  Simply  enter  the  new  ones.  If  the  alternative
  408.  HotKey   could   not   be   installed   KCommodity   uses   the   last   one.
  409.  
  410.  NOTE : Make sure that the HotKeys you enter are not already in use
  411.         by other programs so that it doesn`t conflict.
  412.  
  413.  
  414.  
  415.  HotKey-Definitions
  416.  ------------------
  417.  
  418.  Here   is   a   list   of  descriptive  strings  for  defining  the  HotKeys.
  419.  Just  type  them  down  the  way  you  like,  they  are  case-insensitive and
  420.  take the form :
  421.  
  422.  [<qualifier> [<qualifier>...]] <key>
  423.  
  424.  Qualifiers
  425.  
  426.   alt           either Alt key
  427.   ralt          right Alt key
  428.   lalt          left Alt key
  429.   shift         either Shift key
  430.   rshift        right Shift key
  431.   lshift        left Shift key
  432.   capslock      Caps Lock key
  433.   rcommand      right Amiga key
  434.   lcommand      left Amiga key
  435.   control       Control key
  436.   numericpad    Enables the use of a key on the numeric keypad
  437.   rbutton       Click the right mouse button
  438.   midbutton     Click the middle mouse button
  439.   leftbutton    Click the left mouse button
  440.   newprefs      Preferences changed
  441.   diskremoved   Disk removed
  442.   diskinserted  Disk inserted
  443.  
  444.  
  445.  Keys
  446.  
  447.   a .. z, 0 .. 9, etc.   Normal keys
  448.   f1 .. f10              Function keys
  449.   up, down, left, right  Cursor keys
  450.   help                   Help key
  451.   del                    Delete key
  452.   return                 Return key
  453.   enter                  Enter key (only in conjunction with 'numericpad')
  454.   backspace              Backspace key
  455.   esc                    Escape key
  456.   space                  Space key
  457.   comma                  Comma key
  458.   upstroke               Upstroke key
  459.  
  460.  
  461.  
  462.  
  463.  
  464.  
  465.  The Revision Control System
  466.  ---------------------------
  467.  
  468.  This one`s my favorite :-)
  469.  While  working  on  a  program  the  programmer  sometimes  (not all of them)
  470.  wants   to   know  what  he  changed  since  his  last  changes  (or  working
  471.  version).  So  a  revision  control  system  may  be helpful in keeping track
  472.  of  the  revisions  made  to  a  program.  That`s where KCommodity`s revision
  473.  control systems gets to work.
  474.  Imagine  you`ve  just  added  a  new,  great  function  to  you  program  and
  475.  you  want  to  put  the  info  about  what you`ve done into your source code,
  476.  so  that  you  can  see  how  development  processed  during  the last times.
  477.  Entering  the  log  message  'by  hand'  isn`t  quite  satisfactory. Wouldn`t
  478.  it  be  nice  if these things  were formatted by a program ? This is it, what
  479.  KCommodity  does  for  you.  And even more. It increases the current revision
  480.  number  every time you use  it on your source and adds a define/macro for the
  481.  revision  at  the  bottom  of  the  revision  header  for use in a "$VER:..."
  482.  string  so  that  the  program  VERSION  can print out the current version of
  483.  a program.
  484.  
  485.  How to use it ?
  486.  This function can only be accessed using ARexx.
  487.  
  488.  The syntax is :
  489.  
  490.     REVISE FileName (ASM|C|PAS)
  491.  
  492.  So  just  enter  a  filename  and  an  identifier  (ASM for Assembler source,
  493.  C  for  C  source  or  PAS  for  Pascal  source) and KCommodity gets to work.
  494.  
  495.  First  it  checks  whether  a  header is already persent in the current file.
  496.  This  header  doesn`t  have  to  be  on  top of the file. KCommodity searches
  497.  within  the  first   15  lines  of  your  source  so  you  can  insert  lines
  498.  in front of the header.
  499.  Having  recognized  that  no  header  is  present  a  window  pops  up asking
  500.  for  a  purpose  message  (this  message  can  have 5 lines with 75 chars per
  501.  line). Just enter a message as you wish.
  502.  When  pressing  RETURN  the  next  string  gadget  will  be  activated. If it
  503.  was the last gadget the first gadget will activated.
  504.  You   can   use   HELP   for   escaping  any  string/integer  gadget  without
  505.  activating   the   next   one.  TAB-Key  cycles  the  string/integer  gadgets
  506.  downward. SHIFT-TAB does the opposite.
  507.  The   two  integer   gadgets  at  the  bottom  of  the  window  are  used  to
  508.  enter  a revisionnumber to start/continue with. Simply enter the new revision
  509.  number  and  KCommodity  will  properly  insert  it.  If  nothing  is entered
  510.  or  if  you  enter  0.0  then  KCommodity  will  use  1.0 (on first revision)
  511.  or   will   continue   with   the   next   higher  revision  (1.0  ->  1.01).
  512.  Having  finished  your  inputs  you  can either cancel the system by pressing
  513.  the   CANCEL-Gadget,   the   C-Key,   the   CLOSE-Gadget   or   the  ESC-Key.
  514.  Otherwise   you   can   press   the  OK-Gadget  or  the  O-Key  to  continue.
  515.  
  516.  
  517.  KCommodity now starts to build up the header.
  518.  It will be initialized with a standard Log Message
  519.  (will   be   "initial  relase"),  the  purpose  message  (without  any  blank
  520.  lines   you   might   have   eneterd   to  save  space)  and  of  course  the
  521.  first  define  for  your  "$VER:...".  Behind  the  revision  number  it will
  522.  create  a  define  for  the  revision  date,  so  that  you  can put the date
  523.  into messages of your program.
  524.  The  remaining  part  of  your  "original"  will  just  be  appended  to  the
  525.  "new"  file.  KCommodity   will   store  the   result  of  the  creation in a
  526.  temporary  file  in  T:,  so   make  sure  you  have  enough  Disk/RAM  space
  527.  and     that    you`ve    assigned    T:   to   a   directory   you   desire.
  528.  Having  done  it`s  job,  KCommodity  copys  the  temporary  file back to the
  529.  original and then deletes the temp file.
  530.  
  531.  Revision of an already revised source :
  532.  
  533.  KCommodity  again  searches  for  the  header  string  within  the  first  15
  534.  lines of your file in the specified language.
  535.  If   it   is   successful,   it   will   pop   up   a   Log  Message  window.
  536.  (if  not,  the  purpose  and  initial  release  part  will be worked through)
  537.  The  control  of  this  window  is  the  same  as  for  the  purpose  window.
  538.  Having    finished    your    input    KCommodity   again   gets   to   work.
  539.  It   increases   the  revision  number  (or  even  takes  the  user-defined),
  540.  adds  the  new  LogMessage  in  front  of  the  previous one and refreshs the
  541.  defines,  so  that  the  revision  number  reflects  the current revision and
  542.  that the date does the same.
  543.  
  544.  NOTE:  If  the  first  define  is  not  present or is not located right after
  545.         the  header  KCommodity  "thinks"  that  the  user  is fed up with the
  546.         defines  and  just  leaves  them  out  and continues it`s work without
  547.         defines.
  548.  
  549.  Finally it just appends the rest of the "original". It then copys the
  550.  temp file to the original and deletes the temp file.....
  551.  
  552.  
  553.  
  554.  This is what a revision header would look like in an Assembler source :
  555.  (having revision 1.01. That means one change made since initial release.
  556.   revision was made on 05-Jan-92)
  557.  
  558.  ;
  559.  ; Maximum of 14 lines above header allowed (after creation of header)
  560.  ;
  561.  
  562. ;* $Revision Header built by KCommodity by Kai Iske *** (do not edit) **********
  563. ;*
  564. ;*  Copyright by <COMPANY>
  565. ;*
  566. ;* File             : <this would be the name of the file>
  567. ;* Created on       : Sunday, 05-01-92 02:27:25
  568. ;* Created by       : <AUTHOR>
  569. ;* Current revision : V1.01
  570. ;*
  571. ;*
  572. ;* Purpose
  573. ;* -------
  574. ;*     This is just a test for the purpose string
  575. ;*     and a second line
  576. ;*
  577. ;* Revision V1.01
  578. ;* --------------
  579. ;* changed on Sunday, 05-01-92 02:27:45  by  <AUTHOR>.   LogMessage :
  580. ;*     And a test for a LogMessage
  581. ;*     second line
  582. ;*     third line
  583. ;*
  584. ;* Revision V1.00
  585. ;* --------------
  586. ;*     --- Initial release ---
  587. ;*
  588. ;*******************************************************************************
  589. REVISION  MACRO        ; This is the macro for the revision number
  590.         dc.b "1.01"
  591.         ENDM
  592. REVDATE   MACRO        ; This is the macro for the revision date
  593.         dc.b "05-Jan-92"
  594.         ENDM
  595.  
  596.   ;
  597.   ; This is where your program might start
  598.   ;
  599.  
  600.  
  601.  Just use these macros in your sources. An implementation could look like
  602.  like this :
  603.  
  604.          dc.b "This is my program V"
  605.          REVISION
  606.          dc.b " created on ("
  607.          REVDATE
  608.          dc.b ")",0
  609.  
  610.  Never forget a trailing 0-Byte at then end of the string.
  611.  
  612.  NOTE TO PREVIOUS USERS :
  613.  You   wil   have   to   change   the   layout   of   the   defines   to  have
  614.  KCommodity  remake  them.  So  just  remake  the  defines  to the new format.
  615.  
  616.  
  617.  The  defines  for  C  and Pascal sources take the same names and are handeled
  618.  the same way.
  619.  
  620.  
  621.  NOTE FOR PASCAL SOURCES:
  622.  In  order  to have the defines available, KCommodity adds the CONTS qualifier
  623.  right  after  the  revision  header.  So  you have to put all other constants
  624.  behind  the  ones  defined  by  KCommodity.  Otherwise  your  source will get
  625.  mixed up.
  626.  
  627.  
  628.  To have the <COMPANY> and <AUTHOR> fields filled in you have to set
  629.  two environment variables (for example like this) :
  630.  
  631.          SetEnv COMPANY  "My Company"
  632.          SetEnv AUTHOR   "Hey that`s me"
  633.  
  634.  If one variable or both of them could not be found by KCommodity it will
  635.  set the unset field to "--- Unknown ---".
  636.  
  637.  When  CANCEL  was  hit  within  the  Purpose/LogMessage  window  REVISE  will
  638.  return  FALSE  (0)  in  the  ARexx-Variable  RESULT.  Otherwise if OK was hit
  639.  REVISE  will  return  TRUE  (1).  So  you can distinguish whether to continue
  640.  your ARexx-Script or not.
  641.  
  642.  
  643.  So   enjoy   this   feature   of   KCommodity   helping  you  to  keep  track
  644.  of revisions.
  645.  
  646.  
  647.  
  648.  
  649.  
  650.  
  651.  Telefone bill calculator
  652.  ------------------------
  653.  
  654.  This  one  is  seperated  into  two  windows  you  can  get  to  by using the
  655.  "Telefone bill..." / "Bill preferences..." Gadgets.
  656.  
  657.  Let`s get to the preferences.
  658.  This    window    shows   six   integer   gadgets   near   to   each   other.
  659.  Two  in  a  row  represent  the  normal  and  cheap  tariffs  for  one of the
  660.  three  timezones  KCommodity  manages.  Simply  enter  the  amount of seconds
  661.  for one unit you would like to have.
  662.  For  example  here  are  the  settings  for  the  current tariffs in Germany.
  663.  We  have  three  different  zones  (that`s  why  I`ve  only implemented three
  664.  for now) and two tariffs.
  665.  
  666.  Normal Time/Unit 1 : 360   Means 6 minutes for one unit
  667.  Cheap Time/Unit 1  : 720         12
  668.                        .
  669.                        .
  670.                        .
  671.  
  672.  The   times   default   to   the  current  tariffs  of  the  german  telefone
  673.  company.
  674.  
  675.  The  next  one  is  the  gadget  which  represents  the  cost  for  one unit.
  676.  This    one    is    made   in   1/100   that   means   cents,   Pfennige....
  677.  Just enter your local costs.
  678.  
  679.  Now  following  are  two  mutual  exclude  gadgets  for  setting  the default
  680.  timezone  and  tariff.  These settings will be stored in the preferences file
  681.  and  will  be  loaded  each  startup, so that the settings of the bill window
  682.  will default to the mostly used.
  683.  
  684.  Use  the  "PopUp  Bill  window"  gadget  so  that  the bill window will popup
  685.  on  carrier  detection.  With  a  deselected  "Log  calls"  gadget  the  data
  686.  of a call will not be saved to the specified file.
  687.  To   get   rid   of   a  log  file  simply  press  the  "Clear  log"  gadget.
  688.  
  689.  On   pressing  the  "Save  Log  to..."  a  FileRequester  will  popup  giving
  690.  you   the   possibility   to   specify  a  new  logfile  your  logs  will  be
  691.  written   to   next   time.  If  you  are  already  shure  where  to  put  it
  692.  you  can  simply  enter  the  name  of  the  log  file into the string gadget
  693.  next to the "Save Log to..."-gadget.
  694.  The  next  one`s   an  easy  one.  "Total  sum..."  will  open  up  a  window
  695.  showing  the  contents  of  your  specified  logfile.  After all calls of one
  696.  day  have  been  listed  KCommodity  will  print  out  the  sum for that day.
  697.  At  the  end  of  the  logfile  you  are  given  the  total costs for all the
  698.  phone calls made.
  699.  
  700.  The Bill window.
  701.  This   one   reflects  the  current  time,  online  time  and  costs  arising
  702.  from the current/last phone call.
  703.  Within  this  window  there  are  two  gadgets  giving  you  the  possibility
  704.  to   change   the   timezone/tariff   for   the   call.  Just  click  on  the
  705.  zone/tariff  gadget  you  like  to  use  for  this  call.  If you are already
  706.  online   KCommodity   will  recalculate  the  costs,  so  that  changing  the
  707.  settings   will   allways   result   in   the   correct  costs  for  a  call.
  708.  Underneith  these  gadgets  the  cost  for  one  hour  of  a  phone call will
  709.  be shown according to the current settings.
  710.  
  711.  
  712.  
  713.  
  714.   ARexx-Capability
  715.   ----------------
  716.  
  717.   There is another possibility to configure KCommodity
  718.   or even retrieve settings of the program.
  719.  
  720.   First of all here come the ARexx commands KCommodity can deal with.
  721.  
  722.   ACTIVATE    1|0            Enable/Disable Window-Activation
  723.   MOUSEMODE   1|0            Enable/Disable SUN-Style Window-Activation
  724.   SHOWCLOCK   1|0            Enable/Disable Clock/Memory displaying
  725.   CLOCKWIN    1|0            Enable/Disable Clock/Memory window
  726.   CLOCKWINPOS 'X/Y'          Set Clock/Memory window to new position
  727.   SHOWDATE    1|0            Enable/Disable viewing of date
  728.   SHOWDAY     1|0            Enable/Disable viewing of day
  729.   SHORTDAY    1|0            Only display 3 chars for the day
  730.   SHOWSECS    1|0            Enable/Disable viewing of seconds
  731.   AMIDATE     1|0            Enable/Disable american date-format
  732.   PAGEKEY     'string'       Set HotKey for changing Clock/Memory displays
  733.   PAGENUM     (0-4)          Number of page to be displayed
  734.   ALARM       1|0            Enable/Disable alarm
  735.   ALARMTIME   'hh:mm[:ss]'   Set alarm time
  736.   SETENV      1|0            Enable/Disable writes of date/time to env vars
  737.   SCREENTIME  'secs'         New timeout value for screen blanking
  738.   MOUSETIME   'secs'         New timeout value for mouse blanking
  739.   CYCLEWIN    1|0            Enable/Disable window-cycling
  740.   CYCLEKEY    (0-3)          Specify new qualifier number for Window-Cycling
  741.   CLICK       1|0            Enable/Disable keystroke-clicking
  742.   CLICKVOL    (0-64)         Set new volume for clicking
  743.   LOGCALLS    1|0            Log each phone call
  744.   BILLWINPOS  'X/Y'          Set new position for BillWindow
  745.   BILLPOPUP   1|0            Enable/Disable PopUp of Window on Carrier Detect
  746.   PREFSWINPOS 'X/Y'          Set new position for preferences window
  747.   WBFRONT     1|0            Enable/Disable popup of WorkBench
  748.   LEFTYMOUSE  1|0            Enable/Disable LeftyMouse
  749.   ESCCLOSE    1|0            Enable/Disable ESC-WindowClose
  750.   ESCKEY      (0-4)          Qualifier-number for ESC-WindowClose
  751.   MAPUMLAUT   1|0            Enable/Disable mapping of "Umlauts"
  752.   CLEARLOG                   Clears the log file
  753.   LOADPREFS   'string'       Load a preferences file specified by 'string'
  754.   SAVEPREFS   'string'       Save preferences to file specified by 'string'
  755.   CXPOPKEY   'string'       Change PopUp HotKey for control window
  756.   BILLKEY     'string'       Set new Bill window HotKey
  757.   PREFSKEY    'string'       Set new Preferences window HotKey
  758.   HOTWINKEY   'string'       Set new HotKeys window HotKey
  759.   SHELLKEY    'string'       Set new Shell HotKey
  760.   UMLAUTKEY   'string'       Set neu "Umlauts" HotKey
  761.   SHELLCOMM   'string'       Set new NewShell-Command
  762.   ENABLE                     Enable Commodity`s work (HotKeys, Activation)
  763.   DISABLE                    Disable    "         "          "
  764.   HIDE                       Hide the control window of KCommodity
  765.   POPUP                      Let the control window popup
  766.   STATUS                     Returns information about settings (see below)
  767.   REVISE      'File' [C|ASM] Start the revision control system
  768.  
  769.   NOTE : All parameters surrounded by ' have to be given in quotes, so
  770.          that ARexx doesn`t complain about it.
  771.  
  772.  
  773.   Values for PAGENUM
  774.  
  775.      0 : Display time
  776.      1 : Display free Chip/Fast memory seperately
  777.      2 : Display total free memory
  778.      3 : Display free memory as a gauge
  779.      4 : Display online time
  780.  
  781.   Values for CYCLEKEY
  782.  
  783.      0 : Any alt key
  784.      1 : Any amiga key
  785.      2 : Any shift key
  786.      3 : Control key
  787.  
  788.   Values for ESCKEY
  789.  
  790.      0 : Any alt key
  791.      1 : Any amiga key
  792.      2 : Any shift key
  793.      3 : Control key
  794.      4 : none
  795.  
  796.  
  797.  
  798.   List of STATUS numbers KCommodity currently recognizes
  799.   ------------------------------------------------------
  800.  
  801.   1         Value : Priority of the whole program
  802.   2         Value : Priority of Broker.
  803.   3         String : POPUPKEY (default : LCOMMAND HELP).
  804.   4         BOOL : Should KCommodity pop up on startup
  805.   5         BOOL : State of activation (ON/OFF)
  806.   6         BOOL : SUN-Style mode (ON/OFF)
  807.   7         BOOL : Clock/Memory display (ON/OFF)
  808.   8         BOOL : Clock/Memory window (ON/OFF)
  809.   9         String : Returns position of Clock/Memory window
  810.                      Takes the form X/Y.
  811.   10        BOOL : Display date (ON/OFF)
  812.   11        BOOL : Display day (ON/OFF)
  813.   12        BOOL : Display seconds (ON/OFF)
  814.   13        BOOL : American date-format (ON/OFF)
  815.   14        String : Returns HotKey for changing Clock/Memory displays
  816.   15        LONG : Number of currently displayed page (0-4)
  817.   16        BOOL : Are we to alarm at alarmtime (YES/NO)
  818.   17        String : Returns currently set alarm time (hh:mm[:ss])
  819.   18        BOOL : Is Broker (HotKeys, Activation) disabled (YES/NO)
  820.   19        BOOL : Tell us whether control window is popped up (YES/NO)
  821.   20        BOOL : Tell us whether environment vars are activated (YES/NO)
  822.   21        BOOL : Tell us whether to display the full day string (YES/NO)
  823.   22        LONG : Returns timeout value for screen blanking (0 = disabled)
  824.   23        LONG : Returns timeout value for mouse blanking (0 = disabled)
  825.   24        BOOL : Window-Cycling enabled (YES/NO)
  826.   25        LONG : Number of cycle qualifier (0-3)
  827.   26        BOOL : KeyStroke-Clicking enabled (YES/NO)
  828.   27        LONG : Volume for KeyStroke-Clicking (0-64)
  829.   28        BOOL : Logging of phone calls enabled/disabled (YES/NO)
  830.   29        String : Position of Bill window
  831.   30        BOOL : PopUp on Carrier Detect of Bill window (YES/NO)
  832.   31        String : Position of preferences window
  833.   32        BOOL : PopUp WB on openup of main window (YES/NO)
  834.   33        BOOL : LeftyMouse enabled (YES/NO)
  835.   34        BOOL : ESC-WindowClose enabled (YES/NO)
  836.   35        LONG : Qualifier for ESC-WindowClose (0-4)
  837.   36        String : HotKey for popping up Bill window
  838.   37        String : HotKey for popping up Preferences window
  839.   38        String : HotKey for popping up HotKeys window
  840.   39        String : HotKey for popping up a new shell
  841.   40        String : HotKey for changing "Map Umlauts" mode
  842.   41        String : Parameters for execution with NewShell
  843.   42        BOOL : Mapping of "Umlauts" enabled/disabled (YES/NO)
  844.  
  845.  
  846.   NOTE:  (ON/OFF)  and  (YES/NO)  are  not  strings  in  that  case, these are
  847.          just  boolean  values,  which  take  the value of 1 or 0 according to
  848.          current settings.
  849.  
  850.  
  851.   REMEMBER:  The  default  Port  for  ARexx  commands  is  KComm.1.  So if you
  852.              didn`t   change   the   default   name  issue  ADDRESS  'KComm.1'
  853.              at    the   top   of   your   scripts   to   access   KCommodity.
  854.  
  855.  
  856.  
  857.  Enhancements to come.
  858.  ---------------------
  859.  
  860.  Waiting for suggestions.
  861.  
  862.  
  863.  
  864.  
  865.  
  866.  
  867.  
  868.   --------------------------------------------------------------------------
  869.  
  870.   To contact me just write to :
  871.  
  872.                               Kai Iske
  873.                           Brucknerstrasse 18
  874.                              6450 Hanau 1
  875.                                Germany
  876.           Tel.: +49-(0)6181-850181 (weekdays only from 6:00 PM)
  877.  
  878.   or send an E-Mail to :
  879.  
  880.                        FIDO : 2:249/40.11, Kai Iske
  881.                        SMBX : GURU:SNAKE
  882.                        ZNET : SNAKE%HTH@AMNET.ZER
  883.                        ANNET: SNAKE%HTH.AMN
  884.  
  885.   or on a local BBS without net support :
  886.  
  887.             Star League BBS: 069/5927709
  888.               Pyramania BBS: 069/543603
  889.             HitchHicker BBS: 069/5975113
  890.  
  891.   They all are located in Frankfurt/M GERMANY.
  892.   These are the places I usually can be found most of the time.
  893.   Just write an E-Mail to SNAKE.
  894.  
  895.   You can also get the latest releases of KCommodity there.
  896.   Otherwise you might get it from one of the next Fred Fish Disks
  897.   or KickStart Disks.
  898.  
  899.  
  900.  
  901.   Just let me know about any questions and suggestions.........
  902.