Using Qt-C bindings

Contents

Overview

Including HBasic packages into your project allows you to create and use instances of the components that have been defined in the packages. You may call the methods that have been defined as slots and read or write properties that have been defined for the components. HBasic can query the list of available methods, properties and events of a component through the QMetaObject interface if the component has been derived from the Qt QObject class.

When using Qt classes in the C++ language there are some more methods which might be used in your C++ program.

1) Classes which are not inherited from the QObject class
2) Public methods which have not been defined as a Slot

Using the Qt-C bindings allows you to create instances of all classes defined in the Qt library. Currently there are about 350 classes with different tasks which you may use. Not all of them make sense in the HBasic language but they might be used as a parameter or return value of the more important classes. To set some properties of a buton you might for example need classes like QPoint, QSize, QRect (to call setGeometry) or QPixmap.



Why I don't use special HBasic components

It would be possible to create some HBasic components that can be used as a size or pixmap value but all they had to do when a method of this classes will be called is to call the appropriate Qt method instead. Reading or writing the width and height of a user defined Size component would for example read or write the width and height of the inherited Qt component.
Doing this for 300 Qt classes with approximatly 20-50 public methods each would be a little bit boaring and might never be correct for your current Qt version. If there are updates or other changes in the methods of the Qt library in different versions a component definition created for Qt-3.1 might not be compilable with Qt-3.2.



How does Qt-C support work

As I explained above creating instances and using methods of Qt classes from HBasic needs special wrapper function in the C++ code for each method that might be called. There is already a library called libqtc.so which includes this function calls. This library will normally be used to call Qt methods from C sourcecode. You can normally find this library in the kdebindings package of the KDE distribution. Some distributions might not deliver this package and some users don't want to install the complete kdebindings package to use one library. Therefore I have put a version of the required sourcecode into the qtclib directory of the HBasic distribution. This library will be compiled with HBasic and installed in the /usr/local/hbasic/packages directory.

To access Qt-C bindings HBasic will load the library dynamically if requested. There is some additional information needed about the classes and it's methods. Using the library in C-sourcecode the C-compiler will read this information from the *.h includefiles. Since we cannot read includefiles in HBasic there is a additional file called qtc_info that will provide this information for HBasic. Running make in the qtclib directory will also create and install this information file.
  

Include Qt-C support in HBasic project

Qt-C support will not be loaded on default starting HBasic because they take some resources like memory. Maybe I will change this in future versions. To add Qt-C support to the current project execute the following 2 steps:

1) Open the project options dialog
Either select "project options" in menubar or click with right mousekey on project name in project tree



2) Select the checkbox "Additional libraries/Include Qt C-bindings" to include Qt-C-bindings into the current project.


 

This will load the Qt-C library and the qtc infofile. If you save this project HBasic will load the library when loading this project file automatically if required. If HBasic can load the library without errors you are ready to execute the examples described in the rest of this document.

 

Getting information about Qt-C classes

If you have included the Qt-C support into the current project you will find a new entry in the package list of the package manager named "QT-C classlist". Selecting this icon will display the list of known classes in the current version of the Qt-C library. For each class the package manager can display the inherited classes, a list of methods defined, the constructor methods used to create class instances and a list of constants defined with the Qt class.



The rest of this document will show some simple examples showing how to create and access this Qt classes. You can also find some example programss in the code_examples/qtc folder of your HBasic distribution.

Code completion in the source code editor currently only displays information about Qt-C classes if you create a new class instance (Example c=New QString() will display QString info). If you access Qt-C methods in the code a popup may give you the chance to start the package manager for the Qt-C class referenced. I thought the information for a class defining many methods and constants about a class is too complex to be displayed in a small popup in the editor. If you see a reference like the one displayed in the following image you may open the package manager with a mouseclick on the small info-Button on the left side.



 

Hello world using Qt-C QString class

In this example we want to create an instance of the Qt-C QString class to output the string "Hello QTC world". 


Sub button1_clicked()
   Dim a As QString

   a = New QString( "Hello QTC world" )
   Print a
End Sub
Example qtc_hello.bas:  Create Hello output with Qt-C class .

