This section describes the four basic Prolog predicates used to control XPCE from Prolog. These four predicates map onto the basic functions of XPCE's virtual machine: creating, destroying, manipulating and querying objects, the basic entities of XPCE.
For those not familiar with this jargon, an object is an entity with a state and associated procedures, called methods. Objects may represent just about anything. In XPCE's world there are objects representing a position in a two-dimensional plane as well as an entire window on your screen. Each object belongs to a class. The class defines the constituents of the state as well as the procedures associated with the object. For example, a position in a two-dimensional plane is represented by an object of class point. The state of a point object consists of its X- and Y-coordinates. A point has methods to set the X- and Y-coordinate, mirror the point over a reference point, compute its distance to another point, etc.
The
predicate new/2
(new(?Reference, +NewTerm)) creates an object in the XPCE
world and either assigns the given reference to it or unifies
the first argument with a XPCE generated reference.
An (object-) reference is a unique handle used in further communication
with the object. Below are some examples (?- is the Prolog
prompt):
1 ?- new(P, point(10,20)).
P = @772024
2 ?- new(@demo, dialog('Demo Window')).
The first example creates an instance of class point from the arguments `10' and `20'. The reference is represented in Prolog using the prefix operator @/1 . For XPCE generated references the argument of this term is a XPCE generated integer value. These integers are guaranteed to be unique. The second example creates a dialog object. A dialog is a window that is specialised for displaying controllers such as buttons, text-entry-fields, etc. In this example we have specified the reference. Such a reference must be of the form @Atom. XPCE will associate the created object with this reference.1Normal applications use almost exclusively XPCE generated references. Many of the examples in this manual are typed from the terminal and Prolog specified references are easier to type.
As illustrated by the examples above, the second argument to new/2 is a term. The principal functor denotes the name of the class of which an instance is created and the arguments are the initialisation parameters. The complete transformation rules are given in appendix D.
As stated before, an object has a state. At creation time, the initial state is defined by the class from which the object is created and the initialisation arguments. In our example, the point is assigned an x-value of 10 and and y-value of 20. The dialog is assigned the label `Demo Window'. A dialog window has many slots2The attributes of an object state are called slots. In other languages they may be called instance variables or fields. The example defines the `label'. All the other slots are set to the default value described in the class definition.
The state of an object may be manipulated using the predicate send/2 (send(+Receiver, +Selector(...Args...))). The first argument of this predicate is an object reference. The second is a term. The principal functor of which is the name of the method to invoke (selector) and the arguments are arguments to the operation.
3 ?- send(@772024, x(15)). 4 ?- send(@demo, append(text_item(name))).
The first example invokes the method `x' of the point object. It sets the instance variable x of the corresponding point object to the argument value. The second example invokes the method `append' of class dialog. This method appends a UI component to the dialog window. The component is specified by the term `text_item(name)', which is converted into an object just as the second argument of new/2. The query below opens the dialog window.
5 ?- send(@demo, open).
If everything is ok, a window as shown in figure 1 appears on your screen. The border (in the figure this is the title-bar displayed above the window) is determined by the window manager you are using. It should look the same as any other window on your terminal. If an error of any kind appears, please refer to appendix F.
| Figure 1 : Example Dialog Window |
The next fundamental interface predicate is get/3. It is used to obtain information on the state of objects. The first two arguments are the same as for send/2. The last argument is unified with the return-value. The return value is normally an object reference, except for XPCE name objects, that are returned as a Prolog atom, XPCE integers (int) that are translated to Prolog integers and XPCE real objects, that are translated to Prolog floating point numbers. Examples:
6 ?- get(@772024, y, Y). Y = 20 7 ?- get(@demo, display, D). D = @display/display 8 ?- get(@772024, distance(point(100,100)), Distance). Distance = 117
The first example just obtains the value of the `y' instance
variable. The second example returns the display object on which @demo
is displayed. This is the reference to an object of class display that
represents your screen.3Prolog
would normally print `@display'. The library(pce_portray)
defines a clause for the Prolog predicate portray/1
that prints object references as `@Reference/Class'.
This library is used throughout all the examples of this manual.
The last example again shows the creation of objects from the arguments
to send/2
and get/3
and also shows that the returned value does not need to be a direct
instance variable of the object. The return value is an integer
representing the (rounded) distance between @772024
and point(100,100).
The second example illustrates that get/3 returns objects by their reference. This reference may be used for further queries. The example below computes the width and height of your screen.
9 ?- get(@display, size, Size),
get(Size, width, W),
get(Size, height, H).
Size = @4653322, W = 1152, H = 900
As a final example, type something in the text entry field and try the following:
10 ?- get(@demo, member(name), TextItem),
get(TextItem, selection, Text).
TextItem = @573481/text_item, Text = hello
The first get operation requests a member of the dialog with the given name (`name'). This will return the object reference of the text_item object appended to the dialog. The next request obtains the `selection' of the text_item. This is the text typed in by the user.
The final principal interface predicate is free/1. Its argument is an object reference as returned by new/2 or get/3. It will remove the object from the XPCE object base. Examples:
12 ?- free(@772024). 13 ?- free(@demo). 14 ?- free(@display). No
The second example not only removed the dialog window object from the XPCE object base, it also removes the associated window from the screen. The last example illustrates that certain system objects have been protected against freeing.