home *** CD-ROM | disk | FTP | other *** search
/ ARM Club 1 / ARM_CLUB_CD.iso / contents / apps / program / d / int_help / doc next >
Encoding:
Text File  |  1992-09-27  |  5.0 KB  |  138 lines
  1. Help module for C desktop applications version 2.02
  2. by Ben Summers
  3.  
  4. Overview
  5. ~~~~~~~~
  6. I have written this module to provide a feature that Acorn forgot to include
  7. in the RISCOS library - an easy to use interface to the interactive help
  8. application.
  9.  
  10. This help module uses the application resource 'HelpText' to find the text
  11. of the help. This show the messages to be returned for the window, and icons
  12. in it. The format of this file is described below.
  13.  
  14. The functions provided do not return errors when they fail. This is because
  15. the help system is a non-essential part of the program, and I don't really
  16. think it is worth taking any special action when it fails. However, if help
  17. has not been initialised or help is requested for a window which is not
  18. defined in the HelpText, it will terminate your application with an error
  19. message. These are the only times it will do this.
  20.  
  21. To use the module, just link it into your program. You may use it in any
  22. application you write, PD or commercial. Please send me a copy of any
  23. application you write with it.
  24.  
  25. The module provides three functions, which are documented below.
  26.  
  27. void help_init(BOOL load);
  28. ~~~~~~~~~~~~~~~~~~~~~~~~~~
  29. This function initialiases the help system. It must be called before any
  30. other help functions are called. You must have initialised the wimp modules
  31. of the RISCOS Lib, res and flex before you call this. If load == TRUE, the
  32. helptext is loaded. If load == FALSE, the helptext will be loaded when it is
  33. needed. I would recommend setting load to FALSE so the helptext will not
  34. waste memory.
  35.  
  36. void help_send(const char *win_name);
  37. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  38. This function sends help to the interactive help application when it asks
  39. your application for some help. win_name is the name of the window you want
  40. to send help about.
  41.  
  42. You should add this function to your event handler for a window with a bit
  43. of code like this:
  44.  
  45.   switch (e->e)
  46.   {
  47.       /* other event types... */
  48.  
  49.     case wimp_ESEND:
  50.     case wimp_ESENDWANTACK:
  51.       if(e->data.msg.hdr.action == wimp_MHELPREQUEST)
  52.         help_send("window");
  53.       break;
  54.   }
  55.  
  56. "window" is the name of a window defined in the HelpText resource. See below
  57. for the format of it.
  58.  
  59. void help_send_text(const char *text);
  60. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  61. This function sends text to the interactive help application. The text must
  62. be no longer than help_MAX_HELP_TEXT characters long including the
  63. terminating \0.
  64.  
  65. This function is provided so you can send your own help messages when there
  66. are no icons in the window, and the message changes. For example, you might
  67. want to use this for X,Y coordinates.
  68.  
  69. This function should only be called after a request for help has been
  70. received by your application.
  71.  
  72. BOOL help_dbox_help(dbox d, void *event, void *handle);
  73. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  74. This function allows you to use interactive help on dialogue boxes. To use
  75. it, you must register it with the dbox module with the following function
  76. call:
  77.  
  78.   dbox_raw_eventhandler(d, help_dbox_help, "window");
  79.  
  80.  d        = dbox handle
  81.  "window" = name of window in help text
  82.  
  83. The HelpText resource
  84. ~~~~~~~~~~~~~~~~~~~~~
  85. The HelpText application resource gives the messages to be used. It is a
  86. list of windows with their messages.
  87.  
  88. Each window has a basic message (like 'This window displays your sprite.'),
  89. and messages for the icons in the window. The basic message will always be
  90. sent, followed by an text for an icon.
  91.  
  92. To define a window, you use a line like
  93.  
  94. @win_name:Basic message
  95.  
  96. The lines after this are the messages for the icons. Each line is an icon,
  97. numbered from 0 upwards. There doesn't have to be text for every icon. If
  98. you want to include a line break, put '|M' in the text.
  99.  
  100. There are three special windows, VERSION, DICT and END which must be
  101. included. The basic message for VERSION is the current version number of the
  102. help module * 100. In this version, the value you should use is 200.
  103.  
  104. The DICT window is a dictionary of phrases you oftern use in the text - for
  105. example 'This sets the drive to '. There is no basic message for this
  106. window.
  107.  
  108. To define a dictionary entry, you put an icon in the DICT window which reads
  109.  
  110. item_name:Text for this entry
  111.  
  112. To use this entry in the text of a icon, you insert into the text
  113. '%item_name%' where you want the text to be placed.
  114.  
  115. The HelpText file should be ended by defining the window 'END'.
  116.  
  117. An example HelpText file is included. It is a bit of the HelpText file from
  118. my program FileUtils.
  119.  
  120. The author
  121. ~~~~~~~~~~
  122. This help module was written by Ben Summers. If you have any comments, wish
  123. to report a bug or want to send a token of your apprecation (discs of PD,
  124. applications you write using this etc) please write me at the address below.
  125. Please send an SAE if you want a reply.
  126.  
  127.   Ben Summers
  128.   1 St Clements Hill
  129.   Norwich
  130.   NR3 4DE
  131.  
  132. Legal note
  133. ~~~~~~~~~~
  134. This module is public domain. The copyright of the module remains with me.
  135. When you distribute it as a module, you must include this text file and the
  136. example HelpText file, but you do not need to include it when the module is
  137. linked into your application.
  138.