Class host normally has only one instance representing the programming environment XPCE is connected to. When connected to Prolog, this object is called @prolog and when connected to Lisp it is called @lisp. Other and multiple languages are possible too, but the interfaces have not yet been defined. As the reference manual is geared towards prolog, we will call the instance of class host @prolog.
The object @prolog/@lisp makes the Prolog/Lisp environment available from XPCE code objects.. It allows PCE to pass control to a Prolog predicate by mapping a send operation onto a call to a Prolog predicate with the same name as the selector of the message.
Thus,
?- send(@prolog, format, 'Hello World~n').
Invokes format(Hello World~n’)’and
thus prints Hello World.
Similar, the get operation asks Prolog to compute a value.
Suppose the predicate plus(+A, +B, -C) exists that adds two
numbers. Then
?- get(@prolog, plus, 1, 2, X).
responds with 3 as expected. Sending messages to @prolog is the common way to link UI objects, existing in PCE to the application, running in Prolog:
new(B, button(help, message(@prolog, give_help)))
will invoke the Prolog predicate give_help/0 if the user presses the Help button.
The communication between PCE and the host language may be
synchronous or asynchronous. See host->call_back
and host<-messages.
<-messages
for later retrieval by the host language.
Using call_back is the default. Synchronous interfacing (no
call_back) harms the functionality as PCE code and host-language
code will not be intercallable. Sometimes necessary when PCE is
connected to a host language that is not capable of handling callback.
Defaults: @on (use call_back based interface).
<-call_back
is @off, a message
object is created from the receiver and arguments and this is appended
to this chain for later retrieval by host<-message.
->banner
that prints the banner message when PCE is started. May be useful to
solve incompatibility problems between, for example, two different
Prolog versions.
All supported languages should be assigned a unique identifier name.
|host_data,
unchecked ...<->call
is used to implement PCE send/get methods in the host language.
It attempts to convert the first argument into a name. This argument is used to find the function in the host language. For all other arguments, the special arguments @receiver, @arg1, ... @arg10 are expanded to their current bindings. No further typechecking is done as this is already done by the send_method that normally invokes this method.
Diagnostics: Fails silently if first argument cannot be
converted into a name or the invoked host-language
function fails.
|host_data ...-language.
As requested by the argument types, functions will be evaluated by this
method. The method host<->catch_all
is invoked by the message passing system if there is no method defined,
thus
?- message(@prolog, my_nice_little_predicate).
calls my_nice_little_predicate/0, but
?- message(@prolog, protect).
Invokes object->protect.
See also host<->call.
->call
|host_data ... -> any->catch_all->dispatch
until there is a message in
host<-messages
and then return the head.