HBasic packages

There are some packages that will already be delivered with HBasic. This document should give an overview of this packages and the components in it.

Contents

Creating components / packages
 

Directories for packages in HBasic

The source files for HBasic component-definitions are stored in a subdirectory of the HBasic home directory which is called packges. Each component definition has an own subdirectory within this packages directory which is named like the package (without the version number). The name of the package is created by three parts separated by an underline character. The first part should be the creator of the package (like a vendor name). For hbasic packages use "hbasic" as the first part of the name. The second part is the unique name of the package for the vendor named in the first part. The third part is a version number which should give some information about the release level of the component.

When a package has been compiled there are two files that belong to a package. The first is the library file itself which must be a dynamic link library that HBasic may load at runtime and the second is a description that helps HBasic to find the components and their structure within the package. The names for this two files are <package_name>.hbso for the shared library and <package_name>.desc for the description file. See "source files in a package" to lear how to set up the package source to create these files.

 

Basic requirements to set up a package

HBasic packages are shared libraries that may be linked to the HBasic executable at runtime. These libraries export functions that Hbasic may call to access the functionality of the package. The main part of a package is a function table that points to all functions that HBasic may need. Each package exports a function with name "init_package" that should be called to initialize the package. This function must also initialize the function table and return the start address of the table.

The second important part is the description of the package which is stored in a separate file. The format for this description is a readable text in a XML like format. You can find a short description of the syntax for this file in "Description of methods, properties and events".

 

Source files in a package

To create a new package you normally use a C or C++ source file and a C-compiler like gcc. You may use other methods to create a shared library that exports a function with name "init_package" but I always prefer to use C++. You can find some examples for packages source files within the directory packages of your HBasic distribution.

 

Parts of a component

A component may set up the following parts to be used by a HBasic developer

Methods that can be called from HBasic

A method in a component is a function that may be called from a HBasic program. The code that will be executed is declared in the C or C++ code of the compiled package. HBasic finds the code that should be executed by the function number that is listed in the method description. The init_package must set the matching function address at the specified position in the function table. For the function number 6 which will be used in the following example this should be set up like "function_table[6] = &function_code".

Properties that may be used with read and write access

A property is a variable that is stored local in the component. To read or write the component Hbasic calls a function within the shared library that's deliverd with the package (*.hbso file). For each property there may one function to write the value (set function) and one to read the value (get function). The set function gets the new property value as a parameter and the get function returns the current value of the property.

As for other function calls used by HBasic the starting address of these two functions must be listed in the function_call table that is set up by the init_package function. In the following example the address of the set function must be at position 25 in the function table and the address of the get function is at address 26.

Events which may be catched in HBasic source files

A component may raise an event at any position where it is needed. If there is a function in the HBasic source that is connected to this event the execution of the current Hbasic program will be interrupted and the event will be called as a subroutine. After finishing the event function the program continues at the position where it has been interrupted.

Description for methods, properties and events

The description of a package is a file in with an ascii text that may be read and edited by every normal editor program. The contents is written in XML style. This document should give a short overview of the syntax of this document. If you want to create a new description it is normally simpler to copy an existing file of another package and change it in the way you need it for your own components.

The header of a package

Each package description is made of the one header which describes the package properties and a list of component definitions. The syntax of a package is:

<namespace>
   [package description header]
   <class>
      [description of first component]
   </class>
   <class>
      [description of second component]
   </class>
   ...
   <class>
      [description of last component]
   </class>
</namespace>

Starting with a namespace tag it should be possible to declare more than one namespace (logical structure for components) within one package. Currently this is not used but the namespace tag is needed to support the correct syntax. In the following we show some examples from the description of the hbasic_stdgui package.

<namespace>
  <name>QT_STDGUI</name>
  <version>100</version>
  <shortdesc>Standard GUI-QT components for HBasic</shortdesc>
  <desc>
      <line> "This package defines the standard " </line>
      <line> "GUI Components for the QT library " </line>
      <line> "like Button, Lineedit ..." </line>
  </desc>
   [component definitions]
</namespace>

The tags that may be used in the package header are

See  the example above for the syntax of this tags.

Each component description starts with the <class> tag and ends with </class>. The following tags may be used within this class description:
 
<name> Name of the component
<flaglist> Set different options / flags for the component
<shortdesc> Short description text for component
<method> Describe a method of the component
<property> Describe a property of the component
<event> Describe an event the component may raise
<icon> Set the icon picture for the component

Name of the component
    <name>LABEL</name>

Flags for the component
Flags may set special properties of a component that only accept the values TRUE or FALSE. Currently HBasic only knows the following flags:
 
NOWIDGET Used if the component doesn't have a widget that may be displayed to show the component in a gui window. These components are not visible at runtime but may export the same parts as other components. They are used for example in the file_package or net_package because their components don't need a visible gui.
NOPICTURE This component will not be displayed in the list of components the user may select (component selection window) and can therefore not be instantiated by the hbasic developer. Used for FORM component in hbasic_stdgui. 

    <flaglist>
        <set>NOWIDGET</set>
    </flaglist>

