DEFINITION MODULE DatFraViewer;
(*******************************************************************
Module DatFraViewer (DF_Version_2.2)
Copyright (c) 1997-2006 by Andreas Fischlin and ETH Zurich.
Purpose Allows to inspect all currently present
data frames as stored in memory
(see module DataFrames).
Remarks The default viewer's window is sized to fill
about 2 thirds of the main screen
Programming
o Design
Andreas Fischlin 27/07/1997
o Implementation
Andreas Fischlin 27/07/1997
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: 10/04/1998 AF
*******************************************************************)
FROM DMWindows IMPORT WindowFrame;
FROM DMMenus IMPORT Menu;
FROM DataFrames IMPORT ReadingFilter, ValDefType;
FROM DatFraAux IMPORT SimpleRetrieveMethod, SpecialRetrieveMethod;
(* see module DataFrames for codes used for errors & messages *)
(*******************************************************)
(*##### Basic activation of data frame viewer #####*)
(*******************************************************)
PROCEDURE MakeDatFraViewer;
PROCEDURE DiscardDatFraViewer;
(*
Installs respectively discards the data frame viewer's standard
user interface. It consists of a window, the data frame viewer's
window, and a menu with commands to operate the data frame viewer.
The most important commands are the loading of data frames from
disk files into memory (see below routine
LoadDataFramesFromAnchor), the viewing (see below e.g. routine
ShowDataFrames) and the unloading of data frames from memory (see
below routine UnloadDataFrames). All functions of the data frame
viewer are also available via a client interface, i.e. the
standard user interface can be entirely bypassed, e.g. by calling
ShowDataFrames from a program and by redirect its output to another
window or a file.
*)
(**************************************************)
(*##### Loading/Unloading of data frames #####*)
(**************************************************)
PROCEDURE LoadDataFramesFromAnchor (VAR anchorfn: ARRAY OF CHAR);
(*
LoadDataFramesFromAnchor loads data frames by starting
the reading process from the anchor file with the name
anchorfn. If anchorfn is the empty string, the user may
select an anchor via the standard file opening dialog
(see also module DataFrames). Loading takes place
selectively by regarding only data frames which match the
reading filter tillFilter or file references which match
fromFilter according to the rules explained in module
DataFrames (see also routines EditFilters, GetFilters,
and SetFilters from this module). All other items are
ignored during the loading process (see module
DataFrames). If the routine was successful, anchorfn
returns the actual file name (preceeded by path) used as
anchor file.
*)
PROCEDURE UnloadDataFrames;
(*
UnloadDataFrames frees the memory and deletes all data
frames currently in memory.
*)
PROCEDURE UnloadDataFrame(VAR dataframeident: ARRAY OF CHAR);
(*
UnloadDataFrame unloads just the single data frame with
identifier dataframeident. If dataframeident is the
empty string, a dialog is offered to enter the string at
run time. If the routine was successful dataframeident
returns the data frame identifier of the actually dropped
data frame.
*)
(******************************************************************)
(*##### Display (show) data frames and value definitions #####*)
(******************************************************************)
(*
Note, some of the following routines offer an editing
dialog for its parameters if the actual argument is the
empty string. Yet, internally the module remembers the
last edited identifier, hereby making the data entry for
the user more convenient. Thus, you can call any of these
routines each time with an empty string and still have the
last entered data there for editing, e.g. to correct a
typo etc. Yet, you can use the returned identifier in any
subsequent code to perform some action in addition to what
DatFraViewer did already, which may involve the identifier.
*)
(*----------------------------------------------*)
(*===== Data Frame Specific Operations =====*)
(*----------------------------------------------*)
PROCEDURE ShowDataFrames;
PROCEDURE ShowDataFramesRemarks;
(*
List all currently in memory stored data frames.
ShowDataFrames shows all basic data, ShowDataFramesRemarks
shows partially the same basic information like
ShowDataFrames, but shows mainly just the usually long remarks
of each data frame, which need most of the space available in
the viewer's window.
*)
PROCEDURE ShowValDefIdentifiers (VAR dataframeident: ARRAY OF CHAR);
(*
Lists for a specific data frame denoted by dataframeident
(see module DataFrames) all the identifiers it provides
for value definitions as currently available. If
dataframeident is the empty string, a dialog is offered
to enter the string at run time. dataframeident serves
as an in/out parameter and returns the identifier the
user has edited.
*)
(*--------------------------------------------*)
(*===== Individual Value Definitions =====*)
(*--------------------------------------------*)
PROCEDURE ShowValueDefinition (VAR ident: ARRAY OF CHAR);
(*
Lists for a specific value definition given by ident (see
module DataFrames) its hosting data frames and its
history of redefinitions as currently stored in memory.
If ident is the empty string, a dialog is offered to
enter the string at run time. ident serves as an in/out
parameter and returns the identifier the user has edited.
*)
PROCEDURE RetrieveValue (VAR ident: ARRAY OF CHAR; VAR forType: ValDefType;
VAR sepChar: CHAR;
VAR retrValue: ARRAY OF CHAR);
(*
Lists for a specific value definition given by ident (see
module DataFrames) and its type forType its actual values
as currently stored in memory. If ident is the empty
string, a dialog (calls EditSimpleRetrieveMethod) is
offered to enter the string at run time. ident serves as
an in/out parameter and returns the identifier the user
has edited. sepChar is a in/out parameter and specifies
which retrieval method is to be used in case forType is a
string or identifier (see module DataFrames procedures
GetSs vs. GetSVec and GetIds vs. GetIdVec, sepChar = 0C
=> GetSVec or GetIdVec is used instead of GetSs or
GetIds, respectively). retrValue returns the retrieved
values found, in case of vector retrieval separated by a
delimiting character (see parameter sepChar of routine
SetPreferences this module).
*)
PROCEDURE RetrieveSpecialValue (VAR ident: ARRAY OF CHAR; VAR forType: ValDefType;
VAR specRetrMeth: SpecialRetrieveMethod;
VAR subKeyIdent, retrValue: ARRAY OF CHAR);
(*
Lists for a specific value definition given by ident (see
module DataFrames) and its type forType its associated
data as requested by specRetrMeth. If ident is the empty
string, a dialog (calls EditSpecialRetrieveMethod) is
offered to enter the string at run time. ident serves as
an in/out parameter and returns the identifier the user
has edited. In case specRetrMeth is getSubKeyCol
subKeyIdent (also in/out) denotes the identifier of the
column holding the sub keys. retrValue returns the
retrieved values found, in case of vector retrieval
separated by a delimiting character (see parameter
sepChar of routine SetPreferences this module).
*)
PROCEDURE EditSimpleRetrieveMethod (VAR ident: ARRAY OF CHAR;
VAR retrMeth: SimpleRetrieveMethod;
VAR okeyed: BOOLEAN);
(*
Generally applicable utility which offers a dialogue to
edit the identifier ident and to choose a retrieval
method retrMeth as exported by module DatFraAux for all
methods falling within SimpleRetrieveMethod. retrMeth
serves as an in/out parameter. okeyed returns wether the
user accepted the editing by pressing 'OK'. This routine
is used by procedure RetrieveValue from this module.
*)
PROCEDURE EditSpecialRetrieveMethod (VAR ident: ARRAY OF CHAR;
VAR retrMeth: SpecialRetrieveMethod;
VAR forType: ValDefType;
VAR subKeyIdent: ARRAY OF CHAR;
VAR okeyed: BOOLEAN);
(*
Generally applicable utility which offers a dialogue to
edit the identifier ident and to choose a retrieval
method retrMeth as exported by module DatFraAux for all
methods falling within SpecialRetrieveMethod. forType
returns the value definition type the user has chosen.
subKeyIdent returns the identifier of the subky column
chosen by the user. All parameters, i.e. ident,
retrMeth, forType, and subKeyIdent (except okeyed), serve
as in/out parameters. okeyed returns wether the user
accepted the editing by pressing 'OK'. This routine
is used by procedure RetrieveSpecialValue from this module.
*)
(*********************************************************************)
(*##### Customization of the data frame viewer's appearance #####*)
(*********************************************************************)
(*-------------------------------------------*)
(*===== Controlling Viewer's Output =====*)
(*-------------------------------------------*)
PROCEDURE OpenDataFrameViewer;
(* Opens the data frame viewer's window *)
PROCEDURE IsDatFraViewerOpen(): BOOLEAN;
(*
Returns whether the data frame viewer's window is currently open
*)
PROCEDURE ClearDatFraViewer;
(*
Clears the content of the data frame viewer's window.
*)
TYPE
OutMReadyProc = PROCEDURE(): BOOLEAN;
(*
Type of procedures required to test whether any output producing
routines of this module, such as ShowDataFrames etc., can actually
make the output and to redirect the output to that media.
*)
PROCEDURE IsDatFraViewerReadyForOutput(): BOOLEAN;
(*
Is of type OutMReadyProc and returns the same value as
IsDatFraViewerOpen, i.e. if data frame viewer's window is
currently open, but, as a side effect, this routine makes this
window also ready to receive output by calling
DMWindIO.SelectForOutput(data frame viewer's window). Given
data frame viewer's window is actually open,
IsDatFraViewerReadyForOutput diverts any subsequent DMWindIO
output to this window. The main routines such as ShowDataFrames
of this module allow for redirecting their output. A typical routine
which redirects output to another window as that window offered by
this module, can be easily implemented as this:
VAR
myOutWindow: Window;
PROCEDURE MyWindowIsReadyForOutput(): BOOLEAN;
VAR myOutWindowExists: BOOLEAN;
BEGIN
myOutWindowExists := WindowExists(myOutWindow);
IF myOutWindowExists THEN
SelectForOutput(myOutWindow)
END(*IF*);
RETURN myOutWindowExists
END MyWindowIsReadyForOutput;
NOTE: All following procedures make some output, e.g. to report
on the success of the operation to the user or to show the
results of the operation. The output is always directed to a
medium and will be suppressed in case that medium is not ready
to receive output. This module uses by default
IsDatFraViewerReadyForOutput to determine whether any output is
possible. Use routine InstallWriteProcs (described below) to
redirect the output and to provide your own OutMReadyProc.
*)
(*-------------------------------------------*)
(*===== Redirecting Viewer's Output =====*)
(*-------------------------------------------*)
PROCEDURE CaptureOutputOnFile(VAR pfn: ARRAY OF CHAR);
PROCEDURE StopOutputCapturing;
(*
Captures all output generated by routines from this
module also on a file (until StopOutputCapturing is
called) with the name pfn (may contain a path). If pfn
is the empty string the standard file saving dialog is
offered first before a file is opened. Upon returning
from this routine pfn contains the path and file name the
user has specified. If the dialog has been cancelled,
the empty string is returned. Note, calling
ClearDatFraViewer will discard the entire file content
and make the file ready for rewriting (calls
DMFiles.Rewrite). Be aware also of the fact that file
capturing occurrs in addition to the currently installed
set of writing procedures (see InstallWriteProcs below).
After a call to StopOutputCapturing the original set of
writing procedures present before the call to
CaptureOutputOnFile is restored. IMPLEMENTATION
RESTRICTION: Calling InstallWriteProcs interrupts the
capturing process.
*)
TYPE
WriteVarStringProc = PROCEDURE (VAR ARRAY OF CHAR);
WriteProc = PROCEDURE (CHAR);
PROCEDURE InstallWriteProcs(omrp: OutMReadyProc;
wvsp: WriteVarStringProc; wp: WriteProc;
wln,clear: PROC);
PROCEDURE GetCurWriteProcs(VAR omrp: OutMReadyProc;
VAR wvsp: WriteVarStringProc;
VAR wp: WriteProc; VAR wln,clear: PROC);
(*
Allows to install or retrieve, respectively, a set of writing
procedures. These procedures are the only ones by which the output
routines such as ShowDataFrames etc, from this module produce
output. omrp is the routine used to test whether the output medium
is ready. Note, that these tests are only made a few times, usually
at the beginning of the output producing routines (for efficiency
reasons). By using InstallWriteProcs it is possible to divert the
output e.g. to a file. The default set is
InstallWriteProcs(IsDatFraViewerReadyForOutput,
WriteVarString, Write, WriteLn, Reset);
all routines are from module DMWindIO except for
IsDatFraViewerReadyForOutput (from this module) and Reset, which
is implemented as follows:
PROCEDURE Reset;
BEGIN
EraseContent; SetPos(1,1)
END Reset;
Again, Reset uses only routines from DMWindIO. WriteVarString is
used instead of WriteString for efficiency reasons only. Note, in
case the currently installed procedure omrp returns FALSE, no output
is generated. Hence, if you wish to silently direct output to a file
(without any other output concurrently displayed in a window), pass
to InstallWriteProcs as actual argument for omrp a procedure similar
to this one:
VAR
myCaptureFile: TextFile;
PROCEDURE MyFileIsReadyForOutput(): BOOLEAN;
BEGIN
RETURN IsOpen(myCaptureFile)
END MyFileIsReadyForOutput;
IMPLEMENTATION RESTRICTION: GetCurWriteProcs has to be used
carefully, i.e. if two callees using this module use
GetCurWriteProcs to save a current set of writing procedures and both
try to restore the previous situation in a non-nested sequence, the
resulting behavior of the software may become unpredictable. Thus,
ensure that Get - Install calls are made in exactly matching pairs,
in particular be aware also, that CaptureOutputOnFile and
StopOutputCapturing use also such a sequence.
*)
(*-------------------------------*)
(*===== Viewer's Window =====*)
(*-------------------------------*)
PROCEDURE CloseDatFraViewerWindow;
(*
Closes the window of the data frame viewer
*)
PROCEDURE PlaceDatFraViewer(x,y,w,h: INTEGER);
(*
Allows to place the data frame viewer's window at a
location and with a size different from the defaults,
which fills a big portion of the main screen in its
middle. x,y denote the lower, left corner of the outer
window frame, w and h specify the width and height of the
outer window frame. If the window is already open,
PlaceDatFraViewer moves and resizes the window, otherwise
the window remains closed (use OpenDataFrameViewer to
open it). The position defined by this routine will be
remembered and always stored as part of the permanent
preferences.
*)
PROCEDURE GetDatFraViewerPlace(VAR x,y,w,h: INTEGER);
(*
Returns the current position of the data frame viewer's
window
*)
(*--------------------------------------------*)
(*===== Viewer's Preferences & Modes =====*)
(*--------------------------------------------*)
PROCEDURE EditPreferences;
(*
Offers a dialogue to edit the current preferences of the
data frame viewer. If the editing is finished by
pressing 'OK', values will be remembered and stored as
part of the permanent preferences of the package (see
also routine SetPreferences).
*)
PROCEDURE GetPreferences(VAR traceLoadMode, autoShowMode, showHistoryMode,
showLegendsMode, showFiltersMode: BOOLEAN;
VAR sepChar: CHAR; VAR decDig: CARDINAL);
PROCEDURE SetPreferences(traceLoadMode, autoShowMode, showHistoryMode,
showLegendsMode, showFiltersMode: BOOLEAN;
sepChar: CHAR; decDig: CARDINAL);
(*
Lets you control the current preferences. The values
will be remembered and stored as part of the permanent
preferences.
*)
(*----------------------------------*)
(*===== Data Frame Filters =====*)
(*----------------------------------*)
PROCEDURE EditFilters;
PROCEDURE GetFilters (VAR fromFilter,tillFilter: ReadingFilter);
PROCEDURE SetFilters (fromFilter,tillFilter: ReadingFilter);
(*
Edits, returns, or sets, respectively, the reading
filters to be used by the data frame viewer during
loading of data frames (see routine
LoadDataFramesFromAnchor from this module). The values
will be remembered and stored as part of the permanent
preferences.
*)
PROCEDURE EditReadingFilters(VAR fromFilt,tillFilt: ReadingFilter;
VAR oKClicked: BOOLEAN);
(*
Generally applicable utility which offers a dialogue to
edit any reading filters. The parameters fromFilt and
tillFilt serve as in/out parameters. oKClicked returns
wether the user has cancelled or actually accepted the
dialog by clicking the OK push button.
*)
(*----------------------------------------*)
(*===== Data Frame Viewer's Menu =====*)
(*----------------------------------------*)
PROCEDURE EditDatFraViewerShortCuts;
(*
Offers a dialogue to edit the keyboard short cuts used by
the data frame viewers menu commands. If the editing is
finished by pressing 'OK', values will be remembered and
stored as part of the permanent preferences of the
package.
*)
PROCEDURE GetMenuShortCuts(VAR openAlCh, closeAlCh,
loadAlCh, unloadAlCh,unloadAllAlCh,
showDFsAlCh, showRemsAlCh,
showIdentsAlCh, showValDefAlCh,
retrValAlCh, retrSpecAlCh, clearAlCh,
captOnFAlCh, stopCaptOnFAlCh,
editFiltAlCh, editPrefsAlCh, editAlChsAlCh: CHAR);
PROCEDURE SetMenuShortCuts(openAlCh, closeAlCh,
loadAlCh, unloadAlCh,unloadAllAlCh,
showDFsAlCh, showRemsAlCh,
showIdentsAlCh, showValDefAlCh,
retrValAlCh, retrSpecAlCh, clearAlCh,
captOnFAlCh, stopCaptOnFAlCh,
editFiltAlCh, editPrefsAlCh, editAlChsAlCh: CHAR);
(*
Above procedures lets you control the keyboard short
cuts used by the data frame viewers menu commands.
GetMenuShortCuts is typically used if you wish to modify
only a few of the keyboard shortcuts in a GetMenuShortCuts
(openAlCh,... ; SetMenuShortCuts (openAlCh,... sequence.
The values will be remembered and stored as part of the
permanent preferences. The characters are used as alias
characters for the commands (see above) as follows:
openAlCh - OpenDataFrameViewer
closeAlCh - CloseDatFraViewerWindow
loadAlCh - LoadDataFramesFromAnchor (with empty string)
unloadAlCh - UnloadDataFrame (with empty string)
unloadAllAlCh - UnloadDataFrames
showDFsAlCh - ShowDataFrames
showRemsAlCh - ShowDataFramesRemarks
showIdentsAlCh - ShowValDefIdentifiers (with empty string)
showValDefAlCh - ShowValueDefinition (with empty string)
retrValAlCh - RetrieveValue (with empty string)
retrSpecAlCh - RetrieveSpecialValue (with empty string)
clearAlCh - ClearDatFraViewer
captOnFAlCh - CaptureOutputOnFile (with empty string)
stopCaptOnFAlCh - StopOutputCapturing
editFiltAlCh - EditFilters
editPrefsAlCh - EditPreferences
editAlChsAlCh - EditDatFraViewerShortCuts
*)
PROCEDURE DatFraViewerMenu(): Menu;
(*
Returns the data frame viewer's window menu in order to
customize the menu by installing additional commands in
this menu, e.g. by using routines from DMMenus. Note,
it is also possible to remove the returned menu, but
still use the data frame viewer's window.
*)
(*--------------------------------*)
(*===== Factory Settings =====*)
(*--------------------------------*)
PROCEDURE ResetDatFraViewer;
(*
Reverts the effect of any previous customization, e.g.
by PlaceDatFraViewer call etc. The values will
be remembered and stored as part of the permanent
preferences.
*)
END DatFraViewer.
RAMSES
Modules:
A-Z
Function
Layer
QuickRefs:
DM
AuxLib
AuxLibE
SciLib
EasyMW
MW
ISIS
RMSLib