The StarView -> TycoonLanguage Manual

This document describes how to write your own GraphicalUserInterface in Tycoon based on the StarView class library.

Contents :

Prerequisites for this Manual
The basic elements of a StarView application
C++ classes vs. TL modules
Writing own TL modules
StarView method calls and equivalent TL function calls
Libraries
The resource compiler

Special features

Prerequisites for this Manual

This manual assumes:

basic knowledge about StarView, C++ and Tycoon-Language.
a directory named "src/svenv_examples" which contains examples from the StarView2.0 manual (chapter2 Tutorial) translated into TL.

2. The basic elements of a StarView application:

An application can have different kinds of windows, but one window is the 'application window', the main window of the application. If this window is destroyed, the whole application terminates. You create an 'application window' using a constructor of the ADT workWindow.T and the stylebit WB_APP.
Look at example2 (module 'myWin2'):
```
let win = workWindow.new2(..... window.WB_APP))
```
After creation, initialization, and starting of the event loop (application.execute, see below point iii) ) the window is made visible by the method "window.show(...)".
Look at example2 (module 'example2'):
```
let main(argv :Array(String)) :Int =
  begin
    let aMainWin = myWin2.new()
    .
    .
    .
    window.setText(aMainWin.win "StarView Paint")
    window.show(aMainWin.win)
    application.execute()
  end
```
Event-handlers
Each event, e.g. user input, changes of the application window, appearance of an error, causes StarView to call an event handler and give the user a chance to react to the event. He can start certain actions, according to the demands of his program. This can be accomplished by installing handlers, which are called after starting the event dispatcher. There are two possibilities:
- The handlers are principally virtual methods and can be overridden in a derived class. The overriding of virtual methods is a C++ language concept. The methods are overridden per class, in TL per object. To simulate overriding in TL, the methods with "set" and "get" are used.
- Via the class link (a mechanism provided by StarView).
The first possibility is generally used for virtual methods of the window class, from which most user defined classes are derived.
Look at example2 (module 'myWin2'):
```
window.setMouseButtonDown(t.win ...) :Ok 
	begin               ^
	 .                 | obj.
         .
         .
	end
```
The second possibility is made for handlers of such classes, from which the user does not necessary derive a class (e.g. buttons, scrollbars etc).
```
let colorSelect(win :T pMenu :menu.T) :link.Handler = 
  fun() :Ok
    begin
     .
     .
     .
    end
```
After some initialisations the method main calls application.execute, which enters the StarView event loop by a C-call. If an event happens, e.g. a mouse click at a menu, the corresponding callback to TL is invoked. Typically this TL-function contains some C-calls to StarView. The method systemWindow.close (or respectively a click upon the quit button at window's menu) stops the event loop, and application.execute returns. By means of the X-server the graphic will be refreshed after an event has happened and the callback is done.

3. C++ classes vs. TL modules
StarView provides numerous C++ classes with many methods. In TL, these classes are represented as modules. In TL the names of classes (modules) and methods are equivalent to the corresponding StarView classes and methods, except the classes menu, menuBar and popupMenu, which depend mutually recursive on each other. In TL these classes are collected in the module menu, because modules cannot be recursive.
4. Writing own TL modules
TL is a modular language. For good transparency, it is helpful to use one module for each class.
Classes in TL are represented by tuple types.
Look at example2 (module 'myWin2'):
Let T = Tuple win :workWindow.T var nColor :Int var nWidth :Int var aLastPoint :point.T end
An extract of the interface MyWin2 :
T <:Tuple win :workWindow.T end

5. StarView method calls and equivalent TL function calls
Look at example3 (module 'example3'):
StarView method calls :

aMenuBar.InsertItem(MID_FILE, "~File"); aFileMenu.InsertItem(MID_ABOUT, "About...", MENU_APPEND, MIB_ABOUT); aColorMenu.InsertItem(MID_PENRED, "Red", MENU_APPEND, MIB_CHECKABLE);
Equivalent TL function calls :

menu.insertItem(aMenuBar mid3.FILE "~File") menu.insertItem2(aFileMenu mid3.ABOUT "~About..." menu.MENU_APPEND menu.MIB_ABOUT) menu.insertItem2(aColorMenu mid3.PENRED "~Red" menu.MENU_APPEND menu.MIB_CHECKABLE)
As you see:
In StarView the object appears first and then the method with its parameters is declared.
obj.maximize(...)
In TL the class appears first followed by the method with the first parameter object followed by other parameters.
window.maximize(obj ...)

6. Libraries
Modules have to be collected in a Library.
Look at library svenv_examples:

library svenv_examples import . . . with interface Mid2 MyWin2 module mid2 :Mid2 myWin2 :MyWin2 example2 :Main . . . end;

7. The resource compiler
By using resources it is possible to modify an existing program without recompilation. You only have to bind the resource module to the application. Resources are used principally for applications with a large number of menus, dialogboxes and controls. The source code of the main program can be left unchanged when changing data in the resource. The program does not have to be compiled, because the resources are compiled seperatly with the resource compiler.
The resource modules for your StarView application can be produced interactively by the StarView-Design-Editor . There are two ways to use the Design-Editor (StarView user manual, chapter 5 p.135):

with WABI

with Unix

Hints for using 'designed' withWABI.
Command :
wabi designed.exe

Save your DOS-Files

Translate the DOS files into Unix files.
Shell command :
dos2unix <originalfile> <convertedfile>

Translate the hrc file into a TL file
Command (TL function):
rsc.makeTLFiles(hrcFileName, moduleName, interfaceName,
lib :String sccs :Bool)

Call the resource compiler
Command :
rsc <filename.src>

With Unix:
Command :
designed

Translate the hrc file into a TL file
Command (TL function):
rsc.makeTLFiles(hrcFileName, moduleName, interfaceName,
lib :String sccs :Bool)

Call the resource compiler
Command :
rsc <filename.src>

There is an example how to use the Design-Editor (StarView2.0 manual chapter 5 p.189)
8. Special features

Attention!!! By clicking 'Quit' at the window's menu you leave the TL main loop!
If you do not want to leave the TL main loop append the method systemWindow.close to a special button.
Look at example3 (module 'myWin3'):

let aBox = queryBox.new(win.win int.bitOr(window.WB_OK_CANCEL window.WB_DEF_OK) "Exit Paint") if messBox.execute(aBox) == messBox.RET_OK then systemWindow.close(win.win) else false end

StarView-help : > svhelp /opt/sv/bin/sv.hlp &

I. Hachmann (02-feb-94)