[Oberon] Documentation request

[frey at inf.ethz.ch]

The following small piece of documentation is new in this release. It is on the user level. 

If you want to do Programming on the GUI, there is WMScribble.Mod as an introduction to basic window handling 
(independant of the component system).
For the new component system you might check ComponentViewer.Mod together with FractalDemo.Mod and
Notepad.Mod as simple examples. For more complex examples, search for "WMComponents" in *.Mod.

--Thomas


Tutorial

User Guide

The Graphical User Interface (GUI) of the Bluebottle System is at the same time similar and different from other windowing systems. Nowadays most computer users are well trained to use a mouse for clicking buttons, selecting text and performing drag and drop operations to move items such as windows and texts around the virtual desktop. Since the Bluebottle GUI is similar in this respect, not much needs to be introduced to basic manipulations and working with the system.

There are mainly two main reasons why the Bluebottle GUI implements many features common to most other recent GUI systems. First, these features are well known to most of todays computer users and hence ease the problems inherent to learning a new system. Second, many of these features have been selected and evolved for up to twenty years and proved their usefulness.

While sticking to known metaphors and interfaces can reduce user's fear of learning a new system, it can also lead to a drop in innovation and hence prevent the emergence of novel interface methods. Therefore, the Bluebottle GUI combines a selection of features from many "worlds" and adds some new ones, too. It is for instance. possible to start commands from any place in a text. Also any text is compatible to any other text in the system. The classic Oberon GUI has earned some fame for its unique features in the Human Computer Interaction (HCI) community (see Raskin, The Human Computer Interface). 
Some elements of the classical Oberon GUI have been discarded or adapted to increase the acceptance with the users e.g. no "Interclicks" are needed in the new GUI elements. The tiled display was abandoned in favor of a windowing system. The introduced windows support free shapes and translucency (semi-transparency). In this respect, the Bluebottle GUI surpasses many existing windowing implementations. Windows can moved, rescaled etc. while the programs "behind" the windows keep running. 

	Desktop Navigation using the keyboard and the mouse
		Meta-Mouse-Wheel : zoom in/out
		Meta-Mouse-Move : pan the viewport if the mouse hits the border of the screen
		Meta-PgUp : zoom in 2x
		Meta-PgDn : zoom out 2x
		Meta-Home : All desktop elements visible
		Meta-End : zoom to 1:1
		Meta-Left : Move viewport left by one screen in the current zoom factor
		Meta-Right : Move viewport right by one screen in the current zoom factor
		Meta-Up : Move viewport up by one screen in the current zoom factor
		Meta-Down : Move viewport down by one screen in the current zoom factor
		
		Alt-Shift is a substitute for the Meta key. (The meta key is often marked with symbol that is associated with big software vendor)
		
	The Main Menu
		Ctrl-Esc : Move the main menu to the current screen
		The menu is created using a number of MenuPage??.XML files, where ?? is a two digit decimal number corresponding to the page position in the menu.
		 00, 10, 20, ... 90 are reserved for the release
		Use any other number for a custom design page. 
		It is easiest to open an existing menu page and to edit it according to one's need.
		Example: Notepad.OpenUTF8 MenuPage10.XML ~    <-- the blue marked text is a command. You can click it with the middle mouse button to execute !
		
	Text Editors
		Mouse Commands: 
			Navigation
				Positioning the text cursor : Place the mouse cursor in the text and click the left mouse button
				Mouse-Wheel : Scroll up/down
				Alternatively, the scrollbar can be used for scrolling.
			Selection
				Place the mouse cursor at the beginning of the intended selection, press (and keep pressed) the left mouse button, move the mouse cursor 
				to the end of the intended selection, release the left mouse button
			Drag and Drop
				Select some text (see above), klick into the selected text with the left mouse button. Keep the button pressed and move the mouse to
				the position where to drag the text. If you want a copy to be dragged, keep the keyboard CTRL key pressed.
			Starting Commands
				Position the mouse cursor to a command, then click with the middle mouse button. Make sure command's parameters are delimited with the ~ character.
				OK : WMTT.Open ~  WMTT.Open alone is not encouraged.
				Since many commands can run in parallel, the parameters need to be copied before execution. 
				Although a command  works even without delimiter, it is a waste of memory.
			Copying a text style
				Select the text you want to apply the new style to. Hold down the Alt-key and click into a piece of text that contains the desired style.
				The text where the format is copied from needs to have the keyboard focus, so that it can detect the Alt-key being pressed.
			
		Key Commands :
			Navigation
				Left, Right : move the text cursor left and right by one char. 
							Press the CTRL modifier key to move word by word
				Up, Down : Move the cursor one line up or down 
				PgUp, PgDn : Move cursor one visible page up/down
				Home, End : Begin or end of line.
							Press the CTRL-key to jump to the begin or end of the text
				SHIFT : The SHIFT modifier key can be combined with all the navigation keys above to navigate and select at the same time 
				CTRL-C	(or CTRL-INS) : Copy selection to clipboard	
				CTRL-V	(or SHIFT-INS) : Paste clipboard
				CTRL-X	(or SHIFT-DELETE) : Cut (= copy to clipboard and delete text)
			
			Starting Commands
				Position the text cursor on a command. Press CTRL-Enter. See Starting Commands in the mouse commands for details.  

			Indentation 
				Select the text to indent and then press Alt-Left or Alt-Right to indent the selection
				
			Macros
				Macros are invoked by pressing the Ins key while the cursor is placed behind a macro name.
				Macro parameters are separated by ":"
				Some helpful macros :
					name:M						MODULE ...
					name:P						PROCEDURE ...
					classname:O 				TYPE classname = OBJECT ...
					classname:superclassname:o TYPE classname = OBJECT(superclassname) ...
				output macros: oi, os, oc take one identifier parameter
					e.g. identifier:oi	AosOut.Int(identifier);
					ol	output line takes no parameters
				debug macros: di, ds, dc, dr take one identifier parameter
					e.g. identifier:ds	AosOut.String("identifier = "); AosOut.String(identifier);
				XML macros:
					name:t	<name></name>
					similar:T

				The macros are defined in:
					Notepad.OpenUTF8 Macros.XML ~
					
		Input Method Editors
			Currently there is only a rudimentary Pinyin Input Method Editor available. It can be installed in with WMPinyinIME.Test ~ 
			After it is installed, press CTRL-Space in any editor to enable/disable the input method editor.
			To automatically load the WMPinyinIME, edit the AosConfig.XML ( Notepad.OpenUTF8 AosConfig.XML ~ )
	
	Other Functions
		Storing the desktop
			In the System menu, press the Mark (mark a waypoint) button to store the state of the programs on the desktop (not all programs support
			saving their state)
			
		Reboot the system 
			Ctrl-Alt-Del (terminates the system and reboots without warning !!!)
			
		Backdrop images
			Backdrop images can be added at any place and in any size on the virtual desktop. Clicking on a backdrop will zoom the backdrop to fullscreen.
			Backdrops can be removed by clicking them with the right mouse button and selecting Remove.
			Hint: Try not to put too many backdrops at the same position on the virtual desktop
			To make the backdrop permanent, you can just save store the desktop by pressing the Mark button in the System menu
		
		Window Styles
			The window style can be changed in the Style menu. To make a style permanent, enter the corresponding command in the AosConfig.XML Autostart section.
			
