# 4 Using Browser Objects

All Browsers in the Oz system are Oz objects. The `BrowserClass` is the class definition of these objects. In this section the usage of these objects is described.

## 4.1 Creating A Browser Object

One can create Browser objects similarly to the pre-defined `Browser` one:

> `BrowserObject = {New Browser.'class' init}`

The plain `init` method makes a newly created Browser placed on its own toplevel widget. One can tell a Browser object to use a Tk frame (see for details) as its toplevel frame:

> `declare W F BrowserObject in
> %%
> W = {New Tk.toplevel tkInit(bg:ivory)}
> {Tk.send wm(geometry W "500x300")}
> %%
> F = {New Tk.frame tkInit(parent : W
> bd : 3
> bg : white
> relief : groove
> width : 450
> height : 250)}
> {Tk.send pack(F fill:both padx:10 pady:10 expand:true)}
> %%
> BrowserObject = {New Browser.'class' init(origWindow: F)}
> {BrowserObject createWindow}
> %%
> {BrowserObject
> browse(
> record(
> atom: bonjour
> quotedAtom: 'hello world'
> list: [one two three four five six seven nine]
> integer: 57
> float: 34.56e~76
> string:"adieu, monde cruel!"
> byteString:{ByteString.make "squeeze me"}
> tuple: foo(one(1) two(1 2) three(1 2 3))))}`

The window produced that way is shown on Figure 4.1. Such a browser is called an embedded Browser, compared to a stand-alone Browser using its own toplevel widget.

Figure 4.1: An Embedded Application Browser

Note that when a Browser object is created, either stand-alone or embedded, its window does not appear immediately. This happens when either `createWindow` or `browse` methods are applied.

A Browser window can be closed by means of the `closeWindow` method. Each time a Browser window is closed its buffer is flushed. A Browser object itself can be closed by means of the `close` method, which deletes its window and frees used by the object memory. A subsequent application of a Browser object closed this way proceeds as it were just created\footnote{This feature is used in the pre-defined `Browser`, which can be closed many times but never dies. Note that this behavior is not ``re-creating'' since no new Browser object is created immediately.}.

Note that the `closeWindow` method has no effect for embedded application browsers.

An embedded browser and its frame should be closed by sending the `close` messages on the Browser object and on the frame object in that sequence. For instance, in our example it would be

> `{BO close}
> {F close}`

## 4.2 Browser Object Methods

Browser objects are controlled by user through the Browser GUI, and by means of application of them to the `BrowserClass` methods. At the glance, there are the following public methods of a Browser object, where `X` and `Y` are certain internal default values:

> `meth init(origWindow: OrigWindow <= X)
> meth createWindow
> meth closeWindow
> meth close
> meth browse(Term)
> meth break
> meth clear
> meth clearAllButLast
> meth rebrowse
> meth option(...)
> meth add(Action label:Label <= Y)
> meth set(Action)
> meth delete(Action)
> meth refineLayout`