3.3 Guided tour

This section provides a `guided tour' through the manual system. If you have XPCE/Prolog 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.

3.3.1 Class browser

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. Figure 3 shows this tool in a typical situation. In this example the user is interested in methods dealing with `caret' in an editor.

The dialog to the left-side of the tool specifies what 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 ->initialise.

Below this text a hierarchy is displayed that indicates the place in the inheritance hierarchy as well as the classes to which messages are delegated (see section C.4). The user can select multiple classes only if there is delegation and the tree actually has branches. Use class editor or class view to explore these facilities. After the user has selected one or more classes, the Apply 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.

The large right window displays a list of matching classes, variables, methods and class-variables. If an item is tagged with a ``(+)'' there is additional information that may be obtained by (double-) clicking the card to start the ``Card Viewer'' (see section 3.3.2).

3.3.1.1 The ClassBrowser dialog

The Class text_item (text-entry-field) may be used to switch to a new class. Note that this text_item implements completion (bound to the space-bar).

The Filter menu filters the candidate objects according to their categorisation. Selecting all switches off filtering, which is often useful in combination with Search. Clicking all again switches back to the old selection of categories. The meaning of the categories is:

• Basic
  Principal methods that are used very often. This is, together with Application, the default selection of this menu.
• Advanced
  Less often used and sometimes complicated methods.
• Rare
  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.
• Internal
  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.
• Basic OO
  Methods intended to be redefined in user-defined classes. See chapter 7.
• Advanced OO
  Methods that may be redefined in user-defined classes, but for which this is far less common.
• Application
  Methods implemented in the host-language.

The Display menu determines the objects searched for. Self refers to the class itself, Sub Class 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.

The Search and ... In 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 Name field is useful to find a particular method if the name (or part of it) is known.

3.3.1.2 Example queries to the classbrowser

Below we illustrate how some commonly asked questions may be answered with the class browser.

• What are variables of a bitmap?
  Select variable in the Display menu, clear Search, and set Filter to All. Then type `bitmap' in Class and hit return. Note that by double-clicking on class graphical in the inheritance display not only the variables of class bitmap itself are shown, but also those of class graphical.
• How can I position the caret in an editor?
  The caret can only be changed using send-methods. Either the name or the summary is likely to have `caret' as a substring. Thus, Display is set to Send Method, Field to Name and Summary, search `caret'.

3.3.1.3 Methods with special meaning

This section describes the role of the `special' methods. These are methods that are not used directly, but they define the behaviour of new/2, type conversion, etc. and knowing about them is therefore essential for understanding an XPCE class.

object ->initialise: <Class-Defined>

The ->initialise method of a class defines what happens when an instance of this class is created. It may be compared to the constructor in C++. Note that double-clicking the class description in the class-browser (top-right window) opens the reference card for the ->initialise method. See also new/2, section 2.2.1.

object ->unlink:

The ->unlink method describes what happens when an instance of this class is removed from the object-base and may be compared to the C++ destructor.

object <-lookup: <Class-Defined>

object If defined, this method describes the lookup an already defined instance instead of object creation. For example

1 ?- new(X, font(screen, roman, 13)).
X = @screen_roman_13
2 ?- new(Y, font(screen, roman, 13)).
Y = @screen_roman_13

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: name, font, colour, image and modifier.

object <-convert: <Class-Defined>

object 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 XPCE will call this method to translate the given argument into an instance of this class.

object ->catch_all: <Class-Defined>

The ->catch_all method defines what happens with messages invoked on this object that are not implemented by any other method.

object <-catch_all: <Class-Defined>

any As ->catch_all, but for get-operations.

3.3.2 Reading cards

The other tools of the manual allow the user to find 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. Figure 4 is a screendump of this tool showing the `selection' group of class `device'.

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.

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.

The Goto field allows for switching to a new card. The syntax for this field is similar to manpce/1, tracepce/1 and editpce/1 predicates description in section 12. It consists of a classname, followed by -> to indicate a send-method, <- for a get-method and - to specify an instance-variable without considering associated methods.

The item performs completion 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.^{6Given the dynamic nature of delegation, the system cannot possibly determine all methods available through delegation. Consider a slot specified with type graphical. The system can infer it will surely be able to use behaviour defined at class graphical. If at runtime, the slot is filled with a box, all methods defined at class box will be available too.}

3.3.3 Search tool

The search tool is shown in figure 5. It allows the user to search through all XPCE manual cards in an efficient manner with queries similar to that what is found in WAIS tools. A search specification is an expression formed from the following primitives:

• Word
  Specifies all cards containing a word for which the search specification is the prefix. Case is ignored.
• <Word>
  Specifies all cards that contain the indicated word. Case is ignored.
• Expr1 and Expr2
  Specifies all cards satisfying both conditions.
• Expr1 or Expr2
  Specifies all cards satisfying either condition.

As a special shorthand, just specifying multiple words refers to all cards containing all these words.

If the user stops typing for more than a second, the system will parse the expression and display the number of matching cards.

The browser 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.

3.3.4 Class hierarchy

The ``Class Hierachy'' tool shown in figure 6 may be used to get an overview of XPCE's class hierarchy or to find the (inheritance) relations of a particular class with other classes. Note that XPCE's inheritance hierarchy has a technical foundation rather than a conceptual. Super-classes are motivated by the need for code-sharing.