Programming
		The programming environment is called PET the "Programmer's Editing Tool"
		PET.OpenUTF8 HelloWorld.Mod ~
		
		Press the Compile button to compile the current module file. 
		Errors appear at the bottom of the window. Click on an error to position the cursor at the corresponding position in the source text..
		
		To find a position of a Trap, select the the number ???? behind PC=???? in the kernel log. Then press the find PC.
		If no PC position is selected, PET will ask
		
		The left part of the window gives a structural overview over your program. 
		Click into the tree to position the cursor at the position of the clicked structure in the program text.
		
		To free a module, call S.Free HelloWorld ~
		
Installation
		To install the system, start Oberon and open AosInst.Tool. Follow the instructions.

Miscellaneous
		Bluebottle contains lots of tools, some did not find into the system menu.
		e.g:
			AosTV	:		A TV Application for BT848 compatible TV cards. ( Notepad.OpenOberon AosTV.Tool ~ )
							(an improved release will follow about end of April 2004, check the crazy release)
			Sound :			Currently supported sound cards: 
								Aosi810Sound.Install ~  (Intel/Realtek compatibles)
								EnsoniqSound.Install ~ 
								AosYMF754.Install ~ (Yamaha)

			MP3Player : 	See PET.OpenOberon MP3Player.Mod ~
			OGGPlayer :		Check the crazy release end of April 2004
			
			Network : 		Currently supported network cards:
								AosRTL8139.Install ~
								Aos3Com90x.Install ~
								AosIntel8255x.Install ~
							Check: AosNet.Mod, AosIP.Mod, AosUDP.Mod, AosDNS.Mod, AosTCP.Mod
								
			Webserver: 		HTTP/1.1 plugin enabled multi host webserver.  See PET.OpenOberon WebHTTPServer.Mod ~
			FTP-Server:		See PET.OpenOberon WebFTPServer.Mod ~ 
			
			USB	: 		Support for Mouse and many storage devices. 
							The system is bootable from some usb sticks.
							See AosUsb.Mod, AosUsbUhci.Mod, AosUsbStorage.Mod, AosUsbMouse.Mod
			
			Firewire : 		Check the crazy release end of April 2004

			ARM/XSCALE : If you are interested in the ARM/XSCALE ports write an email to ask at bluebottle.ethz.ch (check the website before ! ;-) )
			
		and many more... you have the source... have fun!