Using a library in your Basic4ppc project

This section covers in details all knowledge required to add and use a library in your project.

The coffee cup analogy: if you are new to libraries

Using libraries includes some topics usually not needed for development with Basic4ppc. Such topics are creating and instantiating "objects", a method of joining components to your program without having either to deal with how they are built, nor add too much of them as "native" Basic4ppc commands. The following section covers the concept of adding objects to a program through an analogy.

Using libraries can be thought of as analogous to the process of making a cup of coffee in your kitchen. Your kitchen is probably a great place, but unless you have some products in it, it lacks the ability to "create" a cup of coffee. Basic4ppc's IDE is the same: your can do anything, you just have to have the right "products" inside.

Imagine standing at your kitchen yearning for coffee. The first thing you do, is purchase a new jar of coffee. This can be of any brand, and can be compared to step 1: adding a library to a project. After you have done this, you now have a kitchen with a jar full of coffee: just like a project with a .dll file added to it.

Second, you use a teaspoon and to take some coffee out of the jar. This teaspoon full of coffee will be used immediately, blended with hot water, sugar and cream. The coffee spoon can be thought of as step 2: creating an object of your library. The jar of coffee you've bought isn't the right thing to use for your coffee cup: it's just the container. Use a spoon to "create" a usable "coffee component" for your cup. Same applies for your library: a library file added to a project is a container. Create  an object, a spoon, to be able to use it. Think of a library file as an endless jar of coffee: your can take out as many spoons ad you need, the amount left inside doesn't change. The same way, you can have as many library's objects as you want: just as if you would have made more than one cup of coffee. Blending the coffee with its ingredients is what gives the final product its taste - sweeter or less sweet, stronger and so on - many cups of coffee started with the same teaspoon taken out of a jar.

Third, you place the coffee from your spoon into a cup. The cup is the place where things are mixed, and a real coffee is created from the ingredients. This is analogous to step 3: use the library's NEW() sub to start working with it. Just like placing the coffee inside the cup dedicates a special three-dimensional space for your coffee, the same way using the NEW() sub allocates a special place in memory for your library's object. You must spare this place for your object, just the same way you must place your coffee inside a cup.

Basic4ppc libraries - Concepts

All Basic4ppc libraries are .dll files contained in a special folder under the application's folder (note: the terms "DLL file" and "Library" will have the same meaning in the documentation). Suppose your Basic4ppc is installed in C:\Program Files\Anywhere Software\Basic4ppc, then the libraries will be held under C:\Program Files\Anywhere Software\Basic4ppc\Libraries. It is important, because Basic4ppc will look for updates for the loaded libraries in both the project's folder, and the [application-path]\Libraries (C:\Program Files\Anywhere Software\Basic4ppc\Libraries in our example) (This applies to versions prior to V6.8. In earlier versions, if you choose to add a library from a different location, Basic4ppc will attempt to copy the library to the \Libraries folder).

Note: holding libraries under the \Libraries folder is recommended, but is not obligatory.

The libraries folder contains not only the library itself (a .dll file). Although optional, for most of the libraries it includes 3 files with identical names and different extensions. If a library is called, for example, lib.dll, then the \Libraries folder shall include the following files:

1.  Lib.dll - the library file itself. This file is required in order to use the library's functionality in your code.

2.  Lib.chm - a help file associated with the library. When found under the \Libraries folder, its name will be added to the list of available libraries' help under the Help menu, as in the following picture (note: this applies only to the desktop IDE and not to the device IDE):

