This section describes the basic interface predicates. These predicates reside in the library module `pce', which is loaded when Prolog is started with PCE loaded on top of it.
new(chain)is translated to an empty chain object rather then the atom
Below we illustrate the use of embedded new/2 terms in InitArg to get access to the reference of in-line created objects. The examples are functionally equivalent.
1 ?- new(@icon_viewer, dialog('Icon Viewer 1')), new(P, picture), send(P, below, @icon_viewer), new(TI, text_item(name, '', and(message(P, display, @arg1), message(@arg1, recogniser, new(move_gesture))))), send(TI, type, bitmap), send(@icon_viewer, append, TI), send(@icon_viewer, open). 2 ?- D = @icon_viewer, new(D, dialog('Icon Viewer 1')), send(new(P, picture), below, D), send(D, append, new(TI, text_item(name, '', and(message(P, display, @arg1), message(@arg1, recogniser, new(move_gesture)))))), send(TI, type, bitmap), send(D, open).
with a variable reference argument is equivalent to invoking `Class
InitArgs ...'. The arguments needed to instantiate a class are defined
->initialise method of this class. See
also section 3.3.1.
The predicate send/[2-12] fails with an error message if one of the arguments cannot be translated or there is a type-error or an argument-error. The method itself may also produce error messages. This predicate only succeeds if the requested method was executed successfully.
Trailing arguments that can handle @default (indicated by square brackets in the type declaration) may be omitted.
If the method accepts many arguments of which most are default, using the named argument convention may be preferred. For example:
..., send(Graphical, graphics_state, colour := red), ...,
The first form using
Selector(Argument...) is the
principal form. The second is translated by the XPCE/Prolog
macro-layer and available for compatibility and style-preference.
If the return value is a XPCE integer, real object or name object, it is unified with a Prolog integer, float or atom. Otherwise if the Prolog return argument is a variable or a term @/1 it is unified with the object reference. Otherwise the Prolog argument should be a compound term. Its functor will be compared with the class-name of the XPCE return value. The arguments will be unified in the same manner with the term-description arguments as declared with the class. Examples:
1 ?- get(@pce, user, User). User = fred 2 ?- get(@display, size, Size). Size = @474573 3 ?- get(@display, size, size(W, H)). W = 1152, H = 900
It is not advised to use the latter construct for other objects than elementary objects such as point, area, size, string, etc..
->free to Reference if it is a valid reference. Defined as
free(Ref) :- object(Ref), !, send(Ref, free). free(_).
This definition implies free/1
only fails if the object may not be freed (see `object
The *_super calls are macro-expanded to send_class/3 or get_class/4. They must appear within a XPCE class definition. Though not enforced, using any of these predicates or macros outside the context of a method-definition should be considered illegal. See chapter 7 for further discussion on defining classes and methods.
1 ?- new(P, point(100,100)). P = @235636/point 2 ?- free(@235636). 3 ?- object(@235636). ---> fail 4 ?- new(S, size(50,50)). S = @235636/size
->free is invoked on an object that has no
references, its memory will be reclaimed immediately. As long as the
memory has not been reused object/1
is guaranteed to fail. If the memory is reused for storing a new object object/1
will succeed, but point to another object than expected. Finally, the
memory may be reused by a non-object data structure. In this case object/1
only applies heuristics to detect whether the memory holds an object.
See also section 12 and section
object(Ref, Term) :- object(Ref), get_object(Ref, self, Term).
:- pce_global(@succeed, new(and)). :- pce_global(@event_receiver, new(@event?receiver)). :- pce_global(@select_recogniser, make_select_recogniser). make_select_recogniser(R) :- new(G, handler_group), send_list(G, append, [ click_gesture(left, '', single, message(@event_receiver?device, selection, @event_receiver)) , click_gesture(left, s, single, message(@event_receiver, toggle_selected)) ]).
See section 6 for more examples.
This predicate works on any object that implements the *as_file
methods. Currently this is only implemented for class text_buffer. See
->truncate_as_file' and `text_buffer
The stream handle is discarded using Prolog's close/1 predicate. For example, to write to a view, one could use:
... pce_open(View, append, Stream), format(Stream, 'Hello World~n', ), close(View), ...
See also `text_buffer
Reading from a stream is used by the PceEmacs editor to verify the
syntax of an entered clause.
<-last_error' holds the id of the trapped error. Any other error that occurs during the execution of Goal will be handled by XPCE's normal error handling mechanism. See section 10.8.
Different Prolog implementations to which XPCE has been connected provide a different library structure and offers different means for accessing library predicates. For this reason, XPCE introduced the require/1 directive. This directive is the preferred way to import library predicates. Below is a typical declaration of an XPCE/Prolog module:
:- module(mymodule, [myapp/0]). :- use_module(library(pce)). :- require([ member/2, send_list/3 ]).
Note the command Pce/PceInsertRequireDirective in PceEmacs Prolog mode, which automatically determines the required require-directive for the current module-file.
auto_call(Goal) :- strip_module(Goal, Module, Predicate), functor(Predicate, Name, Arity), require(Module:[Name/Arity]), Goal.