home *** CD-ROM | disk | FTP | other *** search
/ RISC DISC 1 / RISC_DISC_1.iso / pd_share / code / desklib / !DeskLib / h / Msgs < prev    next >
Encoding:
Text File  |  1993-08-03  |  4.5 KB  |  113 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, 1993 Jason Williams
  13.     Version: 1.01 (04 Aug 1993)
  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.  *  However, it will stop when your destination buffer is full, so infinite
  42.  *  recursion will only occur if your included string is empty except for
  43.  *  including itself.
  44.  *
  45.  *  Remember also that more memory than is immediately obvious will
  46.  *  be needed for messages which include others. However, everything will
  47.  *  be truncated if necessary at "maxlength" characters.
  48.  *
  49.  *  NOTE: leading spaces are NOT removed by this call - you MUST use
  50.  *        a compact, space-free format in your program (though you can use
  51.  *        spaces for readability of your messages files)
  52.  *        [This saves code size in this function, as well as forcing you to
  53.  *         not waste space in your executable]
  54.  *
  55.  *  -If the message for group.tag is not found, then default is returned
  56.  *   (if no default, then the null string is returned - result[0] == '\0')
  57.  *
  58.  *  -If the message is found in the message list, TRUE is returned
  59.  *  -If the default has to be used, TRUE is returned
  60.  *  Otherwise FALSE is returned, and result[0] == '\0'
  61.  *
  62.  *  (Thus, if you get (Msgs_Lookup(...) == FALSE) then you have no valid
  63.  *  text to use. (Acorn's msgs returns the tag, which is very annoying
  64.  *  when you don't want tags appearing in your interface if anything goes
  65.  *  wrong)
  66.  */
  67.  
  68.  
  69. extern void Msgs_printf(char *result, char *formattag, ...);
  70. /*  Equivalent to sprintf(), but the "formattag" string is NOT a format
  71.  *  string, but rather a Msgs tag which is given to Msgs_Lookup in order
  72.  *  to generate a format string for subsequent use.
  73.  */
  74.  
  75.  
  76. extern BOOL Msgs_LoadFile(char *leafname);
  77. /*  Merges the given messages file into the current list of messages
  78.  *  (Uses Resource to supply the pathname)
  79.  *  Messages with the same group.msg tag will be overwritten by the
  80.  *  new messages coming in from the file.
  81.  *
  82.  *  Expects lines of the form:
  83.  *    group.msg: message text continuing to newline
  84.  *  Leading spaces are stripped
  85.  *
  86.  *  NOTE that the last message from the file may be lost unless there are
  87.  *  a couple of return characters on the end of the file.
  88.  */
  89.  
  90.  
  91. extern void Msgs_DropGroup(char *grouptag);
  92. /*  Drops (deletes) a message group from memory
  93.  *  This is useful for regaining memory when a set of messages is no longer
  94.  *  needed (e.g. Help messages can be discarded when a user turns off help)
  95.  *
  96.  *  To get discarded messages back, you must re-call Msgs_LoadFile for the
  97.  *  appropriate messages file.
  98.  */
  99.  
  100.  
  101. extern void Msgs_Report(int errnum, char *tag, ...);
  102. /* Reports an error for the message specified by tag.
  103.  * You can also pass variable parameters for substitution.
  104.  * (See Error.h - Error_Report for the non-messagetrans'd version of this)
  105.  */
  106.  
  107.  
  108. extern void Msgs_ReportFatal(int errnum, char *tag, ...);
  109. /* As for Msgs_Report but calls Error_ReportFatal
  110.  */
  111.  
  112. #endif
  113.