Special methods

Special methods are methods declared in classes, whose name begins with an underscore character, and that are called by the interpreter in some special situations.

The _init special method

The _init method is called when the class is loaded by the interpreter. It must be declared this way :

GB_STATIC_METHOD ( "_init" , NULL , MyClass_init , NULL )

Use this method to do class specific initializations.

The _exit special method

The _exit method is called when the class is unloaded by the interpreter. It must be declared this way :

GB_STATIC_METHOD ( "_exit" , NULL , MyClass_exit , NULL )

Use this method to do class specific cleanups.

The _new special method

The _new method is called when a new object of this class is created. It must be declared this way :

GB_METHOD ( "_new" , NULL , MyClass_new , parameters )

This method can take any parameter you need, and returns nothing. The _new parameters will come from the NEW operator parameters.

Use this method to initialize the newly created object. Note that all object structure fields are set to zero.

The _free special method

The _free method is called when a new object of this class is destroyed. It must be declared this way :

GB_METHOD ( "_free" , NULL , MyClass_free , NULL )

This method take no parameter and returns nothing.

Use this method to cleanup the object. For example, is the object structure contains references to strings or objects, you must release them, otherwise you will create memory leaks.

The _next special method

The _next method is called when the Gambas program use the FOR EACH ... IN instruction to enumerate the object. This method must be declared this way :

GB_METHOD ( "_next" , return type , MyClass_next , NULL )

Or this way :

GB_STATIC_METHOD ( "_next" , return type , MyClass_next , NULL )

The method takes no parameters, and may return an enumerated data.

The method can be static. Then, the class will be enumerable, not the object.

This method can return nothing. Then, you will enumerate the object with a FOR EACH instruction, without the IN part.

Inside the _next method implementation, you will use some specific Gambas Programming Interface functions :

GB.GetEnum will give you a pointer to a enumeration buffer. Use this buffer to store the state of the enumeration. You can store up to 12 bytes into this buffer.

Note that the buffer is initialized with zeros at the beginning of the enumeration, so that you can detect this particular state.

When the end of the enumeration is reached, use the GB.StopEnum function to tell the interpreter, and returns immediately from the implementation function.

The _get special method

The _get method is called when the [ ] operator is used on the object or the class to extract data. This method must be declared this way :

GB_METHOD ( "_get" , return type , MyClass_get , parameters )

Or this way :

GB_STATIC_METHOD ( "_get" , return type , MyClass_get , parameters )

The method can be static. Then, the [ ] operator will have to be used on the class, not the object.

The method can take any parameters. These parameters will be those passed between the [ and the ] operators. For example, the instruction Val = MyObject[X, Y] will cause a call to _get with X and Y as parameters.

This method must return the data extract from the object or the class.

The _put special method

The _put method is called when the [ ] operator is used on the object or the class to insert data in it. This method must be declared this way :

GB_METHOD ( "_put" , NULL , MyClass_put , parameters )

Or this way :

GB_STATIC_METHOD ( "_put" , NULL , MyClass_put , parameters )

The method can be static. Then, the [ ] operator will have to be used on the class, not the object.

The method can take any parameters. These parameters will be the value to insert into the object, and those passed between the [ and the ] operators. For example, the instruction MyObject[X, Y] = Val will cause a call to _put with Val, X and Y as parameters.

This method returns nothing.

The _call special method

The _call method is called when the class or the object is used as a function. This method must be declared this way :

GB_METHOD ( "_call" , return type , MyClass_call , parameters )

Or this way :

GB_METHOD ( "_call" , return type , MyClass_call , parameters )

This method can be static. Then, the class will be able to be used as a function, not the object.

This method can take any parameters, and return anything.

The Message class of the gb.qt component is a good example of the use of this feature.

The _unknown special method

The _unknown method is called when the interpreter didn't find a method or property symbol in the class declaration. This method must be declared this way :

GB_METHOD ( "_unknown" , "v" , MyClass_unknown , "." )

This method takes a variable number of arguments, and returns a Variant value.

Inside the implementation function :

The Application class of the gb.qt.kde component is a good example of the use of this feature : when you do a DCOP call, the interpreter doesn't know if the application is loaded, if the method exists, what its parameters are, and so on. So the _unknown special method is welcome !