Back to Contents        Previous        Next






9. Message files **

It is increasingly common for applications to have Message files (nothing to do with the Wimp’s Messaging system!). These files commonly hold much of the fixed text used by the application. So, for example, it might be used for the interactive help text (see Section 2.10) which can then be easily translated into another language by someone who doesn’t need to know much about programming.

Copy the “Messages” file from the Tutorials folder into the !MyApp directory. Load it into !Edit and have a look at it to become familiar with the Message file format. You will see:

#Message file for tutorial 9.
#Prepared by Andrew Ayre
#version 1.00 (29-Mar-95)

LIB:Doctor Wimp
OS:RISC OS %0
UTIL:Func’n’Proc
VER:1.00 (%0-%1-99)

Note firstly that you can put comments into a Message file simply by starting the comments line with a hash “#”.

Lines which have text to be used in the application start with what is called a token. This is just a few letters (not necessarily upper-case) that the line can be identified by. The token is followed by the required text - separated by a colon. For example:

LIB:Doctor Wimp

We can then use the token in our program instructions, and its corresponding text will be substituted. Thus, if we wanted to use the line of text “Doctor Wimp” in our program, we would reference it by using the token “LIB”.

Note: The message file must be terminated by a <return>, otherwise the last message in the file will not work.

Further, by using parameters, the substituted text can also have other strings inserted into them at the time they are read into the application. For example:

OS:RISC OS %0

which includes the parameter %0 and:

VER:1.00 (%0-%1-99)

which includes the parameters %0 and %1

Taking the last one only, when you read in this line (by referring to the token “VER”) you would also supply two strings. These could be “29“ and “Mar” for example. When the line is read in it ends up as “1.00 (29-Mar-99)”.


Dr Wimp’s provides several wimp-functions to manipulate messages files. They are:

FNwimp_initmessages(path$)

which needs to be called once for each Message file you are going to use. It sets up blocks of memory ready to read in the lines of text. path$ is the full pathname of the Message file. The function returns a handle for that particular messages file, which is used to access the file, with:

FNwimp_messlookup(messagefilehandle%,token$,a$,b$)

as will be demonstrated below.

You can use multiple messages files. By default the maximum number of such files is 16 (in any one application) but this can easily be changed - see later.


So, to use the above-mentioned Message file called Messages it must first be initialised using FNwimp_initmessages(path$)and it is best to do this early within PROCuser_initialise.

For the tutorial, we therefore need to make the initialisation call for the Message file which is now inside the !MyApp directory i.e.

messages%=FNwimp_initmessages(”<MyApp$Dir>”.Messages)

The handle returned to messages% can now be used anywhere in your program.

To fetch, from the Message file, a string which does not have any substitution parameters in it you would use, for example:

FNwimp_messlookup(messages%,”UTIL”,””,””)

This returns the line of text “Func’n’Prc”.

To fetch a string which has just the parameter “%0” in it you would use, for example:

FNwimp_messlookup(messages%,”OS”,”4.02”,””)

This returns the line of text “RISC OS 4.02”.

And finally, to fetch a string which has both the parameters “%0” & “%1” in it you would use, for example:

FNwimp_messlookup(messages%,”VER”,”1st”,”Jan”)

This returns the line of text “1.00 (1st-Jan-99)”.

So, add the following lines to PROCuser_initialise after FNwimp_initmessages and run your application.

lib$=FNwimp_messlookup(messages%,“LIB”,””,””)
PROCwimp_error(appname$,“LIB=”+lib$,1,””,0,2,””)
os$=FNwimp_messlookup(
messages%,“OS”,“3.11”,””)
PROCwimp_error(appname$,“OS=”+os$,1,””,0,2,””)
ver$=FNwimp_messlookup(
messages%,“VER”,“29”,“Mar”)
PROCwimp_error(appname$,“VER=”+ver$,1,””,0,2,””)


These will cause a series of three error boxes to show in turn, each carrying short (and probably bewildering!) text constructed from the Message file. (When you have checked that it works you should delete/REM the above 6 lines.)


[Your !RunImage listing should now look like listing RI_06 in Tutor1 (apart from the REM lines, perhaps). Do not destroy it as the tutorial picks up again in the next section - Section 2.10 - where it continues from this stage.]

Note that you can use %0 and/or %1 as many times as you like in a Message string. You can also put them in any order.



You can also substitute a different messages file for one that has already been initiated, by using:

FNwimp_reinitmessages(messagefilehandle%,path$)

where messagefilehandle% is the handle of the already-initiated messages file and path$ is the full path of the new messages file that you wish to substitute. Substituting a different file in this way does not increase the number of simultaneously active messages files - it simply discards one in favour of another. This process is very useful when producing up-to-the-minute menus from changing messages files e.g. message files constructed by reading a directory’s current contents.

It would be usual to use this function in the following manner:

messages%=FNwimp_reinitmessages(messages%,path$)

That is, assign the new handle to the same variable.

There is no practical limit to the number of times you can re-initiated a file - except that your application WimpSlot needs to be large enough to cope with the largest messages file, but this is unlikely to be a problem.


There is also a wimp-function for finding out how many messages there are in an active messages file, for a given token. It is:

FNwimp_getnumberofmessages(messagefilehandle%,token$)

and its use should be self-explanatory.


Finally, Message files can also be used for creating/recreating menus - see Section 2.18 - and in that section there is also further important guidance on formatting messages files.



As indicated above, by default the maximum number of messages files you can use in an application is 16, which is probably more than adequate - but this is easily changed if it is not enough for a particular application. Inside the DrWimp library - approximately ten lines into FNwimp_initialise - is the global variable wMaxMessagefiles%. Simply change its assigned value here to the maximum number you want.





Top of page        Back to Contents        Previous        Next