Class pce has one predefined instance, called @pce. The object @pce provides operations to control the overall environment of PCE as well as operations that are not a clear action on some object.
@pce is also used to control the debugger/tracer; handle exceptions, etc.
~/.xpce. On Windows it is
<appdata>/xpce, where <appdata> is the directory from
CSIDL_APPDATA. This directory typically contains the following files:
.pl).
Applications using the pce_config.pl
library create additional files.
SIGQUIT So, ^\ can be used to generate an error SIGILL Illegal instruction SIGEMT Emulator trap SIGBUS Bus error (illegal aligned pointer) SIGSEGV Segmentation fault (out-of-range pointer) SIGSYS Bad argument to system call SIGPIPE Broken pipe SIGFPE Floating point exception
See your Unix manual for details on these signals.
Defaults: The initial value is @off (do not trap signals). Some host languages switch this flag to @on at initialisation time.
pce ->trace' and program_object->trace‘.
Defaults: @off (no debugging)
|char_array->load_defaults,
class class_variable
and class_variable/4.
The default value is the file("$PCEHOME/Defaults")
A runtime application that wishes the defauts to be in the resource file should do:
resource(pce, defaults, pce('Defaults')).
:- initialization
send(@pce, defaults, rc(pce, defaults)).
->exception.
Each entry of this sheet maps an exception-name onto a code
object which is executed when the corresponding exception occurs. The
argument bindings for
@arg1, ... are
the second, ... argument passed to pce->exception.
The following exceptions are currently defined:
<-object
Parameters:
@arg1: class name
<-convert
if the error id is not in
@errors. If
defined, it should create an error
object with the requested identifier.
Parameters:
@arg1: identifier of missing error object.
.e. @pce),
but the reference is unknown. Parameters:
@arg1: reference name
@arg1: The existing reference name
->initialisation
method for some instance failed. Parameters:
@arg1: The (partial) instance @arg2 ... The arguments given to ->initialise
@arg1 Exit status of the process
Filled by pce->exit_message.
.ps
<HOME>/prolog/lib
containing the PCE libraries (manual, demo programs, pcedraw, utilities).
->catch_error
and
pce->catch_pop.
win32 The actual version could not be retreived win32s XPCE dowsn't run on this .. win95 DOS-7 based Windows (95,98,ME,...) winnt NT based Windows (NT, 2000)
See also pce<-machine, pce<-window_system, pce<-window_system_revision
and pce->has_feature.
->report
mechanism to report the error and the tracer will not be trapped. The
latter behaviour is the only behaviour supported by the runtime system.
See also pce->trace.'4.4.3, September 1992'
Its format:
These fields are followed by an indication of the time of release.
If the pce<-version
is requested with the argument name, the time of the
release is omitted (i.e. 4.4.3).
Finally, if the version is requested as a number, the value 10000 *
major + 100 + minor + patch is returned.
->forward
behaviour
->forward, put pushing and popping
the argument stack outside the loop.
send() virtual machine operation
|chain]<-last_error.
The method pce->catch_pop
restores the catched errors to the state before invoking pce->catch_error.
The prolog predicate pce_catch_error/2 provides an interface:
?- send(@pce, hello, pce).
[PCE error: send: No implementation for: @pce/pce ->hello
in: send(@pce/pce, hello, pce)]
PCE: 1 fail: send(@pce/pce, hello, pce) ?
While
?- pce_catch_error(no_behaviour,
send(@pce, hello, pce)).
No
After which
?- get(@pce, last_error, E). ==> E = no_behaviour
Note that errors with pce<-feedback:
throw can also be handled using Prolog exception-handling.
->catch_error’.
->confirm
on
@display.
Otherwise the text is formatted on the terminal and PCE requests the
user to type y or n. Used infrequently.
xterm(1) application. The latter is
verified by checking the environment variable TERM for the value xterm.
See also pce->show_console.absolute_position Translation of relative coordinates allocate memory allocation compute Graphicals ->request_compute and ->compute cursor Determining visual cursor dialog Dialog layout editor Various editor happenings event Various things with events fill Filling text (editor) flash Flashing graphicals float Floating point conversions focus Event focusing fragment Fragment handling frame Various frame events gc Incremental garbage collection get_xref Maintenance of X id database image Some image functions clone Cloning objects menu Menu repaint message Execution of message objects obtain Failing obtainers path Smoothing paths popup Popup menu's post Event posting (event ->post) postscript PostScript generation process Actions on handling subprocesses redraw Repaint management save `Object ->save_in_file` scan `char_array <-scan` scroll Scrollbar handling shift text_image shifting of lines spatial execution of spatial constraints text Updating of text_images undo Undo in text_buffers xref X window references database
pce->nodebug_subject
removes an item from this list.
User code may exploit the same mechanism and test whether debugging a
subject is enabled using pce->debugging_subject.
->debug_subject
and pce<-debugging
is @on. This
test may be used in application code to exploit this debugging mechanism
of XPCE.
In a runtime system this method is available, but fails always.
code
when an action is performed that requires details of the class (such as
creating an instance).
All, except for some vital kernel classes of XPCE itself have been declared this way to delay/avoid building the class-definitions.
See also class->realise.
hostAction(HOST_HALT). With a completely
implemented interface, this in return will call PCE's cleanup functions
registered with
hostAction(HOST_ONHALT) and terminate the process.
exit() with the
argument status.
With a proper implemented interface, the normal termination will
execute the pce<-exit_messages,
kill possible subprocesses and terminate the process. The termination
process is the same regardless of whether the
host-language
terminate functions is called or pce->die
is invoked.
Defaults: The default termination status is 0 (indicating success).
<-exception_handlers.
Bugs: The exception mechanism is rudimentaly.
<-exit_messages.
That is: the last exit message registered will be executed the first.
->show_console:
open.
Expose the console window of XPCE. Only implemented for the
MS-Windows version. See also pce->console_label.
-featuresThis method is safe: the name-base may be manipulated during its
execution. Tbe code will not be executed for named added during the
execution of pce->for_name.
.g. @pce, @arg1).
The exit status of the code is ignored. Arguments:
@arg1 Name of the global object (e.g. `pce`, `arg1`).
This method passes the reference-names rather than the objects themselves. As various of them are functions, good understanding of the expansion-rules for functions is necessary.
?- send(@classes, for_all,
message(@pce, format, '%s\t%s\n',
@arg1, @arg2)).
See string->format
for a description of the format specification.
->show_console:
iconic.-version->inform.
Otherwise pce->format
the information on the terminal.
<-core_wasted.
<-defaults.
A Defaults file consists of statements. Each statement is on a
seperate line. A statement may be split over several lines by preceeding
the newline with a backslash (\). The exclamation mark (\!)
is the line-comment character. All input from a ! upto the following
newline is replaced by a single space-character. Empty lines or lines
containing only blank space are ignored.
Default files may include other default files using the statement
<class>.<class-variable>: <value>
Where <class> denotes the name of the class, or * to indicate
the default applies for any class defining this class-variable. If both
forms are found, the statement with the explicit class-name
is used. <class-variable> denotes the class-variable name. <value>
is the default value of the class-variable. The syntax for <value>
is similar to the arguments of send/[2-12]. The (informal) syntax for <value>
is below.
<Any> := <int>
| <float>
| <Name>
| @<Name>
| <Chain>
| <Object>
<Chain> := [ <Any> {, <Any>} ]
| [ {<Blank>} ]
<Object> := <ClassName>()
| <ClassName>(<Any> {, <Any>})
| <PrefixOp> <Any>
| <Any> <InfixOp> <Any>
| <Any> <PostfixOp>
| "<String>"
<String> := {<CharNotDoubleQuote>|""}
<Name> := <Letter>{<Letter>|<Digit>}
| '{<CharNotSingleQuote>|''}}'
-language
interface at initialisation time if the
host-language
wishes to access XPCE from multiple threads. The
host-language
interface should use the functions pceMTLock() and
pceMTUnlock() as wrappers around access to XPCE.
This method fails with an error when invoked too late (for the X11 version this implies after the window system has been initialised). It fails silently if this version of XPCE is not compiled to support multi-threading.
XPCE multi-threading support is currently rather limited: it consists
of one global recursive mutex that ensures the system is
activated in a single-thread only. This mutex should be locked by the host-language
around access to the basic operations (send, get, new and
object) and is locked by XPCE itself for any event processed.
XPCE call-back occurs in the thread waiting for events. In the normal
XPCE/Prolog context this is the main-thread. As the system is locked
during event-processing, smooth interactive operation requires
event-processing to be completed quickly. If an event causes a long
operation to start the host-language
should run this operation in another thread.
->debug_subject
->name_reference.
hostQuery(HOST_CONSOLE) request. The meaning of
the argument:
library(pce_main)
for some standard predicates to realise the toplevel control loop).
new(@succeed, message(@pce, succeed)).
Note that the following is faster:
new(@succeed, new(and)).
-language
keywords are most naturally mapped on PCE-names. This method, which is
normally send by the LISP interface right after PCE has been initialised
performs the following actions:
Defaults: The default word separator is’_’(unchanged).
Bugs: To get compatible resource-handling, resources defined
as type name will be mapped to uppercase (and have their
word-separator changed) when converted. Also, generated
object-identifiers (for fonts, classes, etc.) will be mapped to
upper-case. The run-time generated keywords may lead to unexpected
behaviour.
Finally, when converting of a bitmap- or image-name
to a filename, the name is downcased. This makes it implossible to use
automatic conversion when the file-name
consists of uppercase characters.
->write
and terminates the line with a newline. Useful for dumping information
to the terminal:
send(@images, for_all, message(@pce, write_ln, @arg1, @arg2)).
Dumps a map of all named image objects (which is initially empty).
answer
stack. They are deleted from this stack iff
->lock_objected
(or given a named reference)
Both event-call-back and the execution of a PCE method mark and rewind this stack. Thus
?- new(X, point).
Creates a point and leaves it on the answer-stack, while
?- [user]. create_point :- new(X, point). ^D ?- send(@prolog, create_point).
Creates a point, pushes it on the answer-stack. Then rewinds this
stack on exit of the host->create_point,
garbage collection the point
object. Thus
?- pceusage(send(@prolog, create_point)).
<-convert
provides access to type<-check,
the PCE type checking and conversion system. The first argument is the
object to be checked/converted. The second is the type that should be
met.
Equivalent to type<-check,
but generally more comfortable as this method will automatically
translate a type specification into a type
object.
The following example converts anything convertible to an integer to an integer:
convert_to_int(Any, Int) :-
get(@pce, convert, Any, int, Int).
After which
convert_to_int('78', X) ==> 78
convert_to_int(string('1992'), X) ==> 1992
convert_to_int(hello, X) fails
convert_to_int(100, X) ==> 100
-language
is not included
<-core_wasted
@see tool Statistics
Note that the host language is normally part of the same process.
ctime(3)
and returns the result as a string
object. The returned string has no trailing newline (as its Unix
counterpart). Its format is:
Sun Sep 16 01:03:52 1973
See also class date.
->free’d
by the user, but are still referenced. To avoid crashes, the memory
belonging to such objects is not freed as long as there are references
to the object.If name is PCEHOME and this is not defined as a
Unix environment variable, the value of pce<-home
is returned.
Diagnostics: If the variable is not defined pce<-environment_variable
fails silently.
|functionnew()). @pce pce<-instance
converts the first argument into a class. This process deals with
handling class-names rather then class
objects and invokes the autoloader if the class does not yet exist (see pce_autoload/2
and
pce<-exception_handlers).
Next, the method class<-instance
is called to create the new instance.
The following function creates a new point object each time it is evaluated:
?(@pce, instance, point, 4, 5)
See also class create, class<-instance
and @vmi_new.
int or number. Current range:
-2^29 ... 2^29 - 1 (-536870912 ... 536870911)
<-max_integer
|name -> object=unchecked?- get(@pce, object_from_reference, prolog, Obj) Obj = @prolog
This is the inverse of object<-object_reference.
See also object<-convert.
These methods are used seldomly by application programmers.
get(class(object), no_created, @on, Count)
See class<-no_created
and class<-no_freed.
-no_freed
@see pce<-objects_allocated
@see tool Statisticsperror(2).
Its use is not encouraged.
?- new(TmpFile, file).
See file->initialise.
<-kind,
but have no initialised class associated with them. A name that is not
the name of an existing class will be converted into a type of kind class.
This type is only useful after the class is actually created. This
mechanism allows the programmer to refer to classes as a type before
defining them.
The most likely cause of this trouble is a misspelled type-name or a forgotten class definition.
getlogin()
or password information from the current UID. On Windows it examines the
environment variable %USER%.
See also pce<-user_info.