# Oberon/ETH Oberon/Tutorial/Applic

These tutorial pages were written by André Fischer (afi) with editorial assistance of Hannes Marais, were hosted at the ETHZ and remain under the ETH license. Related content is found in the system via Book.Tool. Extended content is also available on paper. Some tutorial pages are in the WayBack archive.

## Introduction

A collection of applications, more precisely system extensions, is distributed with this release. These applications are, in principle, contained in archive files located in the APPS sub-directory of your current Oberon System 3. If the latter is named "OBERON", use System.Directory C:/OBERON/APPS/* ~ to list of them. Thus, in order to run them they must be installed first.
In the following we shall:
* pass the applications in review
* propose an installation procedure for running an application on a temporarily basis (look and feel) until it is discarded without leaving foot prints or until it is adopted as valuable system extension in your production environment.

## Applications review
### ASCIITab

Components: Desktops.OpenDoc ASCIITab.Arc.
You can use an ASCII character table to insert into documents extended characters not found on most keyboards. These include accented characters, appearing in some country alphabets, aswell as special characters provided in symbol fonts such as Math12.Scn.Fnt for example.
This module's main function is to create a visual gadget representing a table of 8 rows by 32 columns containing the printable characters of the 256 8-bit combinations, as they are defined in Oberon. The visual gadget generator is ASCIITab.NewFrame. Inspection with Columbus, reveals that it has a Name and a Font attribute.

#### Running the application

* Set the caret at an appropriate place where to insert the table.
* Insert the table with Gadgets.Insert ASCIITab.NewFrame ~. The character set of Syntax10.Scn.Fnt is displayed by default.
Clicking any table element with the middle mouse key inserts the represented symbol at the caret (if the latter is set, of course).
The font can be changed by modifying the font name in the table's Font attribute

### Oberon desktop Calculator

Components: Desktops.OpenDoc Calc.Arc.
The Calculator is controlled by a set of Oberon commands edited in any suitable Oberon text viewer: text gadget, text document. The results are displayed in the system log. The Calculator is an old application created by cas back in 1993.

#### Running the application

* Open the Desktops.OpenDoc Calc.Tool to display a few examples of operations that can be performed with the calculator.
* Exercise the examples and observe the results in the system log.
* Edit your own operations in the viewer of your choice and execute them.

#### Calculator operations

The calculator is controlled with the following commands:
Calc.Reset - resets the calculator and removes all the user defined variables which have been defined by Calc.Set commands.
Calc.Set name := expression ~ - assigns the value of the expression to a named local variable.
Calc.List - lists the functors (as a reminder or a help function), the value of pi and e, and the name and the value of the used defined variables.
The next four commands all take an expression as argument. The syntax of the expression is defined by the following syntax:
All operators are left-associative, except "^" which is right-associative.
Calc.Char expression ~ -
Calc.Dec expression ~ -
Calc.Hex expression ~ -
Calc.Real expression ~ -

### Games

Components: Desktops.OpenDoc Games.Arc.
This Oberon System 3 distribution includes a collection of three card games: Solitaire, Spider and Freecell, and four further games: MineSweeper, Scramble, Sokoban and Tetris. They are described in Games.

### HP Calculator - Version 1.2

Components: Desktops.OpenDoc HPCalc.Arc.
The HP Calculator is still being developed and improved.

#### Running the application

* Open the Desktops.OpenDoc HPCalc.Panel.
* Use the calculator intuitively like any other hand-held HP calculator using the reverse Polish notation. Note however, that the input text field in the lower left corner is a genuine text field gadget which can be manipulated according to the Oberon System 3 principles.

#### Calculator operations

The calculator is controlled with the following buttons:

### Remote printing

Components: Desktops.OpenDoc LPRPrinter.Arc.
The remote printer is controlled by a set of Oberon commands edited in any suitable Oberon text viewer: text gadget, text document.

#### Running the application

* Open the Desktops.OpenDoc LPRPrinter.Tool to display a few examples of operations that control remote printing.
* Edit your own operations in the viewer of your choice and execute them.

#### Printer operations

Remote printing is controlled with the following commands:
LPRPrinter.Install - Install the printer driver. Instead of installing the printer driver just when needed, adding this command to Configuration.Text file installs it right from the start.
Desktops.PrintDoc queue@host * - Print the marked document on the specified queue on the specified host, e.g. lph1@lillian or "lph1-ds@lillian".
LPRPrinter.PrintPSFile queue@host ps-file - Print the postscript file on the given queue.
LPRPrinter.ShowJobs queue@host - List all waiting jobs on queue.
LPRPrinter.RemoveJobs queue@host [jobno] ~ - Remove job jobno from the specified queue on the specified host. If no number is given all jobs are removed.
LPRPrinter.BannerPage (on | off) - Switch banner page printing on or off. Printing is on by default.
LPRPrinter.MailBack (on | off) - Switch the sending of an e-mail message when the printer job completes on or off. Message sending is off by default.

### Picture to PostScript Converter

Components: Desktops.OpenDoc PS.Arc.
The ~PS tool creates a PostScript file from an Oberon picture file.

#### Running the application

The module PS exports a single command which is documented in the PS.Tool and is described below.
PS.PictToPost fileName [\[a][e][r][l | p]] [scaling] ~ converts the named Oberon picture file (suffix .Pict) and creates a PostScript file with suffix .ps. The options, which may be specified in any order, are:
* a - create an A3 page
* e - create an EPS (Encapsulated PS) file
* r - use run-length encoding
* l - landscape format
* p - portrait format (default)
The scaling factor is 1 by default.

### Text lines sorter

Components: Desktops.OpenDoc Sort.Arc.
The text lines sorter sorts the lines, terminated by a carrier return, contained in a file or in an open document, and displays the result in a new document viewer. This function has a number of limitations:
* the maximum length allowed is 256 characters, including the terminating CR
* the maximum number of lines allowed is 2000
* gadgets floating in the text are treated as single characters
* fonts, text color and vertical offset are not retained
If any of the above limits is exceeded, a trap will occur.

#### Running the application

The module Sort exports a single command which is documented in the Sort.Tool and is described below.
Sort.Sort (fileName | * | ^) [\[e][r][u]] ~ sorts the lines of the named file and displays the resulting text in a document viewer "Sorted.Text". The total number of lines sorted is dispalyed in the system log. The options, which may be specified in any order, are:
* e - include empty lines containing only blanks or tabs.
* r - sort in reverse order
* u - keep unique lines only, that is, discard duplicate lines

### Converter of Oberon V4 text file - WTS

Components: Desktops.OpenDoc WTS.Arc.
Interesting Oberon extensions developed by users of the Oberon V4 system are regularly published and made available on quite a few FTP sites. If you wish to benefit of these developments as well, here are the instructions for installing valuable Oberon V4 material on your System 3 system.
Among the files that you may find in an FTP directory are a number of Oberon V4 text files. Since their names have the same .Text or .Mod extension as are used in System 3, there is no way to distinguish them at first sight. The *.Text files have been created with the V4 word processor and contain fonts, colors, pictures and other text control elements. The directory path or an eventual ReadMe file may however hint at V4. In any case you have to convert those text files with the WTS facility which is delivered as an archived application which must be installed first. Verify with System.Directory WTS* ~.
The module WTS exports a single command which is documented in the WTS.Tool and is described below.
WTS.Convert fileName [\[s][b]] converts the named Oberon V4 text file to an Oberon System 3 text file. The fonts are also converted while the color and vertical offset of the text is retained. In addition, if the option \s is used the Elems included are converted to corresponding gadgets, that is:
* FoldElems to Outline gadgets (Outlines.New) using WTSFold.Mod
* GraphicElems to their BasicFigures elements (line, rectangle, circle, spline) using WTS.Draw.Mod
* PictElems to pictures (Pictures.NewPicture) using WTSPict.Mod
* StampElems to TimeStamp gadgets (TimeStamps.New) using WTSStamp.Mod
* ParcElems and StyleElems to TextStyle gadgets (TextGadgets.NewStyleProc). The source document may however not contain more than 48 (Text) styles.
If the option \b is used, the original file is renamed to a .Bak name.
Exercises:
Access ftp://nuchem.nsrl.rochester.edu/pub/Oberon/B2Project/ and download in binary with FTP.Get. Extract AnnualReport96.Text. Convert with WTS.Convert AnnualReport96.Text \bs and open the final document AnnualReport96.Text.
If you do not have a working V4, you can still download Postscript files from this directory describing the B2 project architecture, status, etc.
Another example to convert is module ftp://nuchem.nsrl.rochester.edu/pub/Oberon/Goodies/B2Out.Mod .

### Font Editor

Components: Desktops.OpenDoc Win.FontTools.Arc.
Read the description in Font Editor User's Guide.

### PolyWorlds

Components: Desktops.OpenDoc Win.PolyWorld.Arc.
PolyWorlds is a tool for fast display of polygon worlds, i.e. three-dimensional scenes consisting only of polygonal surfaces.

#### Poly panel

A standard panel called "Poly.Panel" is provided which can be opened as a document in the Gadgets environment of the Oberon System 3. On its right side is the currently displayed polygon world, on its left side are several standard interface elements.
World Data A list of available scenery files is located in the lower left corner. Clicking one of the entries with the middle mouse key (MM) will load and display the corresponding scene. On slower machines, you may have to wait for several seconds until the new scene gets drawn, depending on its complexity. The list of names is updated whenever the Show button is activated.
World [Clear] empties the current world.
[Statistics] prints the current number of shapes, points and polygons to the system log.
The Horizon check box enables or disables the display of a horizon.
View [Reset] returns to the default view, where the observer is located at the origin, looking along the negative z-axis.
[Align] rotates the current view until the local coordinate system of the selected shape is aligned with the camera coordinate system. The local coordinate system is the coordinate space in which the shape was defined before being transformed to world space.
[Benchmark] shows a fixed sequence of camera views and prints the duration of the animation, in number of ticks and the approximate time in seconds, to the system log.
Movements Pressing the left mouse key (ML) inside the frame box where the world is displayed invokes the current navigator. The navigator will process mouse and keyboard inputs until the mouse key is released, mapping those inputs to changes of the current view. There are two navigators to choose from:
[Planar] is the default navigator and is active after opening the panel. As long as ML is pressed, the camera is rotated left and right according to horizontal mouse movements. Vertical mouse movements affect the current speed. The keyboard keys 'a' and 'z' move the observer up and down.
[Flying] activates a simple flight model. Mouse movements affect pitch and roll of a virtual airplane. Forward speed is controlled by the keyboard keys 'a' and 'z'.
Field of View The slider as well as the text field below may be used to modify the camera's focal distance, allowing to zoom in or out. The text field displays the opening angle in degrees of the camera's view frustrum.
Clicking the right mouse key (MR) when the mouse arrow points at an object displayed in the current view selects the indicated object (also called shape). A new color for the selected shape may be chosen with a ColorPicker, and its attributes may be inspected and modified using Columbus. The model assigned to the shapes (and to the frame itself) may also be inspected and shows attributes not particular to a single object, such as sky and ground color.
Some shapes possess an attribute "Cmd", which may be set to any Oberon command. The command is activated by clicking over the corresponding shape with the middle mouse key.

#### Creating Polygon Worlds

Polygon Worlds can be created using a simple text editor. PolyWorlds is distributed along with several example scenes, which may serve as a tutorial introduction on scene generation. The following EBNF rules define the PolyWorlds grammar.
Comments start with "#" and reach until the end of the line.A more detailed description of the commands can be found in E. Oswald, PolyWorlds, Diplomarbeit am Institut für Computersysteme, ETH Zürich, 1994.

### Snapshot tool

Components: Desktops.OpenDoc Win.Snapshot.Arc.
A snapshot captures the bitmap contained in the specified Oberon display frame (a viewer, a document, a visual gadget or even the entire screen) and transforms it into a picture object displayed in a Rembrandt frame. Its facilities are very useful for documenting Oberon system extensions. However, you should rather insert active documents in your documentation (Desktops.InsertDoc docName), instead of captured, static pictures. Snapshot is an extension of the Rembrandt tool.
Warning: Remember that the desktop has four quadrants: if the captured frame is not entirely visible on the current quadrant, the picture will be blurred.

#### Snapshot commands

The following three commands are used to make a snapshot of the marked visual object.
Snapshot.Viewer * opens a Rembrandt document named "Snapshot" displaying a snapshot of the marked viewer.
Snapshot.Document * opens a Rembrandt document named "Snapshot" displaying a snapshot of the marked document.
Snapshot.Gadget * opens a Rembrandt document named "Snapshot" displaying a snapshot of the marked gadget.
The next three commands are used to insert a snapshot of the marked visual object at the caret.
Snapshot.InsertViewer * inserts a Rembrandt frame displaying a snapshot of the marked viewer at the caret.
Snapshot.InsertDocument * inserts a Rembrandt frame displaying a snapshot of the marked document at the caret.
Snapshot.InsertGadget * inserts a Rembrandt frame displaying a snapshot of the marked gadget at the caret.
The last two commands are used to make a snapshot of the entire Oberon screen.
Snapshot.Screen opens a Rembrandt document named "Snapshot" displaying a snapshot of the entire screen. No color mapping is performed to ensure correct colors in the picture generated.
Snapshot.Screen2 opens a Rembrandt document named "Snapshot" displaying a snapshot of the entire screen. The colors are mapped to the current Oberon palette and the palette is stored with the picture.
Revised, 28 Nov 1996

## Correction notes for the files contained in the archives:

- Calc.Arc:
    Calc.Char "j" + 1 does not work as expected.
- Hex.Arc must NOT be installed - it is already installed. Redundant.
- HPCalc.Mod: the text at the end after END HPCalc must be revised:
    Calc is now HPCalc
    Calc.Input does not exist (Commentarized in the module text)
    MyBackup.Do does not exist but seems interesting; what is the parameter "always" ?
       .Scn.Fnt .Pr2.Fnt .Pr3.Fnt .Pr6.Fnt
    Syntax 8 8b 8i 8m
    Syntax 10 10b 10i 10m
    Syntax 12 12b 12i 12m
    Syntax 14 14b 14i 14m
    Syntax 16 16b 16i 16m
    Syntax 20 20b 20i 20m
    Syntax 24 24b 24i 24m
    Oberon 8 8b 8i
    Oberon 10 10b 10i
    Oberon 12 12b 12i
    Oberon 14 14b 14i
    Oberon 16 16b 16i
    Oberon 20 20b 20i
    Oberon 24 24b 24i
    Math 10
    Math 12
    Math 14
    Math 16
    Math 20
    Math 24
    Greek 10
    Greek 12
    Greek 14
    Greek 16
    Greek 20
    Greek 24
    Courier 8
    Courier 10
    Courier 12
    Math20.Pr3.Fnt is missing in the distribution.
    Math20.Pr6.Fnt & Math20.Pr2.Fnt are missing.
    Math24.Pr6.Fnt & Math24.Pr2.Fnt are missing.
    Courier12.Pr6.Fnt & Courier12.Pr2.Fnt are missing.
    There are no Greek_.Pr2.Fnt and Greek_.Pr6.Fnt.
- PS.Tool: the options l and p are not shown in the command syntax above.
    PS.Mod: Helv.ps does not exist - erase.
    Figure3.Pict does not exist, replace by Clown.Pict or delete everything after END PS.
    What are the lines
       (*PW = 576; PH = 792; *)
       PW = 580; PH = 820; (*dia*)
       pw0 = 550; ph0 = 800; (*laserwriter*)
       MaxN = 128;
    at the beginning? Only the second has a meaning!
- Inspectors.Arc:
    Libraries.Mod and Libraries.Panel must be renamed to avoid conflict with new version. New version must not be named Libraries2.
- Poly.Arc:
    What is GPakToPoly in TestEyePoly???
- Snapshot.Arc:
    What is Snaphot.Screen2 in Win.Snapshot.Mod? Not documented in Snapshot.Tool.
- PolyWorld.Arc:
    PolyWorlds.Text refers to the Inspector: replace by a reference to Columbus. There is no Directory button but a Show button in the panel.
- Hex.Arc:
    Wrong, old components are delivered (Hex.Mod and Hex.Tool). The new Hex.Mod also requires module ListRiders, which is not there!!
- Win.EditTools.Arc:
    Win.FontRes.Mod imports Log which is in Log.Arc. !!!
    Which component is only applicable to Windows?
    Win.FontRes.Mod or/and FontEditor.Mod????
Installed on 30 05 1997

## Index

A
Applications ASCII table ASCIITab.NewFrame
C
Calc.Char Calc.Dec Calc.Hex Calc.List Calc.Real Calc.Reset Calc.Set calculator: desktop calculator: HP
G
games
H
HP calculator HPCalc.Panel
L
LPRPrinter.BannerPage LPRPrinter.Install LPRPrinter.MailBack LPRPrinter.PrintPSFile LPRPrinter.RemoveJobs LPRPrinter.ShowJobs
P
Poly.Panel PolyWorlds PS converter PS.PictToPost PS.Tool
R
Remote printing
S
Snapshot.Document Snapshot.Gadget Snapshot.InsertDocument Snapshot.InsertGadget Snapshot.InsertViewer Snapshot.Screen2 Snapshot.Screen Snapshot.Viewer snapshot Sort.Sort Sort.Tool
T
text lines sorter
W
Write To Script WTS.Convert WTS.Tool WTS

## Footnotes

* 1 2 Create a B2 directory. Open https://riskfive.com/ and find two B2 links at the left margin. In "B2 overview" find the download link and retrieve the 7z archive into the B2 directory just created. Ascertain that 7z capability is available. In Linux Debian for example, the p7zip-full package is required. Unpack the archive with command "7z e B2_v086_cleaned.7z". Read README.txt.