Oberon/ETH Oberon/Tutorial/GadgetsIntro

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 to Gadgets

---

[ Text | Contents | Index | Master index]

Tutorial objective

Introduce you to the Oberon System 3 graphical user interface (GUI) named Gadgets. The notions of visual and model gadgets are presented. Then gadgets such as panels, documents and desktops are described.

Estimated time: 60 minutes.

Introduction

Gadgets is a graphical user interface management system for Oberon System 3. It consists of a set of end-user objects for building graphical user interfaces. This construction process is done at run-time, hence end-user objects. These end-user objects are called gadgets. Gadgets range from typical dialog elements like buttons and check boxes, to more complicated ones like text and drawing editors. Not only do you have the possibility of using applications that have been built with the Gadgets system, but you can also build your own graphical user interfaces from the provided parts. Also, should the provided gadgets not fulfill your needs, you may program your own, either by extending existing ones, or by building completely new ones. You may also borrow parts from other applications.

Technically, a gadget is a user interface component of varying granularity. For example, a line or a figure in a drawing is a gadget, just as the drawing itself is a (composite) gadget. Later on, we shall introduce the term container gadget to express this. Each gadget knows a well-defined communication protocol that allows it to act as an independent functional unit with a life of its own, and it can be integrated into any environment that provides the communication protocol to it. Gadgets can flow along in text, they may be integrated into panels (somewhat equivalent to windows in other systems) or be used in a page layout system. As they are active objects, their editors are built-in, allowing them to be edited or used where they appear. Each gadget instance behaves in its own special way. However, all of them follow a set of guidelines that are already well-known to Oberon users. Most important, they respond to certain mouse clicks and to keyboard input.

Gadgets classes

There are several gadget classes in the Oberon System 3. The gadget class determines what role the gadget plays in the system, its appearance and its behaviour. We shall now review of a few of them, starting with some of the more interesting visual gadgets, followed by the somewhat more abstract model gadgets. The entire collection of gadgets provided with this Oberon System 3 delivery is reviewed in Using Gadgets. Other important gadgets such as panels, documents and desktops are introduced in later chapters.

Visual gadgets

A visual gadget is represented on your screen by a graphical symbol, most often with a 3-dimensional look (see the button below), which serves as communication agent between you and your computer. In addition, such an agent will demonstrate a simple behaviour when solicited by mouse clicks. Oberon introduces a new way to interact with your computer.

Button

A button can be pressed and released by clicking the middle mouse key on it. Try it now. The button is pressed, displays a rectangular red mark simulating an LED and pops back to its original state when the key is released. Clicking on the button causes the execution of an Oberon command, if so defined. The caption should (preferably) denote the button's function or action.

Alternatively, a button can be defined as a toggling button with two states. In that case the button must be clicked twice for cycling through the two states.

Check box

A check box is very similar to a toggling button but it has no caption and the two states are identified by the presence or the absence of a check mark. Try that with a middle mouse key click. Clicking on the check box causes the execution of an Oberon command, if so defined.

Slider

A slider is used to set a (hidden) numerical value depending on the relative position of the knob which is positioned by dragging on the middle mouse key. The minimum and the maximum values are part of the slider's specification (also hidden).

When the slider is manipulated an Oberon command is executed, if so defined.

List

A list displays a set of strings in alphabetical order without duplicate, as is the case here. Alternatively, the list may be left unsorted in which case duplicate entries are allowed. The control and the behaviour of a list is not so simple anymore compared to that of a button or a check box.

Clicking the left key anywhere in the list focuses the list: a vertical line appears at the left margin. When focused, quick positioning in a longer sorted list is achieved by typing a few initial characters. The list is scrolled to the effect that the list item with matching initial characters is positioned on the first line. Hitting the return key clears the typed word. Also when focused, a selected text may be copied into the list with a right and middle key interclick. In a sorted list, new items are inserted in alphabetical order and are unique. In an unsorted list, new items are inserted at the end of the list.

Clicking the right key on a list item selects it. Clicking again on the selected item deselects it. Dragging on the right key upward or downward extends the selection to several consecutive items. The list will automatically scroll forward or backward if need be. Clicking on a non-selected item starts a new selection. Scrolling may also be controlled with the scroll bar, if present.

