Oberon/ETH Oberon/Tutorial/Columbus

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.

Columbus User's Guide

[ Text | Contents | Index | Master index ]

Objective

Learn how to obtain object and library information and also how to customize objects and manipulate the contents of public libraries with the inspection tool Columbus. Typical activities are: inspecting and modifying gadget attributes and adding new attributes. Columbus not only includes all the facilities currently provided by the Inspector and the DetailInspector, but goes well beyond that. Therefore, the latter tools will be phased out in the medium term.

Before you start reading this tutorial, you should be familiar with the Gadgets system and its components and you should have knowledge about the concept of attributes. To learn more about the gadgets refer to Using Gadgets. A very important thing to know is the use of RefGadgets. A description of the gadget and its use is at the end of the definition file RefGadgets.Def.

Before you start manipulating public libraries, you should be familiar with the concept of libraries used in the Oberon System 3.

Estimated time: 30 minutes.

Introducing Columbus

Welcome to

Columbus is a very versatile instrument that can be applied to any gadget (visual or model) for an inspection of its identity, attributes, links and properties. When applied to a specific gadget, the tool immediately adjusts its shape, so to represent an attribute form for this gadget. Note that this form is a document created by program, however. The tool can also be used to manage public libaries and their content.

In practice, Columbus presents itself in two different "variable geometry" documents (they however always fit in the system track). One of them is used to inspect and configure the state of objects and is called "Objects.Panel". The other one, called "Libraries2.Panel", is used for manipulating public libraries. Parts of the "Libraries2.Panel" are integrated in the object inspector. The "Objects.Panel" can directly be opened from the library editor.

Using the Object Inspector

First, press the Esc key, to make sure that all marks and selections are removed. The inspector panel is opened with the command Columbus.Inspect ~ .

The command is used here without parameter, but later on, you will learn that the name of an object may also be specified after the command. The command tries to locate a gadget to inspect: it can be either a marked (*) or a selected visual gadget. If no gadget can be found, as is the case now, a minimal empty panel document "Objects.Panel" is opened.

It contains only just the Columbus logo and a button captioned with a magnifying glass. This button is the inspect button and is used to inspect an object. We shall refer to it as [Inspect] button.

Move the panel to the system track of your display or to the side of your desktop, depending on your mode of operation. Now, select this panel -> and click on the inspect button. What you see now is the attribute view of the panel being inspected; this is evidenced by the little red LED in the button. But several other views can be accessed using the other buttons in the row. They will be presented and described in a subsequent section. The obj1 panel's attributes are presented with their values.

Select this button -> and click on the inspect button again. As you can see a new button appeared on the right of the inspect button. This button is used to go back one step in the panel's history. Click on the button and you return to the information of the previously selected panel.

In the top right corner you can see a visual reference, which represents the currently inspected object.

The characteristics and the function of this gadget are presented now.

Visual reference gadget

A visual reference gadget stores a reference to any object of type Objects.Object. This frame can have three different representations:

- when it does not refer to an object,

- when it refers to a visual gadget,

- when it refers to a model gadget.

The practical advantage of this gadget is that a reference represents an object irrespective of its type (visual gadget or model) and of its size. It can be dragged-and-dropped or copied over to another context just as easily as the object it represents.

A visual reference can be changed either by dropping a visual gadget into its frame or by copying over a selected visual gadget. Alternatively, a reference from another reference can be dropped or copied over with the same effect. When a reference is changed by such a user interaction, it will execute a consume command if so specified. To remove (or clear) the reference use a right-left interclick inside the reference. Like most other visual gadgets, a reference may execute a command when clicked on.

We may now proceed with a few exercises in order to verify what has just been presented.

To clear the Columbus panel right-left click inside the Current Object reference. The panel returns to a minimal size. Press the [back] button to return to 'obj1'. Now, set a new reference by dropping a gadget into the reference. Middle-right click on the border of any gadget you would like to inspect. The mouse pointer changes to a flat hand. Release the mouse buttons on top of the reference. The Columbus panel now shows information about the dropped gadget. The other way to set a new object is to copy over (left-middle click) a selected gadget into the reference. Now, close the Columbus panel and click on the following command.

In conclusion, this visual reference can be used to clear the panel or to set a new object to inspect.

Columbus.Inspect Columbus.Playground ~

A new Columbus panel opens again (move it to the right side of your screen). The inspected object is a public object named 'Playground' obtained from the "Columbus.Lib". Now open a new text and drag-and-drop its visual reference into the document panel (middle-left click into the reference, drag the mouse over the document and release the mouse buttons). Place the inserted panel in the top left corner of the document. Select the gadget and press the inspect button.

Note that depending on the object this list of available views can differ. Again select this check box -> and inspect the object with the inspect button or drop it into the reference. There are less views you can choose from. Press the button to return to the object "Playground".

We shall now describe in detail all the possible views of an object.

