DEFINITION MODULE Preferences;
(*******************************************************************
Module Preferences (Version 1.0)
Copyright (c) 1996-2006 by Andreas Fischlin and ETH Zurich.
Purpose Manage preferences on behalf of a program.
Remarks Stores preferences permanently in the
resource fork of the file prefsFileName
(e.g. the program module object code file
like "MyMainMod.OBM" or "MyMainMod.R") the
resource of type "STR " with ID = prefsID.
The preference string s has this format
n = 2
m = HIGH(modes)+1
Part of s Stored value Meaning
--------------------------------------------
s[0..1] m Number of modes
s[n+i] modes[i] Mode i
s[n+m..end] str Any string
Example: Store 2 boolean values (modes) and
a file name in "MyMainMod.R" with prefsID 7007
write this code
CONST noModes = 2; fstMode = 0; sndMode = 1;
prefsFN = "MyMainMod.R"; prefsID = 7007;
VAR myMode1, myMode2: BOOLEAN;
myFileName: ARRAY [0..255] OF CHAR;
PROCEDURE StorePrefs;
VAR modes: ARRAY [0..noModes-1] OF BOOLEAN;
BEGIN
modes[fstMode] := myMode1;
modes[sndMode] := myMode2;
StorePreferences(prefsFN,prefsID,modes,myFileName);
END StorePrefs;
PROCEDURE RetrievePrefs;
VAR modes: ARRAY [0..noModes-1] OF BOOLEAN; done: BOOLEAN;
BEGIN
RetrievePreferences(prefsFN,prefsID,modes,myFileName,done);
IF done THEN
myMode1 := modes[fstMode];
myMode2 := modes[sndMode];
END(*IF*);
END StorePrefs;
Programming
o Design
Andreas Fischlin 12/12/1996
o Implementation
Andreas Fischlin 12/12/1996
ETH Zurich
Systems Ecology
CHN E 35.1
Universitaetstrasse 16
8092 Zurich
SWITZERLAND
URLs:
<mailto:RAMSES@env.ethz.ch>
<http://www.sysecol.ethz.ch>
<http://www.sysecol.ethz.ch/SimSoftware/RAMSES>
Last revision of definition: 02/02/1997 AF
*******************************************************************)
CONST
maxModes = 99;
PROCEDURE RetrievePreferences (prefsFileName: ARRAY OF CHAR;
prefsID: INTEGER;
VAR modes: ARRAY OF BOOLEAN;
VAR str: ARRAY OF CHAR;
VAR done: BOOLEAN);
(*
Retrieve the preference consisting of a number of modes
plus a string previously stored with procedure
StorePreferences of type "STR " with ID prefsID in the file
prefsFileName. Note, prefsFileName can be the empty
string. In this case resources are searched according to
the so-called default search strategy, i.e. first in the
resource fork of the currently executing program module's
object file (ProgramModule.OBM), in the running application
(typically a shell or if the program module has been linked
into an application, in the resource fork of this
application), or if still not found, the search continues
to the System File. done returns the success of the
retrieval, regardless of the cause of the error (given file
does not exist or the file does not contain the wanted
resource etc.). If done = FALSE, modes and str have not
been changed.
*)
PROCEDURE StorePreferences (prefsFileName: ARRAY OF CHAR;
prefsID: INTEGER;
modes: ARRAY OF BOOLEAN;
str: ARRAY OF CHAR);
(*
Stores HIGH(modes)+1 modes plus the string str in a resource of type
"STR " with ID prefsID in the file prefsFileName. In case there
exists no such resource yet, the first time you call this
routine, a new resource will be created. It will be named
"Prefences" (use ResEdit to change that name, if you wish to
have another, more specific one).
NOTE: It is recommended to call this routine first with a
non-empty prefsFileName, or you will affect the resource fork
of the application with which you are developping, e.g. the
RAMSES Shell, which is probably not what you actually want.
However, once you have created the resource, you can easily
pass an empty prefsFileName, given you make sure the resource
is present either in the resource fork of the object code of
the program module (e.g. by calling utility InsertRes (from
MacMETH) or use the project facility to make your program
(see RAMSES Help, Topic Projects) or you linked your program
as an application.
IMPLEMENTATION RESTRICTION: The total length of a preference
(including modes and str) must not be longer than 255 bytes
or the data will be truncated.
*)
PROCEDURE AppendStr (VAR dest: ARRAY OF CHAR; substr: ARRAY OF CHAR);
PROCEDURE AppendInt (VAR dest: ARRAY OF CHAR; int: INTEGER);
PROCEDURE AppendReal(VAR dest: ARRAY OF CHAR; r: REAL);
PROCEDURE ExtractStr (VAR(*speedp-up*) src: ARRAY OF CHAR;
start: BOOLEAN; VAR substr: ARRAY OF CHAR);
PROCEDURE ExtractInt (VAR(*speedp-up*) src: ARRAY OF CHAR;
start: BOOLEAN; VAR int: INTEGER);
PROCEDURE ExtractReal(VAR(*speedp-up*) src: ARRAY OF CHAR;
start: BOOLEAN; VAR r: REAL);
(*
Above routines allow for packing substrings into a single
string for easier storing of several items in a preference
string (E.g. "pref1|23|1.0234||text" holds a string, an
integer, a real number, an empty string, and a third string).
Substrings are delimited by "|". The appending routines all
insert the delimiter before appending a new item, if the
destination string is not empty. The extract routines return
item (substring) after substring; to start the extraction
pass start = TRUE, for all subsequent items pass FALSE.
Note: Type BOOLEAN is supported by the modes (see procedures
RetrievePreferences/StorePreferences). Above example can be
stored with:
s:= "";
AppendStr(s,"pref1");
AppendInt(s,23);
AppendReal(s,1.0234);
AppendStr(s,"");
item2 := "text"; AppendStr(s,item2);
StorePreferences(...,s);
or retrieved with:
RetrievePreferences(... s, done)
IF done THEN
ExtractStr(s,TRUE,pref1);
ExtractInt(s,FALSE,myinteger);
ExtractReal(s,FALSE,myreal);
ExtractStr(s,FALSE,mystring);
ExtractStr(s,FALSE,item2);
END(*IF*);
*)
END Preferences.
RAMSES
Modules:
A-Z
Function
Layer
QuickRefs:
DM
AuxLib
AuxLibE
SciLib
EasyMW
MW
ISIS
RMSLib