Clicking the middle mouse key on a list item causes the execution of an Oberon command, if so defined.

Text field

A text field allows the editing of a single line of text. The focus point is set with a left key click. The text field enters then a local editing mode and full swung Oberon text editing capabilities are available. As soon as the cursor is removed (e.g. when pressing the Esc key) or the Return key is pressed, this local editing mode is left. This is made visible by the changing 3D aspect of the field.

Pressing the Return key causes the execution of an Oberon command, if so defined.

Controlling gadgets with the mouse

One of the interesting and novel aspects of gadgets is that they can be changed in size and position, in addition to being used, from creation onwards until they are eventually explicitly locked by the user. This is in contrast to other systems where the user receives his user interface locked, and must "take it or leave it". A significant part of a Gadgets system user's time is spent organizing and building new user interfaces. In this section we explain how interactive composition of gadgets is done at run-time.

Basic mouse key actions

Visual gadgets are, with a few exceptions, rectangular in shape. The rectangular area that a gadget occupies can be conceptually divided into a control area, a few pixels wide on the inside border, and an active area. The width of the control area varies according to the size and the state of the gadget.

When the mouse focus is located in one or the other of these areas, the gadget responds to mouse events differently.

In the active area, the gadget normally adheres to the Oberon conventions or stays close to them; that is, if you already have a good practice of controlling text with the mouse, you will immediately recognize the similarities so that controlling gadgets will soon be a child's play.

■ _ _ Point key: set the caret, the insertion point for a new gadget. Placing the caret in a gadget is called focusing a gadget. There is only one focused gadget at any one time.
_ ■ _ Execute key: a button is pressed, a check box is toggled (checked/unchecked), a slider moved, etc. If a Cmd attribute is defined, that command is executed.
_ _ ■ Select key: select a gadget. A selected gadget is covered by a white semi-transparent pattern.

Try those three single key clicks to convince yourself:

Set the caret in the panel and execute the command Gadgets.Insert Clock ~.

Special attention should be paid to the use of the right mouse key:

• Several gadgets located in the same container may be selected in succession. The group of selected gadgets becomes the selection.
• Pressing that key and dragging causes a spanning rectangle to appear. All the gadgets entirely contained in this rectangle become selected: the group also becomes the selection. This is similar to selecting a text.
• Clicking in an empty area clears the selection.
• Clicking on a selected gadget deselects it.

Exceptions: some gadgets can be selected only when the mouse focus is positioned in the control area. That is the case for panels, name plates, text fields and text gadgets (except for the scroll bar at the left). For the latter three, in the active area the selection operates on the contained text.

Finally, remember this:
■ ■ ■ neutralize the click or interclick.

Copying and deleting the selection

□ _ ■ select gadget(s) and delete the selection.
_ □ ■ select gadget(s) and copy the selection over to caret.
■ □ _ set the caret and copy the selection to caret.

Practice with the gadgets in this panel:

The selection is often the target of Oberon commands and reacts to middle mouse clicks as explained below.

Some gadgets do not respond to all of these mouse key clicks.

Moving and resizing a gadget - MM key

Depending on where the mouse focus is located in the control area, the middle mouse key is interpreted differently: the sides are used to move the gadget and the corners to change its size. Thus, placing the mouse focus:

_ ■ _ on a side and dragging on the middle key moves the gadget (the mouse pointer changes into a grabbing hand). Movement is restricted to the current container and may be rejected when attempting to move the gadget completely out of its current container.

_ ■ _ in a corner and dragging on the middle key resizes the gadget (the mouse pointer changes into a hand with a pointing index).

In both cases when the key is released, the new location or size is set.

Practice resizing and moving with the three gadgets in this colored panel:

You can easily verify the existence of the control area (or its absence) by slowly moving the mouse across a gadget whilst clicking the middle mouse key repeatedly. The control area is absent if the gadget cannot be resized or moved as described.

Movement to another container can only be done with an explicit left or right key interclick as described below.

Moving and copying a gadget - Drag-and-drop with MM key

When moving a gadget, i.e. grabbing it by its side, if at the end of the mouse movement you interclick with the:

