<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en" dir="ltr">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<link rel="stylesheet" href="../../../style.css">
<title>
Gambas Documentation - 1. Introduction
</title>
</head>
<table class="none" width="100%" cellpadding="0" cellspacing="0" border="0">
<tr><td align="left">
<font size="-1">
<a href="../../../help+en"><img class="flag" alt="Home" border="0" src="../../../img/lang/en.png" align="center"></a>&nbsp;
<a href="../overview+en">Up</a>&nbsp;
<a href="../overview+en">Previous</a>&nbsp;
<a href="quick+en">Next</a>&nbsp;
</td></tr></table>
<div class="notab">
<h1>
1. Introduction
</h1>
<h3>What is a component?</h3>
<p>
<a href="../../def/gambas+en">Gambas</a> components are shared libraries written in C or C++ that add new functions to the <a href="../../def/gambas+en">Gambas</a> interpreter.
<p>
They act like <a href="../../def/linux+en">Linux</a> drivers towards the <a href="../../def/linux+en">Linux</a> kernel:
<p>
<ul>
<li>The components and the interpreter communicate through the <a href="../../def/gambas+en">Gambas</a> Programming Interface.
<li>They must be compiled inside the <a href="../../def/gambas+en">Gambas</a> source package.
<li>They are executed in the interpreter environment, and so must not do whatever they want.
<p>
</ul>

A component can contain:
<p>
<ul>
<li><a href="../../lang/new2+en">New</a> classes that are added to the other <a href="../../def/gambas+en">Gambas</a> classes.  These classes are declared to the interpreter using a C structure that contains the description of each symbol, method, constant and event.
<li>Interpreter Hooks: special functions that implement important interpreter operations, like managing the event loop, reading the program parameters...
<li>A programming interface that enhances the <a href="../../def/gambas+en">Gambas</a> Programming Interface, and that other components can use.
<p>
</ul>

A component must have a name. This name is the the word <a href="../../comp/gb/gb+en">gb</a> followed by a dot-separated list of words describing
the role of the component and another component it relies on, if any.
<p>
For example, <tt>gb.qt.kde</tt> is a component that transforms a <a href="../../def/gambas+en">Gambas</a> application into a KDE application. This component
relies on the <tt>gb.qt</tt> component, i.e. loading the first implies loading the second.
<p>
<h3>The <a href="../../def/gambas+en">Gambas</a> Programming Interface</h3>
<p>
The <a href="../../def/gambas+en">Gambas</a> Programming Interface is a set of utilities, functions and macros that allows you to:
<ul>
<li>Describe the component.
<li>Define interpreter hooks.
<li>Manipulate arrays, hash tables...
<li>Manipulate <a href="../../def/gambas+en">Gambas</a> native datatypes.
<li>Create <a href="../../def/gambas+en">Gambas</a> arrays and collections.
<li>Raise events.
<li>Manipulate <a href="../../def/gambas+en">Gambas</a> objects.
<li>Load a file from the project archive.
<li>Load other components.
<li>...
<p>
</ul>

The use of this programming interface is highly recommended, as it prevents a component from doing weird things.
<p>
The <a href="../../def/gambas+en">Gambas</a> Programming Interface is a C structure that contains one function pointer for each function of the
interface.
<p>
This structure is declared in the main file of your component and is automatically initialized by the interpreter at component loading.
<p>
<h3>Writing Good <a href="../../comp/gb/components+en">Components</a></h3>
<p>
Writing good components is the difficult part! Let's suppose you want to write a SDL component, i.e. a component
that lets a <a href="../../def/gambas+en">Gambas</a> project use all the power of the SDL library: graphics, sound, CD-ROM...
<p>
You can be content 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 <a href="../../def/gambas+en">Gambas</a>.
<p>
Your component will be useful, but not very interesting for the <a href="../../def/gambas+en">Gambas</a> programmer, because he will be obliged to program in C or C++ style.
<p>
Instead, you should rack your brain to create a different interface between <a href="../../def/gambas+en">Gambas</a> and the library, by trying to generalize and simplify the original interface of the library.
<p>
That is what I did with QT: it is far easier to use the QT component than programming the QT library directly. 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 put all the useful QT specific stuff into a dedicated extended component, <tt>gb.qt.ext</tt>
<p>
<h3><a href="../../comp/gb/component+en">Component</a> Source Organization</h3>
<p>
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.
<p>
For example, the <tt>gb.qt.kde</tt> component sources are stored in the .<i>src</i>lib<i>qt</i>kde directory.
<p>
A typical component directory contains :
<ul>
<li>The autoconf/automake stuff, i.e. a Makefile.am file that describes how to compile the component. (new topic)
<li>One source file and one header file for each main class implemented in the component.
<li>One main file that implements the entry points of the component.
<li>One component description file.
<p>
</ul>

For example, here is the result of ls <tt>./src/lib/qt/kde</tt> just before the compilation :
<p>
<pre class="code">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
</pre><p><p>
The component source directory structure looks something like this:
<p>
<pre class="code">-+- lib
 |
 +---+- db
 |   |
 |   +----- mysql
 |   |
 |   +----- postgresql
 |
 +----- eval
 |
 +----- example
 |
 +----- net
 |
 +---+- qt
 |   |
 |   +----- editor
 |   |
 |   +----- ext
 |   |
 |   +----- kde
 |
 +----- sdl
</pre><p>

</div>
</body>
</html>

