# Introduction

- What is a component ?
- The Gambas Programming Interface
- Writing Good Components
- Component Source Organization

## What is a component ?

Gambas components are shared libraries written in C or C++ that add new functions to the Gambas interpreter.

They act like Linux drivers towards the Linux kernel :

- The components and the interpreter communicate through the Gambas Programming Interface.
- They must be compiled inside the Gambas source package.
- They are executed in the interpreter environment, and so must not do what they want.

A component can contain :

- New classes that are added to the other Gambas classes. These classes are declared to the interpreter by a C structure that contains the description of each symbol, method, constant and event.

- Interpreter Hooks : they are special functions that implement important interpreter operations, like managing the event loop, reading the program parameters...

- A programming interface that enhances the Gambas Programming Interface, and that other components can use.

A component must have a name. This name is the the word `gb` follow by a dot-separated list of words describing the role of the component and the other component it relies on.

For example, `gb.qt.kde` is a component that transforms a Gambas application into a KDE application. This component relies on the `gb.qt` component, i.e. loading the first implies loading the second.

## The Gambas Programming Interface

The Gambas Programming Interface is a set of utilities functions and macros that allows to:

- Describe the component.
- Define interpreter hooks.
- Manipulate arrays, hash tables...
- Manipulate Gambas native datatypes.
- Create Gambas arrays and collections.
- Raise events.
- Manipulate Gambas objects.
- Load a file from the project archive.
- Load other components.
- ...

The use of this programming interface is highly recommended, as it prevents a component from doing weird things.

The Gambas Programming Interface is a C structure that contains one function pointer for each function of the interface.

This structure is declared in the main file of your component and is automatically initialized by the interpreter at component loading.

## Writing Good Components

Writing good components is all the difficulty ! Let's suppose you want to write a SDL component, i.e. a component that let a Gambas project use all the power of the SDL library : graphics, sound, CD-ROM...

You can content yourself with just wrapping the library functions, structure and constants. It is the easy way, even if wrapping C structures and functions may not be possible in every case with Gambas.

Your component will be useful, but not very interesting for the Gambas programmer, because he will be obliged to program like in C or C++.

I think you should better rack your brain to create a different interface between Gambas and the library, by trying to generalize and simplify the original interface of the library.

That what I did with QT : it is far easier to use the QT component than programming directly the QT library. And if one day somebody writes a GTK+ component, he will be able to use the same interface because I tried to generalize the QT interface by avoiding all the QT specific stuff... Well, to be honest, I putted all useful QT specific stuff into a dedicated extended component, `gb.qt.ext`

## Component Source Organization

The source files of a component are stored in a sub-directory of the `lib` directory of the source package. The path of this directory reflects the name of the component.

For example, the `gb.qt.kde` component sources are stored in the `./src/lib/qt/kde` directory.

A typical component directory contains :

- The autoconf/automake stuff, i.e. a `Makefile.am` file that describes how to compile the component. (new topic)
- One source file and one header file for each main class implemented in the component.
- One main file that implements the entry points of the component.
- One component description file.

For example, here is the result of `ls ./src/lib/qt/kde` just before the compilation :

    CApplication.cpp  CDatePicker.cpp  CDialog.cpp  lib.gb.qt.kde.component  main.h    Makefile.am
    CApplication.h    CDatePicker.h    CDialog.h    main.cpp                 Makefile  Makefile.in

The component source directory structure is something like that:

    -+- lib
     |
     +---+- db
     |   |
     |   +----- mysql
     |   |
     |   +----- postgresql
     |
     +----- eval
     |
     +----- example
     |
     +----- net
     |
     +---+- qt
     |   |
     |   +----- editor
     |   |
     |   +----- ext
     |   |
     |   +----- kde
     |
     +----- sdl