<!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 3.3</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="sec-3.2.html"> <LINK REL=next HREF="sec-3.4.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="sec-3.2.html"><IMG SRC="prev.gif" BORDER=0 ALT="Previous"></A> <A class="nav" href="sec-3.4.html"><IMG SRC="next.gif" BORDER=0 ALT="Next"></A> </DIV> <H2><A NAME="sec:3.3"><SPAN class="sec-nr">3.3</SPAN> <SPAN class="sec-title">Guided tour</SPAN></A></H2> <P>This section provides a `guided tour' through the manual system. If you have <font size=-1>XPCE/P</font>rolog at hand, please start it and try the examples. For each of the central tools of the manual we will present a screendump in a typical situation and explain the purpose and some common ways to use the tool. <H3><A NAME="sec:3.3.1"><SPAN class="sec-nr">3.3.1</SPAN> <SPAN class="sec-title">Class browser</SPAN></A></H3> <A NAME="sec:classbrowser"></A> <P><A NAME="fig:classbrowser"></A> <CENTER> <IMG SRC="classbrowser.gif"> </CENTER> <TABLE ALIGN=center WIDTH="75%"><TR><TD> <B>Figure 3 : </B>The Class Browser</TABLE> <P>The ``Class Browser'' is the central tool of the online manual. It provides an overview of the functionality of a class and options to limit the displayed information. <A class="fig" href="sec-3.3.html#fig:classbrowser">Figure 3</A> shows this tool in a typical situation. In this example the user is interested in methods dealing with `caret' in an <A class="" href="summary.html#class:editor">editor</A>. <P>The dialog to the left-side of the tool specifies <EM>what</EM> information is displayed. The top-right window displays the class together with the initialisation arguments (the arguments needed to create an instance of this class). Double-left-click on this text will open the description for <B><CODE>-></CODE>initialise</B>. <P>Below this text a hierarchy is displayed that indicates the place in the inheritance hierarchy as well as the classes to which messages are <EM>delegated</EM> (see <A class="sec" href="delegation.html">section C.4</A>). The user can select multiple classes only if there is delegation and the tree actually has branches. Use class <A class="" href="summary.html#class:editor">editor</A> or class view to explore these facilities. After the user has selected one or more classes, the <B>Apply</B> button makes the class-browser search for methods in all classes below the selected classes. If a method is found in multiple classes the class-browser will automatically display only the one method that will actually be used by this class. <P>The large right window displays a list of matching classes, variables, methods and class-variables. If an item is tagged with a ``<A NAME="idx::100">(+)</A>'' there is additional information that may be obtained by (double-) clicking the card to start the ``Card Viewer'' (see <A class="sec" href="sec-3.3.html">section 3.3.2</A>). <H4><A NAME="sec:3.3.1.1"><SPAN class="sec-nr">3.3.1.1</SPAN> <SPAN class="sec-title">The ClassBrowser dialog</SPAN></A></H4> <P>The <B>Class</B> text_item (text-entry-field) may be used to switch to a new class. Note that this text_item implements <A NAME="idx:completion:101">completion</A> (bound to the space-bar). <P>The <B>Filter</B> menu filters the candidate objects according to their categorisation. Selecting <B>all</B> switches off filtering, which is often useful in combination with <B>Search</B>. Clicking <B>all</B> again switches back to the old selection of categories. The meaning of the categories is: <P> <UL> <LI><I>Basic</I><BR> Principal methods that are used very often. This is, together with <EM>Application</EM>, the default selection of this menu. <LI><I>Advanced</I><BR> Less often used and sometimes complicated methods. <LI><I>Rare</I><BR> Infrequently used methods. Note that does not mean they are complicated or do things you'd hardly ever want to use. For example, most of the caret-manipulation of class editor is in this category. It is essential and commonly used behaviour of the editor, but rarely used directly from program-control. <LI><I>Internal</I><BR> Behaviour that is not directly intended for public usage. It may be useful to understand how other methods interact. Try to avoid using these methods or variables in your code. <LI><I>Basic OO</I><BR> Methods intended to be redefined in user-defined classes. See <A class="sec" href="udc.html">chapter 7</A>. <LI><I>Advanced OO</I><BR> Methods that may be redefined in user-defined classes, but for which this is far less common. <LI><I>Application</I><BR> Methods implemented in the host-language. </UL> <P>The <B>Display</B> menu determines the objects searched for. <B>Self</B> refers to the class itself, <B>Sub Class</B> refers to the direct sub classes of this class. The other fields refer to instance-variables, methods with send- and get-access and class-variables. <P>The <B>Search</B> and <B>... In</B> controllers limit the displayed cards to those that have the specified search string in one of the specified fields. While searching, the case of the characters is ignored (i.e. lower- and uppercase versions of the same letter match). Searching in the <B>Name</B> field is useful to find a particular method if the name (or part of it) is known. <H4><A NAME="sec:3.3.1.2"><SPAN class="sec-nr">3.3.1.2</SPAN> <SPAN class="sec-title">Example queries to the classbrowser</SPAN></A></H4> <P>Below we illustrate how some commonly asked questions may be answered with the class browser. <P> <UL> <LI><I>What are variables of a bitmap?</I><BR> Select <B>variable</B> in the <B>Display</B> menu, clear <B>Search</B>, and set <B>Filter</B> to <B>All</B>. Then type `bitmap' in <B>Class</B> and hit return. Note that by double-clicking on class <A class="" href="summary.html#class:graphical">graphical</A> in the inheritance display not only the variables of class <A class="" href="summary.html#class:bitmap">bitmap</A> itself are shown, but also those of class <A class="" href="summary.html#class:graphical">graphical</A>. <LI><I>How can I position the caret in an editor?</I><BR> The caret can only be changed using send-methods. Either the name or the summary is likely to have `caret' as a substring. Thus, <B>Display</B> is set to <B>Send Method</B>, <B>Field</B> to <B>Name</B> and <B>Summary</B>, search `caret'. </UL> <H4><A NAME="sec:3.3.1.3"><SPAN class="sec-nr">3.3.1.3</SPAN> <SPAN class="sec-title">Methods with special meaning</SPAN></A></H4> <P>This section describes the role of the `special' methods. These are methods that are not used directly, but they define the behaviour of <A NAME="idx:new2:102"></A><A class="pred" href="sec-D.1.html#new/2">new/2</A>, type conversion, etc. and knowing about them is therefore essential for understanding an <font size=-1>XPCE</font> class. <DL> <DT><STRONG>object ->initialise:</STRONG> <VAR><<VAR>Class-Defined</VAR>></VAR></DT> <DD class="defbody"> <A NAME="idx:objectscreating:103"></A>The <B><CODE>-></CODE>initialise</B> method of a class defines what happens when an instance of this class is created. It may be compared to the <A NAME="idx:constructor:104">constructor</A> in C++. Note that double-clicking the class description in the class-browser (top-right window) opens the reference card for the <B><CODE>-></CODE>initialise</B> method. See also <A NAME="idx:new2:105"></A><A class="pred" href="sec-D.1.html#new/2">new/2</A>, <A class="sec" href="sec-2.2.html">section 2.2.1</A>. </DD> <DT><STRONG>object ->unlink:</STRONG> <VAR></VAR></DT> <DD class="defbody"> <A NAME="idx:objectremove:106"></A>The <B><CODE>-></CODE>unlink</B> method describes what happens when an instance of this class is removed from the object-base and may be compared to the C++ <A NAME="idx:destructor:107">destructor</A>. </DD> <DT><STRONG>object <-lookup:</STRONG> <VAR><<VAR>Class-Defined</VAR>></VAR></DT> <DD class="defbody"> object <A NAME="idx:reusability:108"></A>If defined, this method describes the lookup an already defined instance instead of object creation. For example <PRE class="code"> 1 ?- new(X, font(screen, roman, 13)). X = @screen_roman_13 2 ?- new(Y, font(screen, roman, 13)). Y = @screen_roman_13 </PRE> <P>The same instance of the reusable font instance is returned on a second attempt to create a font from the same parameters. Examples of classes with this capability are: <A class="" href="summary.html#class:name">name</A>, <A class="" href="summary.html#class:font">font</A>, <A class="" href="summary.html#class:colour">colour</A>, <A class="" href="summary.html#class:image">image</A> and <A class="" href="summary.html#class:modifier">modifier</A>. </DD> <DT><STRONG>object <-convert:</STRONG> <VAR><<VAR>Class-Defined</VAR>></VAR></DT> <DD class="defbody"> object <A NAME="idx:typeconversion:109"></A>Defines what can be converted into an instance of this type. If an instance of this class is requested by a type but another object is provided <font size=-1>XPCE</font> will call this method to translate the given argument into an instance of this class. </DD> <DT><STRONG>object ->catch_all:</STRONG> <VAR><<VAR>Class-Defined</VAR>></VAR></DT> <DD class="defbody"> <A NAME="idx:catchall:110"></A>The <B><CODE>-></CODE>catch_all</B> method defines what happens with messages invoked on this object that are not implemented by any other method. </DD> <DT><STRONG>object <-catch_all:</STRONG> <VAR><<VAR>Class-Defined</VAR>></VAR></DT> <DD class="defbody"> any As <B><CODE>-></CODE>catch_all</B>, but for get-operations. </DD> </DL> <H3><A NAME="sec:3.3.2"><SPAN class="sec-nr">3.3.2</SPAN> <SPAN class="sec-title">Reading cards</SPAN></A></H3> <A NAME="sec:card"></A> <P><A NAME="fig:card"></A> <CENTER> <IMG SRC="card.gif"> </CENTER> <TABLE ALIGN=center WIDTH="75%"><TR><TD> <B>Figure 4 : </B>The Card Viewer</TABLE> <P>The other tools of the manual allow the user to <EM>find</EM> cards with documentation on the topic(s) the user is looking for. The information provided by the summary-lists often suffices for this purpose. Whenever a card is marked with a ``(+)'' in the summary list it may be opened by double-clicking it. This starts the ``Card Viewer'' tool. <A class="fig" href="sec-3.3.html#fig:card">Figure 4</A> is a screendump of this tool showing the `selection' group of class `device'. <P>The ``Card Viewer'' displays the formal information and all available attributes from the card related to the displayed object (method, variable, class, ...). It uses patterns to determine relations to other manual material from the text. Each hit of these patterns is highlighted. When the user double-clicks on highlighted text the ``Card Viewer'' will jump to the related material. <P>If the user double-clicks a group-title in the ClassBrowser, all cards in the group will be displayed in the CardViewer. Some objects share their documentation with another object. Opening the card for such an object will show two titles above the card. The card from which the documentation originates will have an underlined type-indicator. <P>The <B>Goto</B> field allows for switching to a new card. The syntax for this field is similar to <A NAME="idx:manpce1:111"></A><A class="pred" href="sec-D.2.html#manpce/1">manpce/1</A>, <A NAME="idx:tracepce1:112"></A><A class="pred" href="sec-D.2.html#tracepce/1">tracepce/1</A> and <A NAME="idx:editpce1:113"></A><SPAN class="pred-ext">editpce/1</SPAN> predicates description in <A class="sec" href="debugging.html">section 12</A>. It consists of a classname, followed by <CODE>-></CODE> to indicate a send-method, <CODE><-</CODE> for a get-method and <CODE>-</CODE> to specify an instance-variable without considering associated methods. <P>The item performs <EM>completion</EM> bound to the space-bar. The first word is completed to a class-name. The second to a send-method, variable or get-method. Method completion considers inheritance and delegation.<SUP class="fn">6<SPAN class="fn-text">Given the dynamic nature of delegation, the system cannot possibly determine all methods available through delegation. Consider a slot specified with type <A class="" href="summary.html#class:graphical">graphical</A>. The system can infer it will surely be able to use behaviour defined at class <A class="" href="summary.html#class:graphical">graphical</A>. If at runtime, the slot is filled with a <A class="" href="summary.html#class:box">box</A>, all methods defined at class box will be available too.</SPAN></SUP> <H3><A NAME="sec:3.3.3"><SPAN class="sec-nr">3.3.3</SPAN> <SPAN class="sec-title">Search tool</SPAN></A></H3> <A NAME="sec:searchtool"></A> <P>The search tool is shown in <A class="fig" href="sec-3.3.html#fig:searchtool">figure 5</A>. It allows the user to search through all <font size=-1>XPCE</font> manual cards in an efficient manner with queries similar to that what is found in <A NAME="idx:WAIS:114">WAIS</A> tools. A search specification is an expression formed from the following primitives: <P> <UL> <LI><I>Word</I><BR> Specifies all cards containing a word for which the search specification is the <EM>prefix</EM>. Case is ignored. <LI><I><TT><</TT>Word<TT>></TT></I><BR> Specifies all cards that contain the indicated word. Case is ignored. <LI><I>Expr1 <TT>and</TT> Expr2</I><BR> Specifies all cards satisfying both conditions. <LI><I>Expr1 <TT>or</TT> Expr2</I><BR> Specifies all cards satisfying either condition. </UL> <P>As a special shorthand, just specifying multiple words refers to all cards containing all these words. <P>If the user stops typing for more than a second, the system will parse the expression and display the number of matching cards. <P>The <A class="" href="summary.html#class:browser">browser</A> window on the left contains all words occurring anywhere in the manual. The window on the right is used to display the card summaries of all matching cards. <P><A NAME="fig:searchtool"></A> <CENTER> <IMG SRC="searchtool.gif"> </CENTER> <TABLE ALIGN=center WIDTH="75%"><TR><TD> <B>Figure 5 : </B>Manual search tool</TABLE> <H3><A NAME="sec:3.3.4"><SPAN class="sec-nr">3.3.4</SPAN> <SPAN class="sec-title">Class hierarchy</SPAN></A></H3> <A NAME="sec:classhierarchy"></A> <P><A NAME="fig:classhierarchy"></A> <CENTER> <IMG SRC="classhierarchy.gif"> </CENTER> <TABLE ALIGN=center WIDTH="75%"><TR><TD> <B>Figure 6 : </B>Class Hierachy Tool</TABLE> <P>The ``Class Hierachy'' tool shown in <A class="fig" href="sec-3.3.html#fig:classhierarchy">figure 6</A> may be used to get an overview of <font size=-1>XPCE</font>'s class hierarchy or to find the (inheritance) relations of a particular class with other classes. Note that <font size=-1>XPCE</font>'s inheritance hierarchy has a technical foundation rather than a conceptual. Super-classes are motivated by the need for code-sharing. <P></BODY></HTML>