1.110.1 Send methods

object ->_check: recursive=[bool]

Validate the type of the instance variables. If the argument is @on or @default, validation continues recursively over instance variables that contain objects. This method is protected against loops in the data-structures.

Normally invoked through the Prolog predicate checkpce/0.

Diagnostics: See related error objects

See also

- !freed_value_value
- !freed_key_value
- !freed_element_value
- !freed_cell_value
- !freed_slot_value
- !bad_slot_value
- !creating
- !no_variable
- !checked_objects
- object->for_slot_reference
- class type

object ->_free:

Inherits description from: object<-_class

See also

- class ?
- object->free

object ->_inspect: bool

Inherits description from: object<-_class

See also

class ?

object ->_instance_of: class

Inherits description from: object<-_class

object ->delete_hyper: hyper

Detach a hyper from an object.

object ->attach_hyper: hyper, object

Called from class hyper as part of hyper->initialise and hyper->unlink. These methods should never be called directly by the user. It is however possible to redefine these methods to intercept the creation and destruction of hyper-links. A redefinition should always call this method.

See also

object->delete_hypers.

object ->attribute: attribute|name, value=[any]

Attach an instance variable to an object rather than to a class. If an attribute with this name is already present, the value of the original attribute is replaced.

An error is raised if the class already defines an instance variable with the same name.

See also

- graphical->popup
- class sheet
- object<-all_attributes
- attribute<-convert
- class attribute
- object-interceptor

object ->convert_loaded_object: old_version=int, current_version=int

Called by source_sink<-object if the current save version is not the same as save version when the file was loaded. The two arguments are the old and the new save versions. See pce<-save_version.

See also

object->initialise_new_slot

object ->delete_attribute: name|attribute

Delete (named) attribute that has previously be attached using object->attribute. Fails silently if the attribute is not present.

Diagnostics: Fails (silently) if the attribute is not defined.

See also

object->attribute

object ->delete_hypers: name=[name], condition=[code]

Delete all hypers matching the name and condition. See object<-find_hyper for the interpretation of the name and condition arguments.

object ->done:

This method is used to help the PCE garbage collector and should normally be invoked after the program is done with the answer of a get operation and wants to be sure that the returned object is deleted when no longer referenced:

.....
get(Area, size, Size),
....
send(Size, done).

The receiving object will be deleted from the object base as with object->free if the receiver has no object<-references, object<-lock_object is @off and object<-protect is @off.

