1.25.1 Instance variables

class-changed_function: alien:SendFunc

C-function activated if a slot of an instance is changed and‘Object class<->inspect’for this instance is @on.

See also

class-changed_messages

class <-> changed_messages: chain*

Chain of code objects activated after a slot of an instance has changed that has object->inspect. Each code object is activated in turn and the returned status of the execution is ignored. Argument binding:

@arg1	Instance who's slot changed
@arg2	Name of the changed slot.

Changes are not notified before the initialisation of the instance is complete or after the destruction has started.

This trap is used by the inspector tool. See also class->created_message and class->freed_message.

See also

- class-freed_messages
- class-created_messages
- object->inspect
- class-changed_function

class-clone_function: alien:SendFunc

C-function pointer. This function is responsible for cloning alien data associated with an instance.

See also

topic Kloning objects

class <-> clone_style: {recursive,none,relation}

Determines how an instance of this class is cloned. Possible values:

recursive

Clone this instance and all its parts recursively.

none

The instance itself is returned. Used for reusable objects.

nil

object<-clone returns @nil.

See also object<-clone and variable<-clone_style.

See also

- topic Kloning objects
- object<-clone

class <-> created_messages: chain*

Chain of code objects invoked when an instance of this class is created. After successful creation of an instance, the following arguments are forwarded to each code object in the chain:

@arg1	Name of the class
@arg2	Reference to the new instance
@arg3	Action that caused the creation of the object

Possible values for @arg3 are:

new	Normal creation (new/2 or class<-instance)
loaded	Loaded by source_sink<-object
clone	Cloned using object<-clone

May be used to keep track of the set of instances of this class in combination wit class->freed_message. See also class->changed_message and class->record_instances.

See also

- class-freed_messages
- class-changed_messages
- class<-instance

class <- delegate: chain

The chain class<-delegate consists of instance variable objects that should be used for delegation. The PCE message passing system will try to forward an incoming message to the values of these instance variables after it failed to locate an implementation at the object or class level. The elements of this chain are tried in the order they appear in the chain.

class->delegate	Adds a variable at the end
class->prepend_delegate	Adds a variable at the start

See also class<-send_method and class<-get_method.

class <-> freed_messages: chain*

When an instance of this class is freed that has‘object class<->inspect: @on’, its reference will be passed to the code objects in this chain. Argument binding:

@arg1:	Object to be freed.

This message is sent as the first action of object->free. See also class->changed_message and class->created_message.

See also

- class-created_messages
- class-changed_messages

class-send_catch_all: [send_method]*

Handle not-yet-handled send messages.

class-get_catch_all: [get_method]*

These variables provide fast access to the methods‘object class<->catch_all’.

See also

class-delegate_classes

class-send_methods: chain

Send methods not inherited.

class-get_methods: chain

Chain of methods of the indicated type (send/get) (re)defined for this class. Inherited or delegated methods are not in this chain. See also class<-get_method and class<-send_method, object<-send_method and‘object class<-get_method’, for resolving methods.

See also

class-get_table

class <- get_table: hash_table

The -local_table maps instance_variable names onto instance variables and is used by object<->slot. The -get_table and -send_table both map selectors onto implementations. The implementation is either a method or a variable. All these tables only contain the currently resolved methods: they are initially empty. Used and maintained by:

-local_table	class<-instance_variable
-get_table	class<-get_method
-send_table	class<-send_method

See also

class-get_methods

class <-> handles: chain*

Graphical classes only. This chain contains handles that are available to each instance of the class. Note that handles can be defined simultaneous at the class- and the instance-level.

Handles at the class level are normally declared using the handle/4 construct expanded by the Prolog defined class compiler.

See also

- topic Connections
- graphical-handles
- class handle

class-in_event_area: alien:SendFunc

C-function pointer to validate whether an event should be regarded to have happened inside a graphical object.

See also

graphical->in_event_area

class-convert_method: [get_method]*

Type conversion.

class-lookup_method: [get_method]*

Type conversion.

class-initialise_method: [send_method]

Direct pointers to these methods for two reasons:

• Get the system started while there are no chains or hash_tables yet.
• Fast implementation of object creation and type conversion.

class <- instance_size: int

Size of an instance in bytes. Note that this does not include the size of parts of the instance.

class <- instance_variables: vector

Vector object holding all instance variables of this class. Initially a copy of the super-class. The variable object at index <n> of this vector describes the <n>-th slot of the object. See also object<-slot.

The behaviour<-context argument may be used to find the class on which a variable is defined. The following code returns a chain of instance variables not inherited:

new(Vs, chain),
send(Class?instance_variables, for_all,
         if(@arg1?context == Class,
                message(Vs, append, @arg1)))

class <- instances: hash_table*

