## A.1 Guided tour

We will now illustrate the functionality of the Dialog Editor by defining a simple prompt dialog that asks for a name and has an ok and cancel button to confirm or cancel the operation. The result is shown in figure 33

Figure 33 : Ask-name dialog generated by the Dialog Editor

### A.1.1 Creating the target dialog window

First, start the manual tools using manpce/0 or user_help/0. Then, start the dialog editor using the option Tools/Dialog Editor. The main window of the dialog editor is now opened on the screen. Use the option File/New Dialog and enter the name `ask_name'. This will add ask_name to the Dialog Windows browser and open an window with the title `Ask Name'. See figure 34. This window is called the `target window'.

Figure 34 : The Dialog Editor with the ask-name target

### A.1.2 Adding controls to the new window

Next, the controls are dragged to the dialog window. The control marked specifies a text-entry-field. Drag this icon using the left-mouse button to the target dialog. If the mouse is above the target dialog, a dotted box will indicate the outline of the new item when it is dropped. Drop it in about the right location. Now drag two instances of to the target dialog and place them again at about the right location. Items can be moved by dragging them with the left button. They can also be copied to other target dialog windows by dragging them there and they can be deleted by dragging them to the window holding the prototypes.

Now, double-click, using the left button, the text-entry field. A dialog with attributes will appear. The caret is positioned at the Name field. Clear the name field (Control-U is the fastest way) and enter `name`, followed by RETURN. The system will automatically fill the Label field with Name (capitalising the name of the control). If the label should be anything else than the capitalised name, type the correct label now. The other fields are self-explanatory, except for the Type field. This specifies the type of object edited by the text-entry field. See `text_item`<->`type' for details. Pressing Help creates a window containing the online manual cards of all displayed attributes.

Double click on both buttons to fix the name/label. Assign the ok button to be the default button. The result is shown in figure 35.

Figure 35 : The Dialog Editor after specifying attributes

### A.1.3 Defining the layout

Next, the Mode menu of the main Dialog Editor window is used to select Layout Mode. The button Layout guesses the symbolic layout description of the dialog and places the items. If you are not satisfied with the result, press Undo. Next, you can help the layout mechanism by positioning the items closer to the intended position and try again, or place the items by hand. In the latter case, the generated code will express the layout using pixel-locations rather then a symbolic description and the result may look bad if the end-user runs XPCE with a different look-and-feel. The Fit button adjusts the size of the dialog window to its content.

### A.1.4 Specifying the behaviour

The next step is to specify the behaviour of the dialog window. Select the Action mode and press the Behaviour Model button to open the behaviour window. Now drag all items from the target dialog window to the behaviour window.

Each control is now represented by a behavioural component. Each such component defines a number of ports. The Dialog Editor distinguishes between three types of ports:

- send-port
  A send-port is the representation of a send-method defined on the controller represented by the behavioural component.
- get-port
  A get-port is the representation of a get-method defined on the controller.
- event-port
  An event-port is the representation of an instance variable defined on the controller that can hold an executable (code) object (see section 10.2). Controls use these variables to define the callback actions of the dialog item.

The window (background) represents the target dialog as a whole. Ports may be added to both behavioural components and the background window using the popup menu associated with the right mouse-button.

While hovering over the various parts of the behavioural model, the feedback window at the bottom describes the meaning of the current item. The popup menus defined on all components of the model provide context-sensitive access to the XPCE online manual as well as the online documentation of the Dialog Editor.

In general, the action(s) associated with a control are specified by connecting its event-ports to a send-port in the diagram. The line connecting both ports has a fat dot in the middle. Get-ports may be linked to this fat dot to specify arguments for the send-operation. If a get-method needs to be performed on the value of a get-port to define the argument, Extend the get-port, define a new get-port on the extension and link the result to the argument dot.

For our Ask Name dialog, we need to make a modal dialog, see section 4.4. Such a dialog returns by invoking the `->`return method on the dialog window. The popup of the background is used to define a send-port named `return`, representing `->`return to the dialog. Position the pointer above the new item to validate your action.

Now, as both methods will make the dialog return immediately, link the `message` event-port of both buttons to this `return` send-port. Link the `selection` get-port of the text field to the argument dot of the link from the Ok button. This specifies that the dialog will return with the `text_item`<-`selection' if the Ok button is pressed. Add the constant @nil to the background using the popup menu on the background. This finishes the specification of our dialog window. The resulting behaviour model is shown in figure 36.

Figure 36 : Behaviour model of Ask Name

### A.1.5 Generating source code

To generate source code, start PceEmacs using the Edit command from the background menu. This will open PceEmacs on the file `ask_name.pl`. Any other PceEmacs window editing a Prolog source file will do as well. Drag the `ask_name` entry from the main window of the Dialog Editor to the PceEmacs window. The window will indicate it is ready to accept the Prolog source code. Now `drop' the code. The source code will be inserted at the caret location. See figure 37.

Figure 37 : Creating source-code

### A.1.6 Linking the source code

The generated source is a description of the dialog window. This description requires an interpreter to create the dialog window and use it in an application. This interpreter is implemented by make_dialog/2:

make_dialog(?Reference, :Identifier)
  Create a dialog window from a description generated by the Dialog Editor. The predicate make_dialog/2 searches for a predicate dialog/2 and calls this using the given dialog Identifier to obtain a description of the dialog window. See dialog/2 for the syntax of the description.
dialog(?Identifier, ?Description)
  Clause as generated by the dialog editor. The description is a list of <Name> `:=` <Value> pairs. It contains the following elements:

  - object
    Points to the Prolog variable defining the main object reference (the first argument of make_dialog/2).
  - parts
    A list of <Var> `:=` <NewTerm>. make_dialog/2 will simply call new/2 on these terms to create the parts of the dialog window.
  - modifications
    List of <Var> `:=` <ListOfModifications> that have to be applied to the parts to modify them from the default to the target configuration. The <ListOfModifications> is a list of <Attribute> `:=` <Value>.
  - layout
    List of `below(<Part1>, <Part2>)` and `right(<Part1>, <Part2>)`, describing the symbolic layout of the dialog window.
  - behaviour
    List of <Part> `:=` <ListOfBehaviour>, describing the behaviour of the control element. <ListOfBehaviour> is a list of <Attribute> `:=` <Message>, describing the code objects associated with the controls.

The wrapper program to make the dialog-description useful from an application is given below. First make_dialog/2 is used to create the dialog. Next the dialog is opened in the center of the display and the system waits for the `frame`->`return' message to be send.

    ask_name(Name) :-
            make_dialog(D, ask_name),
            get(D, confirm_centered, RawName),
            send(D, destroy),
            Name = RawName.

### A.1.7 Summary

We have now completed the first guided tour through the Dialog Editor, introducing the main concepts and the process of creating a dialog window using this tool. After creating a target dialog window, controls are added to the dialog using drag-and-drop. Their attributes are edited by double-clicking the new controls and filling the subsequently shown dialog window. Next, the items are dragged roughly to the right location, the editor is placed in layout mode and the layout button is used to let the Dialog Editor guess the symbolic layout description. Next the behaviour is defined using the behaviour model editor. Event-ports (control-attributes defining the callback of a control) are linked to send-ports (send-method ports) and arguments are linked to this activation relation. Finally the dialog window is dropped in a PceEmacs window running in Prolog mode (the default when editing a file with extension `.pl` or `.pro`). Finally, a small wrapper must be defined that creates the dialog window from the description using make_dialog/2 and opens the dialog in the proper way.