A.2 Miscellaneous topics

This section discusses various topics that were omitted from the Guided Tour to keep it simple.

A.2.1 Specifying callback to prolog

Using the background popup of the behaviour editor, the object @prolog (see section 6) can be added to the model. Select Add Send Port to add a new predicate to the @prolog interface. Then type the name of the predicate. Now link the event-port of a control to the predicate and link the arguments.

If the predicate is not defined, select `Edit' on menu of @prolog to start PceEmacs on the source file. Now drag the predicate to the PceEmacs window. This will insert the head of the predicate at the caret. See figure 38

A.2.2 Advanced example of behaviour

Figure 39 is the screen dump of an application and its behaviour model of a tool that shows all files in a directory and clicking on a file shows the file's contents in the editor to the left. It demonstrates various aspects of advanced features for specifying behaviour.

• The text-field directory
  Represented in the model by (1). It is a normal text_item, but the `text_item<->type' field is set to `directory'. This implies the <-selection of the text-item will return a directory object.
• Showing the files of the directory
  If the text-item is modified, a list of files in the directory should be shown in the `file_list', a list_browser. The method `list_browser->members' may be used to fill the browser with a collection of items. This method expects a chain object. The get method `directory<-files' provides a chain holding the names of all files in the directory.

  Thus, the event-port `message' of the directory field must invoke the send-port `members' of the file-list. The argument should be the result of applying <-files on the <-selection of the text-entry field. To specify this, the get-port `selection' is expanded using the popup menu of this port. This operation adds (2) to the diagram. The system infers this expansion is an instance of class directory and shows the most useful get-ports in its get-port menu. The `files' get-port is added to (2) and linked to the activation relation between `text_item->message' and `list_browser->members'.

  To test this part, put the Dialog editor in `run' mode, type the name of a directory and ENTER to activate the event-port. If anything goes wrong, the Simulate option of the various popup menus in the diagram may be used to test small parts of the model. The Documentation option of these menus may be used to view the relevant documentation from the online manual tools.

• Specifying the initial directory as a parameter
  Initialisation of the dialog is expressed by adding one or more init-ports to the diagram using the background menu. In this particular case, we would like to be able to pass a directory to start as a parameter. Hence, a parameter-port is added with the name `dir'. First, the ->selection is set using the parameter and then the item is ->executed to activate its ->message.

  Code generation will append the directory parameter to the identifier of the dialog/2 clause. In this case, this clause will start as:

  dialog(viewer(Dir),
         [ ...
         ]).
  

  An instance is opened using the following calls:

          ...,
          make_dialog(D, viewer(StartDir)),
          send(D, open),
          ...
  

• Showing a file
  The first step is to link the event-port `select_message' of the file_list to the file_contents (3) editor object's send-port `load'. This method expects a file. Due to the type conversion rules of class file, the name of a file suffices, but the names from file_list are relative to the directory object (2). First, the <-selection of the file_list is expanded, resulting in (5), a dict_item object. The `dict_item<-key' contains the name of the file.

  The method `directory<-file' can be used to create a file object from a name, that specifies an absolute path. A get-port `file' is added to (2) and this get-port is linked to the activation relation. This get operation requires the filename argument from (5).

A.2.3 Specifying conditional actions

Figure 40 shows an example of a conditional activation relation. A conditional relation is created making a connection from the fat dot in the middle of an activation relation to a send-port. Success or failure of the send-port will be interpreted as a condition on the activation relation.

A.2.4 Load and save formats

The Dialog Editor provides two load/save formats. The Load, Save, Save As and Save All save and load the status of the dialog editor as an XPCE object using `object->save_in_file'. This format loads quickly, but is rather vulnerable to future changes in the Dialog Editor or any of the graphical classes.

Alternatively, the Dialog Editor can restore itself from the identifier of a dialog/2 clause generated by itself or (slightly) modified. In this case, the layout of the behaviour model will be lost.

We advice to use Save/Load during application development. If, during the maintenance phase of your product it is necessary to modify a dialog, either simply edit the dialog/2 clause, or load both the application and the dialog editor and use Reload From Id to restart the Dialog Editor.