Acting on Objects Using Methods

In order to perform an action on an object’s instance data, you must call one of the object’s methods. In addition to their own specific methods, all object classes shipped with IDL except for the IDL_Container class have four methods in common: Cleanup, Init, GetProperty, and SetProperty. The Cleanup and Init methods are life-cycle methods, and cannot be called directly except within a subclass’ Cleanup or Init method. The GetProperty and SetProperty methods allow you to inspect (get) or change (set) the various properties associated with a given object.

Method Invocation Operators

IDL recognizes two forms of the method invocation operator:

Form	Syntax	Notes
.	Obj.Method_Name	Introduced in IDL 8.0
->	Obj->Method_Name	Introduced in IDL 5.0

Beginning with IDL 8.0, you can use the . and -> forms of the operator interchangeably; they are equivalent. Code intended to run on systems hosting versions of IDL prior to 8.0 should use the -> form.

Note: Discussion and example code in the IDL help system uses both forms of the method invocation operator. Discussion of object-oriented programming generally uses the older -> form, while discussion of the IDL graphics API introduced in IDL 8.0 generally uses the . form.

Object Method Syntax

In an object reference topic, the Syntax section of each object method shows the proper syntax for calling the method.

Procedure Methods

IDL procedure methods have the syntax:

Obj.Procedure_Name, Argument [, Optional_Arguments]

or

Obj->Procedure_Name, Argument [, Optional_Arguments]

where Obj is a valid object reference, Procedure_Name is the name of the procedure method, Argument is a required parameter, and Optional_Argument is an optional parameter to the procedure method. The square brackets around optional arguments are not used in the actual call to the procedure, they are used to denote the optional nature of the arguments within this document.

Function Methods

IDL function methods have the syntax:

Result = Obj.Function_Name(Argument [, Optional_Arguments])

or

Result = Obj->Function_Name(Argument [, Optional_Arguments])

where Obj is a valid object reference, Result is the returned value of the function method, Function_Name is the name of the function method, Argument is a required parameter, and Optional_Argument is an optional parameter. The square brackets around optional arguments are not used in the actual call to the function, they are used to denote the optional nature of the arguments within this document.

Note: All arguments and keywords to functions should be supplied within the parentheses that follow the function’s name.

Arguments

The Arguments section describes each valid argument to the method.

Note: These arguments are positional parameters that must be supplied in the order indicated by the method’s syntax.

Named Variables

Often, arguments that contain values upon return from the function or procedure method (“output arguments”) are described as accepting “named variables.” A named variable is a valid IDL variable name. This variable does not need to be defined before being used as an output argument. Note, however that when an argument calls for a named variable, only a named variable can be used—sending an expression causes an error.

Keywords

The Keywords section describes each valid keyword argument to the method.

Note: Keyword arguments are formal parameters that can be supplied in any order.

Keyword arguments are supplied to IDL methods by including the keyword name followed by an equal sign (“=”) and the value to which the keyword should be set. Note that keywords can be abbreviated to their shortest unique length. For example, the XSTYLE keyword can be abbreviated to XST.

Note: In the case of Init, GetProperty and SetProperty methods, keywords often correspond to object properties.

Setting Keywords

When the documentation for a keyword says something similar to, “Set this keyword to enable logarithmic plotting,” the keyword is a switch that turns an option on and off. In general, setting such keywords equal to 1 (or using the /KEYWORD syntax) causes the option to be turned on. Explicitly setting the keyword to zero (or not including the keyword) turns the option off.