/*
    ####             #    #     # #
    #   #            #    #       #          The FreeWare C library for 
    #   #  ##   ###  #  # #     # ###             RISC OS machines
    #   # #  # #     # #  #     # #  #   ___________________________________
    #   # ####  ###  ##   #     # #  #                                      
    #   # #        # # #  #     # #  #    Please refer to the accompanying
    ####   ### ####  #  # ##### # ###    documentation for conditions of use
    ________________________________________________________________________

    File:    Msgs.h
    Author:  Copyright  1992, 1993 Jason Williams
    Version: 1.01 (04 Aug 1993)
    Purpose: MessageTrans-like message handling functions.
             (If you want MessageTrans, use the SWI interface, if you want
             high-level message handling, use this code...)
*/

#ifndef __Desk_Msgs_h
#define __Desk_Msgs_h


#ifdef __cplusplus
extern "C" {
#endif


#ifndef __Desk_Core_h
#include "Desk.Core.h"
#endif

extern Desk_bool Desk_Msgs_Lookup(const char *tag, char *result, int maxlength);
/*  Looks up the tag in the current message list, and copies the appropriate
 *  message into result if found. (no more than maxlength characters will
 *  be copied, so you can copy directly into icon indirected text, etc.
 *  REMEMBER that arrays start at 0, so if you have "char result[12]", use
 *  Desk_Msgs_Lookup(tag, result, 11))
 *
 *  The tag string should be of the form:
 *    "group.tag:default"  or  "group.tag"
 *
 *  The message found will be searched for <> includes. If any are found,
 *  Desk_Msgs_Lookup() will be recursively invoked in order to compile
 *  the final string. Note that circular references are not detected,
 *  and will cause stack-chewing recursion until all memory is eaten up,
 *  at which point the recursion (and all life as it we know it) will stop.
 *  However, it will stop when your destination buffer is full, so infinite
 *  recursion will only occur if your included string is empty except for
 *  including itself.
 *
 *  Remember also that more memory than is immediately obvious will
 *  be needed for messages which include others. However, everything will
 *  be truncated if necessary at "maxlength" characters.
 *
 *  NOTE: leading spaces are NOT removed by this call - you MUST use
 *        a compact, space-free format in your program (though you can use
 *        spaces for readability of your messages files)
 *        [This saves code size in this function, as well as forcing you to
 *         not waste space in your executable]
 *
 *  -If the message for group.tag is not found, then default is returned
 *   (if no default, then the null string is returned - result[0] == '\0')
 *
 *  -If the message is found in the message list, Desk_bool_TRUE is returned
 *  -If the default has to be used, Desk_bool_TRUE is returned
 *  Otherwise Desk_bool_FALSE is returned, and result[0] == '\0'
 *
 *  (Thus, if you get (Desk_Msgs_Lookup(...) == Desk_bool_FALSE) then you have no valid
 *  text to use. (Acorn's msgs returns the tag, which is very annoying
 *  when you don't want tags appearing in your interface if anything goes
 *  wrong)
 */


extern void Desk_Msgs_printf(char *result, const char *formattag, ...);
/*  Equivalent to sprintf(), but the "formattag" string is NOT a format
 *  string, but rather a Msgs tag which is given to Desk_Msgs_Lookup in order
 *  to generate a format string for subsequent use.
 */


extern Desk_bool Desk_Msgs_LoadFile(const char *leafname);
/*  Merges the given messages file into the current list of messages
 *  (Uses Resource to supply the pathname)
 *  Messages with the same group.msg tag will be overwritten by the
 *  new messages coming in from the file.
 *
 *  Expects lines of the form:
 *    group.msg: message text continuing to newline
 *  Leading spaces are stripped
 *
 *  NOTE that the last message from the file may be lost unless there are
 *  a couple of return characters on the end of the file.
 */


extern void Desk_Msgs_DropGroup(const char *grouptag);
/*  Drops (deletes) a message group from memory
 *  This is useful for regaining memory when a set of messages is no longer
 *  needed (e.g. Help messages can be discarded when a user turns off help)
 *
 *  To get discarded messages back, you must re-call Desk_Msgs_LoadFile for the
 *  appropriate messages file.
 */


extern void Desk_Msgs_Report(int errnum, const char *tag, ...);
/* Reports an error for the message specified by tag.
 * You can also pass variable parameters for substitution.
 * (See Error.h - Desk_Error_Report for the non-messagetrans'd version of this)
 */


extern void Desk_Msgs_ReportFatal(int errnum, const char *tag, ...);
/* As for Desk_Msgs_Report but calls Desk_Error_ReportFatal
 */
 
#ifdef __cplusplus
}
#endif

#endif
