DEFINITION MODULE DMWTextIO;
(*******************************************************************
Module DMWTextIO ('Dialog Machine' DM_V3.0)
Copyright (c) 1990-2006 by Andreas Fischlin, Olivier Roth and
ETH Zurich.
Purpose Saves a stream of characters of an arbitrary
length (text) to memory for later reference like
redisplay, transfer to the clipboard, or printing
(object can be mapped to a DMTextFields.TextSegment
if smaller than 32000 characters).
Remarks All DMWindIO character or string writing
routines (Write, WriteLn, WriteString,
Write(Long)Card, Write(Long)Int,
Write(Long)Real, Write(Long)RealSci) may be
used to produce text objects.
A text object belongs always to a particular
'Dialog Machine' window and in a particular moment
a window can own only a single text object.
This module belongs to the 'Dialog Machine'.
Programming
o Design
Andreas Fischlin 04/01/1990
Olivier Roth 04/01/1990
o Implementation
Andreas Fischlin 04/01/1990
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: 28/01/1990 AF
*******************************************************************)
FROM SYSTEM IMPORT ADDRESS;
FROM DMWindows IMPORT Window, RectArea;
VAR
TextIODone: BOOLEAN;
(*
Read only variable, which returns whether any of the
following procedures has been successful. E.g. if
enough memory is available, etc.
*)
PROCEDURE StartTextSave;
(*
Saves in memory all subsequent DM-Window character based output
in a textual data object associated with the current Dialog
Machine output window unless PauseTextSave or StopTextSave is
called. Any character processed by the procedures Write,
WriteLn (EOL=15C), WriteString, Write(Long)Card,
Write(Long)Int, Write(Long)Real, Write(Long)RealSci will be
accumulated, even those which might not be visible since they
are written outside a clip rectangle or beyond the current
window frame. Calling this procedure a second time will
silently discard any previously accumulated text. Note that the
text is stored in memory and text accumulation won't be stoped
unless PauseTextSave, StopTextSave is called or the window is
closed; hence don't forget to call any of these procedures in
order to avoid memory shortage. Note also that the end of line
character EOL saved is not 36C but 15C to be compatible with
Macintosh conventions, i.e. no translation is necessary to
transfer a text into the clipboard or take from there (see
also module DMClipboard).
*)
PROCEDURE PauseTextSave;
PROCEDURE ResumeTextSave;
(*
Temporarily stops or resumes the storing of character based output
*)
PROCEDURE StopTextSave;
(*
Definitly stops the storing of character based output and terminates
the stored text data structure with a 0C character.
*)
PROCEDURE DisplayText (ownerWindow: Window; destRect: RectArea; fromLine: LONGINT);
(*
Displays the text associated with the Dialog Machine window
ownerWindow onto the current Dialog Machine output window in
the destination rectangle destRect starting with line fromLine
at the top left corner of the rectangle destRect. If the text
contains long lines exceeding the width of the destRect, their
display will be clipped (no auto-wrap). The status of the text
in the owner window and in the destination window remain
untouched. In case there is currently a text or picture object
open (see also module DMWPictIO), note that the text will be
appended to the already existing text or picture of the current
output window. This mechanisms allows to transfer a text into a
picture and/or into a text object (different from
DMWPictIO.DisplayPicture).
*)
PROCEDURE DiscardText;
(*
Discard the text associated with the current output window
completely, and make the allocated memory space available for
other uses. Note that once discarded, it is no longer possible
to print the text, write it to a file, or transfer it to the
clipboard (s.a. DMPrinting.PrintText, DMPTFiles.DumpText, and
DMClipboard.PutTextIntoClipboard).
*)
(* --------------------------------------------------------------
The following routines make the text object of the current output
window available to the advanced programmer. A text object can
be of the type ARRAY [0..limit] OF CHAR, whereby limit must not
exceed 32000 (compiler implementation restriction). Consider such
an array as a window allowing to access a limited portion
(segment) of the actual text object.
----------------------------------------------------------------*)
PROCEDURE GrabWText(VAR txtbeg: ADDRESS; VAR curTextLength: LONGINT);
PROCEDURE ReleaseWText;
(*
These procedures allow to temporarily lock the text object in
memory to access its content via a data structure of the type
DMTextFields.TextSegment. This data structure is restricted to
32000 characters, since array indices are restricted by the
current compiler implementation. GrabWText returns current
address and size of the text object. Don't forget to call
GrabWText before actually accessing the object, since its begin
txtbeg might otherwise change (object is implemented as a
handle, which can move in memory). Warning: Do NOT forget to
release a text object before appending text by procedure
AppendWText or changing its length by procedure SetWTextSize.
*)
PROCEDURE AppendWText(txtbeg: ADDRESS; length: LONGINT);
(*
Append text block stored in memory at address txtbeg of length
length to the text object associated with the current
output window. Precondition is that StartTextSave and
ReleaseWText has been called for the current output window.
Note that all length characters contained in text block will be
appended regardless of an eventually present character 0C.
*)
PROCEDURE SetWTextSize(newTextLength: LONGINT);
(*
Sets the size of the text object associated with the current
output window to newTextLength regardless of its current
content. This allows to allocate a large memory block before
actually assigning the text or to deallocate the memory
currently in use (warning: if newTextLength is set smaller than
the current text length, the text portion beyond character
newTextLength-1 will be lost).
*)
END DMWTextIO.
RAMSES
Modules:
A-Z
Function
Layer
QuickRefs:
DM
AuxLib
AuxLibE
SciLib
EasyMW
MW
ISIS
RMSLib