Object views

The current view is always identifiable by the red LED in the button.

[Attr] - attribute view
This view displays the attributes of the inspected object with their values in the Attributes section. It is the preferred view which is always presented first when a new object is inspected (but for a library the library view is presented first, of course). You can change the attribute values and apply them to the object by clicking the [Apply] button on the right side of the inspector panel.

Try this: change the attribute 'Color' to 1 and press the [Apply] button. The previously inserted panel in the document changes its color to red.

The New Attribute section is used for adding an attribute to the current object. It features two text fields: in the first one enter the new attribute's name, in the second one its value. To add the attribute click on the [Add] button. An added attribute can be removed with a click on the [Del] button. Enter the name of the attribute to delete in the Attr. Name field.

Try this: enter a name (e.g. 'New1') and a value (e.g. 'Value1') and press the [Add] button. The attribute is immediately added to the object's attribute list. Try another one, with 'Name2' and value 'Yes'.

This view is the starting point for an inspection tour of the current object with excursions to other related objects or libraries. Every step is recorded in a history stack, making it possible to regress step by step by clicking the button. However, if any other view (among those described below) is presented, clicking on the Current Object reference at the top right, will project this view again.

[Link] - link view
This view shows the links of the inspected object in the Links section. You can change the object links and apply them to the object by clicking the [Apply] button on the right side of the inspector panel.

The New Link section is used for adding a link to the current object. It features a text field for specifying the new link's name, and an empty visual reference where to drop the object to link. To add the link click on the [Add] button. An added link can be removed with a click on the [Del] button. Enter the name of the link to delete in the Link Name field.

To check out, how this works, drag-and-drop the object of this reference -> into the link 'Picture' on the inspector panel (use middle-right interclick). Press the [Apply] button and see the panel in the text (nice ?!).

[Coords] - coordinates view
This button is present only when a visual gadget is being inspected. This view shows the coordinates of a visual gadget. This view is not available for models (see the panel with 'Columbus.Background').

Try this: Change the 'W' to 190 and 'H' to 130 and press the [Apply] button. Feel free to play with the panel and its content, but don't forget to return here to take the rest of the tour.

[Comp] - component view
This button is present only when a container gadget is being inspected. This view lists the components the container gadget with their generator procedure and visual reference. You may inspect each reference - with middle mouse click, but you can not change them. Inspect some of them, but before you continue, make sure you're back in this view (back button).

- call Watson
Columbus gives you the opportunity to see additional descriptions of the inspected object. These are tutorials, definition files or module files. This button calls Watson.ShowObj with the object's generator name as parameter. Click on the button and the text 'Panels.Def' (or 'Panels.Mod' if exists) opens.

[Lib] - library view
This button is present only when the object inspected is bound to a public or a private library. Obviously enough, when a library is inspected, the library view is the preferred view which is always presented first. The views lists the objects contained in the library. The generator procedure, the reference number, and in the case of a public library, the name in the index are displayed for each object, together with a visual reference (see component view above). Use the reference to inspect a particular object in the library. The name of the inspected public library is displayed in the top right corner. In the case of a private library, the text is simply "(Private)". The object which was being inspected when the library view was called is easily spotted: look for the blue text line. If there is no current object, no line is highlighted.