□ ■ _ left key: the gadget is moved to a new container at the mouse focus or when it remains in the current container, it is brought to the front of overlapping gadgets.
_ ■ □ right key: a copy of the gadget is inserted at the mouse focus (in the same or in a different container).

Practice with the three gadgets in this colored panel:

Moving a gadget from one container to another is called a consume operation. The new container consumes the gadget and the gadget is removed from its old location. Not only is this used to move an object from one panel to another, but also to provide a general drag-and-drop facility. The consumer (called the receiver or recipient) may interpret the drop event in different ways: it may either absorb the consumee (which is called the sender or initiator) as a descendant (like most containers do), or it may initiate some other event. For example, a trash can may delete the file gadgets that it consumes, or a compiler may compile source texts. Some (receiver) gadgets may execute a user-defined command on a consume event. The Icon gadget is such a receiver.

Moving and copying the selection: an alternative way

When a gadget is selected, the control area is extended to the entire area covered by the gadget and it has the same functionality as the borders.

There exists an alternative way to move or to copy the selection: press the middle mouse key on any selected gadget and drag the selection to a new location. If more than one gadget was selected, a rectangle spanning all the gadgets appears. An interclick with the left or the right mouse key has the same meaning as for a drag-and-drop operation.

Gadget locking

A flexible mechanism exists that allows the user to lock a gadget and so prevent inadvertent changes to a gadget.

A locked container such as an iconizer, a note book or a panel cannot be resized. It can be moved with the middle mouse key when the mouse focus is positioned anywhere in the control area and it can be selected with a right move click anywhere in the gadget.

Most application interfaces are supplied locked, but they can be unlocked at any time to be customized to the user's requirements or personal taste.

Model gadgets

A model gadget stores a data value useful to an application. It is quite simple in structure and behavior and it cannot visualize itself on the display. The Gadgets system only provides a limited set of model gadgets that can store the basic Oberon data types namely BOOLEAN, LONGINT, LONGREAL and string (ARRAY 64 OF CHAR).

To visualize the value stored in a model gadget the help of a visual gadget like the ones presented above is required. This is the well-known Smalltalk Model-Viewer-Controller framework ( MVC). The model gadget contains the data vizualised by a visual gadget.

In practice, several visual gadgets can show the value of the same model gadget - an example in given below. Each view ensures that it remains consistent with the model it represents. We also say that the visual gadget is linked to a specific model gadget.

The idea behind a model gadget is that it can easily be manipulated by an Oberon program. In return, the visualization of the model is updated accordingly without the application program knowing that or how many such linked visual gadgets exist. This allows application programmers to insulate code against changes made to a user interface.

You should however clearly understand that many visual gadgets (those described earlier are only a small subset of them) are programmed in such a way that they can also function without being linked to a model gadget.

Boolean

Stores a BOOLEAN value. It may be linked to a button or a check box.

Integer

Stores a LONGINT value. It may be linked to a button, a check box, a slider or a text field.

Real

Stores a LONGREAL value. It may be linked to a slider and a text field.

String

Stores an ARRAY OF CHAR of up to 64 characters. It may be linked to a slider or a text field.

Some concrete examples

Radio buttons

Select a channel

Here are three radio buttons. Like the buttons on a radio or TV tuner, clicking on a radio button selects only one of several (here 3) mutually exclusive options. When an option is selected its associated LED is lit.

This effect is obtained by linking the set of radio buttons to a single integer gadget. Each button is given the specification of an integer value, and when the model gadget has that value, that button appears pressed.

Check boxes as radio buttons

Red	Green	Blue
			Select a color

Here is another form of radio buttons using check boxes. In this mode, the check mark is replaced by a rectangular mark.

Here also, this effect is obtained by linking the set of check boxes to a single integer gadget. Each check box is given the specification of an integer value, and when the model gadget has that value, that box is checked.

A model gadget with two views

Here is an example of a gadget constellation where a slider and a text field are both linked to the same integer model gadget. The two visual gadgets act as views of the same invisible object. Behind the scene, things are organised as follows:

Changing the position of the slider cause the integer gadget to be updated accordingly, which in turn causes the text field to be informed that the value of its model has changed. No programming is required to obtain this effect. It suffices to specify the gadgets and their linking.

