ETHZ_Logo RAMSES_Logo_Right   RAMSES   RAMSES_Logo_Left Systems Ecology  
Start    search button      Modules:   A-Z   Function   Layer        QuickRefs:   DM   AuxLib   AuxLibE   SciLib   EasyMW   MW   ISIS   RMSLib

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.

  Contact RAMSES@env.ethz.ch Last updated: 25-Jul-2011 [Top of page]