This file is indexed.

/usr/share/doc/swi-prolog-doc/UserGuide/sec-3.3.html is in swi-prolog-doc 5.6.59-1.

This file is owned by root:root, with mode 0o644.

The actual contents of the file can be viewed below.

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
<!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>-&gt;</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 -&gt;initialise:</STRONG> <VAR>&lt;<VAR>Class-Defined</VAR>&gt;</VAR></DT>
<DD class="defbody">
<A NAME="idx:objectscreating:103"></A>The <B><CODE>-&gt;</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>-&gt;</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 -&gt;unlink:</STRONG> <VAR></VAR></DT>
<DD class="defbody">
<A NAME="idx:objectremove:106"></A>The <B><CODE>-&gt;</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 &lt;-lookup:</STRONG> <VAR>&lt;<VAR>Class-Defined</VAR>&gt;</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 &lt;-convert:</STRONG> <VAR>&lt;<VAR>Class-Defined</VAR>&gt;</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 -&gt;catch_all:</STRONG> <VAR>&lt;<VAR>Class-Defined</VAR>&gt;</VAR></DT>
<DD class="defbody">
<A NAME="idx:catchall:110"></A>The <B><CODE>-&gt;</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 &lt;-catch_all:</STRONG> <VAR>&lt;<VAR>Class-Defined</VAR>&gt;</VAR></DT>
<DD class="defbody">
any As <B><CODE>-&gt;</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>-&gt;</CODE> to 
indicate a send-method, <CODE>&lt;-</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>&lt;</TT>Word<TT>&gt;</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>