7.1 The class definition skeleton

We introduce the syntax for user-defined classes using a skeleton. Except for the pce_begin_class/[2,3] and pce_end_class/0, everything in the skeleton is optional and may be repeated multiple times. The order of declarations is not important, but the order of the skeleton is the proposed order. An exception to this rule is the pce_group/1 directive, that may be placed anywhere and defines the group-identifier for the declarations that follow. The skeleton is given in figure 14.


:- pce_begin_class([<Meta>:]<Class>[({<TermName>})], <Super>[, <Summary>]).

:- use_class_template(<TemplateClass>).
:- send(@class, <Selector>{, <Arg>}).
:- pce_class_directive(<Goal>).

variable(<Name>, <Type>[:= <Value>], <Access> [, <Summary>]).

delegate_to(<VarName>).

class_variable(<Name>, <Type>, <Default> [, <Summary>]).

handle(<X>, <Y>, <Kind>, <Name>).

:- pce_group(<Group>).

<SendSelector>(<Receiver>{, <Arg>[:[<AName>=]<Type>]}) :->
[<Summary>::]
<PrologBody>.

<GetSelector>(<Receiver>{, <Arg>[:[<AName>=]<Type>]}, <RVal>[:<Type>]) :<-
[<Summary>::]
<PrologBody>.

:- pce_end_class.


Figure 14 : Skeleton for user-defined classes

7.1.1 Definition of the template elements

pce_begin_class(+[Meta:]Class, +Super, [+Summary])
Start the definition of an XPCE user-defined class. This directive can appear anywhere in a Prolog source file. The definition must be closed using pce_end_class/0 and definitions may not be nested. Class describes the class to be created. Besides giving the class-name, the meta-class (class of the class) may be specified. When omitted, the meta-class of the Super will be used, which is normally class class. An example of meta-class programming can be found in PceDraw's file shape.pl, see Wielemaker, 1992.

The class-name may be followed by a list of TermNames that define the result of object/2. object/2 unifies its second argument with a term whose functor is the name of the class and whose arguments are the result of a `get' operation using the TermName as selector. For example, point(x,y) specifies that object(P, T) unifies T to a term point /2 with the <-x and <-y of the point instance as arguments. When omitted, the term-description of the super-class is inherited.

use_class_template(TemplateClass)
Import a class template. See section 7.5.2.1.
send(\index{@class}\objectname{class}, ...)
Directives like this may be used to invoke methods on the class under construction. This can be used to modify the class in ways that are not defined by this preprocessor. The following example tells the system that the `visual' attribute of an imaginary user-defined class should not be saved to file when the object is saved using `object->_save_in_file'.
:- send(@class, save_style_variable, nil).

See also pce_class_directive/1 and section 7.5.3.

pce_class_directive(+:Goal)
Define Goal to be a goal that manipulates the class instance directly. See section 7.5.3.
variable(Name, Type, Access, [Summary])
Define a new instance variable. Name is the name of the variable, which is local to the class and its subclasses. Type defines the type. See section 3.2.1 and section 7.5.1. The type may be postfixed with := Value to specify an initial value. If Value can be modified (i.e. is not a constant, int or name) it is often desirable to use := new(NewTerm) to force each instance to create its own unique copy of the initial value. Access defines which implicit universal methods will be associated with the variable. A universal method is defined to be a method that reads or writes the slot, without performing any additional actions. See also section 7.2.
delegate_to(VariableName)
Declares the variable named VariableName to be a candidate for delegation. See section C.4.
class_variable(Name, Type, Default, [Summary])
Declare a class-variable for the class. Class-variables describe common properties for all instances of the class. The Default value for a class-variable can de defined in the Defaults file. See chapter 8 for details.

The Default entry describes the default value if there is no value specified in the Defaults file. Example:

class_variable(size, size, size(400,200), "Default size of object").
handle(X, Y, Kind, Name)
Equivalent to the expression below. See also section 5.3.
:- send(@class, handle, handle(X, Y, Kind, Name)).
pce_group(GroupIdentifier)
Sets the `behaviour<->group' attribute of any variable or method definition following this directive. Groups are used to organise methods by the ClassBrowser. Groups have no semantic implications. :- pce_group(@default). makes methods inherit their group from the method that is re(de)fined. If no method is re(de)fined, the group will be miscellaneous.
pce_end_class(Class)
End the definition of the named Class. Class must be the same as the class-name used by the most recent pce_begin_class/[2,3]. This variation of pce_end_class/0 provides better documentation and error correction.
pce_begin_class()
Close the definition of the most recently started class. See also pce_end_class/1.

7.1.1.1 Syntax details

Table table 6 describes the details of the non-terminals in the above skeleton in more detail. The notation is an incomplete BNF notation.

<Meta> ::=<Name> Name of the class this class will be an instance of. Default is the meta-class of the super-class
<Class> ::=<Name> Name of the class to be defined
<TermName> ::=<Name> Selector name to fetch object/2 argument. For example, a point is translated into point(<X>, <Y>) and the description is point(x,y)
<Super> ::=<Name> Name of the super-class. object refers to the most general class
<Summary> ::="{<Char>}" Summary description as appearing in the online manual. < 40 characters, no newlines, Prolog string
<TemplateClass> ::=<Name> Import a template class. See section 7.5.2.1
<Selector> ::=<Name> Name of a method
<X> ::=<IntExpr> See class handle
<Y> ::=<IntExpr> See class handle
<Kind> ::=<Name> Category indicator. See class handle
<Access> ::=both | get | send | none Defines the access right to this variable
<VarName> ::=<Name> Name of variable used for delegation
<Group> ::=<Name> Functional group of the following methods or variables. Used to organise the ClassBrowser
<SendSelector> ::=<Name> Name of send-method to define
<GetSelector> ::=<Name> Name of get-method to define
<Receiver> ::=<Variable> Prolog variable bound to the receiver
<Arg> ::=<Variable> Prolog variable bound to argument
<RVal> ::=<Variable> Prolog variable that should be bound to the return value
<AName> ::=<Name> XPCE name for named argument
<Type> See section 3.2.1 and section 7.5.1
<PrologBody> Ordinary Prolog code
<Value> Initial value for the instance variable. At this moment, only using constants is supported (int, name, bool)
Table 6 : Syntax details for User Defined Classes