Creating shared object libraries

This document lists the examples of shared object libraries that will be delivered with HBasic and shows some examples how you can set up new libraries.

Contents

Create simple shared library

To show you how simple it is to set up a shared object library for HBasic we start with a single method. This method should do nothing more than receive a value from HBasic and return a changed value. Create a new file called testlib.cpp with the following code in your favourite editor: 


int add_two( int in_par )
{
	return( in_par + 2 );
}
Example: Simple method example for shared library.

To compile this source code to a library call gcc in the following way:

gcc -o testlib.so -shared -g testlib.cpp

This will create a new shared library testlib.so which exports our method definition. Compiling the program with debuggin support will help us to set up the library description. Since HBasic tries to find libraries in /usr/local/hbasic/packages you may copy the library to this directory but you can also keep it in any other directory.

Examples delivered with HBasic

To display how to work with methods exported by a shared library I have put two examples into the HBasic distribution. In the directory code_examples/solib you can find C++ code that exports 3 global method definitions and in the directory packages/example_package you can find e library exporting two class definitions.

Start the command make in this directories and you will have a shared library called solib.so that exports 3 symbols.
  1. A method intvalue which when started will return a value of 1234.
  2. A method addthem which will return the sum of two integer parameters passed as parameter value
  3. A method addcpp which will also return the sum of two integers but is implemented as a cpp method
To include this libraries into your HBasic projects you have to add some library description. Have a look at the simple shared library example or read the following paragraphs to find out how you can set up this library description.

Create class example in C++

If you want to use Qt objects and widgets or event handling within HBasic you need a little bit more complex code in your C++ library. Libdesc therefore allows you to define your own classes. The capabilities of a class definition are between user defined types and object oriented class definitions. To set up a class definition that may be used in a shared object library you will need three things.
  1. A C++ class definition which inherits QObject or QWidget.
  2. A global method which creates an instance of the class and returns a pointer to it
  3. A component description created with the libdesc program
With this descriptions available you can create instances of the class in HBasic with the formdesigner or with a variable definition like

Dim varname As componenttype

HBasic may than access the signal, slot and property definitions exported by the component. You may call every public slot of the Qt class like a method in the form varname.methodname( parameter ). You can catch events triggered by the Qt class as a signal definition with a function definition like Sub button1_clicked () which connects to the clicked event of the button widget and read or write values of property definitions.

You can find examples of this component definitions in the packages folder of your HBasic distribution. The example_package folder contains a simple class definition which exports one class derived from QObject and one class derived from QWidget.

The following code declares an example class derived from QObject and a global method to create an instance for this class. The class currently only exports a method definition.


class Nogui : public QObject
{
	Q_OBJECT

public:
	Nogui( void );

public slots:
	int add( int p1, int p2 );
}

Nogui::Nogui( void ) : QObject()
{
}

int Nogui::add( int p1, int p2 )
{
	return( p1 + p2 );
}

/* ----------------------------------- */

long new_nogui()
{
	return( (long)new Nogui() );
}
Example: Class definition for shared object class.

Beside the normal class definitions you only need to set up some methods like add and define them as public slots. This is enough for HBasic to find the method description and create a method call for the runtime interpreter or compiler generated code. Have a look at the Qt documentation to learn how to define new properties, signals and slots within your Qt class.

Deriving class definitions from QObject or QWidget

Class definitions set up in C++ can be derived from QObject or QWidget as a base class. If the class is derived from QWidget the class creating method must be defined as

QWidget *new_classname( QWidget *parent );

The class should return a pointer to an instance of the matching C++ class as a QWidget * pointer. If the class is derived from QObject HBasic will create the class with the method

QOBject *new_objectname( void );

You can tell libdesc if your class is derived from QObject or QWidget in the field Class type of the component editor dialog.

   

If you create an instance of a class that is derived from QObject in the formdesigner HBasic will display a small button that represents the class instance. The button displays the class icon if you have defined one.



If you click on this button you can edit the properties of the matching class instance in the property editor.