The Dim statement may be used in the normal way to define a variable instance of each Qt-C class. After that we have to create an instance of the QString class with the New statement. The parameters for the constructor may be the same as the matching Qt-C constructor methods. They are similar to the Qt constructor methods. Code completion for this methods will be implemented later to give you some detailed information of the methods and parameters available.

After the New statement has been executed the variable a holds a pointer to the QString class that has been created. The Print statement will show the contents of the QString class. This will display the string "Hello QTC world" in the current form.

 

Printing Qt-C string values

As already used in the "Hello QTC" example you can use the normal Print statement to display the contents of a QString Qt-C object. This will print the current contents of the QString on the active form.


Sub button1_clicked()
   Dim a As QString

   a = New QString( "Hello QTC world" )
   Print a
End Sub
Example qtc_hello.bas:  Create Hello output with Qt-C class .

 

Using QString for string functions

In this example we want to call some methods of the QString class. Therefore we create two strings a and b and call QString.append to append b to the end of a, QString.length to retrieve the length of a string and call QString.insert to insert one string into another.


Sub button1_clicked()
   Dim a As QString
   Dim b As QString
   Dim i As integer

   a = New QString( "Hello " )
   b = New QString( "QTC world" )
   a = a.append( b )
   Print a

   i = a.length()
   Print i

   b = New QString( "super " )
   a = insert( 6, b )
   Print a
End Sub
Example qtc_string.bas:  Example of method calls for QString class.


 

Reading constants/enum values from Qt-C classes

Some Qt classes provide enumeration values that may be used in method calls as a parameter value. The Qt-C bindings can read and use this values in every expression. You may therefore also use this values as a parameter in Qt-C method calls.

The following example will display the values of three enum names from the Qt library.


Sub button1_clicked()
   Print QAccessible.MenuStart
   Print QAccessible.SelectionRemove
   Print QAccessible.EditableText
End Sub
Example qtc_enum.bas:  Example of .

 

Creating visible Qt components with Qt-C

Beside using invisible classes like QString you may also create visible widgets like a QWidget or a QButton. t is simpler to do this with the HBasic GUI Designer but this example should show how you can do it with code that creates instances of Qt-C classes.


Sub button1_clicked()
   Dim w As QWidget
   Dim a As QPushButton
   Dim s As String

   w = New QWidget( NULL, "wgt", 0)
   s = New QString( "OK" )
   a = New QPushButton( s, w, "Hallo" )

   w.show()
   w.resize( 200, 100)
   a.setGeometry( 20, 30, 80, 28 )
End Sub
Example qtc_button.bas:  Example of  visible Qt-C widgets

 

Using HBasic components with Qt-C

Both types of classes (HBasic packages and Qt-C classes) have advantages and disadvantages. It therefore makes sence if it is possible to assign a HBasic object pointer to a Qt-C object pointer. Since Qt-C objects only need the pointer to the objects components created with the HBasic GUI-editor can pass there object-pointer through the widget property. The following example reads the widget property of the push button button1 that has been created in the formdesigner and assigns it to a QPushButton class variable. This classpointer will be used afterwards to resize the components with the Qt-C resize method.
  

Sub button1_clicked()
   Dim a As QPushButton

   a = button1.widget
   a.resize( 200, 50 )
End Sub
Example qtc_use_button.bas:  Example of using HB components with Qt-C.

 

Using static methods with Qt-C

Every Qt-C class may provide two types of methods. Normal methods need an instance of the baseclass and will be called as class_variable.methodname. HBasic will automatically pass a pointer to the class instance of class_variable to this methods. The second type of methods are static methods which may be called without an instance of a Qt-C class.

Have a look at the following example program where the current date should be stored in the variable d of type QDate. When calling the currentDate method there is no instance of the QDate class which may provide the current date value. Therefore the currentDate method is implemented as a static method which may be called without an instance of a class variable.

To call this kind of method you have to use the class name (QDate in the example) instead of a variable instance in the methodcall.

Call Classname.static_method_name( variable_list) for static methods


Sub button1_clicked()
   Dim d As QDate

   d = New QDate()
   d = QDate.currentDate()
End Sub
Example qtc_date.bas:  Example of using static methods with Qt-C.