Given the name of a structure that defines an object class, the OBJ_NEW function returns an object reference to a new instance of the specified object type by carrying out the following operations in order:

  1. If the class structure has not been defined, IDL will attempt to find and call a procedure to define it automatically. If the structure is still not defined, OBJ_NEW fails and issues an error.
  2. If the class structure has been defined, OBJ_NEW creates an object heap variable containing a zeroed instance of the class structure.

  3. Once the new object heap variable has been created, OBJ_NEW looks for a method function named Class::INIT (where Class is the actual name of the class). If an INIT method exists, it is called with the new object as its implicit SELF argument, as well as any arguments and keywords specified in the call to OBJ_NEW. If the class has no INIT method, the usual method-searching rules are applied to find one from a superclass. For more information on methods and method-searching rules.

    The INIT method is expected to initialize the object instance data as necessary to meet the needs of the class implementation. INIT should return a scalar TRUE value (such as 1) if the initialization is successful, and FALSE (such as 0) if the initialization fails.

    Note: OBJ_NEW does not call all the INIT methods in an object’s class hierarchy. Instead, it calls the first one it finds. Therefore, the INIT method for a class should call the INIT methods of its direct superclasses as necessary.

  4. If the INIT method returns true, or if no INIT method exists, OBJ_NEW returns an object reference to the heap variable. If INIT returns false, OBJ_NEW destroys the new object and returns the NULL object reference, indicating that the operation failed. Note that in this case the CLEANUP method is not called.

If called without arguments, OBJ_NEW returns a NULL object reference. The NULL object reference is a special value that never refers to a value object. It is primarily used as a placeholder in structure definitions, and as the initial value for elements of object arrays created via OBJARR. The null object reference is useful as an indicator that an object reference is currently not usable.

Syntax

Result = OBJ_NEW( [ObjectClassName [, Arg1...Argn]] )

Return Value

Returns a reference to a new instance of the specified object type. If called without arguments, OBJ_NEW returns a NULL object reference. The NULL object reference is a special value that never refers to a value object. It is primarily used as a placeholder in structure definitions, and as the initial value for elements of object arrays created via OBJARR. The null object reference is useful as an indicator that an object reference is currently not usable.

Arguments

ObjectClassName

String giving the name of the structure type that defines the object class for which a new object should be created.

If ObjectClassName is not provided, OBJ_NEW does not create a new heap variable, and returns the Null Object, which is a special object reference that is guaranteed to never point at a valid object heap variable. The null object is a convenient value to use when defining structure definitions for fields that are object references, since it avoids the need to have a pre-existing valid object reference.

Arg1…Argn

Any arguments accepted by the INIT method for the class of object being created can be specified when the object is created.

Keywords

Any keywords accepted by the INIT method for the class of object being created can be specified when the object is created.

Version History

5.0

Introduced

See Also

OBJ_CLASS, OBJ_DESTROY, OBJ_HASMETHOD, OBJ_ISA, OBJ_VALID, Overview of Object Graphic Destinations