home *** CD-ROM | disk | FTP | other *** search
/ NetNews Usenet Archive 1992 #19 / NN_1992_19.iso / spool / comp / sys / acorn / tech / 91 < prev    next >
Encoding:
Internet Message Format  |  1992-09-03  |  10.0 KB
  1. Path: sparky!uunet!wupost!waikato.ac.nz!aukuni.ac.nz!cs18.cs.aukuni.ac.nz!jwil1
  2. Newsgroups: comp.sys.acorn.tech
  3. Subject: MsgTrans info
  4. Message-ID: <1992Sep3.005623.25930@cs.aukuni.ac.nz>
  5. From: jwil1@cs.aukuni.ac.nz (TMOTA)
  6. Date: Thu, 3 Sep 1992 00:56:23 GMT
  7. Sender: jwil1@cs.aukuni.ac.nz (TMOTA)
  8. Organization: Computer Science Dept. University of Auckland
  9. Lines: 234
  10.  
  11. Well, some people wanted some information on how to use MsgTrans, so here's
  12. a (rather old but should be correct) bit of info that might help...
  13.  
  14. Note that it's also very easy to write a teensy bit of code to do something
  15. very similar to msgtrans, which saves you getting a binary distrib ution
  16. license from Acorn (hmmm... there's a good reason not to have to have bdl's)
  17. and also lets you tune things to how you need them to be... but at least keep
  18. compatible with the MsgTrans file format, to save confusion, etc.
  19.  
  20. ---
  21.  
  22. MessageTrans
  23.  
  24. Overview
  25. --------
  26.  
  27. This document describes the SWI interface to the MessageTrans module, which
  28. provides message translation services, and the format of the message files
  29. that it uses.
  30.  
  31.  
  32. SWI MessageTrans_FileInfo
  33.    In   R1 -> filename
  34.    Out  R0 = flag word:
  35.          bit 0 set => file is held in memory (can be accessed directly)
  36.          bits 1..31 reserved (ignore them)
  37.     R2 = size of buffer required to hold file
  38.          if R0 bit 0 set, the buffer is not required for read-only access
  39.  
  40. SWI MessageTrans_OpenFile
  41.    In   R0 -> 4-word data structure
  42.           must be held in the RMA if R2=0 on entry
  43.     R1 -> filename, held in the RMA if R2=0 on entry   
  44.             (NOTE: FILENAME MUST REMAIN UNCHANGED FOR THE
  45. DURATION OF THE FILE BEING OPEN)
  46.     R2 -> buffer to hold file data
  47.           0 => allocate some space in the RMA,
  48.            or use the file directly if possible
  49.     Error: "Message file already open" if R0 points to a structure
  50.            already known to MessageTrans (ie. already open).
  51.  
  52.     An application may decide that it would like to buffer the file in
  53.     its own workspace (rather than the RMA) if it needs to be loaded, or
  54.     use the file directly if it is already in memory.  To do this:
  55.  
  56.         SYS "MessageTrans_FileInfo",,filename$ TO flags%,,size%
  57.         IF flags% AND 1 THEN buffer%=0 ELSE buffer%=FNalloc(size%)
  58.         SYS "OS_Module",6,,,17+LENfilename$ TO ,,filedesc%
  59.         $(filedesc%+16)=filename$
  60.         SYS "MessageTrans_OpenFile",filedesc%,filedesc%+16,buffer%
  61.  
  62.     where FNalloc() allocates a buffer of a given size, by using the
  63.     Wimp_SlotSize or "END=" command.  Note that in fact the filename and
  64.     file descriptor only need to be in the RMA if R2=0 on entry to
  65.     MessageTrans_OpenFile.
  66.  
  67.   Note: If R2=0 on entry to this SWI, and the application uses direct
  68.     pointers into the file (rather than copying the messages out) or
  69.     uses MessageTrans_MakeMenus, it should also trap
  70.     Service_MessageFileClosed, in case the file is unloaded.
  71.  
  72. SWI MessageTrans_Lookup
  73.    In   R0 -> 4-word data structure passed to MessageTrans_OpenFile
  74.     R1 -> token, terminated by any char <= 32, or "," or ")"
  75.           or token:default message terminated by 0 char.
  76.     R2 -> buffer to hold result (0 => don't copy it)
  77.     R3 = buffer size (if R2 non-0)
  78.     R4 -> parameter 0 (0 => don't substitute for "%0")
  79.     R5 -> parameter 1 (0 => don't substitute for "%1")
  80.     R6 -> parameter 2 (0 => don't substitute for "%2")
  81.     R7 -> parameter 3 (0 => don't substitute for "%3")
  82.    Out  R1 -> terminator of token
  83.     R2 -> result string (read-only with no sustitution if R2=0 on entry)
  84.     R3 = size of result before terminator
  85.          (terminator = 10 if R2=0 on entry, else 0)
  86.  
  87.    This SWI allows a message token to be translated into a string, with
  88.    optional parameter substitution.
  89.  
  90.    The application must have called MessageTrans_OpenFile beforehand in
  91.    order to use this SWI, although you can still call it if the file has
  92.    been automatically closed by the system, because it will automatically
  93.    re-open it as well.
  94.  
  95.    If the message token does not match, the error "Message token not found"
  96.    is returned unless the token was followed by ":default value", in which
  97.    case the default value is returned (I.E. either copied to the buffer or
  98.    pointed at).  This error is also given if the value to be returned is on
  99.    the last line of the file, and does not have a terminating CHR$(10).
  100.  
  101.  
  102.    See the "File format" section for further details.
  103.  
  104.  
  105.  
  106. SWI MessageTrans_MakeMenus
  107.    In   R0 -> 4-word data structure passed to MessageTrans_OpenFile
  108.     R1 -> menu definition (see below)
  109.     R2 -> RAM buffer to hold menu structure
  110.     R3 = size of RAM buffer
  111.    Out  [R1..] = menu data
  112.     R3 = bytes remaining in buffer (should be 0 if you got it right)
  113.     "Buffer overflow" error if buffer is too small
  114.  
  115.    Menu structure:
  116.     +0 (n)  Token for menu title, terminated by any char <= 32, or "," or ")"
  117.         null => no more menus, otherwise:
  118.     +n (1)  menu title foreground and frame colour
  119.        (1)  menu title background colour
  120.        (1)  menu work area foreground colour
  121.        (1)  menu work area background colour
  122.        (1)  height of menu items
  123.        (1)  gap between items
  124.     Menu items:
  125.        (n)  Token for menu item, terminated by any char <= 32, or "," or ")"
  126.        Word-align to here (addr := (addr+3) AND (NOT 3))
  127.        (4)  Menu flags (bit 7 set => last item)
  128.        (4)  Offset from RAM menu start to RAM submenu start
  129.         0 => no submenu
  130.        (4)  Icon flags
  131.  
  132.    This SWI allows a menu structure to be set up from a structure
  133.    containing references to tokens, and sets up menu widths.  Parameter
  134.    substitution is not allowed.
  135.  
  136.    The application must have called MessageTrans_OpenFile beforehand in
  137.    order to use this SWI, although you can still call it if the file has
  138.    been automatically closed by the system, because it will automatically
  139.    re-open it as well.
  140.  
  141.    If the icon flags have bit 8 clear (ie. they are not indirected), the
  142.    message text for the icon will be read into the 12-byte block that forms
  143.    the icon data, otherwise the icon data will be set up to point to the
  144.    message text inside the file data.  In the latter case they are
  145.    read-only.
  146.  
  147.    If the menu item flags bit 2 is set (writeable) and the icon is
  148.    indirected, the 3 words of the icondata in the RAM buffer are assumed to
  149.    have already been set up by the calling program.  The result of looking
  150.    up the message token is copied into the buffer indicated by the first
  151.    word of the icon data (truncated if it gets bigger than the buffer size
  152.    indicated in [icondata,#8]).
  153.  
  154.  
  155. SWI MessageTrans_CloseFile
  156.    In   R0 -> 4-word data structure passed to MessageTrans_OpenFile
  157.  
  158.  
  159. Service_MessageFileClosed
  160.    In   R0 -> 4-word data structure passed to MessageTrans_OpenFile
  161.    Out  If the application recognises the value of R0 passed in, and it has
  162.     any direct pointers into the message data that it relates to, it
  163.     should re-initialise itself by calling MessageTrans_OpenFile again
  164.     to re-open the file, and recache its pointers.  If it has used
  165.     MessageTrans_MakeMenus, it should call Wimp_GetMenuState to see if
  166.     its menu tree it open, and delete it using Wimp_CreateMenu(-1) if
  167.     so.
  168.  
  169.    This service call is only ever issued if the file is not held in the
  170.    user's own buffer.  It tells the application that its file data has been
  171.    thrown away, for example if the file is held inside a module which is
  172.    then reloaded.
  173.  
  174.    It is only necessary to trap this service call if direct pointers into
  175.    the file data are being used.  Otherwise, the MessageTrans module will
  176.    make a note in the file descriptor that the file has been closed, and
  177.    simply re-open it when MessageTrans_Lookup or MessageTrans_MakeMenus is
  178.    next called on that file.
  179.  
  180.    It is recommended that applications that cannot trap service calls do not
  181.    use direct pointers into the file data (eg. indirected icons with
  182.    MessageTrans_MakeMenus).  They can still use such indirected icons, if
  183.    they provide a buffer pointer in R2 on entry to MessageTrans_OpenFile (so
  184.    that the message file data is copied into the buffer).
  185.  
  186.  
  187. Service_Reset
  188.  
  189.    Since MessageTrans does not close message files on a soft reset,
  190.    applications that do not wish their message files to be open once they
  191.    leave the desktop should call MessageTrans_CloseFile for all their open
  192.    files at this point.  However, it is perfectly legal for message files to
  193.    be left open over soft reset.
  194.  
  195.  
  196. File format
  197. -----------
  198.  
  199. Message files contain a series of one-line token / value pairs, terminated
  200. by character 10 (linefeed).
  201.  
  202.     <file> ::= { <line> }*
  203.     <line> ::= <tokline> | "#" <comment><nl> | <nl>
  204.      <tokline> ::= <token> { "/"<token> | <nl><token> }* : <value><nl>
  205.        <token> ::= <tokchar> { <tokchar> }*
  206.      <tokchar> ::= <char> | <wildcard>
  207.     <char> ::= any character > " " except ",", ")", ":", "?" or "/"
  208.     <wildcard> ::= "?"      (matches any character)
  209.      <comment> ::= { <anychar> }*
  210.      <anychar> ::= any character except <nl>
  211.       <nl> ::= character code 10
  212.        <value> ::= { <anychar> | "%0" | "%1" | "%2" | "%3" | "%%" }*
  213.  
  214. Note that the spaces in the above description are purely to improve
  215. readability - in fact spaces are significant inside tokens, so should only
  216. really appear in <comment> and <value>.
  217.  
  218. Alternative tokens are separated by "/" or <nl>.  If any of the alternative
  219. tokens before the next ":" match the supplied token, the value after the
  220. next ":" up to the following <nl> is returned.  The "?" character in a token
  221. in the file matches any character in the supplied match token.  Case is
  222. significant.
  223.  
  224. If R2 is not 0 on entry to MessageTrans_Lookup, "%0", "%1", "%2" and "%3"
  225. are subsitituted with the parameters supplied in R4..R7, except where the
  226. relevant register is 0, in which case the text is left alone.  "%%" is
  227. converted to "%" - otherwise if no parameter substitution occurs the text is
  228. left alone.  No other substitution is performed on the string.
  229.  
  230. For example:
  231.  
  232.     # This is an example message file
  233.  
  234.     TOK1:This value is obtained only for "TOK1".
  235.     TOK2
  236.     TOK3/TOK4:This value is obtained for "TOK2","TOK3" or "TOK4"
  237.     TOK?:This value is obtained for "TOK<not 1,2,3 or 4>"
  238.  
  239.     ANOTHER:Parameter in R4 = %0, parameter in R5 = %1.
  240.  
  241. -- 
  242. _________________  "I'd like to answer this question in two ways:
  243.   /____ _ _/_ __       First in my normal voice, and then
  244.  // / //_//_ /_/       in a silly, high-pitched whine." (Monty Python)
  245.