1.117.2 Send methods

pce ->banner:

Writes a standard banner message for PCE, indicating version, hardware, operating system, the hostlanguage to which PCE is connected and a copyright notice.

See also

- pce-version
- host-system

pce ->bench: message=message, times=int, how={forward,execute,qad,send}

Sends messages in a tight loop for benchmarking purposed. First argument is the message that is executed repeatedly. Second argument is the number of iterations. Last argument indicates which part of the message invocation is placed in the loop. The rest is moved out of the loop. Its values are:

forward

Invoke the full code->forward behaviour

execute

As pce->forward, put pushing and popping the argument stack outside the loop.

send

Invokes the full send() virtual machine operation

invoke

Move method-resolution outside the loop. Typechecking the arguments and starting the implementing code is all which is left inside the loop.

See also

pce<-cpu_time

pce ->catch_error: identifier=[name|chain]

Inform PCE's error recovery mechanism that the application takes care of the indicated error, one of the indicated errors or all errors (@default). If such an error occurs the method normally fails silently, setting pce<-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.

See also

- pce->catch_pop
- pce->catched
- pce-catched_errors
- class error

pce ->catch_pop:

Restores the catched errors to the state before the latest‘pce pce->catch_error’.

See also

- pce->catch_error
- class error

pce ->catched: identifier=name

Test if the indicated error_id is currently catched. If this method succeeds, raising the indicated error will make the method fail rather than printing an error-message.

See also

- pce->catch_error
- class error

pce ->confirm: format=char_array, argument=any ...

If pce is connected to an open display, invokes display->confirm on @display. Otherwise the text is formatted on the terminal and PCE requests the user to type y or n. Used infrequently.

See also

- pce->inform
- display->confirm

pce ->console_label:

Set the label of the console-window from which XCE was started. Currently only implemented for the MS-Windows version of XPCE, and XPCE started from a Unix xterm(1) application. The latter is verified by checking the environment variable TERM for the value xterm. See also pce->show_console.

pce ->debug_subject: subject=name

Prints messages to the terminal to debug certain aspects of the system. The debug_id's supported change quickly from release to release. Below is a tentative list.

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.

See also

- display->open
- pce->nodebug_subject
- topic Tracing
- pce->debug

pce ->debugging_subject: subject=name

Test whether the named subject is registered using pce->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.

pce ->define_class: name=name, super=name, summary=[string], realise=code

Declare a class without details. The system will run 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.

pce ->die: status=[int]

Exit from the combined PCE/{Prolog,Lisp,...} process indicating status. It performs the following steps:

• Request the host language to exit. This is done using the C-interface call 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.
• If the host refuses to kill the process, PCE itself will call its registered cleanup functions and call 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).

  See also

  pce-exit_messages

pce ->exception: identifier=name, context=any ...

Raise an exception. The first argument is the name of the exception. The remaining arguments are passed as context parameters to the code dealing with the exception. The exception handlers are defined in the sheet pce<-exception_handlers.

Bugs: The exception mechanism is rudimentaly.

See also

- class<-convert
- class<-instance
- pce-exception_handlers

pce ->exit_message: message=code

Prepends code object to pce<-exit_messages. That is: the last exit message registered will be executed the first.

See also

pce-exit_messages

pce ->expose_console:

Backward compatibility equivalent of pce->show_console: open.

Expose the console window of XPCE. Only implemented for the MS-Windows version. See also pce->console_label.

pce ->fail:

Fails immediately without side-effects.

See also

pce->succeed

pce ->feature: any

Inherits description from: pce-features

pce ->for_name: message=code

Executes the code object on all instances of class name. @arg1 is bound the the successive name objects.

This 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.

pce ->for_name_reference: message=code

Executes code for each defined global name reference (e.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.

See also

- pce<-object_from_reference
- pce->rename_reference

pce ->format: format=char_array, argument=any ...

Write formatted output to the main window. Normally only used for reporting debugging information. For example, the following query dumps the mapping represented by the hash_table object @classes to the terminal:

?- send(@classes, for_all,
                message(@pce, format, '%s\t%s\n',
                                @arg1, @arg2)).

See string->format for a description of the format specification.

pce ->iconify_console:

Backward compatibility equivalent of pce->show_console: iconic.

pce ->info:

@see pce-version

pce ->inform: format=char_array, argument=any ...

If there is an open display, run display->inform. Otherwise pce->format the information on the terminal.

See also

- display->inform
- pce->confirm

pce ->initialise:

Called at boot time to create the one-and-only instance called @pce. No more instances may be created.

pce ->list_wasted_core: list_content=[bool]

Dumps a map of wasted-core cells. Wasted core is core allocated, freed and not yet reused. With list_content @on, PCE tries to identify the object deleted. This might lead to crashes. See also pce<-core_wasted.

See also

pce<-core_wasted

pce ->load_defaults: source_sink

Loads class_variable object default values from the given source. Initialisation of XPCE loads pce<-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

• include <file> Default statements are of the form:

  <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>|''}}'

pce ->multi_threading:

Enable thread-safe access to XPCE. This method is normally sent from the host-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.

pce ->nodebug_subject: subject=name

Inherits description from: pce->debug_subject

See also

pce->debug_subject

pce ->rename_reference: old=name, new=name

Change the name of a global reference. This method may be used to rename functions. Its use is strongly discouraged for normal application programmers. See also object->name_reference.

See also

- object->name_reference
- pce->for_name_reference

pce ->show_console:

Control visibility of the console window, if accessible. This call only works in the Windows version of XPCE, and only if the host interface honours the hostQuery(HOST_CONSOLE) request. The meaning of the argument:

open

The console is opened normally. This is the normal situation for program development.

iconic

The console is displayed as an icon. This is useful for testing applications. If the applications behaves strange, the console may be opened to check it for error messages.

hidden

The console windows is removed from the display. This is the normal situation for finished applications. Make sure that the application terminates if the last windows disappears (see library(pce_main) for some standard predicates to realise the toplevel control loop).

pce ->succeed:

Succeeds without side effects. Maybe used if a code objects that always yields success is needed:

new(@succeed, message(@pce, succeed)).

Note that the following is faster:

new(@succeed, new(and)).

See also

pce->fail

pce ->syntax: syntax={uppercase}, word_separator=[char]

Some languages (notably LISP) use case-insensitive keywords, internally represented in upper-case. host-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:

• Map names to uppercase All predefined names of PCE that are strictly lowercase are mapped onto uppercase. This implies the lowercase equivalents disappear: classes, methods, variables and all other constants referred to in this manual will have uppercase names.
• Change the word-separator. The default word separator of PCE,the’_’is replaced by the given character in all name objects.

  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.

  See also

  name->syntax

pce ->write: argument=any ...

Write the arguments using PCE's internal pretty-printing routine. The arguments are separated by spaces. Note that output is generally not flushed.

See also

pce->write_ln

pce ->write_ln: argument=any ...

Writes the arguments as pce->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).

See also

pce->write