Now, look at this similar example in which the integer gadget's value is manipulated by a (very simple!) program capable of only just incrementing and decrementing that value by 1. You can observe that by clicking on either blue triangle.

Extending the set of model gadgets

Typically application programmers would add their own model gadgets according to their needs. This requires programming. For example, it is often useful to construct compound models that store more than one data value. The only such compound model that is delivered with the standard gadget collection is the complex gadget which stores the real and the imaginary parts of a complex number. The source code for this gadget is supplied in the module Complex.Mod and an example of its use in an application is given in the module Lissajous.Mod.

Panel

A panel is a two-dimensional organizer of gadgets. It may be regarded as a sheet of paper, on which gadgets are organized in a two-dimensional fashion. The gadgets contained inside a panel are called descendant gadgets or its descendants and the panel itself is called the ancestor or also the context of any of these descendants. It is also adequate to categorize a panel as a container gadget. Since a panel is itself a gadget, panels may appear inside panels, nested to any depth.

A panel also supports operations on groups of descendant gadgets and operations providing for an optimal layout and alignment of its descendants. A snapping grid allows easy positioning of descendants. These can be aligned to the same baseline, height, size, or width, or organized vertically and horizontally. Operations on panels can be activated from the tools in the Gadgets.Panel. This panel is a user interface for creating and manipulating gadgets.

The descendants are organized in priority and may overlap each other. A descendant generally keeps its current priority after being moved. Oberon commands put a gadget behind or in front of other gadgets. Newly inserted gadgets are always placed in front. The simplest way to bring a gadget to the front is to pick it up and consuming it again (Middle + left mouse key interclick).

Mouse commands on panels

Mouse events in panels are, with a few exceptions, consistent with what has been said before about gadgets. A right key dragging ending with a middle key interclick makes a shallow copy of the selection and copies it over to the caret position.

Here is what is handled differently.

When the panel is not locked:

□ ■ □ Execute key: recognized by a descendant gadget when the mouse focus is positioned on it and without effect elsewhere in the active area.
□ □ ■ Select key: recognized only when the mouse focus is positioned in the control area.

When the panel is locked:

□ ■ □ Execute key: recognized by a descendant gadget when the mouse focus is positioned on it and without effect elsewhere in the active area.
□ □ ■ Select key: may be clicked anywhere to select it.

A locked panel cannot be resized, and it can be moved with the middle mouse key when the mouse focus is positioned anywhere in the control area.

Panel with a model gadget

A panel may be linked to a model gadget. In that case the panel is not used as a viewer of the model gadget but rather as a placeholder for important data which is then usually represented by descendants.

Document

Definition

A document is a named collection of gadgets that can be stored to and loaded from disk in one atomic action. Look at the name plate at the top left corner of this document: it's name is "GadgetsIntro.Book". The disk file is given the same name as the document.

Documents can be opened and displayed in the well-known, familiar Oberon viewer system. In addition, documents can be inserted (i.e. opened) in what we call a 'desktop' as will be explained in the next chapter.

A document usually presents itself with a menu bar containing often used commands related to that document, e.g. 'Close', 'Search', 'Store', etc., and a name plate . This appearance is familiar to Oberon users. Alternatively, a document can be inserted on the desktop without a menu bar.

Document type

Documents have a primary type that is determined by the root frame they consist of. For example, there are text and panel document types. The document may contain further sub-frames of any type. Each document is stored in a file and can be reconstructed/loaded from disk by the document manager when just the file name is known. The document is self-contained and knows enough about itself to load, store and print. The main advantage is that the user need not know which application program is needed to open a certain document.

The document type is determined by what is called the document New procedure when a new document is opened (see below) which is also recorded in the file when the document is stored. This information is used again when the document is opened. Here is a correspondence table 'Document New Procedure' to 'Document type':

TextDocs.NewDoc	Text document
PanelDocs.NewDoc	Panel document

Open an empty document - Desktops.OpenDoc

Desktops.OpenDoc "("documentNewProcedure")" opens an empty, unnamed document of the specified type and inserts it in the desktop.

Try this Desktops.OpenDoc (PanelDocs.NewDoc) . Watch the name plate: it is empty.

Open an existing document - Desktops.OpenDoc

