(*
https://web.archive.org/web/20041227180027/http://www.oberon.ethz.ch:80/ethoberon/defs/Viewers.Def.html
*)
DEFINITION Viewers; (* portable *)

(*
The module viewers provide the data type for implementing the tiled viewers

of the Oberon system. Each track of the Oberon system consists of a number of
viewers.
*)
 IMPORT Display;

 TYPE
  Viewer = POINTER TO ViewerDesc;
  ViewerDesc = RECORD ( Display.FrameDesc ) 
   state: INTEGER;
         (* state > 1: displayed
      state = 1: filler
      state = 0: closed
      state < 0: suspended.*)
  END;

 VAR 
  curW: INTEGER; (* Current width of the logical display. *)
  minH: INTEGER; (* Minimum viewer height. *)

 (* Open a new viewer V with top at Y in track X. *)
 PROCEDURE Open (V: Viewer; X, Y: INTEGER);

 (* Expand or shrink a viewer vertically to new top Y. *)
 PROCEDURE Change (V: Viewer; Y: INTEGER);

 (* Remove viewer V from the display. *)
 PROCEDURE Close (V: Viewer);

 (* Recall most recently closed viewer. *)
 PROCEDURE Recall (VAR V: Viewer);

 (* Return viewer located at display coordinates X, Y. *)
 PROCEDURE This (X, Y: INTEGER): Viewer;

 (* Return next upper neighbour of V in a track. *)
 PROCEDURE Next (V: Viewer): Viewer;

 (* In the track at X locate the following viewers: filler fil, bottom-most
viewer, an 
 alternative viewer alt of height >= H, and the viewer with the maximum height.
*)
 PROCEDURE Locate (X, H: INTEGER; VAR fil, bot, alt, max: Display.Frame);

 (* Append to the current logical display and init track of width W and height
H, and install filler. *)
 PROCEDURE InitTrack (W, H: INTEGER; Filler: Viewer);

 (* Open new track overlaying span of [X, X +W[. *)
 PROCEDURE OpenTrack (X, W: INTEGER; Filler: Viewer);

 (* Close track at X and restore overlaid tracks. *)
 PROCEDURE CloseTrack (X: INTEGER);
END Viewers.

(* Remarks:

1. Each track consists of a filler and a set of viewers linked together in a
ring 
(with the next field) with the filler as sentinel. The filler is the top-most
viewer 
in a track and covers the remainding part of the track the viewers do not cover.

The set of tracks form the root objects of the display space.

2. Tracks can overlay each other. Closing a track exposes the track (and viewers)

lying below it. Overlayed tracks and viewers do not receive message broadcasts

in the display space. Before being overlayed, the contents of a track receive
a 
Display.ControlMsg with id set to suspend.

3. The logical display increases from X coordinate 0 onwards through multiple

physical displays. Opening a new display involves adding a tracks beyond curW

(typically a system and user track). Oberon uses a single coordinate system
to 
address all the different displays. Note that many Oberon systems restrict the

size of the display to the size of the host window.

4. Changing the top coordinate of a viewer with Change results in a 
Display.ModifyMsg with id set to reduce or extend (in size) being sent 
to the viewer contents (located in V.dsc).

5. The ratio of user and system track width is 5:3.

6. Programmers seldom need to use the Viewers module. Higher level modukes 
like Documents provide a simpler display abstraction.

*)