H Class summary descriptions

This appendix provides a complete overview of all built-in classes of XPCE. For each class, it presents the name, arguments needed to create an instance, place in the inheritance and delegation hierarchies as well as a summary description. For many classes we added a small illustrative example of typical usage of the class.

The summaries stress on describing what the class is commonly used for and what other classes are designed to cooperate with the class.

The classes are presented in alphabetical order. Some classes that are closely related and have symbol-names (>, +) are combined into one description, sometimes violating the alphabetical order.

Instances of this class are used to specify named arguments, see section 2.4. Example:
send(Editor, style,
     sensitive, style(underline := @on,
                      colour := dark_green)),
Conditional code object that succeeds if both arguments evaluate to the same object. Normally used to specify the conditions of if or while. The following example yields the names of all user-defined classes:
?- new(UDC, chain),
   send(@classes, for_all,
        if(@arg2?creator \== built_in,
           message(UDC, append, @arg1))).
Class ?, pronounced as `obtainer', represents a `dormant' get-operation. Obtainers are commonly used to `obtain' arguments for other code objects. For example:
send(Dialog, append,
     new(TI, text_item(name))),
send(Dialog, append,
     button(ok, message(Dialog, return, TI?selection))),
Class @= assigns a symbolic reference name to the argument object. It is used to define global objects in the class-variable display.initialise. See the system defaults file <pcehome>/Defaults. The following example from Defaults creates the objects @_dialog_bg and @_win_pen depending on whether or not the display is monochrome or colour.
display.initialise: \
        and(_dialog_bg @= when(@colour_display, \
                               grey80, white), \
            _win_pen   @= when(@colour_display, \
                               0, 1))
Code object that executes its arguments one by one. It fails as soon as one of the arguments fails and succeeds otherwise. Commonly used to specify multiple actions for controllers. For example:
get(Dialog, frame, Frame),
send(Dialog, append,
     new(Function, text_item(function))),
send(Dialog, append,
            and(message(Frame, switch_to,
                message(Function, clear)))),
An application object is a visual object used to combine multiple frames. See section 10.5 for a discussion on its usage.
Graphical primitive describing a section from a circle. It may be used to create a pie-chart segment.
?- new(A, arc(100, 20, 50)),
   send(A, close, pie_slice).
