so_libraries

Handling HBasic packages

Overview

Most scripting languages available for LINUX provide some kind of modules that may be loaded at runtime to extend the functionality of the base program. This modules are normally shared object libraries set up with C or C++ code. The binary code may be loaded at runtime and the functions implemented can be called from the scripting language.

Currently there are different formats for shared object libraries in HBasic. This mainly depends on the description of the methods and components that have been implemented in the (shared object) library. The library descriptions need different formats for HBasic packages, Qt-C support and the access to common shared object libraries added in the last version.

Starting with version 0.8.8 I have implemented one common format of descriptions for shared libraries. Packages created for this new format still need a separate documentation file but there is a separate program called libdesc with a graphical user interface to set up and edit this descriptions. Therefore it is no longer necessary to edit XML style files needed in previous versions of HBasic. The libdesc program can check the syntax of the exported parts of a library and can generate some information needed automatically. This will make many parts of handling components much simpler than before.

What is a component

A component is a piece of precompiled C or C++ code which may be used from your HBasic program. A component always will be delivered with a machine readable description of the exported parts. HBasic uses this description to check the correct syntax of a method call prior to executing the code, to display the methods in the package manager or to implement code completion in the source code editor. Components may implement additional functions, set up interfaces to libraries published in C or C++ or connect to widgets that may be used in the formdesigner.

HBasic can only load groups of components which will be called packages. A package can export component definitions, global methods or global constants. If you only want to make some C++ methods available in HBasic you should take a look at the simple example . If you C++ code needs to store local variables for each instance of a class style type you can set up a C++ class and let HBasic create instances of this class. This classes must be derived from QObject or QWidget if they should represent visible Qt widgets. HBasic uses the Qt metaobject interface to query the signals, properties and slots of this class definitions. You may catch the signals similar to event definitions in your HBasic code, call the slots like methods and read or write the property values. You do not need to create any interface definition to make this happen. The Qt MOC compiler set's up all information needed when compiling your component definitions. You can find some documentation how to create class definitions here. You can also take a look at the code examples in the packages folder of your HBasic distribution. All components and widgets of the formdesigner that will be used in HBasic code examples are implemented as shared object libraries and you can find the sourcecode in the subdirectories of the packages folder.

Loading the library description in the package manager

If you have the shared library solib.so and the description file solib.dso you can tell HBasic projects to use this library in your current project. This will be done by adding the library description to the package list of your project. Saving the project will store this package list and reload it with the project file later. To add the shared library description to your project click on Add package and select the solib.dso file in the file selector dialog.

Image: HBasic package manager displaying components of example_package

You should now see a new red symbol for the library description solib.dso and the methods available in this shared library. Since there are no class definitions within this shared library descriptions (all symbols are defined global) the ListView classlist in the package manager will stay empty for this packages.

Calling methods in the shared library

After you have included the shared library description into your project with the package manager you can call methods of the library from the HBasic sourcecode. To use for example the method addthem to compute the sum of to integers 22 and 44 call the method like any other global defined symbol.


' Call a method from a shared object library

Sub button1_clicked()
   Print addthem( 22, 44)
End Sub

Example: Call method in shared library.

Executing this program HBasic will transfer the parameter into the format needed, find the method start in the library file, call the method and transfer the return value back to a HBasis value. You can find some small example programs in the code_examples/solib folder of the HBasic distribution. This examples try to load solib.dso from /usr/local/hbasic/packages and call the methods defined in the shared library solib.so. In this examples you can see that there is no difference in HBasic between calling the C-function addthem and calling the cpp function add_cpp.

Using constants defined in the shared library

With the libdesc program you may define some constant values that may hide some values used with the library behind a textual representation. This constants may be used everywhere in you HBasic program if you have added the library to your current project with the package manager.

The hbasic_stdgui library defines for example a constant Pi for which you can display the value with a code like


' Print the value of the constant Pi

Sub button1_clicked()
   Print Pi
End Sub

Example: Display constant value defined in shared library.

Passing components as Qt class parameter

If you want to call methods for components that are inherited from predefined Qt classes there may be parameter values that are pointer to other Qt classes. Let's take an example where we want to set the position and size of the button widget which is inherited from the Qt class QPushButton. The position and size may be set with a parameter of type QPoint and QSize. You cannot use normal HBasic types to create this parameters. I have created some additional classes named Point and Size which represent this Qt classes but if HBasic tries to compare the Qt parameter type "const QPoint &" with the HBasic style component type Point it cannot find a match.

If you put the name of a Qt class into the field named "Qt class" in the class editor HBasic takes this as a hint that the component of type Point may be used instead of a parameter of type QPoint in a method call. Therefore the following code will no longer abort with an "illegal parameter" error.


Public p As Point
Sub setButtonPos( xpos As integer, ypos As integer )
   p = QPoint( xpos, ypos )
   button1.move( p )
End Sub

If your components just creates a pointer to a Qt class insert the name of the Qt class in the class editor as the component description. Otherwise leave this field blank.

Using component icons

In the component editor of the program libdesc you may select an icon image to represent the component in the formdesigner. When HBasic loads a shared library package you can see an icon for all components that have been defined with an icon image.

The image above shows some icons from the hbasic_stdgui package which declares the default widget components for HBasic. If you select one of this component icons in the select window and click on the formdesigner window afterwards HBasic will create an instance of the component that belongs to the icon and displays the component properties in the property editor. If the component has been derived from QWidget an instance of the component will be created in the formdesigner. If the component is derived from QObject a small button will be created instead. In this case you can edit the properties of the component in the property editor if you select this button with a mouseclick.

Using component instances in HBasic

Create intance in formdesigner or define component instance with code like "Dim varname As componentname". You can find different examples how to define and use components in the code_examples/components folder of your HBasic directory.