The hash_table object class<-instances contains all instances of this class that have been created since the table was attached to the class. Note that instances of sub-classes are not in this table. The table is maintained by the new() and free() virtual machine operations as well as by object<-clone and source_sink<-object.

This table is attached using class->record_instances. If the first argument is @on or @default an class<-instances table is attached. If this argument is @off a possible associated table is detached. If the second (recursive) argument is @on (default), class->record_instances will be invoked with the same arguments on all sub-classes. Thus

?- send(class(object), record_instances).

Will record the instances of all classes.

See also class->created_message and class->freed_message.

class <- local_table: hash_table

Inherits description from: class-get_table

class <- name: name

Name of the class. Class names are global and must be unique. The table @classes maps class-names into class objects.

PCE built-in classes have relatively short and simple names. It is adviced to prefix application classes with a common prefix to avoid conflicts with other packages or future PCE classes. For example, all classes consituting PceDraw are called draw_<something>.

class-no_freed: int

Number of instances freed.

class-no_created: int

Number of instances created/freed. By default it returns the number of created instances of the class itself. If subtoo is @on it adds the number of instances created in all class<-sub_classes recursively.

To find the actual number of existing instances, subtract class<-no_freed.

See also

pce<-objects_allocated

class <- realised: bool

Bool indicating whether or not the class is fully built. A class that is not realised class<-name, class<-super_class, class<-sub_classes, class<-summary and -make_class_function are defined. All other slots have undefined values.

When information or instances of a non-realised class are requested, XPCE will invoke class->realise on the class to build the class.

Inherits description from: class->realise

class <-> save_style: {normal,external,nil}

Flag to help object->save_in_file. If this methods encounters a slot holding an instance of this class it will save the instance according to the value of class<-save_style:

normal	Save the instance to the file
external	Save the (named) reference to the file
nil	Write @nil to the file

See also variable<-save_style and source_sink<-object.

See also

object->save_in_file

class <-> selection_style: {none,invert,corner_handles,side_handles,corner_and_side_handles,line_handles,path_handles}*

If class is a subclass of class graphical, the selection_style determines the visual feedback of graphical objects that have‘graphical class<->selected: @on’. See also graphical.selection_style. This class_variable object is redefined for each subclass of graphical.

class <- send_table: hash_table

Inherits description from: class-get_table

class-solid: bool

@see device-area_must_be_cleared

class <-> source: source_location*

Location in the sources.

class <- super_class: class*

Immediate super class.

class-sub_classes: chain*

The variables class<-sub_classes and class<-super_class define the class hierarchy. The class hierarchy is visualised using the‘Class Hierarchy’tool from the online manual tools. The class<-super_class of class object is @nil.

The method class<-super_class_name is used to create the appropriate term description (see object<-_arg).

class <-> term_names: vector*

Vector of selectors of get_methods that do not require arguments. The elements of this vector object are used by object<-_arg to return the nth (1-based) argument of the term-description.

If element <n> of this vector has value <selector>, the class must define <-<selector> and the nth (1-based) result of object<-_arg is the result of <-<selector> on the object.

For example, class point defined class<-term_functor: point and class<-term_vector vector(x,y). Therefore the term has the form:

point(`point<-x`, `point<-y`)

See also

- object<-_arg
- topic Object -> Term

class-neighbour_index: alien:int

Index of neighbour in hierarchy.

class-tree_index: alien:int

Used for very fast implementation of class->is_a and object->instance_of. After a modification on the class hierarchy (normally a class created), PCE numbers the class-hierarchy top-down and left-to-right.

The slot -tree_index is assigned the current number when this class is first reached, while the slot -neighbour_index is assigned the current number after numbering the subtree below this class. Now, a class A is_a B iff

(A<-tree_index) >= (B<-tree_index)        AND
(A<-tree_index) <  (B<-neighbour_index)

class <-> un_answer: bool

Hint for the incremental garbage collector. By default, fresh created instances (either by new/2 or some get method that generates an instance) are stored in a special table. As these instances are answers to methods, this table is called the answer table internally.

If an object is made an attribute of another object, it will be removed from the answer table and reclaimed by the garbage collector it its reference count drops to zero. Object remaining in the answer table are reclaimed if the context in which they where created is ended. The main event-loop starts/ends such a context and likewise do all method executions.

Now consider the code below, which produces an alphabetically ordered list of class-names:

?- new(Chain, chain),
   send(@classes, for_all,
                message(Chain, append, @arg1)),
   send(Chain, sort).

With the above schema, Chain will be an answer object after creation. It will be made a slot of the message object, thus loosing its answer status. After the chain->for_all, PCE will garbage collect the message. The reference count of the chain drops to zero and thus the chain is reclaimed too.

This situation is common and therefore class code sets the class<-un_answer flags to @off. This tells variable->send not to remove the chain from the answer table.