Tutorial: Adding a library to a Basic4ppc program and using it

This tutorial is intended to give a straightforward explanation of the practical steps required to work with libraries in Basic4ppc. For a more information than supplied here, refer to the libraries complete reference - using a library in a Basic4ppc application. This in an abridged version of the full discussion there.

Using DLL (libraries) in your project

Using DLLs in your Basic4ppc project has 3  steps:

1. Add library to the project: attach the .dll file(s) to your project.

2. Declare the variable name: create an object from within the library added.

3. Save room in memory for the object: call the object's NEW sub (exists in every library).

4. Start working...

 

Step 1/3: Adding a library to your project (all steps)

In order to start using a library you must first add it to your project. This is done from the IDE. Open the Tools menu and select Components:

The following dialog box appears, allowing you to choose the libraries file to be added to your project:

Adding a library is done by clicking the "Add DLL" button. The white columns represent the files added in your project for both your desktop application and your device application. Sometimes, .dll files are different between the two. A convention is to name the .dll with the target platform's name attached in these cases, such as "serialDesktop.dll" and "serialDevice.dll". In case each application (desktop/device) uses its own .dll, use the "Add DLL" button found under the target-device's name to select the wanted file. In case the desktop and the device use the same library, use the middle button. It is your responsibility to know whether or not to use the same file for both . Basic4ppc will not find this out for you and the following situation is possible, resulting in disability to run the desktop application:

Copying the libraries into the application folder and working with a recent version

When you add a library to your project, Basic4ppc will copy the the libraries file to your project folder. This is the reason why you should save your project prior to adding a library (otherwise there is no project folder). From this moment  on, Basic4ppc uses the copy held under the project's folder (Versions prior to 6.8: a message will appear indicating success or failure to copy the files. Click OK).

Removing a previously selected file from a list is done by first selecting the file name, and then clicking the "Remove" button under the relevant list.

Copy libraries checkbox

If you leave the "Copy libraries to the libraries folder" checked: , Basic4ppc will copy the library's file to the default libraries folder as described above.

Note: starting from V6.8, Basic4ppc no longer copies the files to the default libraries folder and this checkbox does not exist. This has a number of consequences, mainly a difficulty in finding a library not in the default folder, and the lack the library's name under the Help menu. You should take care yourself of placing your libraries where you want them.

When finished with the Components dialog box, click the OK button to finish the DLL selection part.

Notes:

• Starting from V6.8, in order to prevent versioning conflicts, each time you open a project Basic4pcc checks for a newer version - based on its modification time -in the libraries folder, and copies the new file, if found.

• Exception when working on the device IDE:

  • Note that libraries are not automatically copied to your device when installing Basic4ppc. Make sure you manually copy all files required for your application to the app folder.

Step 2 of 3: Creating an object of a library you've added (all steps)

After you've added desired libraries to your project, you must first create an object from one of the object-types contained in it. Each library can hold many object types. You can create as many objects of a single library file as you want. Adding an object is equivalent to declaring a variable with the type of this object (referred to as "object type" later, and sometimes as "class").

There are two ways  to create a new object of a library to your project:

• at design time, using the Tools menu. This is the preferred option, when possible.

• at runtime, using the AddObject keyword.

Adding an object at design time: Use the Tools menu, and select "Add Object", to create a new object from your library. Note, that a library may contain more than one object you can create. For example, If you add these libraries to your project:

In order to find out which objects to add to your program, use the help file that is usually associated with the .dll itself, as described here. For more details, see the Getting help with a library section.

After selecting the object you want to add, you must first name it. A dialog box appears, asking you to name your object:

Second option - adding an object at runtime:

Many times it's impossible, or impractical, to add all your objects at design time. Use the AddObject keyword to add them at runtime. This keyword replaces in one line the multiple-stages process described above. After adding the .dll file to your project (see step 1), use the AddObject keyword anywhere in your code to create a new object from your added library. The highlighted line, when executed, will cause your program to do exactly the same thing described above using the menues:

Step 3/3 - call the object's NEW sub (all steps)

Calling an object's NEW sub is the way to allocate a place for it. Apart from allocating place in memory, the object's NEW sub may also take some data as parameters. Calling the object's NEW sub is called instantiating (creating an instance). The reason is that when you call the NEW sub you actually spare memory for the object and name this memory portion. This creates an instance - a copy - of your object. The "object type", TreeView in the example above, is not changed at all - all actions you will perform from now on will affect only the instance (saved in its new place in the memory, hence the name "NEW" for the sub).

This way two goals are achieved:

1. More instances of the same object can be created, all with the default properties of the object type

2. Any change to an object instance doesn't affect other instances of the same object, thus allows you to have, for example, many TreeViews with different properties (that is, different color, different nodes and so on).

Consturctor

Every object must have a sub called NEW (actually, it is called NEW1). The NEW sub of an object is called constructor. A constructor builds a place in memory and assigning the name to it. Constructors can have further functionality, such as initializing properties to default values, as we will see.

The following example calls the "tvMain" object (of type TreeView, created programmatically a line earlier) and supplies some required parameters.

We will focus on the highlighted line again. The "New1" constructor is called. The parameters passed to it describe needed information: to which form to add the new instance, and what size should it be (where to place its corners relative to the form).

Using your object

Once you've called an object, you can start using it. The following example demonstrates how to add tow nodes to a TreeView object, called tvMain:

Overloading - more than one constructor

An object can have more than one constructor (that is, more than one NEW sub). To distinguish between them, each sub called new has a number attached to it: NEW1, NEW2 and so on. For example, the BinaryFile library has two constructors: