Tech Note 04b: Creating an Images Database

Tech Note 04b: Creating an Images Database

May 01, 2008

Contributed by Oscar De Leon odeleon© finework.cl

This Tech Note shows a simple way to implement an Images Database separate database from your application.

The process has 3 steps:

Prepare the images.
Create the images database.
Use the images database in your program.

Before you start:

What you need:

An image processing tool for preparing the images.
Pilot Resource Compiler, PilRC, that can be downloaded from http://www.ardiri.com/, for creating the images database.
A device.
Of course, NSBasic/Symbian OS.

1. Prepare the images.

The basic preparation of the images is:

Size them the appropriate height and width for your application.
Save them as BMP. The bitmap format is the only one supported by PilRC at this time.

2. Create the images database.

The images database is created using PilRC. This command line utility uses a .rcp file with information about the resources to compile.
The complete syntax of the .rcp file is not described here for simplicity, and because PilRC is well documented in Aaron's website.

Create two text files with notepad or your favorite editor, resources.rcp and createdb.bat:

resources.rcp

My sample has 55 images, called Cat00001.bmp to Cat00055.bmp, so the .rcp file looks like this:

BITMAPCOLOR ID 2001 "Cat00001.bmp"
BITMAPCOLOR ID 2002 "Cat00002.bmp"
BITMAPCOLOR ID 2003 "Cat00003.bmp"
...
BITMAPCOLOR ID 2004 "Cat00054.bmp"
BITMAPCOLOR ID 2005 "Cat00055.bmp"

createdb.bat

This one line script file was created just to simplify PilRC command line syntax, and to be able to run it from the Windows Explorer or from a shortcut.
You can write this at the DOS command prompt if you prefer.

PilRC -ro -type data -creator FW10 -o ItemsGRDB.prc resources.rcp

The syntax above will create the images database with the following characteristics:

-ro	tell PilRC to create a prc database
-type data	database Type "data".
-creator aaaa	database Creator Id. Use the same creator id as your application so the images database is removed with your application.
-o filename	database name. The name the database will have in your device. Include ".prc".
resources.rcp	the resource information file created above.

Run the script createdb.bat and voila!, your image database is created (in the example, ItemsGRDB.prc).

3. Use the images database in your program

Now that you have your images database, add it to your project as a resource.

Now, you need to know how to find the right image and how to display it.

I will explain this with an example.

My application allows to create Purchase Orders, picking items from a Sports Items Database, the Price List.

It has 3 databases: OrdersDB.PDB, to store the purchase orders; ItemsDB.PDB, the items' price list; and ItemsGRDB.PRC, the items' images.

The user can access the Price List directly, showing the screen below:

If the user selects item 15 and press [ i ] to get more detail about the item, the next screen is shown:

This image was shown using the code below in the form's After Code. Only the relevant code is shown.

Sub Form1060_After()

'Local Variables.
Dim dbItemsGRDB as Database         'Database Handle.
Dim nItemsGRDB as Integer          'dbOpen() Result.
Dim nImageID    as Integer          'Image Index.
Dim bmpPtr      as Variant          'SysTrapFunc() Result.
Dim Tbmp        as Integer          'Resource Type.
Dim bmpID       as Short            'Image Handle.

...

'Draw a Frame Around the Image.
DrawRectangle 4, 75, 152, 64, 0

'Display Image.
nItemsGRDB = dbOpen(dbItemsGRDB, "ItemsGRDB.prc", 0) 'Open Database.
If nItemsGRDB = 0 Then                        'Database Opened.
    'Check if Image Exists.
    Tbmp = 1415736688                         'Resource Type (Tbmp)
    bmpID = 2000 + Val(ItemDescInfo.ItemCode) 'Resource Index.
    bmpPtr = SysTrapFunc(96, 2, Tbmp, bmpID) 'DmGet1Resource.
    If bmpPtr <> 0 Then
        DrawBitmap bmpID, 5, 76               'Image Exists.
    EndIf
    dbClose(dbItemsGRDB)                      'Close Database.
EndIf
...

Note that the image index is calculated adding 2000 to the item index, 15 in the example above, that is contained in the global structure element ItemDescInfo.ItemCode, so this code will try to find the resource with ID = 2015. This is related with the ID value used in the .rcp file.

You can use any number index for the images, from 0001 to 9999, since dmGet1Resource looks for the resource in the last opened database, in this case, the images database, so there is no risk of retrieving the wrong resource from other databases.
That's why the images database is opened just before displaying the image, and closed immediately.

Finally, if you plan that your application looks professional, it should behave like one.

Drawbitmap crashes the application if the resource (image) is not found, so:

Check to see if the images database exists (dbOpen() = 0).
Check if the resource (image) exists in the database. If not, just display a "Preview Not Available" or similar text.
I just used a label in the form at design time. If the image exists at run time, it is drawn over the text.
If not, the screen below is shown:

Last words,

This tech note would not have been possible without valuable help from Douglas Handy. His infinite patience and excellent guidelines resulted in what you see now.
I hope you enjoy it. More sophisticated graphics (hi res) and bitmap families are also topics not covered by this tech note. Perhaps someone else with deep knowledge of these issues could write a tech note!