Creating Custom Object Method Routines

IDL objects can have associated procedures and functions called methods. Methods are called on objects via their object references using the method invocation operator.

While object methods are constructed in the same way as any other IDL procedure or function, they are different from other routines in the following ways:

Object methods are defined using a special naming convention that incorporates the name of the class to which the method belongs. See Defining Method Routines below.

All method routines automatically pass an implicit argument named self, which contains the object reference of the object on which the method is called. See The Implicit Self Argument.

Object methods cannot be called on their own. You must use the method invocation operator and supply a valid object reference, either of the class the method belongs to or of one of that class' subclasses. See Calling Method Routines.

Note
Keyword inheritance is an extremely important concept to understand when working with object methods. See Keyword Inheritance for details.

Defining Method Routines

Method routines are defined in the same way as other IDL procedures and functions, with the exception that the name of the class to which they belong, along with two colons, is prepended to the method name:

PRO ClassName::Method 
    IDL statements 
END

FUNCTION ClassName::Method, Argument1 
    IDL statements 
RETURN, value 
END

For example, suppose we create two objects, each with its own "print" method.

First, define two class structures:

struct = { class1, data1:0.0 } 
struct = { class2, data2a:0, data2b:0L, INHERITS class1 }

Now we define two "print" methods to print the contents of any objects of either of these two classes. (If you are typing this at the IDL command line, enter the .RUN command before each of the following procedure definitions.)

PRO class1::Print1 
    PRINT, self.data1 
END 
PRO class2::Print2 
    PRINT, self.data1 
    PRINT, self.data2a, self.data2b 
END

Once these procedures are defined, any objects of class1 have access to the method Print1, and any objects of class2 have access to both Print1 and Print2 (because class2 is a subclass of—it inherits from—class1). Note that the Print2 method prints the data1 field inherited from class1.

Note
It is not necessary to give different method names to methods from different classes, as we have done here with Print1 and Print2. In fact, in most cases both methods would have simply been called Print, with each object class knowing only about its own version of the method. We have given the two procedures different names here for instructional reasons; see Method Overriding for a more complete discussion of method naming.

The Implicit Self Argument

Every method routine has an implicit argument parameter named self. The self parameter always contains the object reference of the object on which the method is called. In the method routines created above, self is used to specify which object the data fields should be printed from using the structure dot operator:

PRINT, self.data1

You do not need to explicitly pass the self argument; in fact, if you try to specify an argument called self when defining a method routine, IDL will issue an error.

Calling Method Routines

You must use the method invocation operator (->) to call a method on an object. The syntax is:

ObjRef->Method

where ObjRef is an object reference and Method is a method belonging either to the object's class or to one of its superclasses. Method may be specified either partially (using only the method name) or completely using both the class name and method name, connected with two colons:

ObjRef->Class::Method

See Specifying Class Names in Method Calls for more information.

The exact method syntax is slightly different from other routine invocations:

; For a procedure method. 
ObjRef->Method 
 
; For a function method. 
Result = ObjRef->Method()

Where ObjRef is an object reference belonging to the same class as the Method, or to one of that class' subclasses. We can illustrate this behavior using the Print1 and Print2 methods defined above.

First, define two new objects:

A = OBJ_NEW('class1') 
B = OBJ_NEW('class2')

We can call Print1 on the object A as follows:

A->Print1

IDL prints:

0.00000

Similarly, we can call Print2 on the object B:

B->Print2

IDL prints:

0.00000  
0           0

Since the object B inherits its properties from class1, we can also call Print1 on the object B:

B->Print1

IDL prints:

0.00000

We cannot, however, call Print2 on the object A, since class1 does not inherit the properties of class2:

A->Print2

IDL prints:

% Attempt to call undefined method: 'CLASS1::PRINT2'.

Searching for Method Routines

When a method is called on an object reference, IDL searches for it as with any procedure or function, and calls it if it can be found, following the naming convention established for structure definition routines. (See Automatic Class Structure Definition.) In other words, IDL discovers methods as it needs them in the same way as regular procedures and functions, with the exception that it searches for files named

classname__method.pro

rather than simply

method.pro

Remember that there are two underscores in the file name, and two colons in the method routine's name.

Note
If you are working in an environment where the length of filenames is limited, you may want to consider defining all object methods in the same .pro file you use to define the class structure. This practice avoids any problems caused by the need to prepend the classname and the two underscore characters to the method name. If you must use different .pro files, make sure that all class (and superclass) definition filenames are unique in the first eight characters.