This header declares functions to read in token - text pairs from files and then lookup the text, like you do with MessageTrans. This is intended to aid, for instance, internationalisation of your program, so all error messages, menu text, etc. if in a text file or files rather than being compiled into the program.
These are much simpler than the equivalent MessageTrans SWIs (which MsgTrans provides an interface for). There are also various other library functions which allow you to directly supply Msgs tokens in place of strings (eg. Menu2_CreateFromMsgs).
Not that for the system to work properly all tags should be in the form "group.tag" not just "tag" (they should all have two parts), and neither the 'group' nor 'tag' part should be longer than 8 characters.
This looks up the given tag in the current message list, and copies the corresponding message (if it exists) into 'result'. No more than 'maxlength' characters will be copied, though a terminator may be added in result[maxlength]. The tag string should be in the form "group.tag:default message" or "group.tag". The default message (if given) will be used if the tag cannot be found.
The message found will be searched for other messages included with "<tag>" includes. Msgs_Lookup will be recursively invoked in order to compile the final string, if any such includes are found. Note that circular references are not detected and so the recursion can be infinite (or at least until your program crashes). However, the recursion *will* stop when there is no more space in the buffer, so it is only really infinite if a message does nothing except include itself. Remember that messages which include others will need more memory than is immediately obvious.
This function returns TRUE if the tag is found, or if a default message was supplied and used. Otherwise, FALSE is returned, and result[0] is set to '\0' (the result string is empty).
The works like sprintf, but using a format string looked up from the loaded list of messages. You simply pass in a message tag where you would supply a format string.
This function returns TRUE if the tag is found, or if a default message was supplied and used. Otherwise, FALSE is returned, and result[0] is set to '\0' (the result string is empty).
The loads the given messages file into your list of messages. The file is found using resource_pathname and the given leafname. This merges the loaded file with the current list, overwriting messages which had the same tag and leaving the others alone.
The file should be made up of a series of "group.msg: message text" lines. The "group" and "msg" parts are both limited to a maximum eight characters. Comments can be included if the line starts with #, and messages can include other messages by putting the tag inside angle brackets ('<' and '>'). This means that in order to write '<' inside a messages file, you should use "<>" in its place.
You should leave a couple of return characters at the end of the file, as otherwise the last message may be lost.
This deletes the given message group from memory. This is useful for regaining memory when you know a given group of messages is no longer needed, for instance you have created the menus that the text was needed for.
You cannot reload a single group of messages. If you want to get the dropped messages back you have to reload the file they were read from originally.
This calls Error_Report with the error message format string supplied by looking up the given tag in the current list of messages.
This calls Error_ReportFatal with the error message format string supplied by looking up the given tag in the current list of messages.