class -> send_method | Describes a send-method |
class <- get_method | Describes a get-method |
class - variable | Describes an instance variable |
For example:
?- manpce(button->message).
will start the CardViewer on this method. See also editpce/1.
Sending a message is composed of the following steps:
If all these steps succeed and the implementation succeeds, send/2
succeeds. If anything fails, an error is raised through
object->error.
If the error has
error<-feedback: throw, a Prolog exception is raised;
otherwise XPCE itself reports the error.
See also get/3, send_class/3, send_super/2, new/2 and free/1.
Class must be a super-class of the class to which Object belongs.
This construct is normally not used directly. Instead, send_super/2 should be used, which is translated at compile time to a proper send_class/3 call.
:- pce_begin_class(myapp, frame).
initialise(A) :->
send_super(A, initialise, 'My 1st application'),
send(A, append, new(D, dialog)),
...
See also send_class/3, send/2 and get_super/3.
send_list([Box,Circle], pen, 2).
is equivalent to
send(Box, pen, 2), send(Circle, pen, 2).
send_list/3 is often used to append menu items to a menu:
send_list(Menu, append,
[ menu_item(quit, message(@arg1, free))
, menu_item(hide, message(@arg1, hide))
]).
In general, get-behaviour does not modify the object base, with the possible exception of creating new instances that serve as the answer to the query. Send-behaviour is intended to modify the receiving object; nothing in the implementation enforces this, and some get-behaviour has side-effects beyond creating the answer.
The answer of get-behaviour can be an attribute of an object (e.g.
graphical<-area
returns the area object associated with the graphical), or it can be a
freshly created object (e.g.
graphical<-size
returns a new size object reflecting the size of the graphical). The
documentation is the only source for this detail.
Knowing this can be important. For example, modifying the size object
returned by graphical<-size
is valid but does not affect the graphical. Modifying the area returned
by a graphical however will leave the graphical in an incoherent state.
Under normal circumstances, there is no need to ->free the object returned by a get-operation. If the object is not referred to, it will automatically be discarded by the incremental garbage collector once its scope of creation ends.
See also get_class/4, get_super/3, get_object/4 and get_chain/3.
get_chain(Ref, Selector, List) :-
get(Ref, Selector, Chain),
chain_list(Chain, List).
->for_all,
chain<-find_all,
etc.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).
In all other cases this predicate fails silently. Note that, if the term is of the form @<integer>, heuristics are used to determine whether the indicated memory location refers to a valid object.
object/2 converts an object into a descriptive term. See the User Guide for complete information.
See also @pce<-object_from_reference and
object->name_reference.
Default may take the form
resource(Object, ResourceName)
in which case Value will be bound to the result of
object<-resource_value: ResourceName.
Note that the message-passing kernel passes omitted arguments as
@default. Example:
image(R, I:[image]) :->
"Set image of object"::
default(I, image('pce.bm'), Image),
...
->_check
on this chain. This finds all visual objects (via @display_manager), all
classes (via @classes) and all other globally defined objects as well as
objects referred from them.
@pce<-unresolved_types).
Types with a Prolog pce_autoload/2
declaration are omitted.
The predicate succeeds if no errors were found and fails otherwise. Error messages are written to the host-language window. See also object->_check.
A typical setup has the background thread compute a result and ask the GUI to present it. The result may be passed as an argument to Goal or held in dynamic predicates. Both threads run in parallel, so update/read of shared dynamic data must be properly coordinated. To wait for the GUI to complete the calling thread can use a message queue:
sync_call(Goal) :-
thread_self(Me),
in_pce_thread(make_sync_goal(Goal, Me)),
thread_get_message(sync_goal(Result, Binding)),
( Result == true
-> Goal = Binding
; Result == exception
-> throw(Binding)
).
make_sync_goal(Goal, Thread) :-
( catch(Goal, E, true)
-> ( var(E)
-> Msg = sync_goal(true, Goal)
; Msg = sync_goal(exception, E)
)
; Msg = sync_goal(false, _)
),
thread_send_message(Thread, Msg).
Works on any object that implements the *_as_file
methods. Currently those are the subclasses of class source_sink:
<-read_as_file
<-size_as_file
->truncate_as_file
->write_as_file
In addition, the following methods provide partial support:
char_array<-read_as_file,
char_array<-size_as_file and
stream->write_as_file.
The stream handle is discarded with Prolog's close/1 predicate. For example, to write to a view:
pce_open(View, append, Stream), format(Stream, 'Hello World~n', []), close(Stream),
See also text_buffer->format.
Reading from a stream is used by PceEmacs to verify the syntax of an
entered clause.
pce_server/1
implements a simple generic server. Its sources may be used as a
starting point to write dedicated servers. The Unix command xpce-client
may be used to connect to XPCE sockets. Below is an example of using
this library:
% xpce <banner> ?- pce_server(gnat). yes % on another terminal on the same machine % xpce-client gnat (pce) send(new(P, picture), open). P = @364728 (pce) exit %
The reserved command exit closes the server socket --
only this connection.
.path
class variable, adding the path Spec expanded through
Prolog's path-specification mechanism to the image search path. See also image->load,
image->initialise
and image<-convert.
It also prepends Spec to the file_search_path/2
specification for image. Normally used as a directive.
@pce<-last_error holds the id of the trapped error. Any
other error encountered while Goal runs is handled by XPCE's
normal error-handling mechanism.
Exceptions are repairable errors. Exception handlers may be
installed in @pce<-exception_handlers.
The first argument is the global reference being declared. The second is either the name of a predicate capable of creating the object, or a term wrapped in new/1 representing the object.
Examples:
:- pce_global(@center,
new(spatial(xref = x+w/2, yref = y+h/2,
xref = x+w/2, yref = y+h/2))).
:- pce_global(@pce_icon, make_pce_icon).
make_pce_icon(Ref) :-
new(Ref, bitmap),
send(Ref, load, 'pce.bm').
auto_call(Goal) :-
functor(Goal, Name, Arity),
pce_require([Name/Arity]),
call(Goal).
Prolog systems with a library-predicate autoloader provide an empty definition for this predicate. Other Prolog systems can search the library index and call use_module/2 to import the predicates.
Term defines both the class name and the term structure when an instance of the class is transformed into a Prolog term. The term has the form
+Class(...+Selector...)
where Class denotes the class name and the optional list
of selectors gives the (argument-free) get-behaviours used to obtain the
arguments of the term representation. See
Object->Term.
The description term may be prefixed with the meta-class to be used.
For example, the following declaration ensures the meta-class is my_meta_class:
my_meta_class:myobject
Super is the name of the super-class. It must be the name of a defined XPCE class or a class declared via pce_autoload/2.
Doc is an approximately 40-character summary documentation string visible in the manual tool.
XPCE classes are not created immediately when a Prolog file holding a class definition is loaded. Instead, the specification is translated into Prolog facts; if a reference is later made to the class, the XPCE class counterpart is created. This means it is not possible to invoke behaviour on the class being defined using ordinary Prolog directives.
A goal declared with pce_class_directive/1
is stored with the Prolog class definition. When the class object is
actually created the declared class-directives are executed. During the
execution
@class is a var object referring to the class being built.
The preprocessor automatically tags directives of the form
:- send(@class, ...) with this directive.
Method declarations following this directive get the specified group identifier, which gives a better overview of the class through the manual tools (ClassBrowser).
The value @default (pushed by pce_begin_class/[2,3])
assigns a method to the same group as an inherited method of the same
name, or the group miscellaneous if no such method exists.
The directive has no semantic implications.
See also pce_begin_class/[2,3], pce_extend_class/1
and
method<-group.
This declaration supersedes resource/4. Unlike with resource/4, Default is a term that is translated as the arguments to send/[2-12].
send and get
operations. Valid values are:
See also class->instance_variable.
->handle.<->delegate).
Expanded by the XPCE/Prolog class compiler.Suppose an application requires specialisations of several primitive graphical classes. Three ways are available: use pce_expand_class/1 on one of the super-classes (unsafe, as the methods become available to all users), make subclasses of every class needing the extension and duplicate the source (bad: hurts maintenance), or use a class template.
To use a template: first create a subclass of class template
and define all variables and methods that need to be attached to the
target class. Then write:
:- pce_begin_class(mybox, box). :- use_class_template(my_graphical_extensions). :- pce_end_class.
This behaves exactly as if all text defining
my_graphical_extensions were duplicated at the
use_class_template/1
call. The method implementation (the Prolog predicate) is shared between
the classes that use the template.
Note that you can normally not create instances of the template class itself since it may lack methods that need to be refined in the target classes. Note also that you cannot further refine a method imported from a template in the same class -- the import behaves like text duplication, so a new definition simply overwrites the one from the template. You can refine the method in a subclass.
classname | Edit the class |
class->send_method | Edit a send-method |
class<-get_method | Edit a get-method |
class-variable | Edit the class that defines the variable |
For class-variable, if the variable is inherited from
the specified class the editor opens on the class the variable is
inherited from.
->selector or class<-selector.
Example:
?- tracepce(box->event). Trace method: graphical ->event
See also spypce/1 and breakpce/1.
->break,
spypce/1
and nobreakpce/1.->send_method
or
class<-get_method.
The predicate locates the method, determines the Prolog predicate
implementing it and calls spy/1
to put a Prolog spy-point on that predicate.
Can only be used on methods defined using the Prolog class definition mechanism realised with pce_begin_class/[2,3] and pce_end_class/0. See also tracepce/1 and breakpce/1.