Handles

Several of the interface functions return ``handles'', which are variables which contain a reference to a complex data object. The handles are in turn passed to other functions which operate on the referenced data object. If an active handle is passed to the Print family of functions, a string giving the type of handle will be printed.

When done with a handle, it should be closed (with the Close function) to free the memory used by the data object. The same effect is obtained by applying the delete operator to the handle. When iterating over a list-type of handle, the handle will be closed automatically when iteration is complete.

There are many different types of data object that can be accessed with a handle, some examples being:

string lists
database objects
file descriptors
properties

With a few exceptions, notably the file descriptor, a handle generally points to a list of objects, such as the currently selected objects, that can be iterated through. Once the iteration is complete, the handle is automatically closed, and further references will not reference an object.

See the section on math operators (18.6) for a discussion of the operations available on handles.

The HandleContent function can be called on any handle, and will return the number of objects that can be referenced through the handle. Zero is returned when the handle has iterated to completion. This function is useful in loops which contain iterations over handles.

If a handle still contains references but it is no longer needed, the Close function should be called on the handle, or the delete operator applied to the handle, to free internal resources.