## 2.8 Example: show files in directory

In this section we illustrate the above with some simple examples. We also show how the GUI can call procedures in the Prolog system.

The demo creates a list of files from a given directory and allows the user to view a file. Figure 2 shows the result.

Figure 2 : The FileViewer demo

    fileviewer(Dir) :-
            new(DirObj, directory(Dir)),
            new(F, frame('File Viewer')),
            send(F, append(new(B, browser))),
            send(new(D, dialog), below(B)),
            send(D, append(button(view,
                                  message(@prolog, view,
                                          DirObj, B?selection?key)))),
            send(D, append(button(quit,
                                  message(F, destroy)))),
            send(B, members(DirObj?files)),
            send(F, open).

    view(DirObj, F) :-
            send(new(V, view(F)), open),
            get(DirObj, file(F), FileObj),
            send(V, load(FileObj)).

The main window of the application consists of a frame holding two specialised window instances. A frame is a collection of tiled windows. Any opened window in XPCE is enclosed in a frame. The windows are positioned using the methods `->`above, `->`below, `->`right and `->`left. The frame ensures that its member windows are properly aligned and handles resizing of the frame. See also section 10.6.

In line 3, a browser is `->`appended to the frame object. A browser is a window specialised for displaying a list of objects. Next, a dialog is positioned below the browser. A dialog is a window specialised in handling the layout of controllers, or dialog_item objects as XPCE calls them.

Line 5 adds a button to the dialog. `view' specifies the name of the button. XPCE defines a central mapping from `dialog_item `<->`name' to the label displayed. The default mapping capitalises the name and replaces underscores with spaces. In section 11.7, we describe how this can be used to realise multi-lingual applications. The second argument of the button specifies the action associated with the button. A message is a dormant send-operation. When pressed, the button executes

    send(@prolog, view, DirObj, B?selection?key)

If a message is sent to @prolog, this calls a predicate with the name of the selector of the message and an arity that equals the number of arguments to the message (2 here).

The second argument is a term with principal functor ? and defines an `obtainer', a dormant get-operation. It is defined as a Prolog infix operator of type `yfx`, priority 500. This implies that `B?selection?key` should be read as4Initial versions of XPCE lacked the obtainer. In this case the browser B would be passed to the predicate view/1, which would extract the current filename from the browser. Obtainers improve the readability and avoid the need to mix UI related code with application code.

    ?(?(B, selection), key)

The result of the get-operation `<-`selection on a browser returns the dict_item object currently selected. Dict-items are the elements of a dict, the underlying data object of a browser. A dict_item consists of a `<-`key (its identifier), a `<-`label (the visual text) and optionally an associated `<-`object.

Line 8 appends a second button to the dialog window. The dialog window will automatically align this one to the right of the first. The action sends a message directly to another XPCE object and `->`destroys the frame object if the quit button is pressed. Note that this will erase all UI objects associated with the frame. The garbage collector destroys all related objects.

Line 10 fills the browser with the files from the specified directory. The expression `DirObj?files` defines an obtainer operating on an instance of class directory. The obtainer evaluates to a chain, XPCE's notion of a list, holding the names of all files in the directory. This chain is sent to the members-method of the browser B.

Again, the garbage collector takes care of the directory and chain objects. The browser automatically converts the given names to dict_item objects.5This conversion is implemented with class dict_item. In fact, the browser just specifies the desired type and the message passing kernel invokes the conversion method of class dict_item.

Finally, the frame is `->`opened. This will cause the frame to ask each of the windows to compute its desired size, after which the frame aligns the windows, decides on their final geometry and creates the Window-system counterpart.

The view/2 callback predicate opens an instance of view, a window specialised in text-editing, gets the file-object for the given filename F. and loads the file into the view. The method `view`->`load' expects an instance of class file. Again, the type-conversion will deal with this.