3. A .cs file (c sharp, .NET's technology main programming language). When compiled, Basic4ppc programs are first translated into c# programs and then complied using standard c# complier. Including the .cs file in the libraries folder enables Merging. Merging will be discussed in details later this chapter.

Using DLL (libraries) in your project

Using DLLs in your Basic4ppc project has 3  steps. They are discussed in details below:

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 window 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".  Follow this convention when deploying dll's you have written yourself, to prevent user mistakes. 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 to select the file. 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.).

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.

The Add Code buttons

The two Add Code buttons below the libraries lists both function as a special way to manage differences in application's code easily. Similarly to the way modules work in Basic4ppc, this option allows you to integrate to your program an external file containing Basic4ppc code. This code is merged "as is" into the main module at compile time, thus allowing you to call its subs and so on. Unlike with modules, this way easily allows you to include totally different basic code inside your Device application than this included in your desktop application. This is a powerful feature beyond the scope of this article. However, it's worth mentioning.

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.

  • It is a good habit to keep your Basic4ppc source files entirely under the synchronization folder of your ActiveSync. Many versioning issues are solved just by keeping dlls synchronized. Keep everything in subfolder there during developement, and promise you are always on sync.

Dependency

When working with DLLs, your application becomes dependent on its libraries in order to compile and run. Some dependencies issues can be eliminated by merging the DLLs into your application upon compile (see details below), but not all libraries can be merged. DLLs themselves may be dependent on other DLL files, and so on. Basic4ppc automatically tracks dependency issues when copying the library into your project's folder, and warns you if a dependency problem raises.

Merging

As stated, libraries must be found in the application folder for the application to be able to find them when needed: failure to find a .dll file will result in a runtime error and execution will stop. It is the developer's responsibility to make sure that all needed files are deployed and copied correctly to the destination machine. Either by building a setup program or by any other method of instructing the user, files should be where needed when application is run.

In order to eliminate to minimum the need to manually handle additional files issues, Baisc4ppc allows for merged files into your application's executable. If a library's source code (c# code) can be found under the \Libraries folder, the code will be inserted as is into the application's main executable upon compilation. This way the .dll is merged into the application and becomes a part of it, thus making deployment significantly simpler.

Most official Basic4ppc libraries can be merged (that is, they all contain a [dll-name].cs file with their source code). Not all external libraries support this feature, from various reasons. If you do not have the .cs file, you have to take care yourself of the deployment issues.

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 of each one. Going with the coffee cup analogy, this is analogous to taking a teaspoon full of coffee out of a magical, endless coffee jar. Although have different meaning in other programming languages, in Basic4ppc the term Object is used to indicate the "usable variable held in a library". Each library can contain more than one object type. You create your objects from the object-type, as if you take a spoon full of coffee out of a coffee jar. You can create as many objects of a single library file as you want. Each one can have slightly different characteristics. For example, you can have 3 different TreeView objects, each with different nodes in it, different colors ect., but they all are objects created from the TreeView library.

Put simple, creating an object is equivalent to declaring a variable. In Basic4ppc, apart from arrays you don't have to declare any variable, but it is allowed to do so using the Dim keyword. Adding an object is actually declaring a variable, with the type of the object (referred to as "object type" later).

In place of the Dim keyword, there are two ways  to create a new object of a library to your project:

    1. At design time, using the Tools menu - this is the preferred way.

    2. 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:

Use only the objects you need. There is no point in adding too many objects to your program. 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 above. For more details, read Getting help about a library..

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

Adding an object at runtime:

Many times it's impossible, or impractical, to add all your objects at design time. Although this lets you use the properties list while typing, you may want to create your object only at runtime. Doing so is possible using the AddObject keyword. 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:

Actually, at this stage, we cannot yet use our new object. Of course, it was not added to any form, but what's more important: its NEW sub was not yet called.

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

Consider your new object as the spoon of coffee you took out of the jar: now, you know it's a coffee, you know you placed the right amount in a spoon, but you yet don't know where to place it - where is the cup. A new object's cup is its NEW sub.

Calling an object's NEW sub is the way to allocate a place for it. Actually, this is exactly what happens when you call the NEW sub: a place in the computer's memory is allocated for the new object, taking into account all future changes it may undergo.

Apart from allocating place in memory, the object's NEW sub may also take some data as parameters. These parameters are used for initialization of some object's properties. Not all NEW subs do that.

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).  This way two goals are achieved:

    1. Many 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.

The following example calls the "tvMain" object;s constructor (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).

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

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: