# 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 `_exit` special method
- The `_new` special method
- The `_free` special method
- The `_next` special method
- The `_get` special method
- The `_put` special method
- The `_call` special method
- The `_unknown` special method

## 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 `GB.IsProperty` function will tell you if the unknown symbol was used as a property or as a method.
- The `GB.GetUnknown` function will return the name of the unknown symbol.
- The `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 !