## D.2 Additional interface libraries

This section describes Some of the predicates available from the XPCE/Prolog library.

### D.2.1 Library ``pce_util''

The predicates in this section used to be XPCE principal predicates. Changes to XPCE, the interface and our current understanding about programming the XPCE/Prolog environment have made these predicates less important.

send_list(+Receiver, +Selector [, +Argument])
  Invoke send-behaviour as send/[2-12]. Each of the arguments is either as accepted by send/[2-12] or a list of such arguments. The definition of send_list/2 is below.

      send_list([], _) :- !.
      send_list(_, []) :- !.
      send_list([Object|Objects], Selectors) :- !,
              send_list(Object, Selectors),
              send_list(Objects, Selectors).
      send_list(Object, [Selector|Selectors]) :- !,
              send_list(Object, Selector),
              send_list(Object, Selectors).
      send_list(Object, Selector) :-
              send(Object, Selector).

  Note that, since send/2 accepts `Selector(Arg...)` the following is now valid code:

              ...,
              send_list(Box,
                        [ colour(red),
                          fill_pattern(colour(greed))
                        ]),

get_object(+Receiver, +Selector, +Argument..., -Result)
  Equivalent to get/[3-13], but instead of unifying a variable with a reference the variable is unified with the term-description. The arguments are unified as in get/[3-13]. Normally only used from the Prolog top level for debugging purposes.
chain_list(?Chain, ?List)
  Converts between a XPCE chain and a Prolog list. This may be useful to exploit Prolog's list-processing primitives. Note however that XPCE chains define various operations that may be exploited to avoid the translation. Suppose `Pict' is a picture and `Pos' is a point object. We want to determine the topmost graphical object overlapping with `Pos'. The following two programs are identical:

      topmost_graphical(Pict, Pos, Gr) :-
              get(Pict, graphicals, Grs0),
              chain_list(Grs0, Grs1),
              topmost(Grs1, Pos, @nil, Gr),
              Gr \== @nil.

      topmost([], _, Gr, Gr).
      topmost([H|T], Pos, _, Gr) :-
              send(H, overlap, Pos), !,
              topmost(T, Pos, H, Gr).
      topmost([_|T], Pos, Gr0, Gr) :-
              topmost(T, Pos, Gr0, Gr).

  Or, using XPCE's list processing:

      topmost_graphical(Dev, Pos, Gr) :-
              get(Dev, graphicals, Grs),
              get(Grs, find_all,
                  message(@arg1, overlap, Pos), O),
              get(O, tail, Gr),
              send(O, done).

  The second implementation is not only shorter, it also requires far less data conversions between Prolog and XPCE and is therefore much faster.

get_chain(+Receiver, +Selector, -List)
  Utility predicate implemented as:

      get_chain(Receiver, Selector, List) :-
              get(Receiver, Selector, Chain),
              chain_list(Chain, List).

  See comments with chain_list/2.

### D.2.2 Library ``pce_debug''

The predicates in this section provide shorthands for common commands for debugging XPCE programs. See section 12 for more information on debugging XPCE/Prolog programs.

tracepce(+Class `<-|->|-` Selector)
  Find send- (`->`), get- (`<-`) method or variable (`-`) and cause invocations thereof to be printed on the console.

  Syntax note: (`->`) is a standard Prolog operator with priority > 1000. Therefore many Prolog systems require additional brackets:

      1 ?- tracepce((graphical ->selected)).

  In SWI-Prolog this is not necessary. To be able to trace get-methods with this predicate (`<-`) must be declared as an infix operator.

notracepce(+Class `<-|->|-` Selector)
  Disables trace-point set with tracepce/1.
checkpce
  Collect all global (named-) objects and run `object`->`_check' on them. This performs various consistency checks on the objects and prints diagnostic messages if something is wrong. `object`->`_check' checks all objects it can (recursively) find through slot-references, chains, vectors and hash-tables and deals properly with loops in the data-structure.
show_slots(+Reference)
  Prints the values of all instance variables of Reference:

      1 ?- new(@move_gesture, move_gesture).
      2 ?- show_slots(@move_gesture).
      @move_gesture/move_gesture
              active                @on/bool
              button                middle
              modifier              @810918/modifier
              condition             @nil/constant
              status                inactive
              cursor                @default/constant
              offset                @548249/point

  A graphical tool for inspecting instance variables is described in section 12.5.

### D.2.3 Accessing the XPCE manual

manpce
  Start the XPCE online manual tools. This opens a small GUI console at the top-left of the screen, providing access to the manual, demo programs and tools described in this manual. See chapter 3.
manpce(+Spec)
  As manpce/0, but immediately opens the the manual from Spec. Spec is either a class-name, opening the ClassBrowser, or a term Class `<-|->|-` Selector (see tracepce/1) to open the manual-card of the specified behaviour. Examples:

      1 ?- manpce(box).
      2 ?- manpce((view->caret)).