1.99 class method

Methods are used by the PCE message passing algorithm to map the combination of an object/class, the type of the message (send or get) and the selector of message onto executable code.

Additionally, methods define the expected argument types and the argument names of the operation. The PCE message passing algorithm uses this information to verify and if necessary and possible convert the types of the arguments presented,

The implementation of a method is either a C-function pointer (used for system-defined methods), or a PCE code object (used for user-defined methods). While executing the latter, the following arguments are forwarded:

@receiver	Receiver of the message
@arg1 ... arg<n>	Arguments to the message

See also class behaviour, send_method->send, get_method<-get, class->send_method, class->get_method, object->send_method and object<-get_method.

See also

- topic Specification
- class send_method
- class get_method
- object->send_method
- object->get_method
- class->send_method
- class->get_method
- class class
- class code
- topic Types

1.99.1 Instance variables

behaviour <- context: class|object*

When attached to a class, behaviour<-context refers to this class. When member of a method_group, attached to an interceptor or not attached at all, its value is @nil.

method-function: alien:Func

When implemented in the C-language, this slot contains a pointer to the implementing C-function. When implemented with a code object, the value of this slot is NULL.

method-group: [name]

Conceptual group of the method. Used for structuring the reference manual. If the variable is @default, method<-group will

1. check for an instance variable of the same name
2. check for a method<-inherited_from method. and return the first non @default value encountered.

method <-> message: code|host_method*

Implementation of the method object. This slot cooperates with the -function variable:

• @nil In this case the -function is a pointer to a C-function implementing the method. This function will be passed the receiver and the arguments of the method. If the last type of the method denotes multiple arguments (...), the C-function will be passed an integer for the number of arguments and a pointer to an array of objects for the actual arguments. Internal use only.
• host_method object An opaque handle, provided by the host language, that refers to a procedure in the host language. See also pce_predicate_reference/2.
• A code object If the method is a get_method object, this must be a function object.

  If the method is executed, @receiver points to the receiver of the message and @arg1, ... point to the arguments provided to the message. See also method->initialise.

behaviour <- name: name

Selector or name of the method.

method <-> source: source_location*

Sourcefile and linenumber where this method is defined. The Prolog defined class compiler fills this argument.

The source editor of this manual uses it to find the sources. This editor uses the TAGS file in the PCE source directory to find the sources of PCE's built-in methods.

Defaults: @nil (location of sources is unknown)

See also

class source_location

method-summary: [string]*

Summary description of the method. It should be a string of about 45 characters maximum width describing the function implemented by the method.

The summary attribute is used by the summary lists of methods, etc. displayed by these manual tools. It is defined for all built-in methods and may be defined in the body of a Prolog defined method.

If the slot contains @default, and the behaviour<-context is a class object, the method will extract the summary from a variable with the same name or a method on a super-class with the same name (in this order).

See also

tool Summary List

method <- types: vector

The method<-types slot describes the type-checking performed when the method is invoked. it is a vector of type objects. The elements of the vector denote the argument types for the corresponding argument positions. When a C-function is invoked the arguments are the receiver, followed by the arguments that activated the method. When a code object is invoked, @receiver is bound to the receiver, @arg1 is bound to the first argument, @arg2 to the second, etc.

See also class type and send_method->send.

See also

- topic Conversion
- topic Checking

1.99.2 Send methods

method ->initialise: name=name, types=[vector], implementation=code|host_method, summary=[string]*, source=[source_location]*, group=[name]*

Create a new method object. Methods come in two flavours: send_method objects for procedures and get_method objects for functions.

Method objects may be associated to a class or to an individual object using the methods class->send_method, class->get_method, object->send_method or object->get_method.

The arguments to method->initialise are:

behaviour<-name	Name of the selector to handle
method<-types	Vector of type objects for arguments
implementation	method<-message implementing the method
method<-summary	Online manual summary description
method<-source	Source-file location of the definition
method<-group	Functional group of the method

Messages to classes are normally associated using the class definition interface implemented by pce_begin_class/[2,3], pce_end_class/0 and various macros defined by these predicates.

The example below defines a move_gesture object that is only active if the window in which the graphical to be moved defines an attribute (get_method) method<-mode that yields the value edit.

...,
new(G, move_gesture),
send(G, send_method,
         send_method(verify, vector(event),
                                 @arg1?window?mode == edit)),
...

The alternative would be to define a new class for move gestures that only operate in windows that are editabe:

:- pce_begin_class(move_if_editable_gesture,
                                   move_gesture).

verify(_G, Ev:event) :->
        "Test if the window is editable"::
        get(Ev?window, mode, edit).

:- pce_end_class.

1.99.3 Get methods

method <-group: -> name

Inherits description from: method-group

method <-inherited_from: -> method

If method is a method of a class, this method will return a method of the same type (send_method or get_method) of a super-class with the same selector.

This method may be regarded as a redefinition (usually refinement) of the returned method. Used by the reference manual to generate the Refinement of: lines.

method <-print_name: -> name

Textual representation of the method of the form:

<class> <access><selector>

See also variable<-print_name.