# Gambas Object Model

@{index}

## [1. Objects & Classes]

An **object** in Gambas is a data structure that provides properties, variables, methods and events.

It is created or *instanciated* by using the [/lang/new] operator, a class describing the object (see 1.1), and optional arguments for the object constructor (see 1.5).

Objects are accessed "by reference", i.e. by using a pointer to it, or by using a variable whose value is the address of the object data structure in memory.

[[ tip
You can see the address of an object by using the [../../lang/print] instruction:
[[ code gambas
Dim aStr As New String[]

Print aStr
]]
[[ result
    (String[] 0x80dccf8)
]]
]]

The object data structure is described by its **class**.

### [1.1. Classes]

Each Gambas object has a **class** that describes all its public properties, methods and events.
This class is a Gambas object too, whose class is the class named [../../comp/gb/class].

A **static class** is a class whose all members are **static** (see below). In Gambas, a static class is also named a **module**.

A static class cannot be instantiated: it would create an object with no dynamic variable, which is useless.

[[ box
**Example**

The [../../comp/gb.eval/system] class is a static class: all its methods are static, and you cannot create an object whose class would be [../../comp/gb.eval/system].
]]

A **virtual** class is an hidden pseudo-class whose objects cannot be explicitly manipulate. They are used internally for giving a different "view" of an already existing normal object.

### [1.2. Properties, methods and variables]

Properties and methods allow to manipulate the data structure.

A [/def/property], a [/def/method] or a [/def/variable] can be **static**:
* A static variable will be shared by all instances of the same class.
* A static property or method can only access or modify static variables.

A method or a variable can be either **public** or **private**. A property is always public.

Private symbols can only be used from the class inside.
Public symbols can be used everywhere, provided you have a reference pointing at the object.

### [1.3. References]

There is no garbage collector in Gambas. So each object has a **reference counter** that is incremented each time the object is referenced by any variable, array, collection or other object, and decremented when it is released.

This reference counter is zero at object creation, and when it becomes zero again after a reference release, the object is freed.

If an object has created any other objects within itself that raise events (eg. timers, sockets, etc.), references to these other objects must be explicitly freed before the the reference to the object itself can be freed. This is because as soon an object A that raises events is created inside another object B, the object A internally references the object B as its "event observer". So B cannot be freed before the object A is freed.


### [1.4. Invalid objects]

An object can become **invalid**. Because, for example, it is linked to an internal object not managed by Gambas that was destroyed (for example, a window).

Trying to use an invalid object raises an error.

### [1.5. Special methods]

Special methods are methods declared in classes, whose name begins with an underscore character, and that are called by the interpreter in the following situations:
* When an object is created.
* When an object is freed.
* When the object class is loaded.
* When the object class is unloaded.
* When using an object as if it is an array.
* When enumerating the object.
* When using an object as if it is a function.
* When an object is attached to or detached from its parent.
* When trying to use an unknown object method or property.
* To know if that unknown symbol is a method or a property. 
* When an object construction is finished, and is ready to be used.
* When serializing an object to a stream.
* When unserializing an object from a stream.

See [/lang/special] and [Special Methods] (/dev/api/cat/special "For component developers") for more information.

## [2. Events & Observers]

### [2.1. Events]

Events are signals sent by an object when something happens on it.

If an object raises events, it will hold a reference on its *default observer*, or *parent object*.

This default observer is another object that implements *event handlers*. An *[event handler](/def/eventhandler)* is just a public method
that is called each time the event is raised.

By default, the observer is the current object where the newly instantiated object is declared.

To raise events, an object **must** have an *event name*. This event name is assigned at object instantiation, 
when using the [/lang/new] instruction and the [/lang/as] keyword, and is the prefix of all event handler methods.

#### Example
This creates a [/comp/gb.qt4/button] control that will raise events.
[[ code gambas
Dim hButton As Button

hButton = New Button(Me) As "ButtonEventName"

Public Sub ButtonEventName_Click()

  Print "This is the 'Click' event handler for the previous button."

End
]]

