home *** CD-ROM | disk | FTP | other *** search
/ BCI NET 2 / BCI NET 2.iso / archives / programming / c / simpleguide1.lha / SimpleGuide.doc < prev    next >
Encoding:
Text File  |  1995-02-06  |  3.9 KB  |  96 lines
  1. ------------------==================================------------------
  2. 950205
  3.            SimpleGuide: A simple AmigaGuide interface
  4.  
  5.                               Release 1
  6.  
  7.     Copyright (C) 1995 Ultima Thule Software, All Rights Reserved.
  8.                         Author: Petter Nilsen
  9.  
  10. ------------------==================================------------------
  11.  
  12. SimpleGuide is created and programmed by Petter Nilsen, with input and
  13. comments  from  Marius Mortensen.  Thanks to Michael Sinz for creating
  14. to original SimpleRexx ARexx code which gave me the idea for doing the
  15. same with AmigaGuide.
  16.  
  17. This  code  is  not  public  domain  but may be freely distributed for
  18. non-commercial  purposes.   Use  it at your own risk.  However, if you
  19. intent  to  use this code in one of your own applications, please give
  20. me credit. Hope you find it helpful! 
  21.  
  22. What is SimpleGuide?
  23. ~~~~~~~~~~~~~~~~~~~~
  24. SimpleGuide  was  created  by  me for own use in our program THOR, the
  25. most  advanced  offline  reader  currently on the Amiga (todays ad :).
  26. SimpleGuide  does  much  of the gruntwork associated with the creation
  27. and  use  of the AmigaGuide online help that Commodore has provided to
  28. users  and programmers.  To use it, you simply link you program to the
  29. SimpleGuide  module (simpleguide.c) and call SimpleGuide to create the
  30. AmigaGuide  help  system,  open  nodes,  close  the  help  system etc.
  31. Currently,  this  code  only  supports  opening AmigaGuide as an async
  32. prosess.   There  might  be  some  problems  with  earlier versions of
  33. amigaguide.library with this, but as far as I know these problems only
  34. exist  with  V33  and early V34 versions.
  35.  
  36. Using SimpleGuide
  37. ~~~~~~~~~~~~~~~~~
  38.  
  39. Setting  up  the AmigaGuide help system for your application should be
  40. fairly easy if you follow these simple steps:
  41.  
  42. 1.   When  you  need  the  help  system,  call AmigaGuideOpen() with a
  43. initialized NewAmigaGuide structure, as described in the documentation
  44. for AmigaGuideOpen().  This function will open amigaguide.library, the
  45. AmigaGuide   help  system  and  wait  for  the  startup  message  from
  46. amigaguide.library.   This function will return a pointer to a context
  47. that must be passed to all the other functions in SimpleGuide whenever
  48. you  call  them.   Keep  the pointer around but don't modify it or its
  49. contents.   You  might  call AmigaGuideOpen() more than once to set up
  50. the  help  system  for  ie.  several different AmigaGuide files.  Each
  51. call will return a unique context.
  52.  
  53. 2.     Get    a    signal   from   SimpleGuide   with   the   function
  54. GetAmigaGuideSignal()  and  wait  on  this signal in your usual signal
  55. loop.   When  a  signal  arrives, use HandleAmigaGuide() to answer all
  56. messages received from AmigaGuide.
  57.  
  58. 3.  Whenever the user presses the HELP key (rawkey decimal code 95) or
  59. requests  menyhelp,  call the SetGuideContext() function to align onto
  60. the  node  you  want  to  show  for  the  user (se the documetation on
  61. AmigaGuideOpen()   for   more   details)   then   call   the  function
  62. SendGuideContext() to actually show the node.
  63.  
  64. 4.   When you are through with the help system, call AmigaGuideClose()
  65. for each context you received from AmigaGuideOpen().
  66.  
  67. Please  see  the  simpleguide.c  file for further information on these
  68. functions.
  69.  
  70. History:
  71. ~~~~~~~~
  72. 950205 - Initial release 1
  73.  
  74. Limitations:
  75. ~~~~~~~~~~~~
  76. - Only supports async opening of amigaguide.library.
  77. - Does not support all functions in amigaguide.library
  78. - Only replies to messages from amigaguide.library, without any error
  79.   handling. 
  80.  
  81. Please  feel  free to modify the code as you like, but if you discover
  82. any bugs or want to make additions, send a mail to me about them.
  83.  
  84. I can be contacted in one of the following ways:
  85.  
  86.            Email: pettern@powertech.no
  87.  
  88. Ultima Thule BBS: +47 776-81999 / +47 776-13205 / +47 776-39830
  89.  
  90.       Snail-Mail: Ultima Thule Software
  91.                   Attn. Petter Nilsen
  92.                   Strandveien 59B
  93.                   N-9007 TROMSOE
  94.                   NORWAY
  95.  
  96.