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.
_init special method
_exit special method
_new special method
_free special method
_next special method
_get special method
_put special method
_call special method
_unknown special method
_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.
_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.
_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.
_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.
_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.
_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.
_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.
_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.
_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 :
GB.IsProperty function will tell you if the unknown
symbol was used as a property or as a method.
GB.GetUnknown function will return the name of
the unknown symbol.
GB.NParam function will return the number of arguments
passed to the 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 !