Try this: Columbus.Inspect Watson - the library view is presented immediately. Now, inspect the "ModFile" text field (Ref # 4) and then access the library view again (not by clicking the button!).

[Editor] - library editor
This button is present only when the object inspected is bound to a public library. The library editor more or less the same as the library panel, described in the next section. With it you can remove a library from memory, store a library on disk, retrieve objects, free objects or install objects in a library.

You reached the end of this tour. Close all panels and text, you opened during this course and step to the next section about the library panel.

Using the Library Inspector

The library panel is opened with the command Desktops.OpenDoc Libraries2.Panel ~

The panel is divided into three parts. The top part contains the button [Directory], two check boxes and a list. The list shows the library names. You can choose the kind of libraries you want to see. To view the list of libraries stored on disk, select "Disk". To view the list of libraries currently loaded in memory, select "Memory". Click on the button [Directory] to see the list of your choice.

Select a library in the list with a click. The text field Library is updated: it shows the library which will become the target of the library management operations controlled by the buttons in the middle part.

• [Unload] - Removes the library from memory.
• [Store] - Stores the library on disk (the library remains cached in memory).
• [Cleanup] - Collects the unused objects and stores the library on disk.

At the same time, the list of objects contained in the library is displayed. Each object can be inspected by clicking its visual reference at the right side.

Select an object in the list with a click on its Name button. The text field Object is updated: it shows the object which will become the target of the operations controlled by the buttons in the bottom part.

• [Retrieve] - Inserts the object at the caret or opens it as a document (if it is a document gadget). The three check boxes at the right indicate if retrieval from the library should involve no, a deep or shallow copy (deep copies are default).
• [Rename] - Renames the object with the specified name. All changes made to the object will be reflected immediately to the clients of the object. The text field on the right is used to specify the new name.
• [Install] - Inserts the object under the specified name in the library. An object with this name is overwritten. The text field on the right is used to specify the name. The empty reference gadget is used to specify the object to install.
• [Free] - Frees the selected object from the library.

Columbus commands

Inspection command - Columbus.Inspect

The Columbus.Inspect command can take different forms, but in every case it opens a panel document named "Objects.Panel".

Columbus.Inspect ~ (without parameter!) attempts to locate a marked (*) or a selected (the most recently selected one) visual gadget, or also the object cited in the most recent selection. The latter case, which takes precedence over the others, is described below. If successful, the attribute view of the gadget is presented. Otherwise, a minimal panel is opened. The star-shaped (*) mark allows a finer grain selection of an object. As you may suspect, this command is hidden in the Cmd attribute of the [Inspect] button.

To see the difference, try inspecting the caption "obj1" in the two ways. If you select the panel, you have to access the components view and to click on the TextsFields.NewCaption reference to reach the same view as you would by setting a mark.

Columbus.Inspect LibName [.ObjName] | [^] ~ presents inspection information on the named public library or on the object in a public library, according to the following rules:

• If the name in the parameter represents a library, e.g. Watson, the "Objects.Panel" panel contains the library view enumerating all the objects in the library.
• If the qualified name in the parameter represents an object in a library, e.g. Watson.Order, the attribute view of the object is presented.
• If the object cannot be found in the library, e.g. Watson.Disorder, an enumeration of all the objects in the library is also presented.
• Finally, if the first name part is not that of a library (library cannot be found), e.g. What.Order or NotaLib, a minimal library view is presented (empty library).

Try out all the examples with: Columbus.Inspect ^

Link inspection command - Columbus.InspectLink

Columbus.InspectLink LinkName opens a panel document named "Objects.Panel". The object to inspect is taken from the executor gadget's link "LinkName". If the link does not exists or no object is present, a minimal 'Objects.Panel' document is opened. (This command can be used as Cmd or ConsumeCmd of a RefGadget.)

Showing the objects in a library - Columbus.ShowObjs

Columbus.ShowObjs LibName opens a text document "Columbus.ShowObjs" listing the objects exported by the named library. The name must have a ".Lib" extension. The information provided is a subet of and is more rudimentary than that obtained with Columbus.Inspect LibName .

Try this: Columbus.ShowObjs Watson.Lib and compare with what was obtained earlier.

Retrieving an object from a library - Columbus.GetObj

Columbus.GetObj LibName.ObjName retrieves an object "ObjName" from the library "LibName.Lib". If the object is a document gadget, a copy of the document is opened on the display. A gadget frame will be inserted at the caret position. A copy is made depending on the value of an object named "copy style". If this object cannot be found in the current context, the copy style is assumed to be deep. A model is set to all selected frames as "Model"-link. (No copies are made for models).

Removing an object from a library - Columbus.FreeObj

Columbus.FreeObj LibName.ObjName removes the object "ObjName" from the library "LibName.Lib". Objects contained by the freed object are not removed (see Columbus.CleanupLib).

Adding an object to a library - Columbus.AddObj

Columbus.AddObj LibName.ObjName inserts a new object named "ObjName" into the library "LibName.Lib". If an object with that name already exists in the library, is replaced by the new object. The new object is taken from a visual reference named "value" in the current context.

Renaming an object in a library - Columbus.RenameObj

Columbus.RenameObj LibName.OldName NewName replaces the name "OldName" in the index of the library "LibName.Lib" with "NewName".

Commands to manage libraries

Columbus.ShowLibs [ObjName] inserts the names of the libraries currently loaded in memory cache into the named list in the current context. If the list is not found, a text document "Columbus.ShowLibs" is opened instead. As an example, the button [Directory] in the "Libraries2.Panel" uses this command. This command is closely related to the command System.ShowLibraries, with the difference that font libraries are not listed.

Columbus.StoreLib ({LibName} | ^) stores the named libraries on disk in the current directory. The names must have a ".Lib" extension.

Columbus.UnloadLib ({LibName} | ^) removes the named libraries from memory. The names must have a ".Lib" extension.

Columbus.CleanupLib ({LibName} | ^) frees unreferenced objects from the named libraries. A cleaned-up library is stored on disk and reloaded into memory. The names must have a ".Lib" extension.

Index

C

Columbus.AddObj
Columbus.FreeObj
Columbus.GetObj
Columbus.Inspect
Columbus.InspectLink
Columbus.RenameObj
Columbus.ShowObjs
Columbus

L

library inspector

O

object inspector

V

visual reference gadget

---

Revised, afi 16 Aug 1996
Installed on 30 05 1997