If no event name is specified, then the object won't raise events.

Some events can be cancelled by the event handler, by using the [/lang/stopevent] instruction.
The effect of this cancellation depends on the event. It usually at least stop the possible event propagation.

### [2.2. Default parent object (or default default observer)]

Some objects can have a default parent object if you do not define it by specifying an event name with the `As "xxx"` syntax.

At the moment, the only objects having a default parent object are [forms](/comp/gb.qt4/form), which use themselves as default parent object.
This was done to mimic the behaviour of Visual Basic&trade; and help old VB developers.

If you create a Form and specify its event name with the `As "xxx"` syntax, that default behaviour will be overridden.

### [2.3. Locking Objects]

An object can be locked so that it stops raising events, and can be unlocked so that it raises them again.
See the [Object.Lock] (../../comp/gb/object/lock) and [Object.Unlock] (comp/gb/object/unlock) methods.

[[ warning
An object is automatically locked during the execution of its constructor: he cannot send nor receive any events.
]]

### [2.4. Observers]

[Observers] (/comp/gb/observer) are objects that allow you to intercept events raised by other objects. They "observe" them.

You can intercept events just before they have been raised, or just after.

For each intercepted event, the observer will raise an event with the same name and the same arguments. 
These events are raised in addition of the original event handled by the *parent object*.

If you use [../../lang/stopevent] inside an observer event handler, the original event is cancelled.

#### Example
[[ code gambas
Private $hButton As Button
Private $hObserver As Observer

Public Sub Form_Open()

  $hButton = New Button(Me) As "Button"
  $hButton.Text = "&Click"
  $hButton.Height = 28
  $hButton.Width = 80
  $hObserver = New Observer($hButton) As "Observer"

End

Public Sub Observer_Click()

  Debug "The button has been clicked. I have cancelled the event!"
  Stop Event

End
 
Public Sub Button_Click()

  Debug "If you see me this is a bug!"

End
]]

## [3. Inheritance]

Inheritance is the way for a class to become a specialized version of another class.

### [3.1. What is inherited?]

The class inherits from its parent every method, property, constant
and event.

[[ warning
You must use the [/lang/me] keyword to access the inherited elements from the class implementation code.
]]

### [3.2. Which class can be a parent class?]

You can inherit any class, even a native one!

For example, you can create
a custom MyListBox class that inherits [/comp/gb.qt4/listbox]
but allows to associate a tag with each list item.

Note that you cannot use '[/lang/inherits]' in a form class file, because forms already
inherit the [/comp/gb.qt4/form] class. It's the same constraint for every other types of forms, like [/comp/gb.report2/report], [/comp/gb.web.form/webform]...

[[ warning
The inheritance tree depth cannot be greater than 16. This is a constant hard-coded inside the Gambas interpreter.
]]

### [3.3. Virtual dispatching]

When calling a method or accessing a property from an object reference, Gambas always
uses **virtual dispatching**.

It means that the real class of the object is always used, and
not the type of the variable that references the object - as it was in Gambas 1.0.

### [3.4. Inheritance and constructor]

Contrary to all the object languages I am aware of, each class in the inheritance
hierarchy consumes the parameters passed to the constructor.

Let's suppose we have the following inheritance tree:

    MyListBox ➞ ListBox ➞ Control

* [/comp/gb.gtk/control]._new() does not exist.
* [/comp/gb.qt4/listbox]._new() takes one parameter: the parent control.
* MyListBox._new() takes one parameter: a name - It is just an example.

So '[/lang/new] MyListBox' will take two parameters.

* The first will be sent to [/comp/gb.qt4/listbox]._new().
* The second to MyListBox._new().

Be careful: the [/comp/gb.qt4/listbox]._new() will be called first,
so that you are sure that the [/comp/gb.qt4/listbox] control exists
when you are in MyListBox._new().


Then you will create a MyListBox control this way:

[[ code gambas
hMyListBox = NEW MyListBox(hContainer, "Name")
]]

