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 exist,
what its parameters are, and so on. So the _unknown
special method is welcome !