<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
<HTML>
<HEAD>
<TITLE>Programming in XPCE/Prolog: Section A.1</TITLE><LINK REL=home HREF="index.html">
<LINK REL=contents HREF="Contents.html">
<LINK REL=index HREF="DocIndex.html">
<LINK REL=summary HREF="summary.html">
<LINK REL=previous HREF="dialogeditor.html">
<LINK REL=next HREF="sec-A.2.html">
<STYLE type="text/css">
/* Style sheet for SWI-Prolog latex2html
*/
dd.defbody
{ margin-bottom: 1em;
}
dt.pubdef
{ background-color: #c5e1ff;
}
pre.code
{ margin-left: 1.5em;
margin-right: 1.5em;
border: 1px dotted;
padding-top: 5px;
padding-left: 5px;
padding-bottom: 5px;
background-color: #f8f8f8;
}
div.navigate
{ text-align: center;
background-color: #f0f0f0;
border: 1px dotted;
padding: 5px;
}
div.title
{ text-align: center;
padding-bottom: 1em;
font-size: 200%;
font-weight: bold;
}
div.author
{ text-align: center;
font-style: italic;
}
div.abstract
{ margin-top: 2em;
background-color: #f0f0f0;
border: 1px dotted;
padding: 5px;
margin-left: 10%; margin-right:10%;
}
div.abstract-title
{ text-align: center;
padding: 5px;
font-size: 120%;
font-weight: bold;
}
div.toc-h1
{ font-size: 200%;
font-weight: bold;
}
div.toc-h2
{ font-size: 120%;
font-weight: bold;
margin-left: 2em;
}
div.toc-h3
{ font-size: 100%;
font-weight: bold;
margin-left: 4em;
}
div.toc-h4
{ font-size: 100%;
margin-left: 6em;
}
span.sec-nr
{
}
span.sec-title
{
}
span.pred-ext
{ font-weight: bold;
}
/* Footnotes */
sup.fn { color: blue; text-decoration: underline; }
span.fn-text: { display: none; }
sup.fn span {display: none;}
sup:hover span
{ display: block !important;
position: absolute; top: auto; left: auto; width: 80%;
color: #000; background: white;
border: 2px solid;
padding: 5px; margin: 10px; z-index: 100;
font-size: smaller;
}
</STYLE>
</HEAD>
<BODY BGCOLOR="white">
<DIV class="navigate"><A class="nav" href="index.html"><IMG SRC="home.gif" BORDER=0 ALT="Home"></A>
<A class="nav" href="Contents.html"><IMG SRC="index.gif" BORDER=0 ALT="Contents"></A>
<A class="nav" href="DocIndex.html"><IMG SRC="yellow_pages.gif" BORDER=0 ALT="Index"></A>
<A class="nav" href="summary.html"><IMG SRC="info.gif" BORDER=0 ALT="Summary"></A>
<A class="nav" href="dialogeditor.html"><IMG SRC="prev.gif" BORDER=0 ALT="Previous"></A>
<A class="nav" href="sec-A.2.html"><IMG SRC="next.gif" BORDER=0 ALT="Next"></A>
</DIV>
<H2><A NAME="sec:A.1"><SPAN class="sec-nr">A.1</SPAN> <SPAN class="sec-title">Guided
tour</SPAN></A></H2>
<P>We will now illustrate the functionality of the Dialog Editor by
defining a simple prompt dialog that asks for a name and has an <B>ok</B>
and <B>cancel</B> button to confirm or cancel the operation. The result
is shown in <A class="fig" href="sec-A.1.html#fig:diaaskname">figure 33</A>
<P><A NAME="fig:diaaskname"></A>
<CENTER>
<IMG SRC="diaaskname.gif">
</CENTER>
<TABLE ALIGN=center WIDTH="75%"><TR><TD>
<B>Figure 33 : </B>Ask-name dialog generated by the Dialog Editor</TABLE>
<H3><A NAME="sec:A.1.1"><SPAN class="sec-nr">A.1.1</SPAN> <SPAN class="sec-title">Creating
the target dialog window</SPAN></A></H3>
<P>First, start the manual tools using <A NAME="idx:manpce0:596"></A><A class="pred" href="sec-D.2.html#manpce/0">manpce/0</A>
or <A NAME="idx:userhelp0:597"></A><SPAN class="pred-ext">user_help/0</SPAN>.
Then, start the dialog editor using the option <B>Tools/Dialog Editor</B>.
The main window of the dialog editor is now opened on the screen. Use
the option
<B>File/New Dialog</B> 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 <A class="fig" href="sec-A.1.html#fig:diaeditor1">figure
34</A>. This window is called the `target window'.
<P><A NAME="fig:diaeditor1"></A>
<CENTER>
<IMG SRC="diaeditor1.gif">
</CENTER>
<TABLE ALIGN=center WIDTH="75%"><TR><TD>
<B>Figure 34 : </B>The Dialog Editor with the ask-name target</TABLE>
<H3><A NAME="sec:A.1.2"><SPAN class="sec-nr">A.1.2</SPAN> <SPAN class="sec-title">Adding
controls to the new window</SPAN></A></H3>
<P>Next, the controls are dragged to the dialog window. The control
marked
<IMG SRC="textitemicon.gif"> 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 <IMG SRC="buttonicon.gif"> 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 <B>copied</B> to
other target dialog windows by dragging them there and they can be <B>deleted</B>
by dragging them to the window holding the prototypes.
<P>Now, double-click, using the left button, the text-entry field. A
dialog with attributes will appear. The caret is positioned at the <B>Name</B>
field. Clear the name field (Control-U is the fastest way) and enter <TT>name</TT>,
followed by RETURN. The system will automatically fill the <B>Label</B>
field with <B>Name</B> (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 <B>Type</B>
field. This specifies the type of object edited by the text-entry field.
See <A NAME="idx:textitembothtype:598"></A>`<B>text_item<CODE><-></CODE>type</B>'
for details. Pressing <B>Help</B> creates a window containing the online
manual cards of all displayed attributes.
<P>Double click on both buttons to fix the name/label. Assign the ok
button to be the default button. The result is shown in <A class="fig" href="sec-A.1.html#fig:diaeditor2">figure
35</A>.
<P><A NAME="fig:diaeditor2"></A>
<CENTER>
<IMG SRC="diaeditor2.gif">
</CENTER>
<TABLE ALIGN=center WIDTH="75%"><TR><TD>
<B>Figure 35 : </B>The Dialog Editor after specifying attributes</TABLE>
<H3><A NAME="sec:A.1.3"><SPAN class="sec-nr">A.1.3</SPAN> <SPAN class="sec-title">Defining
the layout</SPAN></A></H3>
<P>Next, the <B>Mode</B> menu of the main Dialog Editor window is used
to select <B>Layout Mode</B>. The button <B>Layout</B> guesses the
symbolic layout description of the dialog and places the items. If you
are not satisfied with the result, press <B>Undo</B>. 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 <font size=-1>XPCE</font> with a different look-and-feel. The <B>Fit</B>
button adjusts the size of the dialog window to its content.
<H3><A NAME="sec:A.1.4"><SPAN class="sec-nr">A.1.4</SPAN> <SPAN class="sec-title">Specifying
the behaviour</SPAN></A></H3>
<P>The next step is to specify the <EM>behaviour</EM> of the dialog
window. Select the <B>Action</B> mode and press the <B>Behaviour Model</B>
button to open the behaviour window. Now drag all items from the target
dialog window to the behaviour window.
<P>Each control is now represented by a behavioural component. Each such
component defines a number of <EM>ports</EM>. The Dialog Editor
distinguishes between three types of ports:
<P>
<UL>
<LI><I>send-port</I><BR>
<A NAME="idx:sendport:599"></A>A send-port is the representation of a
send-method defined on the controller represented by the behavioural
component.
<LI><I>get-port</I><BR>
<A NAME="idx:getport:600"></A>A get-port is the representation of a
get-method defined on the controller.
<LI><I>event-port</I><BR>
<A NAME="idx:eventport:601"></A>An event-port is the representation of
an instance variable defined on the controller that can hold an
executable (<A class="" href="summary.html#class:code">code</A>) object
(see <A class="sec" href="exeobjects.html">section 10.2</A>). Controls
use these variables to define the
<EM>callback</EM> actions of the dialog item.
</UL>
<P>The window (background) represents the <EM>target</EM> 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.
<P>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 <font size=-1>XPCE</font> online manual
as well as the online documentation of the Dialog Editor.
<P>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 <EM>arguments</EM> for the
send-operation. If a get-method needs to be performed on the value of a
get-port to define the argument, <B>Extend</B> the get-port, define a
new get-port on the extension and link the result to the argument dot.
<P>For our <B>Ask Name</B> dialog, we need to make a <EM>modal</EM>
dialog, see
<A class="sec" href="modal.html">section 4.4</A>. Such a dialog returns
by invoking the <B><CODE>-></CODE>return</B> method on the dialog
window. The popup of the background is used to define a send-port named <TT>return</TT>,
representing <B><CODE>-></CODE>return</B> to the dialog. Position the
pointer above the new item to validate your action.
<P>Now, as both methods will make the dialog return immediately, link
the
<TT>message</TT> event-port of both buttons to this <TT>return</TT>
send-port. Link the <TT>selection</TT> get-port of the text field to the
argument dot of the link from the <B>Ok</B> button. This specifies that
the dialog will return with the <A NAME="idx:textitemgetselection:602"></A>`<B>text_item<CODE><-</CODE>selection</B>'
if the <B>Ok</B> button is pressed. Add the constant <A NAME="idx:nil:603"></A><B>@nil</B>
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 <A class="fig" href="sec-A.1.html#fig:diaeditor3">figure 36</A>.
<P><A NAME="fig:diaeditor3"></A>
<CENTER>
<IMG SRC="diaeditor3.gif">
</CENTER>
<TABLE ALIGN=center WIDTH="75%"><TR><TD>
<B>Figure 36 : </B>Behaviour model of <B>Ask Name</B></TABLE>
<H3><A NAME="sec:A.1.5"><SPAN class="sec-nr">A.1.5</SPAN> <SPAN class="sec-title">Generating
source code</SPAN></A></H3>
<P><A NAME="idx:sourcecodefromdialogeditor:604"></A>To generate source
code, start PceEmacs using the <B>Edit</B> command from the background
menu. This will open PceEmacs on the file <TT>ask_name.pl</TT>. Any
other PceEmacs window editing a Prolog source file will do as well. Drag
the <TT>ask_name</TT> 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
<A class="fig" href="sec-A.1.html#fig:diaeditor4">figure 37</A>.
<P><A NAME="fig:diaeditor4"></A>
<CENTER>
<IMG SRC="diaeditor4.gif">
</CENTER>
<TABLE ALIGN=center WIDTH="75%"><TR><TD>
<B>Figure 37 : </B>Creating source-code</TABLE>
<H3><A NAME="sec:A.1.6"><SPAN class="sec-nr">A.1.6</SPAN> <SPAN class="sec-title">Linking
the source code</SPAN></A></H3>
<P>The generated source is a <EM>description</EM> 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 <A NAME="idx:makedialog2:605"></A><A class="pred" href="sec-A.1.html#make_dialog/2">make_dialog/2</A>:
<DL>
<DT class="pubdef"><A NAME="make_dialog/2"><STRONG>make_dialog</STRONG>(<VAR>?Reference,
:Identifier</VAR>)</A></DT>
<DD class="defbody">
Create a dialog window from a description generated by the Dialog
Editor. The predicate <A NAME="idx:makedialog2:606"></A><A class="pred" href="sec-A.1.html#make_dialog/2">make_dialog/2</A>
searches for a predicate <A NAME="idx:dialog2:607"></A><A class="pred" href="sec-A.1.html#dialog/2">dialog/2</A>
and calls this using the given dialog <EM>Identifier</EM> to obtain a
description of the dialog window. See <A NAME="idx:dialog2:608"></A><A class="pred" href="sec-A.1.html#dialog/2">dialog/2</A>
for the syntax of the description.
</DD>
<DT class="pubdef"><A NAME="dialog/2"><STRONG>dialog</STRONG>(<VAR>?Identifier,
?Description</VAR>)</A></DT>
<DD class="defbody">
Clause as generated by the dialog editor. The description is a list of
<<VAR>Name</VAR>> <TT>:=</TT> <<VAR>Value</VAR>> pairs. It
contains the following elements:
<P>
<UL>
<LI><I>object</I><BR>
Points to the Prolog variable defining the main object reference (the
first argument of <A NAME="idx:makedialog2:609"></A><A class="pred" href="sec-A.1.html#make_dialog/2">make_dialog/2</A>).
<LI><I>parts</I><BR>
A list of <<VAR>Var</VAR>> <TT>:=</TT> <<VAR>NewTerm</VAR>>. <A NAME="idx:makedialog2:610"></A><A class="pred" href="sec-A.1.html#make_dialog/2">make_dialog/2</A>
will simply call <A NAME="idx:new2:611"></A><A class="pred" href="sec-D.1.html#new/2">new/2</A>
on these terms to create the parts of the dialog window.
<LI><I>modifications</I><BR>
List of <<VAR>Var</VAR>> <TT>:=</TT> <<VAR>ListOfModifications</VAR>>
that have to be applied to the parts to modify them from the default to
the target configuration. The <<VAR>ListOfModifications</VAR>> is
a list of <<VAR>Attribute</VAR>> <TT>:=</TT> <<VAR>Value</VAR>>.
<LI><I>layout</I><BR>
List of <TT>below(<<VAR>Part1</VAR>>, <<VAR>Part2</VAR>>)</TT>
and <TT>right(<<VAR>Part1</VAR>>, <<VAR>Part2</VAR>>)</TT>,
describing the symbolic layout of the dialog window.
<LI><I>behaviour</I><BR>
List of <<VAR>Part</VAR>> <TT>:=</TT> <<VAR>ListOfBehaviour</VAR>>,
describing the behaviour of the control element. <<VAR>ListOfBehaviour</VAR>>
is a list of
<<VAR>Attribute</VAR>> <TT>:=</TT> <<VAR>Message</VAR>>,
describing the <A class="" href="summary.html#class:code">code</A>
objects associated with the controls.
</UL>
</DD>
</DL>
<P>The wrapper program to make the dialog-description useful from an
application is given below. First <A NAME="idx:makedialog2:612"></A><A class="pred" href="sec-A.1.html#make_dialog/2">make_dialog/2</A>
is used to create the dialog. Next the dialog is opened in the center of
the display and the system waits for the <A NAME="idx:framesendreturn:613"></A>`<B>frame<CODE>-></CODE>return</B>'
message to be send.
<PRE class="code">
ask_name(Name) :-
make_dialog(D, ask_name),
get(D, confirm_centered, RawName),
send(D, destroy),
Name = RawName.
</PRE>
<H3><A NAME="sec:A.1.7"><SPAN class="sec-nr">A.1.7</SPAN> <SPAN class="sec-title">Summary</SPAN></A></H3>
<P>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 <B>layout</B>
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 <TT>.pl</TT> or <TT>.pro</TT>). Finally, a small
wrapper must be defined that creates the dialog window from the
description using <A NAME="idx:makedialog2:614"></A><A class="pred" href="sec-A.1.html#make_dialog/2">make_dialog/2</A>
and opens the dialog in the proper way.
<P></BODY></HTML>
