Documentation Set for Swarm 2.2
Prev | Reference I. Defobj Library | Next

# Customize

## Name

Customize -- Create-phase customization.

## Description

Some types accept create-time messages not only when creating a new instance, but to customize a new version of the type itself. Objects created from a customized type will have all options preset that create-time messages sent to the customized type object have already set. If many objects all need the same create-time options, it is often simpler (and can also be faster) to create a customized version of a type first, and then create further instances from that type.

Customizing a type object does not modify the original type object, but instead creates a new type object that has the customizations built-in. A create: message on the new type object creates a new instance as if the same sequence of create-time messages had been sent to the original type object using createBegin: and createEnd. A type is customized by bracketing the sequence of create-time messages not with the createBegin: and createEnd messages used to create a new instance, but with customizeBegin: and customizeEnd messages instead.

Whether a customized version of a type can be created depends on the implementation of the type itself. If a type does not support customization, a customizeBegin: message on the type raises an error. All types defined by an @protocol declaration may be relied on to support at least one cycle of customization to create a new type object. Whether an already customized type object (returned by customizeEnd) supports a further cycle of customization (by another sequence of customizeBegin:/customizeEnd) depends on the implementation of the original starting type. A type should not be relied on to support more than one cycle of customization unless it is specifically documented to do so.

## Protocols adopted by Customize

None

## Methods

### Phase: Creating

- - customizeCopy: aZone
  The customizeCopy: message creates a new copy of the interim object returned by customizeBegin: which may be used for further customizations that do not affect the customization already in progress. It may be used to branch off a path of a customization in progress to create an alternate final customization.
  customizeCopy may be used only on an interim object returned by customizeBegin: and not yet finalized by customizeEnd. The new version of the interim object being customized may be allocated in the same or different zone as the original version, using the zone argument required by customizeCopy:

  Example defobj/Customize/-customizeCopy:/1.

       newArrayType1 = [Array customizeBegin: aZone];
       [newArrayType1 setCount: 100];
       newArrayType2 = [newArrayType2 customizeCopy: aZone];
       [newArrayType2 setDefaultMember: UnsetMember];

       newArrayType1 = [newArrayType1 customizeEnd];
        newArrayType2 = [newArrayType2 customizeEnd];
       array1 = [newArrayType1 create: aZone];  // no DefaultMember option
       array2 = [newArrayType create: aZone];   // DefaultMember option set

- - customizeEnd
  Returns the new, customized version of the original type.

- + customizeBegin: aZone
  Returns an interim value for receiving create-time messages much like createBegin:.
  The zone passed to customizeBegin: is the same zone from which storage for the new, finalized type object will be taken. This zone need not be the same as any instance later created from that type, since a new zone argument is still passed in any subsequent create message on that type.

## Examples

Example defobj/Customize/1.

     newArrayType = [Array customizeBegin: aZone];
     [newArrayType setCount: 100];
     newArrayType = [newArrayType customizeEnd];
     array1 = [newArrayType create: aZone];
     array2 = [newArrayType create: aZone];
     // [array1 getCount] and [array2 getCount] are both 100

Prev | Home | Next
CreatedClass | Up | DefinedClass