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.
Class(+InitArg...)new(+TermDescription)new(chain) is
translated to an empty chain
object rather then the atom chain.
new(?Reference, +TermDescription)prolog(Term)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).
Using new/2
with a variable reference argument is equivalent to invoking `Class<-instance:
InitArgs ...'. The arguments needed to instantiate a class are defined
by the ->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->protect').
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
If ->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
10.3.3
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
`text_buffer<-read_as_file', `text_buffer<-size_as_file',
`text_buffer
->truncate_as_file' and `text_buffer->write_as_file'.
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->format'.
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.