home *** CD-ROM | disk | FTP | other *** search
/ The Datafile PD-CD 2 / DATAFILE_PDCD2.iso / utilities2 / desklib / !DeskLib / h / Msgs < prev    next >
Encoding:
Text File  |  1993-07-14  |  4.2 KB  |  107 lines
  1. /*
  2.     ####             #    #     # #
  3.     #   #            #    #       #          The FreeWare C library for 
  4.     #   #  ##   ###  #  # #     # ###             RISC OS machines
  5.     #   # #  # #     # #  #     # #  #   ___________________________________
  6.     #   # ####  ###  ##   #     # #  #                                      
  7.     #   # #        # # #  #     # #  #    Please refer to the accompanying
  8.     ####   ### ####  #  # ##### # ###    documentation for conditions of use
  9.     ________________________________________________________________________
  10.  
  11.     File:    Msgs.h
  12.     Author:  Copyright © 1992 Jason Williams
  13.     Version: 1.00 (08 Apr 1992)
  14.     Purpose: MessageTrans-like message handling functions.
  15.              (If you want MessageTrans, use the SWI interface, if you want
  16.              high-level message handling, use this code...)
  17. */
  18.  
  19. #ifndef __dl_msgs_h
  20. #define __dl_msgs_h
  21.  
  22. #ifndef __dl_core_h
  23. #include "Core.h"
  24. #endif
  25.  
  26. extern BOOL Msgs_Lookup(char *tag, char *result, int maxlength);
  27. /*  Looks up the tag in the current message list, and copies the appropriate
  28.  *  message into result if found. (no more than maxlength characters will
  29.  *  be copied, so you can copy directly into icon indirected text, etc.
  30.  *  REMEMBER that arrays start at 0, so if you have "char result[12]", use
  31.  *  Msgs_Lookup(tag, result, 11))
  32.  *
  33.  *  The tag string should be of the form:
  34.  *    "group.tag:default"  or  "group.tag"
  35.  *
  36.  *  The message found will be searched for <> includes. If any are found,
  37.  *  Msgs_Lookup() will be recursively invoked in order to compile
  38.  *  the final string. Note that circular references are not detected,
  39.  *  and will cause stack-chewing recursion until all memory is eaten up,
  40.  *  at which point the recursion (and all life as it we know it) will stop.
  41.  *
  42.  *  Remember also that more memory than is immediately obvious will
  43.  *  be needed for messages which include others. However, everything will
  44.  *  be truncated if necessary at "maxlength" characters.
  45.  *
  46.  *  NOTE: leading spaces are NOT removed by this call - you MUST use
  47.  *        a compact, space-free format in your program (though you can use
  48.  *        spaces for readability of your messages files)
  49.  *        [This saves code size in this function, as well as forcing you to
  50.  *         not waste space in your executable]
  51.  *
  52.  *  -If the message for group.tag is not found, then default is returned
  53.  *   (if no default, then the null string is returned - result[0] == '\0')
  54.  *
  55.  *  -If the message is found in the message list, TRUE is returned
  56.  *  -If the default has to be used, TRUE is returned
  57.  *  Otherwise FALSE is returned, and result[0] == '\0'
  58.  *
  59.  *  (Thus, if you get (Msgs_Lookup(...) == FALSE) then you have no valid
  60.  *  text to use. (Acorn's msgs returns the tag, which is very annoying
  61.  *  when you don't want tags appearing in your interface if anything goes
  62.  *  wrong)
  63.  */
  64.  
  65.  
  66. extern void Msgs_printf(char *result, char *formattag, ...);
  67. /*  Equivalent to sprintf(), but the "formattag" string is NOT a format
  68.  *  string, but rather a Msgs tag which is given to Msgs_Lookup in order
  69.  *  to generate a format string for subsequent use.
  70.  */
  71.  
  72.  
  73. extern BOOL Msgs_LoadFile(char *leafname);
  74. /*  Merges the given messages file into the current list of messages
  75.  *  (Uses Resource to supply the pathname)
  76.  *  Messages with the same group.msg tag will be overwritten by the
  77.  *  new messages coming in from the file.
  78.  *
  79.  *  Expects lines of the form:
  80.  *    group.msg: message text continuing to newline
  81.  *  Leading spaces are stripped
  82.  */
  83.  
  84.  
  85. extern void Msgs_DropGroup(char *grouptag);
  86. /*  Drops (deletes) a message group from memory
  87.  *  This is useful for regaining memory when a set of messages is no longer
  88.  *  needed (e.g. Help messages can be discarded when a user turns off help)
  89.  *
  90.  *  To get discarded messages back, you must re-call Msgs_LoadFile for the
  91.  *  appropriate messages file.
  92.  */
  93.  
  94.  
  95. extern void Msgs_Report(int errnum, char *tag, ...);
  96. /* Reports an error for the message specified by tag.
  97.  * You can also pass variable parameters for substitution.
  98.  * (See Error.h - Error_Report for the non-messagetrans'd version of this)
  99.  */
  100.  
  101.  
  102. extern void Msgs_ReportFatal(int errnum, char *tag, ...);
  103. /* As for Msgs_Report but calls Error_ReportFatal
  104.  */
  105.  
  106. #endif
  107.