Desktops.OpenDoc fileName opens the document fileName. If a document with that name has previously been stored, it is loaded and the document is inserted in the display space. Otherwise, an empty document of a certain type is created. The type is implicitely determined by the file name's suffix:

.Text	Text document
.Panel	Panel document
.Pict	Picture document
anything else	Text document

Open and recast an existing document - Desktops.OpenDoc

Desktops.OpenDoc fileName "("documentNewProcedure")" does the same as above and attempts (not always successful) to cast the original document to a new type.

Insert an existing document at the caret - Desktops.InsertDoc

Desktops.InsertDoc fileName opens the document fileName. If a document with that name has previously been stored, it is loaded and the document is inserted in the display space at the caret, without a menu bar. Otherwise, an empty document is opened. The document type is determined by the rule described earlier for Desktops.OpenDoc.

Replace an existing document - Desktops.ReplaceDoc

Desktops.ReplaceDoc fileName replaces the document from which the command is executed with another document fileName. If a document with that name has previously been stored, it is loaded and it substitutes itself to the current document. Otherwise, an empty document is opened. The document type is determined by the rule described earlier for Desktops.OpenDoc. An in-place switching of documents takes place.

Example of application: this command is frequently used in the tool documents supplied with the system, such as Desktops.Tool, Programming.Tool, etc. The command is used there in the hypertext links such as [ Desktop ], [ Applications ], etc.

Store the marked document - Desktops.StoreDoc

Desktops.StoreDoc * stores the marked document in a file whose name is taken from the document's name plate. If executed from the document itself, the document from where the command is executed is implied. The document must then not necessarily be marked and the * parameter is also not required. The file is stored in the current directory. If a file with that name already exists, it is renamed: the suffix '.Bak' is appended to its original name.

Print the marked document - Desktops.PrintDoc

Desktops.PrintDoc printerName * prints the marked document on the named printer.

With the DOS version, you may choose between the name of a printer server or LPT1, LPT2, etc.

In Oberon for Windows, the printerName parameter is IGNORED and the default printer, defined in the Windows Print Manager, is used to print the document. Also, in Oberon for Windows, printing is indicated by a reverse video mouse pointer until the document has been placed on the printer queue.

In the MacOberon version, you may choose between the printer names QuickDraw, PostScript and EPS. QuickDraw prints to the printer selected in the chooser, PostScript generates a postscript file and EPS an encapsulated postscript file.

If executed from the document itself, the document from where the command is executed is implied. The document must then not necessarily be marked.

Recall a document - Desktops.Recall

Desktops.Recall reopens the last closed document in the desktop in which the command is executed. The document is opended in the state it had when it was closed and it is placed in the center, but if the star-shaped marker is set first, the marker focus determines the top left corner if the document.

Selection in a document

As indicated before, a document acts as an invisible "wrapper" for the main gadget it contains. To distinguish a selection of the main gadget from that of the wrapper a two-phase selection is used. Clicking with the right mouse key in the main gadget's control area selects it (appears in white), while a second click selects the document (appears in blue); that is, gadgets are selected in an inside-out manner and are identified by their color.

Desktop

Definition

A desktop is a named work surface on which documents and a variety of other gadgets are organised in a two-dimensional fashion with overlapping objects. Look at the name plate at the top left corner of this desktop: it's name is most probably "Oberon.Desk". A desktop can be stored to and loaded from disk in one atomic action. The disk file is given the same name as the desktop. This certainly reminds you what has been said earlier about documents.

When a desktop is stored, only the layout of the work surface is recorded: the documents on the desktop are not stored, these have to be stored explicitely by the user. Later on the same desktop can be reloaded and recreated from the recorded information.

In this way a user can create many different work environments that are suited to the task at hand and to the display resolution available. Similarly, several users may share the same computer and open their personalised desktop. Like any other file, a desktop can be ported to other computers.

Open a desktop - Desktops.Open

Desktops.Open fileName opens a desktop fileName. If a desktop with that name has previously been stored, it is loaded and inserted in the display space. Otherwise, a new default desktop is created. Normally Gadgets uses the same strategy to place the desktop as Oberon's Edit.Open to place a viewer, i.e. in the user track. However, you can override this preference and indicate where the desktop should appear by placing the star-shaped marker. The desktop is placed in the track of the pointer and its top edge will be at the height of the pointer.