So the order of arguments is the following:


* Mandatory arguments are consumed first, and then optional arguments if they are available.
* The arguments of elder classes are specified first.

[[ warning
In Gambas 2.0, the arguments order was reversed!
]]

For example, if you have the following inheritance:

    MyForm ➞ Form ➞ Window

with the MyForm constructor being:

[[ code gambas
Sub _new(FirstArg As String, SecondArg as Integer, Optional ThirdArg As Integer)
]]

Note: the [../../comp/gb.qt4/form] constructor takes no argument, and the [../../comp/gb.qt4/window] constructor takes an
optional parent argument.

The signature of the final constructor will be:

[[ code gambas
New MyForm(FirstArg As String, SecondArg As Integer, Optional Parent As Control, Optional ThirdArg As Integer)
]]

In a more general way, the order of arguments for a three level inheritance tree is:

* Mandatory arguments of the grand-parent constructor.
* Mandatory arguments of the parent constructor.
* Mandatory arguments of the final constructor.
* Optional arguments of the grand-parent constructor.
* Optional arguments of the parent constructor.
* Optional arguments of the final constructor.

### [3.5. Symbol Overriding]

The rules for symbol overriding are the following:

* A dynamic symbol must be overridden by a dynamic symbol, a static one by a static one.
* A method must be overridden by a method with exactly the same signature.
* A read/write property must be overridden by a read/write property.
* A read-only property must be overridden by a read-only property.
* A constant can be overridden by another constant.
* Variables cannot be inherited. @{since 3.12}

Moreover, the signature of the symbol in the child class must be *compatible* with the signature of the symbol in the parent class.
- For properties and constants, it means that the child datatype must be compatible with the parent datatype.
- For methods, it means that the child return datatype and arguments datatypes must be compatible with the parent return datatype and arguments datatypes.

A child datatype is compatible with its parent datatype when either:
- They are exactly the same.
- The parent datatype is [/lang/type/object] and the child datatype is any class.
- The parent datatype is a class, and the child datatype is another class that inherits the parent class.


## [4. Components]

Gambas component are external shared libraries written in C, C++ or in Gambas that add new functions and/or classes to the Gambas interpreter.

[/comp/gb/classes] are grouped according to the component they come from.

### [4.1. Default internal component]

The interpreter includes an internal component named [/comp/gb] that defines all standard classes of the language.

This component is always loaded by default, and can be considered as part of the language.

### [4.2. Symbol tables]

Each component has its own private class symbol table, so that class names do not conflict.

### [4.3. Global symbol table]

So that components can work together, there is a global symbol table, where all classes exported by components and all classes exported by the current project are stored.

If there is a name conflict in this global symbol table, the last loaded class overrides the
previous loaded class with the same
name, by using inheritance. In other words, the overriding class extends the overridden one.

This last feature can be used for:
* Extending an already declared class by adding new methods or properties to it. For example, the '[../../comp/gb.qt4]' [/comp/gb.qt4/application] class reimplements the '[../../comp/gb/gb]' [/comp/gb/application] class.
* Overriding the methods of an already declared class. For example, the '[../../comp/gb.form.dialog]' component replaces most of the static methods of the [/comp/gb.qt4/dialog] class.

### [4.4. Project symbol table]

Your project has its own private symbol, like any component, and can export any of its classes to the global symbol table
by using the [../../lang/export] keyword.

The project classes are loaded after all components. So your exported class can override any exported classes declared in any component.

### [4.5. Namespaces]

@{since 3.17}

Namespaces allow to choose the name of a class when it is exported.

In that public name, it is now possible to insert a colon, where the part before the colon is the "namespace".

For the Gambas interpreter, namespaces are just a convention. It only deals with the full exported name of the class.

That feature allows to create a library without worrying about possible class name conflicts with other libraries.

See the documentation of [/lang/export] for more details.

### See also
[[ seealso
* [/comp/gb/object] 
* [/comp/gb/class]
* [/lang/export]
]]
