File: XMessage.mesa - last edit:
Copyright (C) 1984, 1986 by Xerox Corporation
Tim Diebert: November 24, 1986 3:42:17 pm PST
DIRECTORY
NSString USING [String],
Rope USING [ROPE];
XMessage: CEDAR DEFINITIONS = BEGIN
Types
ROPE: TYPE ~ Rope.ROPE;
ClientData: TYPE = REF;
DestroyMsgsProc: TYPE = PROCEDURE [clientData: ClientData];
Handle: TYPE = REF Object;
Object: TYPE;
MsgID: TYPE = CARDINAL;
MsgKey: TYPE = CARDINAL;
MsgKeyList: TYPE = RECORD [ data: SEQUENCE length: CARDINAL OF MsgKey];
StringArray: TYPE = RECORD [ data: SEQUENCE length: CARDINAL OF NSString.String];
Messages: TYPE = RECORD [ data: SEQUENCE length: CARDINAL OF MsgEntry];
MsgEntry: TYPE = RECORD [
msgKey: MsgKey,  -- runtime mesage access handle
msg: NSString.String,  -- message body
translationNote: NSString.String ← NIL, -- special instructions to the translators
translatable: BOOLEAN ← TRUE, -- IF FALSE do not translate
type: MsgType ← userMsg, -- assertion as to who the client is
id: MsgID];   -- unique handle for the life time of message
MsgType: TYPE = {userMsg, template, argList, menuItem, pSheetItem, commandItem, errorMsg, infoMsg, promptItem, windowMenuCommand, others};
Error: ERROR [type: ErrorType];
ErrorType: TYPE = {arrayMismatch, invalidMsgKeyList, invalidStringArray, invalidString, notEnoughArguments};
Operations for obtaining messages
Get: PROCEDURE [h: Handle, msgKey: MsgKey] RETURNS [msg: NSString.String];
Returns message corresponding to the given msgKey.
GetList: PROCEDURE [h: Handle, msgKeys: REF MsgKeyList, msgs: REF StringArray];
Fills the client-supplied array with the requested messages.
Operations for inserting/extracting arguments into a message template
Compose: PROCEDURE [source: NSString.String, args: REF StringArray]
RETURNS [NSString.String];
composes a message consisting of the passed message template and inserted arguments.*
ComposeOne: PROCEDURE [source: NSString.String, arg: NSString.String]
RETURNS [NSString.String];
Add a single argument to a message template. Template has no numbered argument, e.g., "The <> field should be filled in".
Decompose: PROCEDURE [source: NSString.String] RETURNS [args: REF StringArray];
Returns an array of strings that resulted from parsing the supplied source.*
Message initialization operations
AllocateMessages: PROCEDURE [applicationName: NSString.String, maxMessages: CARDINAL, clientData: ClientData, proc: DestroyMsgsProc] RETURNS [h: Handle];
allocates and initializes a data structure for subsequent message registry and access. The DestroyMsgsProc is used when the message data structure is to be destroyed (unloading Tool or application).
DestroyMessages:PROCEDURE [h: Handle];
deletes all the messages in currently registered (by calling the registered DestroyMsgProc) and then destroys any private data structures.
RegisterMessages: PROCEDURE [h: Handle, messages: REF Messages,
stringBodiesAreReal: BOOL];
Allows a client to initialize a range of messages. If the value of BOOLEAN stringBodiesAreReal is TRUE it indicates to the implementor of RegisterMessages that it is ok to use the pointer messages[n].msg in your private data structures. If this BOOLEAN = FALSE then the string body must be copied if its value is to be retained after the call.
Message initialization from a file
MessagesFromFile: PROCEDURE [fileName: ROPE, clientData: ClientData,
proc: DestroyMsgsProc] RETURNS [msgDomains: REF MsgDomains];
MessagesFromFile will look in the system files for a file named fileName or filename.messages. The return parameter msgDomains will contain an entry for message domain in the message file. It should be freed using the operation FreeMsgDomainsStorage.
MsgDomains: TYPE = RECORD [ data: SEQUENCE length: CARDINAL OF MsgDomain];
MsgDomain: TYPE = RECORD [applicationName: NSString.String, handle: Handle];
FreeMsgDomainsStorage: PROCEDURE [msgDomains: REF MsgDomains];
MessagesFromReference: PROCEDURE [file: ROPE, clientData: ClientData,
proc: DestroyMsgsProc] RETURNS [msgDomains: REF MsgDomains];
MessagesFromReference will get the messages from file. The return parameter msgDomains will contain an entry for message domain in the message file. It should be freed using the operation FreeMsgDomainsStorage.
END. -- of Message