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