Short description of the component
    <shortdesc>General form widget</shortdesc>

Method definition in component description

<method>
   <name>TAN</name>
   <callfunction>6</callfunction>
   <return>double</return>
   <parameter>double</parameter>
</method>

To set up a function definition you can use the following tags:
 
<name> Name of the method
<callfunction> Position of the function in the function table which should be called when HBasic wants to call the method.
<return> Type of return value of the method. If there is no return value the default is a method without a return value.
<parameter> Type of the parameters of the method. You may set up one, more than one or no parameter. HBasic uses this description to check the method call in the parser for the correct syntax.

This describes the method TAN which when used in a habsic program calls the function number 6 of the package through the function table of the package. The method call has only one parameter of type double.

Property description in component description

<property>
   <name>prop1</name>
   <set>25</set>
   <get>26</get>
   <type>long</type>
</property>

This describes a property prop1 which when used in a HBasic propgram calls a set function to write the property value or get function to read the property value. The type of the property value is long and the name of the property is prop1. If you declared a variable comp1 from this component type you may read or write the property with statements like

comp1.prop1 = <newvalue>
Print comp1.prop1

Event definition in component description

The event desciption uses the following tags:
 
 
<name> Name of the event
<id> Unique id of the event
<parameter> Type for each parameter that will be transferred when raising the event.

When Hbasic wants to connect a component with an event handling function it must store a reference in the memory of the component. When designing the memory structure of a component the developer has to reserve this memory. Each event address starting with id 0 needs a long value. Since the first address in each component is a pointer to the function table of the package the address table for the events start behing this address. A structure definition for a component with event id's 0, 1, and 2 should look like the following:

struct COMP_MEMORY
{
   void *function table;
   long event_address_0;
   long event_address_1;
   long event_address_2;

   [definition of other event memory parts]
}

The contents of this fields will be initialized and used by HBasic.

<event>
   <name>CLICKED</name>
   <id>0</id>
   <parameter>
      <TYPE>short</TYPE>
      <TYPE>short</TYPE>
   </parameter>
</event>

When you want to raise an event from the C++ code of the package you start the global function startEvent( event_id, component_memory). This function needs the unique id number of the event and the starting address of the component as parameters to the call. HBasic will search the connected HBasic function if the user has defined one in it's source code and start it.

Icon of the component

To select a component within the GUI editor of HBasic each component of a package will be displayed as a small icon in the component selection window. You can set the image for this icon with the <icon> tag in the component definition. The format of the picture is similar to a XPM format. To create a new icon start a program like gimp and create a new image with a pixelwith and height between 16 and 24 pixel. Save this image in XPM format (name.xpm) and copy the created text file with an editor like vi to yout component description.

A picture in XPM format normally looks similar to the following lines:

/* XPM */
static char * label_xpm[] = {
"17 17 3 1",
"  c Black",
"X c Gray74",
"O c None",
"OOOOOOOOOOOOOOOOO",
"OOOOOOOO  OOOOOOO",
"OOOOOOO   OOOOOOO",
"OOOOOOO   OOOOOOO",
"OOOOOO     OOOOOO",
"OOOOOO     OOOOOO",
"OOOOO  O    OOOOO",
"OOOOO  O     OOOO",
"OOOO  OO     OOOO",
"OOOO          OOO",
"OOO           OOO",
"OOO  OOOOO    OOO",
"OO   OOOOO     OO",
"O    OOOOO      O",
"O     OOO       O",
"OOOOOOOOOOOOOOOOO"};

Since I didn't find a better way to separate between the lines of the picture than putting each line in new tags you have to correct this for each line of your XPM file. Surround each picture line with this tags as you can see in the following example. Afterwards delete some the leading and finishing lines that define comments or the C++ character array for the picture. You may now use the resulting lines as an icon definition within your HBasic package description.

<icon>
  <line>17 17 3 1</line>
  <line>  c Black</line>
  <line>X c Gray74</line>
  <line>O c None</line>
  <line>OOOOOOOOOOOOOOOOO</line>
  <line>OOOOOOOO  OOOOOOO</line>
  <line>OOOOOOO   OOOOOOO</line>
  <line>OOOOOOO   OOOOOOO</line>
  <line>OOOOOO     OOOOOO</line>
  <line>OOOOOO     OOOOOO</line>
  <line>OOOOOO      OOOOO</line>
  <line>OOOOO  O    OOOOO</line>
  <line>OOOOO  O     OOOO</line>
  <line>OOOO  OO     OOOO</line>
  <line>OOOO          OOO</line>
  <line>OOO           OOO</line>
  <line>OOO  OOOOO    OOO</line>
  <line>OO   OOOOO     OO</line>
  <line>O    OOOOO      O</line>
  <line>O     OOO       O</line>
  <line>OOOOOOOOOOOOOOOOO</line>
</icon>
 

Creating components / packages