Combination of X, Y, Width and Height used by graphical to store the bounding box of the graphical. Also used to communicate with graphical objects and frames about their dimension.
get(Box, area, area(X, Y, W, H)),
Arrow-head. Normally only used implicitly to attach arrows to a line, arc or path, the subclasses of class joint. See `joint->arrows'. arrow can be used directory to create fancy arrows.
?- new(L, line(0, 0, 100, 50, second))
Assign a value to an instance of class var, an XPCE variable. Used to realise variables in compound executable objects.
and(assign(new(C, var), @arg1?controller),
    message(C, ...),
    message(C, ...),
Attributes can be associated with any object to store data related to that object without the need to create a subclass. Normally attribute objects are used implicitly through the method `object<->attribute'.
send(Frame, attribute, visualises, bicycle24)
Super class of method and variable, representing the two types of objects that can realise behaviour in classes. Not useful for the application programmer.
Create a Bezier curve from start to end using one or two control-points (quadradic or cubic Bezier curve). Bezier curves are nice smooth curves departing and arriving in a specified direction. See also path.
Arithmetic conditional code objects. These objects are normally used to specify the conditions of if or while. The following example creates a chain holding all graphicals on a device that either have <-width < 5 or <-height < 5.
get(Device?graphicals, find_all,
    or(@arg1?width < 5,
       @arg1?height < 5),
Arithmetic functions, commonly used for computation of graphical dimensions or to specify spatial relations using class spatial or for simple functional computation from Prolog. For example:
send(Box, height, Text?height + 10),
A bitmap turns an image or pixmap into a graphical object that can be displayed on a device.
?- new(I, image('pce.bm')),
   new(B, bitmap(I)).
A block is similar to and, but provides formal parameters.
?- send(block(new(A, var),
              new(B, var),
              message(@pce, write_ln, A, B)),
        forward, hello, world).

hello world
Class bool defines two instances: @on and @off, representing `true' and `false'. The use cannot create instances of this class.
send(Image, transparent, @on)
Graphical representing a rectangle. Corners can be rounded, the interior can be filled, the texture and thickness of the line can be controlled and a shadow can be defined.
?- new(B, box(100, 50)),
   send(B, radius, 10).
A browser is a window version of a list_browser. A browser visualises a list of dict_item objects. The items are organised in a dict, providing fast access to browser items, even if there are many items in the browser. Individual items may be coloured, underlined, etc. using the style mechanism also available for editor. Columns can be realised using tab_stops on the text_image object that displays the actual text of the browser.
?- new(B, browser),
   send_list(B, append, [gnu, gnat]).
Internal class dealing with selection handling in class list_browser.
A button is a push-button controller. It has an associated message that is executed if the button is activated using the mouse. Inside a dialog, one button can be assigned as `default' button.
?- new(B, button(hello,
                 message(@pce, write_ln, hello))).
Class c is a subclass of class host, providing communication to C and C++ code. It is not used directly by the application programmer.
Class c_pointer encapsulates an anonymous C pointer (void *). It is used to register references to Prolog predicates with XPCE methods. See also chapter 7.
?- pce_predicate_reference(gnat:gnu(_,_), X).
X = @1190997/c_pointer
Class chain represents a single-linked list of arbitrary objects. Chains are commonly used inside XPCE to represent collections. Chains have methods to find elements, sort the chain, delete elements, etc. The predicate chain_list/2 converts between an XPCE chain and a Prolog list. It also provides methods to run code on all elements of the list, which is generally faster than translating the chain to a Prolog list and using Prolog iteration. In the example, `device<-graphicals' returns a chain holding the graphicals displayed on the device. The example changes the font of all objects of class text to `bold'.
send(Device?graphicals, for_all,
     if(message(@arg1, instance_of, text),
        message(@arg1, font, bold))),
Link two objects with a `chain'. If either dies, the other will die with it. See also the library library(hyper) and section 10.11.
Version of a hash_table that allows multiple values to be associated with the same key. The key can be any object. If the value for a key is requested, a chain of values associated with this key is returned.
Class char_array is a super-class of the classes string, representing modifiable text and name, representing read-only unique textual constants. Class char_array defines most of the analysis methods for its two subclasses. Almost the only usage of this class for application programmers is as type specifier for methods in user-defined classes that do not modify textual arguments.
insert_bold_text(Editor, Text:char_array) :->
        "Insert text with fragment of bold text"::
        get(Editor, caret, Start),
        send(Editor, insert, Text),
        get(Editor, caret, End),
        Len is End-Start,
        new(_, fragment(Editor, Start, Len, bold)).
Equivalent to an ellipse with the same <-width and <-height. Not used frequently.
All XPCE classes are represented by an instance of class class. A class is a normal object and can thus be manipulated using send/[2-12], get/[3-13] and new/2. Classes are normally only created and modified through the user-defined class layer described in chapter 7. Get methods on classes are used to extract meta-information about its instances, as exploited by the online manual tools.
?- get(@pce, convert, box, class, ClassBox),
   get(ClassBox, super_class, X).
X = @graphical_class/class.

A class_variable provides can be used to describe class properties as well as to provide access to the XPCE Defaults database. Typically, class-variables are defined similar to instance-variables in the XPCE/Prolog class definition:

:- pce_begin_class(title_text, text).

class_variable(font, font, huge, "Default font for titles").

Class click_gesture is a recogniser that parses button-events to a click. If the click is detected, it will execute the associated message. This class is normally used to make graphical objects sensitive to clicks.
send(Bitmap, recogniser,
     click_gesture(left, double, message(Bitmap, open))),
Class code is a super-class for all `executable' objects. An important sub-class is class function, representing executable objects that yield a value. The method `code->forward: any ...' pushes the var objects @arg1, ... and then executes the code object. Code objects are often associated with controllers to describe the action the controller should perform. They also serve the role of lambda functions. See also section 10.2.
?- send(message(@prolog, format, 'Hello ~w.', @arg1),
        forward, world).
Hello world.
A code_vector is a subclass of class vector that can represent functions as well as normal objects. It is used for packing multiple arguments passed to a variable-argument method. Do not use this class directly. See section 7.5.2.
A colour represents an `RGB' triple.21Colour screens create their colour by mixing the `primary' colours `red', `green' and `blue'. With an `RBG' triple, we refer to a triple of three numeric values representing the intensities of the three primary colours Colours are used as attributes to graphicals, windows, styles and pixmaps
Manipulate the colourmap. Colourmaps are normally left untouched, but using a 256 entries colour palette in MS-Windows they can be used to improve full-colour image rendering. See also section 10.10.1.
A connect_gesture allows the user to connect two graphicals by dragging from the first to the second. This requires two graphicals with handless attached, a link that is compatible with the handles and a connect_gesture associated width the graphical at which the connection should start. The demo program PceDraw as well as the XPCE Dialog Editor described in chapter A exploit connections and connect_gestures.
A connection is a line between two graphical objects that automatically updates on geometry, device and displayed-status changes to either of the connected graphicals. Both of the graphicals must have one or more handles associated with them. The connection can be attached to a specific handle, or to any handle of the proper `handle<-kind'. In the latter case, the system will automatically choose the `best-looking' handle.
A constant is a unique handle. XPCE predefines the following constants: @nil, @default, and from the subclass bool, @on and @off. The use can define additional constants and give them their own unique meaning. The most obvious usage is to indicate a slot that can hold arbitrary data including @nil and @default is in a special state.
?- new(@uninitialised,
                'Not yet initialised slot')).