Layout and properties

A desktop presents itself as an Oberon viewer without menu bar. Although the menu bar is absent, it can be resized: positioning the mouse focus in a narrow invisible area at the top and pressing the left key cause a thick blue horizontal line to appear, telling you that a tracking mode has been entered. Dragging on the left key will determine the new top position in the track. On release of the key, the top edge moves to the height of the mouse focus and the desktop content is redrawn. The range of movement is restricted in the same manner as it is for Oberon viewers.

If the middle mouse key is interclicked while dragging, the desktop may be placed anywhere on the display. In particular, it may be relocated across track boundaries. That may of course only be the case in a hybrid (Oberon - Gadgets) display layout.

Try this Desktops.Open YourNewDT .

You have just realised that the display surface may contain more than one desktop at a time: a desktop is also a (container) gadget. In such a layout, gadgets and documents may be moved or copied across desktops.

Grow a desktop - Desktops.Grow

Desktops.Grow enlarges the desktop in which the command is executed. The desktop grows to cover the whole track in which it appears, or if it already fills a track, it grows to cover the whole display.

Copy a desktop - Desktops.Copy

Desktops.Copy opens a copy of the desktop in which the command is executed. The copy displays the same data as the original desktop It is a clone).

Close a desktop - Desktops.Close

Desktops.Close collapses or removes the desktop in which the command is executed.

Store a desktop - Desktops.Store

Desktops.Store fileName stores the desktop in which the command is executed in a disk file with the specified name, i.e. the name appearing in the name plate. If a file with that name already exists, it is renamed: the suffix .Bak is appended.

Change the backdrop - Desktops.ChangeBackdrop

Desktops.ChangeBackdrop picturefileName change the backdrop of the marked desktop. Use the name of a non-existing picture to reset the backdrop.

View

A view is a camera view with a variable perspective on a gadget which cannot easily be presented in its entirety on the display surface. Such may be the case with a large drawing. A second view of the same visual gadget could also show a different part of the same drawing. Even multiple views may be constructed: any of them may be edited since they all represent the same base gadget.

Original picture	Scaled view #1	Scaled view #2

Behind the scene the situation is comparable to what you have experienced with the model with two views but here the model is a visual gadget (a picture).

Pressing the middle key when the mouse focus is positioned inside one of these views causes a spanning rectangle to appear showing the real dimension of the object being viewed. Dragging on that key in any direction causes the rectangle to move. When the key is released, the new view is drawn. The picture used here is named "Default.Pict" and is included in this Oberon System 3.

A view is also a gadget and views may be nested. A view may be empty, that is displays nothing. Dropping a gadget inside an empty view makes the view display the consumee.

    

The last example on the right shows a camera view of a panel with a button. The viewpoint can be changed by picking the panel by its border and dragging it a new location.

What's next?

Acquire a deeper knowledge in the use and the composition of gadgets and get to know an extended collection of gadgets in Using Gadgets.

Learn how to manipulate gadgets from within Oberon programs in Using Gadgets from within Oberon.

If you had liked to develop your own gadgets learn all about it in Programming new Gadgets.

Index

[ A | B | C | D | E | G | L | M | P | R | S | T | V ]

---

A

active area
ancestor

B

Button

C

check box
complex gadget
consume operation
container
context
control area
copy selection

D

delete selection
descendant
Desktops.ChangeBackdrop
Desktops.Close
Desktops.Copy
Desktops.Grow
Desktops.InsertDoc
Desktops.OpenDoc
Desktops.Open
Desktops.PrintDoc
Desktops.Recall
Desktops.ReplaceDoc
Desktops.StoreDoc
desktop
Desktops.Store
document New procedure
document
drag-and-drop
drag-and-drop

E

end-user objects

G

gadgets
graphical user interface

L

link
list
lock

M

menu bar
model gadget
Model-Viewer-Controller
mouse key actions
move
MVC

P

panel

R

radio button
radio button
resize

S

slider
Smalltalk

T

text field

V

view
view
visual gadget

---

Revised on July 6, 1996
Installed on 30 05 1997