In the example above object->done is equivalent to object->free as the size object returned by area<-size is created by this method (provided the .... computation does not lock, protect or make the size an attribute of some other object. In the example below, using object->free will corrupt PCE's database:

....
get(Graphical, area, Area),
....
free(Area).		% ==> ERROR!!!

The area object will be deleted and the slot graphical<-area will be pointing in the dark (checkpce/0 will find such problems).

Using object->done is often not necessary. After a user-event has been processed all unreferenced and unlocked objects will be deleted from the object base automatically. Unreferenced objects created during the execution of a user-defined method for a PCE class are also deleted automatically. object->done is useful when a lot of garbage objects are created in a loop.

See also

object<-lock_object

object ->equal: to=any

Succeeds if the argument has the same reference. Note that this method is redefined by various classes. Equality may also be tested using class ==. See also object->same_reference.

Bugs: The notion of equality is not very clear in PCE.

See also

- class \==
- class ==

object ->error: error=error, context=unchecked ...

Raise an error (exception) on this object. Error (normally specified by its error<-id and converted by error<-convert) is the error to be raised. The remaining context arguments provide context information about this error. Performs the following steps:

• if error<-kind equals ignored, silently fail.
• assigns pce<-last_error.
• If the error is not catched (pce->catched), it invokes error->display on the error object.

  See also class error and object->report.

  Diagnostics: Diagnostics depend on the error object invoked.

  See also

  - visual->report
  - pce->catched
  - error-id

object ->for_slot_reference: action=code, recursive=[bool]

This method is intended to help writing analysis programs for the database. It scans all slot-references of the receiving object. When the argument is @on or @default, it will continue recursively over the slot-fillers.

For each slot-reference, code is executed with the following bindings:

@arg1	The instance
@arg2	Type of slot reference
@arg3	The slot
@arg4	The value of the slot

The Type of slot reference is one of:

slot

For normal objects. @arg3 is bound to the name of this variable

cell

For chains. @arg3 is bound to the 1-based index of the cell

element

For vectors. @arg3 is bound to the index

key

For hash_tables. @arg3 is bound to the key; @arg4 to the related value.

See also

object->_check

object ->free:

Remove an object from the PCE object base. This behaviour is the normal way to get rid of existing objects. object->free performs the following steps:

• Invoke object->unlink. This allows a class to unlink the object from the environment.
• Removes all attribute references by setting all slot values that contain an object to @nil.
• Removes the global name association if this existed.
• Reclaim the memory if the object has no object<-references. Otherwise reclaim is delayed. See pce<-deferred_unalloced.

  object->unlink is often defined on objects that need to inform some other object that they are destroyed. For example, graphical objects inform their device to allow the device to remove the object from the display and update their book-keeping.

  The method object->unlinking is provided as a test whether or not object->free is in progress on the receiver.

  See also visual->destroy to destroy entire hierarchies of (visual) objects.

  Diagnostics: Fails silently if object<->protect equals @on.

  Bugs: Window object->free should just delete the window from it's object<-frame. In new code, please delete frames using object->free.

  See also

  - object->unlink
  - visual->destroy
  - topic Removing Objects
  - object->protect
  - object->destroy
  - object->_free

object ->get_method: get_method|chain

Add a get-method to this individual object. Object-level defined get-methods overrule Class-defined get-methods. An object level method may refer to its corresponding class level method using object->get_class.

See also

- object<-get_class
- class method_group
- class method
- object<-slot
- object<-all_get_methods
- object->send_method
- class->get_method
- object-interceptor

object ->has_get_method: selector=name

Test if object defines get_method.

object ->has_send_method: selector=name

Test whether object implements the specified send/get behaviour. This test is equivalent to testing whether {object<-get_method, object<-send_method} returns a value but avoids the creation of a tuple. See also class<-send_method and class<-get_method.

object ->is_off: name

Test if Obj object<-name returns @off.

object ->is_on: name

Test if Obj object<-name returns @on.

object ->not_has_value: name, any

Test if Obj object<-name not-equal 2nd argument.

object ->has_value: name, any

Execute the get operation object<-Name and compare the result to the argument. Succeed if they are equal (have same reference), fail otherwise.

This method is intended to test on attribute values. Similar and more powerful results can be obtained using class ==.. It's usage is to be preferred. The following code objects and Prolog fragments all test whether the point<-x of the point object @p equals 3:

Prolog:

get(@p, x, 3)              % Uses Prolog unification
send(@p, has_value, x, 3)

Code fragments:

message(@p, has_value, x, 3)
@p?x == 3

object->not_has_value is equivalent to object->has_value, but returns the inverse result. object->is_on is equivalent to object->has_value: @on and object->is_off is equivalent to object->has_value: @off.

See also

- object->is_on
- object->is_off
- class \==
- object->not_has_value
- class ==

object ->initialise:

No-operation (just succeeds). Implemented to allow any class perform a

send_super(Self, initialise).

Any class should have a method object->initialise. This method is invoked from PCE's virtual machine to initialise an object from the parameters given to the object creation operation (new/2. class create, class<-instance.

The creation of objects is discussed in detail with class<-instance.

See also

- class<-instance
- topic Creating Objects

object ->initialise_new_slot: new=variable

Part of saved-object conversion (see source_sink<-object). Called when -while loading an instance from a file-, the current definition of the class has a new instance variable (compared to when the instance was saved to file using object->save_in_file). The argument is the new variable object from the class. May be used to initialise the new slot to some sensible value.

See also

object->convert_loaded_object

object ->inspect: bool

If @on and the class of the object has one of the change trapping messages attached to it, changes to the object are forwarded (to the application) via these change messages. If @off, these messages have no effect.

See also

- class-changed_messages
- object<-inspect
- topic Changes
- class->freed_message
- class->created_message
- class->changed_message

object ->instance_of: class

Succeeds if the object is an instance of the argument class or one of its subclasses. Note that class<-convert converts class-names to class objects:

send(Obj, instance_of, graphical)

is the advised way to verify that Obj is a graphical.

The method pce<-convert may be used to combine testing with possible type conversion. See also type->validate and type<-check. If one wants to test whether an object is a graphical object, a node object or @nil, the following two test are equivalent:

(   send(Obj, instance_of, graphical)
;   send(Obj, instance_of, node)
;   Obj == @nil
)

or

send(type('graphical|node*'), validate, Obj)

See also

pce<-convert

object ->lock_object: bool

Inherits description from: object<-lock_object

See also

- object<-lock_object
- object<-_flags
- object->protect

object ->name_reference: name*

Give/change the global named reference associated with the object. See also object<-object_reference.

Diagnostics:

• Name reference <Name> already in use The requested new name-reference is already in use.

  Bugs: Unlike with the predicate new/2, no exception is raised if the object already exists.

  See also

  - pce->rename_reference
  - object<-name_reference
  - topic Global references

object ->protect:

Protect an object against destruction with object->free or one of the other objects destruction methods. The global PCE objects @pce, @prolog, etc. are protected this way.

There is no way to unprotect protected objects or to destroy them.

See also

- visual->destroy
- object<-protect
- object<-_flags
- topic Removing Objects
- object->lock_object
- object->free
- object->destroy

object ->report: kind={status,inform,progress,done,warning,error,fatal}, format=[char_array], argument=any ...

Report a message related to the specified object. This method locates the visual object from which the user invoked the current command using constant<-receiver and invokes visual->report on this object.

If @event is unbound the error is caused by a query from the host-language interaction window and PCE thus prints the message using pce->format.

Some classes redefine this method because they know they are related to some visual object. See also object<-report_to.

See also

visual->report

object ->same_class: object

Test if two objects belong to the same class. The following two executable objects are the same:

Obj1?class == Obj2?class.

and

message(Obj1, same_class, Obj2)

See also

- object<-class
- class->is_a

object ->same_reference: to=any

Test if i'm the same object as the argument. This method verifies both objects have the same identity. The method object->equal performs the same test, but is refined by various classes to test for same properties. See -for example- point->equal.

object ->save_in_file: file

Save an object and all objects that can be reached from it to a file. This method takes care of cyclic structures. The save-format is binary. The object may be reloaded in this or in another PCE process using source_sink<-object. When the object is reloaded in this PCE process, the combined functionality is similar to object<-clone.

When the data, manipulated by the application is stored in PCE, the normal way is to attach all this information to a single object (normally a hash_table, sheet or chain) and save this object to a file. All attached objects (i.e. all data needed by the application to save its persistent data) are then saved in the file.

PCE's save and load functionality has a limited way to deal with versions. The conversion activities are described with source_sink<-object.

Diagnostics:

• Do not know how to save <object> Object cannot be saved because it contains alien references and no defined behaviour to take care of them. This is the case with most objects that refer directly to the X-window system (e.g. windows, cursors, etc.).

  Diagnostics related to opening, writing and closing a file are applicable as well.

  Bugs:

• User-defined classes currently cannot define private save and load behaviour.

  See also

  - !cannot_save_object
  - source_sink->check_object
  - object<-clone
  - source_sink<-object
  - class-save_style
  - topic Saving to File

object ->send_class: selector=name, argument=unchecked ...

Invoke send behaviour of the class, bypassing object-level send_method objects attached to this object. See object<-get_class for details..

See also

object->send_method

object ->send_hyper: hyper_name=[name], selector=name, argument=unchecked ...

Perform a broadcast send-operation to all (named) object<-hypered objects. Similar to object<-get_hyper, but does not stop if the method is received successfully. Succeeds if there was at least one hypered object accepting the message, fails otherwise.

object ->send_method: send_method|chain

Add a send-method to this individual object. Object-level defined send-methods overrule Class-defined send-methods. An object level method may refer to its corresponding class level method using object->send_class.

See also

- object->send_class
- class method_group
- class method
- object<-all_send_methods
- object->slot
- class->send_method
- object->get_method
- object-interceptor

object ->send_sub: selector=name, argument=unchecked ...

Send to @receiver, using behaviour at the level of the class @receiver is an instance of. See also object<-get_sub.

object ->send_super: selector=name, argument=unchecked ...

Invoke behaviour of the super-class. This behaviour is intended to be used only for using behaviour of the super-class when defining new classes.

See also

- object<-get_super
- topic Methods
- topic Class-level Programming

object ->send_super_vector: unchecked ...

Combines object->send_super and object->send_vector, creating an argument vector from the leading arguments and vector and invoking behaviour defined at the super-class. See object->send_super and object->send_vector for details.

See also

- object->send_super
- object->send_vector

object ->send_vector: unchecked ...

object->send_vector supports the implementation of methods with variable argument list. Its format is:

unchecked..., Vector, [shift]

First, a list is created containing the following arguments:

• The objects from unchecked...
• The elements of the vector, with the first [shift] elements skipped.

  Next, the first element of this list is used as the selector and the remaining arguments as the arguments to the message. Examples:

• send(@prolog, send_vector, vector(write_ln, 'Hello World')).
• send(@prolog, send_vector, write_ln, vector('Hello World')). Defaults: Shift defaults to 0.

  Diagnostics: Fails silently if the selector cannot be created,

  See also

  - !bad_vector_usage
  - code->forward_vector
  - object->send_super_vector
  - object<-get_vector
  - topic Delegation

object ->slot: name|int, unchecked

Set the value of a (class-defined) slot without activating the corresponding method.

The slot specification (first argument) is either the slot-name, or the offset in the object (1-based). The latter possibility is for very specific (internal) use.

This method should only be used from a send-method that has the same name (selector) as the slot and serves as a wrapper around the slot to deal with side-effects:

:- pce_begin_class(person, object).

variable(date_of_birth,	date, get, "When person was born").
...

date_of_birth(Person, Date:date) :->
        (   send(Date, after, new(date))
        ->  send(Person, report, error,
                     'Cannot be born in the future!'),
                fail
        ;   send(Person, slot, date_of_birth, Date)
        ).

Bugs: This message should also apply to object-level defined attributes (see object->attribute.

See also

- class variable
- object<-slot
- class->send_method
- object->send_method

object ->unlink:

The method object->unlink is called by object->free. Its task is to unlink the instance from its environment. The object->unlink method may not be called directly by the user. The user should provide an unlink method when writing a user-defined class that requires specialised unlink behaviour.

Some examples:

• Graphicals notify their device when they are destroyed, so the device can delete them from device<-graphicals and update the display.
• A window will destroy the associated Xt-widget realising the window in X.
• A char_array will unalloc the associated C-data-structure representing the text.

  NOTE: Unlink should never be called directly by the user. Any user-defined object->unlink method should invoke the method of the super-class (see object->send_super).

  See also object->free, object->done, visual->destroy and object->unlinking

  See also

  object->free

object ->unlinking:

Succeeds if the object is in currently being object->unlink’ed. Intended as a test in object->unlink methods to avoid unnecessary computation.