A constraint is a relation between 2 objects that has to be maintained if either of the objects is changed. The `constraint<-relation' is a description of the relation maintained by the constrained. The system defines the relations identity (both objects have an attribute that has same value) and spatial (general purpose geometry-relation between two (graphical) objects. It is possible to define new relation classes. Constraints are getting out of fashion as XPCE lacks a good mechanism to detect when an object has been changed and therefore evaluates the relation far too often. User-defined classes, possibly combined with hyper objects form an attractive alternative. The following keeps a text centered in a box.
new(_, constraint(Box, Text, identity(center))),
Function that creates an instance of a class. It is often required if a code fragment executed by an `iterator' method such as `chain->for_all' has to create objects. The following code generates dict_items from all send_methods of the specified class and displays them to a browser.
send_methods_of_class(ClassName) :-
        new(B, browser(ClassName)),
        get(@pce, convert, ClassName, class, Class),
        get(Class, send_methods, SendMethods),
        send(SendMethods, for_all,
             message(B, append,
        send(B, open).
A cursor defines the shape that indicates the position of the pointer (also called mouse). The system provides a large set of predefined cursors from X11. The Win32 version adds the standard Windows cursors to this set. Cursors can also be created from an image. The demo program Cursors displays all defined cursors.

Cursors can be associated with graphicals and windows using the ->cursor method. They are also associated to gestures, where they define the cursor that is visible while the gesture is active (i.e. while the mouse-button that activated the gesture is down).

Type-conversion converts names into cursor objects. Explicit creation of cursors is rarely used.

send(Box, cursor, gobbler),
A date objects represents a point in time. The underlying representation is the POSIX file time-stamp: seconds elapsed since 00.00, Jan 1-st, 1970. This limits the applicability of this class to time-stamps of computer resources (files), agenda systems and other domains that do not require a granularity below 1 second or have to represent time-stamps in far history or future. Class date can parse various textual representations into date objects.
?- send(@pce, format, 'It is now "%s"\n',
It is now "Tue Jan 30 14:07:05 1996"
A graphical device is a compound graphical. It is the super-class of class window. It is a sub-class of graphical, which implies devices can be used to create a consist-of structure of graphical objects, giving structure to a diagram. Devices are commonly refined to establish user-defined graphics, see section 10.12. See also class figure.
make_icon(Icon, Image, Label) :-
        new(Icon, device),
        send(Icon, display,
             new(BM, bitmap(Image))),
        send(Icon, display,
             new(T, text(Label, center))),
        send(T, y, BM?bottom_side),
        send(T, center_x, BM?center_x).
A dialog is a window specialised for the layout and message handling required by dialog_items, the super-class of the XPCE controllers. In most cases, controller-windows are created by simply ->appending a number of controllers to a dialog window. The frame- and dialog-layout services take care of proper window sizes and layout of the controllers. Dialog windows are also involved in forwarding ->report messages (see section 10.7) and keyboard accelerators, handling the default button.
:- pce_autoload(file_item, library(file_item)).

edit_file_dialog :-
        new(D, dialog('Edit File')),
        send(D, append,
             file_item(edit_file, '')),
        send(D, append,
             button(edit, message(@prolog, emacs, @arg1))),
        send(D, append,
             button(cancel, message(D, destroy))),
        send(D, open).
A dialog_group is a collection of dialog_items. Dialog groups may be used to realise a (labeled) box around a group of controllers, or to combine multiple controllers into a compound one for technical or layout reasons. See also tab.
Class dialog_item is a super-class of all XPCE controllers. It contains the code necessary to negotiate geometry with its neighbours and enclosing dialog window and provides default fonts for the label, etc. Class graphical defines similar methods to allow integration of raw graphical objects into dialog windows easily, but graphical uses the more expensive object-level attributes for storing the necessary status. Open the class-hierarchy below class dialog_item to find all available controllers.
A dict is an abbreviation of dictionary. Dicts map keywords to dict_item objects. Small dicts simply use a linear list (chain) of items. Large dicts will automatically built a hash_table for quick lookup on the first request that profits from the availability of a table. A dict provides the storage for a list_browser. See also class browser.
Item in a dict. The key is used for lookup. label is the text displayed by the browser (@default uses the key). Object is an arbitrary object that can be associated to the dict. If a dict presents a set of XPCE objects, it is common practice to extract the key and or label from the object and store the object itself in the `dict_item<->object' slot.

A name is translated to a dict_item using the name as key, default label and @nil object. `dict_item<->style' can be used to give an item special attributes (colour, font, etc.).

A directory represents an node (folder) in the computer's file-system. Directories are most commonly used to enumerate the files and sub directories. Directory objects can also be used to create or delete directories from the file-system.
?- get(directory(.), files, Files).
A display represents what X11 calls a screen, a desktop on which windows can be displayed with a mouse and keyboard attached to it. XPCE support multiple display instances under X11 and only the predefined default display @display under Win32. The display implements a number of global operations: getting the screen <-size, showing modal message boxes using ->inform and ->confirm, etc.
?- get(@display. size, size(W, H)).
W = 1024, H = 786
The object @display_manager is the only instance of this class. It represents the collection of available display objects and provides access to the system-wide event-dispatching services. It is the root of the consist-of hierarchy of visual objects as displayed by the Visual Hierarchy tool.
Used internally to handle selection inside a text object. See also the library library(pce_editable_text).
An editor is a general-purpose text editor. It is a graphical. Class view provides a window-based version of the editor. XPCE's editors have commands and key-bindings that are based on GNU-Emacs. Editors are fully programmable. The associated key_binding object parses key-strokes into commands that are defined as methods on the editor.

An editor is a compound object and a subclass of device. The other components are a text_image to form the actual display, a text_buffer to provide the storage for the text, elementary operations on the text and undo, a text_cursor to indicate the location of the caret, and optionally a text_margin to visualise the presence of annotations.

A single text_buffer can be associated with multiple editor objects, providing shared editing.

Editors can handle sensitive regions, different fonts, colours and attributes using fragment objects. All text windows in XPCE's demo programs (PceEmacs, cards from the online help, application help, etc.) either use class view or class editor to display the text.

An elevation object describes an elevated region on the screen. Elevations come in two flavours: as a shadow for monochrome displays and using light and dark edges on colour displays. The elevation object itself just contains the colour definitions. The actual painting is left to the graphical object the elevation is attached to.

Most controllers handle elevations. The only general purpose graphical supporting an elevation is figure.

Elliptical shape. Class ellipse defines similar attributes as box: pen, texture, fill_pattern and shadow. See also circle.
An error object represents a runtime message. Whenever an error is trapped or a message needs to be displayed, the system will invoke `object->error: id, context ...' to the object that trapped the error. If this method is not redefined, the system will report the error using the `object->report' mechanism described in section 10.7. Errors can be prevented from being reported using pce_catch_error/2. The Error Browser of the online manual shows all defined errors.

The development system will report errors that are considered `programming errors' (undefined methods, type violations, invalid object references, etc.) to the terminal and start the tracer. See also section 12.

An event represents an action from the application user: pressing a key, moving the mouse, pressing a mouse-button, or entering or leaving an area with the mouse. The main loop of XPCE will read window-system events from the computing environment (X11 or Win32). If the event concerns a repaint or similar system event, it will be handled appropriately. If it can be expressed as an XPCE event, an event object will be created and send to the window for which the event was reported by the system using the method `event->post'.

Graphical objects and windows can redefine their event handling using two mechanisms: by redefining the ->event method or by associating a recogniser object using `graphical->recogniser'.

Normally, XPCE will read and dispatch events when `there is nothing else to do'. For processing events during computation, see `graphical ->synchronise' and `display->dispatch'.

An event_node is a node in the event `is_a' hierarchy. See the demo program Events. Event-types are normally tested using `event->is_a'.
event(Dev, Ev:event) :->
        "Forward all keyboard events to the text"::
        (   send(Ev, is_a, keyboard)
        ->  get(Dev, member, text, Text),
            send(Ev, post, Text)
        ;   send(Dev, send_super, event, Ev)
Event `is_a' hierarchy. The only instance is @event_tree.
A figure is a refinement of a device. It is a compound graphical, but in addition can define a background, surrounding box with margin, possibly rounded corners and elevation and a clipping region. Finally, figures may be used not only to display all member graphicals, but also to show `one of' the member graphicals only. See `figure->status'. An example of the usage of figures are the `object cards' of the Inspector tool.
An XPCE file object represents a file on the computers file-system. It can be used to specify a file, query a file for various attributes, read a file, etc. See also directory.
?- get(file('summary.doc', size, Size).
Size = 30762
A font is a reusable object that describes the typeface of text. Section 10.9 documents the specification of physical and logical fonts.
send(Text, font, bold),
A format describes the layout of graphicals on a device. It can specify `tabular' and `paragraph' style layout. A format itself just specifies the parameters, `device ->format' actually realises the format.
A fragment defines a region of text in a text_buffer using a start-position and a length. Fragments are automatically updated if the contents of the text_buffer changes. A fragment can be assigned a logical `category', called `style'. The editor visualising the text_buffer maps the style-names of fragments into style objects using `editor->style'.
send(Editor, style, title, style(font := huge)),
new(_, fragment(Editor, Start, Len, title)),
A frame is a collection of tiled windows. Frames handle the layout, resizing, etc. of its member windows. Any XPCE window is enclosed in a frame, though it is often not necessary to specify a frame explicitly. Applications are often implemented as subclasses of frame. Section 10.6 describes the layout of windows inside a frame.
new(F, frame('My application')),
send(F, append, new(B, browser)),
send(new(P, picture), right, B),
send(F, open).
A function is a code object that yields a value when executed. See section 10.2.2.
Class gesture is the super-class for the recogniser classes that deal with the sequence mouse-button-down ... dragging ... mouse-button-up. This super-class validates the various conditions, handles the cursor and focus and activates the ->initiate, ->drag and ->terminate methods that are redefined in its subclasses. This class is often sub-classed.
Specification of get-behaviour that is associated with a class using `class->get_method' or with an individual object using `object ->get_method'. Normally specified through the preprocessor layer defined in chapter 7.
The most generic graphical object. This class defines generic geometry management, display, update, event-handling, etc. This class can be sub-classed to defined specialised graphics. See section 10.12.
Embed a graphical in a parbox. Using left or right alignment, grbox can also be used to have text floating around graphical illustrations. See section 11.10.
A handle defines a typed and named position on a graphical used by connections to connect to. The positions are formulas expressed in the with and height of the graphical. The following definitions are encountered regularly:
:- pce_global(@north_handle,
              new(handle(w/2, 0, link, north))).
:- pce_global(@south_handle,
              new(handle(w/2, h, link, south))).
:- pce_global(@east_handle,
              new(handle(0, h/2, link, east))).
:- pce_global(@west_handle,
              new(handle(w, h/2, link, west))).
A handler is the most primitive recogniser, mapping an event-type to a message. Since the introduction of the more specialised gesture and key_binding as well as the possibility to refine the `graphical->event' method, it is now rarely used.
send(Graphical, recogniser,
             message(Graphical, report,
                     'Hi, I''m %s',
A handler_group is a compound recogniser object. When asked to handle an event, it will try each of its members until one accepts the event, after which it will return success to its caller. The following defines a combined move- an resize-gesture. Note the order: resize gestures only activate close by the edges of the graphical, while move gestures do not have such a limitation.
:- pce_global(@move_resize_gesture,
A hash_table is a fast association table between pairs of objects. For example, @classes is a hash_table mapping class-names into class objects. Names are often used as keys, but the implementation poses no limit on the type of the key.
?- new(@ht, hash_table),
   send(@ht, append, gnu, image('gnu.img')).

?- get(@ht, member, gnu, Image).
Superclass of tbox and grbox dealing with document-rendering. Instances of hbox itself can be used to define `rubber'. See section 11.10 for details.
Class host represents the host-language, Prolog for this manual. It predefines a single instance called @prolog. Sending messages to @prolog calls predicates. See also section 6.
?- send(@prolog, write, hello).
Support class for passing data of the host-language natively around in XPCE. The Prolog interface defines the subclass prolog_term and the interface-type prolog. Details are discussed in the interface definition in section 6.2.
A hyper is a binary relation between two objects. The relation can be created, destroyed and inspected. It is automatically destroyed if either of the two connected objects is destroyed. The destruction can be trapped. Messages may be forwarded easily to all related objects. See also section 10.11.
An identity is a relation that maintains the identify between an attribute on one object and an attribute on another object. Given a slider and a box, the following ensures the selection of the slider is the same as the width of the box, regardless of which of the two is changed. See also constraint.
new(_, constraint(Slider, Box,
                  identity(selection, width)))
Code object implementing a branch. All three arguments are statements. Both `then' and `else' are optional, and when omitted, simply succeed. Class if is most commonly used in combination with the iteration methods such as `chain->for_all':
send(Device?graphicals, for_all,
     if(message(@arg1, instance_of, device),
An image is a two-dimensional array of pixels. Images come in two flavours: monochrome, where each pixel represents a boolean and colour, where each pixel represents a colour. XPCE can save and load both monochrome and colour images. Images are displayed on a graphical device using a bitmap. They are also used to specify cursor objects and the icon associated with a `frame'. See section 10.10.
Subclass of text_item for entering integer values. Has stepper buttons for incrementing and decrementing the value.
Class joint is a super-class of the various line-types with a start- end end-point. It provides the code dealing with attached arrow-heads at either end. As well as common code to reason about the start and end. See also line, path, arc and connection.
A key_binding object parses events into messages or methods on the object for which it is handling events. Key-bindings are used by the classes text, text_item, editor and list_browser. They can be used to defined keyboard-accelerators, though `menu_item<->accelerator' is generally more suitable for this purpose.
A label is a controller used to display read-only text or image. Labels can handle ->report messages. See section 10.7. The code below is the typical way to associate a label that will catch report messages for all windows of the frame in which the dialog is enclosed.
send(Dialog, append, label(reporter)),
Subclass of dialog_group for the definition of compound controllers with a properly aligned label at their left-hand side.

A layout_manager may be attached to a graphical device (including a window) to manage the layout of graphicals displayed on the device, as well as painting the background of the device. See table for a typical example.

Class of the document-rendering system to render a list environment, a sequence of labels and text. See section 11.10 for details.
A line is a straight line-segment with optional arrows, thickness and texture. Class path implements a `multi-line'.
A link is a reusable specification for a connection. Links are used for defining connections and connect_gesture objects. A connection knows about the link used to instantiate it. The example defines the handles, link and connect_gesture and shapes that allows the user to create links with an error from `out' ports to `in' ports.
:- pce_global(@in_handle,
              new(handle(0, h/2, in, in))).
:- pce_global(@out_handle,
              new(handle(w, h/2, out, out))).
:- pce_global(@inout_link,
              new(link(out, in,
                       line(arrows := second)))).
:- pce_global(@link_in_out_gesture,
              new(connect_gesture(left, '',

make_shape(S) :-
        new(S, box(50,50)),
        send_list(S, handle,
                  [@in_handle, @out_handle]),
        send(S, recogniser, @link_in_out_gesture).
A list_browser is a graphical version of a browser, the visualisation of a list of items (dict_item) stored in a dict. The graphical version is sometimes displayed with other controllers on a dialog window. The example created a list_browser holding all current Prolog source files. Double-clicking a file will start PceEmacs on the file. Selecting a file and pressing Consult will (re)consult the file.
show_source_files :-
        new(D, dialog('Prolog Source Files')),
        send(D, append, new(B, list_browser)),
        forall(source_file(X), send(B, append, X)),
        send(B, open_message,
             message(@prolog, emacs, @arg1?key)),
        send(D, append,
                    message(@prolog, consult,
        send(D, open).
Class menu realises various different styles of menus and is the super-class for popup. Basically, a menu presents multiple values, allows the user to choose one or more items (`menu ->multiple_selection') and defines a `look'. The `menu->kind' set the various attributes to often-used combinations. The other `look-and-feel' attributes may be used to fine-tune the result afterwards.

Menu-items can have a textual or image label. Labels can be coloured and specify a different font.

new(M, menu(gender, choice)),
send_list(M, append, [male, female]),
send(M, layout, horizontal),
A menu-bar is a row of pull-down menus. Many applications define a single menu-bar at the top of the frame presenting the various commands in the application.
:- pce_begin_class(my_application, frame).

initialise(F) :->
        send(F, send_super, initialise,
             'My Application'),
        send(F, append, new(MBD, dialog)),
        new(V, view),
        send(new(B, browser, left, V)),
        send(B, below, MBD),
        send(MBD, append, new(MB, menu_bar)),
        send(MB, append, new(F, popup(file))),
        send(MB, append, new(E, popup(edit))),
        send_list(F, append,
                  [ menu_item(load,
                              message(F, load)),
Item of a menu or popup. For popup menus, the items are normally created explicitly as each item often defines a unique command. For menus, it is common practice to simply append the alternatives as menu_item will translate a name into a menu_item with this <-value, <-message @default and a <-label created by `capitalising' the value.
A message is a dormant `send-operation'. When executed using ->execute or ->forward, a message is sent to the receiver. Message are the most popular code objects. See section 10.2 and many examples in this chapter.
Class method is the super-class of send_method and get_method. Instances of this class itself are useless.
A modifier is a reusable object that defines a condition on the status of the three `modifier keys' shift, control and meta/alt. Modifiers are used by class gesture and its sub-classes. They are normally specified through their conversion method, which translates a name consisting of the letters s, c and m into a modifier that requires the shift, control and/or meta-key to be down an the other modifier keys to be up. The example specifies a `shift-click' gesture.
click_gesture(left, 's', single,
If a move_gesture is attached to a graphical, the graphical can be moved by dragging it using the specified mouse-button. See also move_outline_gesture.
send(Box, gesture, new(move_gesture)),
Similar to a move_gesture, but while the gesture is active, it is not the graphical itself that is moved, but a dotted box indicating the outline of the graphical. If the button is released, the graphical is moved to the location of the outline. Should be used for complicated objects with many constraints or connections as a direct move_gesture would be too slow.
A name is a unique textual constant, similar to an atom in Prolog. Whenever an atom is handed to XPCE, the interface will automatically create a name for it. There is no limit to the number of characters that can be stored in a name, but some Prolog implementations may limit the number of characters in an atom. On these platforms, it is implementation-dependent what will happen to long names that are handed to the Prolog interface.
A node is a node in a tree of graphical objects.
new(T, tree(new(Root, node(text(shapes))))),
send(Root, son, node(circle(50))),
send(Root, son, node(box(50, 50))),
Code object that inverses the success/failure of its argument statement. Often used for code objects that represent conditions.
primitives(Device, Primitives) :-
        get(Device?graphicals, find_all,
            not(message(@arg1, instance_of, device)),
A number is the object version of an integer (int). If may be as a storage bin. To compute the widest graphical of a device:
widest_graphical(Device, Width) :-
        new(N, number(0)),
        send(Device, for_all,
             message(N, maximum, @arg1?width)),
        get(N, value, Width),
        send(N, done).
Class object is the root of XPCE's class-inheritance hierarchy. It defines methods for general object-management, comparison, hypers, attributes, etc. It is possible to create instances of class object, but generally not very useful.
Part of XPCE's object parser. Not (yet) available to the application programmer.
Disjunctive code object. An or starts executing its argument statements left-to-right and terminates successfully as soon as one succeeds. The empty or fails immediately.
Class to render text with mixed fonts and colours together with graphics. Class parbox is the heart of the document-rendering primitives described in section 11.10.
Part of XPCE's object parser. Not (yet) available to the application programmer.
A path is a multi-segment line. It comes in two flavours: poly as a number of straight connected line-segments and smooth as an interpolated line through a number of `control-points'. Its line attributes can be defined and the interior can be filled. Paths are used both to define new graphicals, for example a triangle, or to defines curves.
draw_sine :-
        send(new(Pict, picture), open),
        send(Pict, display, new(P, path)),
        (   between(0, 360, X),
                Y is sin((X * 6.283185)/360) * 100,
                send(P, append, point(X, Y)),
        ;   true
Class pce defines a single instance called @pce. Actions that cannot sensibly be related to a particular object are often defined on class pce.
?- get(@pce, user, User).
User = jan
Reserved for future usage.
A picture is a window with scrollbars, normally used for application graphics. If a graphical window without scrollbars is required, window should be considered.
A pixmap is a subclass of image that is reserved for colour images. All functionality of this class is in class image. The main reason for its existence is that some graphical operations require a colour image and the introduction of a class for it is the only way to allow this to be specified using XPCE's type system. The ->initialise method is specialised for handling colour images.
Position in a two-dimensional plane. Together with size and area used to communicate with graphicals about geometry.
get(Box, center, Point),
get(Point, mirror, Mirrored),
send(Box, center, Mirrored),
A popup menu is a menu that is shown after pressing a button on the object the menu is attached to. Popups are used in two different contexts, as pulldown menus attached to a menu_bar and as popup-menus associated with windows or individual graphical objects.

Popups are ->appended to menu_bars. Various classes define the method ->popup to associate popup menus. Finally, class popup_gesture provides a gesture that operates popup menus.

A popup consists of menu_items, each of which normally defines a message to be executed if the corresponding item is activated. Pull-right sub-menus are realised by appending a popup to a popup.

new(P, popup(options)),
send(P, append,
     new(L, popup(layout, message(Tree, layout, @arg1)))),
send_list(L, append, [horizontal, vertical, list]),
send(P, append,
     menu_item(quit, message(Tree, destroy))),
A popup_gesture parses events and activates a popup menu. Popup gestures are explicitly addressed by the application programmer to define compound gestures involving a popup:
:- pce_global(@graph_node_gesture,

make_graph_node_gesture(G) :-
        new(P, popup),
        send_list(P, append, [...]),
        new(G, handler_group(connect_gesture(...),
A process encapsulates a stream- or terminal program to get its input from a graphical program and redirect its output to the same graphical program. Various of the XPCE tools and demo programs exploit processes: The M-x shell, M-x grep and other shell commands of PceEmacs, the ispell program and the chess front-end. See also socket.
Code object with semantics like the LISP progn function. A progn executes its statements. If all statements are successfully executed and the last argument is a function, execute the function and return the result of it or, if the last argument is not a function, simply return it. Used infrequently in the XPCE/Prolog context.
The super-class of almost the entire `meta-word' of XPCE: classes, behaviour, attributes, types, etc. Class program_object defines the XPCE tracer. See tracepce/1 and breakpce/1.
Most of XPCE is defined to evaluate function objects at the appropriate time without the user having to worry about this. Sometimes however, type-checking or execution of a statement will enforce the execution of a function where this is not desired. In this case class quote_function can help. As a direct sub-class of object, it will generally be passed unchanged, but type-conversion will translate extract the function itself if appropriate, while delegation allows the quote_function to be treated as a function.

In the example, ChainOfChains is a chain holding chains as its elements. The task is to sort each of the member chains, using the function ?(@arg1, compare, @arg2) for sorting. If not enclosed in a quote_function, the message will try to evaluate the function. Now it passes the quote_function unchanged. The `chain->sort' method requires a code argument and therefore the function will be extracted from the quote_function.

send(ChainOfChains, for_all,
     message(@arg1, sort,
         quote_function(?(@arg1, compare, @arg2)))),
A real is XPCE's notion of a floating-point number. Reals are represented using a C single-precision `float'. Reals define the same operation as class number, its integer equivalent.
Class recogniser is the super-class of all event-parsing classes. The sub-tree gesture handles mouse-button related events, key_binding handles typing and handler may be used for all events. The main purpose of this class itself is to provide a type for all its sub-classes.
A regex is XPCE's encapsulation of the (GNU) Regular Expression library. Regular expression form a powerful mechanism for the analysis of text. Class regex can be used to search both char_array (name and string) text and text from a text_buffer as used by editor. It is possible to access the `registers' of the regular expression.
?- new(S, string('Hello World')),
   new(R, regex('Hello\s +\(\w+\)')),
   send(R, match, S),
   get(R, register_value, S, 1, name, W).

W = 'World'
A region defines a sub-region of a graphical. They are used to restrict handler objects to a sub-area of a graphical. Backward compatibility only.
Class relation is the super-class of identity and spatial. Relations form the reusable part of constraints. Class relation may be sub-classed to define new relation-types.
A resize_gesture handles mouse-drag events to resize a graphical object on the corners or edges. See also move_gesture and resize_outline_gesture.
send(Box, recogniser, new(resize_gesture)),
Outline version of the resize_gesture, often used to resize objects that are expensive to resize, such as editor or list_browser.
Gesture that can be used together with class table to allow the user dragging the boundaries between columns and rows in a table. See also section 11.5.

A resource is data associated with the application. It is most commonly used to get access to image-data. Example:

resource(splash, image, image('splash.gif')).

show_splash_screen :-
        new(W, window),
        send(W, kind, popup),           % don't show border
        new(I, image(resource(splash))),
        get(I, size, size(W, H)),
        send(W, size, size(W, H)),
        send(W, display, bitmap(I)),
        send(W, open_centered),
        send(timer(2), delay),
        send(W, destroy).
Defines how elastic objects in the document-rendering system such as hbox and its subclasses are. Used by parbox to realise layout. See section 11.10 for a full description of the rendering primitives.
A scroll_bar is used to indicate and control the visible part of a large object viewed through a window. Though possible, scroll_bars are rarely used outside the context of the predefined scrollbars associated with list_browser, editor and window.
send(Window, scrollbars, vertical),
A send_method maps the name of a method selector onto an implementation and defines various attributes of the method, such as the required arguments, the source-location, etc. Send-methods are normally specified through user-defined classes preprocessor as described in chapter 7.
A sheet is a dynamic set of attribute/value pairs. The introduction of object-level attributes implemented by `object <->attribute' and user-defined classes have made sheets obsolete.
Combination of <-width and <-height used to communicate with graphical objects about dimension. See also point and area.
Controller for a numeric value inside a range that does not require exact values. Specifying volume or speed are good examples of the use of sliders. They can also be used to realise a percent-done gauge.
new(Done, slider(done, 0, 100, 0)),
send(Done, show_label, @off),
send(Done, show_value, @off),
send(Done, selection, N),
send(Done, synchronise),
Communication end-point for a TCP/IP or Unix-domain interprocess communication stream. XPCE supports both `server' and `client' sockets. On the Win32 platform, only TCP/IP sockets are provided and only Windows-NT supports server sockets. The library(pce_server) provides a good starting point for defining server sockets. The support executable xpce-client may be used to communicate with XPCE server sockets. See also PceEmacs server mode as defined in library('emacs/server').
Specifies the location in a source file. Used by method objects to register the location they are defined.
Abstract super-class of file, resource and text_buffer for type-checking purposes. All source_sink objects may be used for storing and retrieving image-data. Notably a resource can be used for creating images (see section 9 and text_buffer can be used to communicate images over network connections (see section 11.9).
A spatial defines a geometry relation between two objects. The first two equations express the reference point of the 1st graphical in terms of its x, y, w and h. The second pair does the same for the second graphical, while the remaining two equations relate the mutual widths and heights. The example defines the second graphical to be 10 pixels wider and higher than the first, to share the same lower edge and be centered horizontally.
new(_, constraint(Gr1, Gr2,
                  spatial(xref=x+w/2, yref=y+h,
                          xref=x+w/w, yref=y+h,
                          w2=w+2, h2=h+2)))
Class stream is the super-class of socket and process, defining the stream-communication. It handles both synchronous and asynchronous input from the socket or process. It is not possible to created instances of this class.
A string represents a string of characters that may be modified. This class defines a large number of methods to analyse the text that are inherited from char_array and a large number of methods to manipulate the text. Class regex can analyse and modify string objects. There is no limit to the number of characters in a string. Storage is (re)allocated dynamically and always is `just enough' to hold the text. For large texts that need many manipulations, consider the usage of text_buffer that implement more efficient manipulation.

Strings are commonly used to hold descriptions, text entered by the user, etc.

A style defines attributes for a text fragment as handled by a editor/classtext_buffer or a dict_item as handled by a list_browser/dict. It defines the font, fore- and background colours as well as underlining, etc. The example defines a browser that displays files using normal and directories using bold font.
make_browser(B) :-
        new(B, browser),
        send(B, style, file, style(font := normal)),
        send(B, style, directory, style(font := bold)),
        send(B, open).

append_file(B, Name) :-
        send(B, append,
             dict_item(Name, style := file)).
append_dir(B, Name) :-
        send(B, append,
             dict_item(Name, style := directory)).
Syntax tables are used by class text_buffer to describe the syntax of the text. They describe the various syntactical categories of characters (word-characters, digit-characters), the syntax for quoted text, for comments as well as a definition for the end of a sentence and paragraph. Syntax tables are introduced to support the implementation of modes in PceEmacs. See also the emacs_begin_mode/5 directive as defined in library(emacs_extend).
A tab is a subclass of dialog_group, rendering as a collection of dialog_items with a `tag' associated. Tabs are normally displayed on a tab_stack, which in turn is displayed on a dialog. Skeleton:
        new(D, dialog(settings)),
        send(D, append, new(TS, tab_stack)),
        send(TS, append, new(G, tab(global))),
        send(TS, append, new(U, tab(user))),
        <fill G and U>
        send(D, append, button(ok)),
        send(D, append, button(cancel)).
Defines a stack of tagged sub-dialogs (tab objects) that can be displayed on a dialog. See tab for an example.
A table defines a two-dimensional tabular layout of graphical objects on a graphical device. The functionality of XPCE tables is modelled after HTML-3. Example:
simple_table :-
        new(P, picture),
        send(P, layout_manager, new(T, table)),
        send(T, border, 1),
        send(T, frame, box),
        send(T, append, text('row1/col1')),
        send(T, append, text('row1/col2')),
        send(T, next_row),
        send(T, append,
             new(C, table_cell(text(spanned, font := bold)))),
        send(C, col_span, 2),
        send(C, halign, center),
        send(P, open).

Provides the layout_interface to a table. Table cells are automatically created if a graphical is appended to a table. Explicit creation can be used to manipulate spanning, background and other parameters of the cell.


These classes are used for storing row- and column information in table objects. They are normally created implicitly by the table. References to these objects can be used to change attributes or delete rows or columns from the table. Example:

        get(Table, column, 2, @on, Column),
        send(Column, halign, center),
Add text using a defined style to a parbox. Part of the document-rendering infra-structure. See section 11.10.
A relation_table defines a multi-column table data object that can have one or more indexed key fields. They are (infrequently) used for storing complex relational data as XPCE objects.
Graphical representing a string in a specified font. Class text defines various multi-line and wrapping/scrolling options. It also implements methods for editing. Class editable_text as defined in library(pce_editable_text) exploits these methods to arrive at a flexible editable text object.
A text_buffer provides the storage for an editor. Multiple editors may be attached to the same text_buffer, realising shared editing on the same text. A text_buffer has an associated syntax_table that describes the character categories and other properties of the text contained. It can have fragment objects associated that describe the properties of regions in the text.

See class editor for an overview of the other objects involved in editing text.

Cursor as displayed by an editor. Not intended for public usage. The example hides the caret from an editor.
send(Editor?text_cursor, displayed, @off),
A text_image object is used by the classes editor and list_browser to actually display the text. It defines the tab-stops and line-wrapping properties. It also provides methods to translate coordinates into character indices and vise-versa. The user sometimes associates recogniser objects with the text_image to redefine event-processing.
A text_item is a controller for entering one-line textual values. Text items (text-entry-field) can have an associated type and/or value-set. If a value-set is present or can be extracted from the type using `type<-value_set', the item will perform completion, which is by default bound to the space-bar. If a type is specified, the typed value will be converted to the type and an error will be raised if this fails. The following text-item is suitable for entering integers:
new(T, text_item(height, 0)),
send(T, type, int),
send(T, length, 8),
A text_margin can be associated with an editor using `editor->margin_width' > 0. If the text_buffer defines fragments, and the style objects define `style<-icon', the margin will show an icon near the start of the fragment. After the introduction of multiple fonts, attributes and colour this mechanism has become obsolete.
Tiles are used to realise the `tile-layout' of windows in a frame. Section 10.6 explains this in detail. Tiles can also be used to realise tabular layout of other re-sizable graphical objects.
Small window displayed on top of a frame at the right/bottom of a user-adjustable window. Dragging this window allows the user the adjust the subwindow layout.
Timers are used to initiate messages at regular intervals, schedule a single message in the future or delay execution for a specified time. The example realises a blinking graphical. Note that prior to destruction of the graphical, the timer must be destroyed to avoid it sending messages to a non-existing object.
new(T, timer(0.5, message(Gr, inverted,
A tokeniser returns tokens from the input source according to the syntax specified. It is part of the XPCE object parser and its specification is not (yet) public.
Trees realise hierarchical layout for graphical objects. Class tree itself is a subclass of figure. The hierarchy is built from node objects, each of which encapsulates a graphical. Trees trap changes to the geometry of the displayed graphicals and will automatically update the layout. For an example, see node.
Anonymous tuple of two objects. Commonly used by get-methods that have to return two values.
A type defines, implicitly or explicitly, a set of object that satisfy the type, as well as optional conversion rules to translate certain other object to an object that satisfies the type. The basic set consists of a type for each class, defining the set of all instances of the class or any of its sub-classes, a few `primitive' types (int, char and event_id are examples). Disjunctive types can be created. See also section 3.2.1 and section 7.5.1.
?- get(type(int), check, '42', X). X = 42
A var object is a function that yields the stored value when evaluated. Vars in XPCE have global existence (like any object), but local, dynamically scoped, binding. Scopes are started/ended with the execution of (user-defined) methods, `code->forward' and the execution of a block.

The system predefines a number of var objects providing context for messages, methods, etc: @arg1, ... @arg10 for argument forwarding, @event for the current event, @receiver for the receiver of an event or message and @class for the class under construction are the most popular ones. Class block and and give examples of using these objects.

A variable is a class' instance-variable. They are, like send_method and get_method, normally defined through the user-defined classes preprocessor described in chapter 7.
Vector of arbitrary objects. Vectors can be dynamically expanded by adding objects at arbitrary indices. Vectors are used at various places of XPCE's programming world: specifying the types of methods, the instance variables of a class, to pack the arguments for variable-argument methods, etc. They share a lot of behaviour with chain can sometimes be an attractive alternative.
A view is a window displaying an editor. View itself implements a reasonable powerful set of built-in commands conforming the GNU-Emacs key-bindings. See also PceEmacs and show_key_bindings/1.
Visual is the super-class of anything in XPCE that can `visualise' things. The class itself defines no storage. Each subclass must implement the `visual<-contains' and `visual<-contained_in' methods that define the visual consists-of hierarchy as shown by the Visual Hierarchy. Class visual itself plays a role in the ->report mechanism as described in section 10.7 and defines `visual->destroy' to ensure destruction of a sub-tree of the visual consists-of hierarchy.
Class when realises a function version of if. It evaluates the condition and then returns the return-value of either of the two functions. It is commonly used to define conditional class-variable values.
editor.selection_style: \
        when(@colour_display, \
             style(background := yellow), \
             style(highlight := @on))
Code statement executing body as long as condition executes successfully. Not used frequently. Most iteration in XPCE uses the ->for_all, ->for_some, <-find and <-find_all methods defines on most collection classes.
The most generic XPCE window class. A window is a sub-class of device and thus capable of displaying graphical objects. One or more windows are normally combined in a frame as described in section 10.6. The four main specialisations of window are dialog for windows holding controllers, view for windows holding text, browser for windows displaying a list of items and finally, picture for displaying graphics.

Class window can be used as a graphics window if no scrollbars are needed.

A window_decorator is a window that displays another window and its `decorations': scrollbars and label. A picture for example is actually a window displayed on a window-decorator displaying the scrollbars. Almost never used directly by the application programmer.