8.5 Image libraries

When an application uses several bitmaps or photos, it is useful to group all these images into a single file called an image library. Image libraries can be saved to files and loaded later, restoring all images that were stored inside the library. Moreover image libraries files are functors that can be linked to your application so that graphical resources like images can be packaged inside your application binaries.

The function QTk.newImageLibrary returns an empty image library. An image library is an object that implements the following interface:

• newPhoto(...): Adds a photo to the image library. All the parameters are the same as the ones for QTk.newImage photo(...), except a supplementary one: name:A that defines the image's name inside the image library. If not specified, a name is determined by the file name or url, or an error is raised if no name could be determined. A must be an atom.

• newBitmap(...): Adds a bitmap to the image library. All the parameters are the same as the ones for QTk.newImage bitmap(...), except a supplementary one: name:A that defines the image's name inside the image library. If not specified, a name is determined by the file name or url, or an error is raised if no name could be determined. A must be an atom.

• get(name:A image:V): Binds V to the image in the image library that has the name A. The returned image is similar the images built using then QTk.newImage function. However, if you modify these images after they were created inside the image library, the image library won't be updated. You need to explicitly save and reload the modified image into the library.

• getNames(V): Binds V to a list of atoms that are all the names of all avalaible images in the library.

• remove(name:A): Removes the image named A from the library if present, does nothing otherwise.

Image libraries can be also be saved and loaded to files:

• {QTk.saveImageLibrary L VS}: This procedure saves the image library L to a file named VS.

• {QTk.loadImageLibray VS}: This function returns an image library loaded from the file VS.

Saved image libraries are functors that you can directly import and link into your application's functor. To achieve this, you must do the following:

• Build an image library, place all needed images inside and save it to a file ending with .ozf and whose first letter is uppercase (for example MyLib.ozf).

• In your application's functor, you must require the image library and prepare the library by adding the following similar lines:

  require MyLib
prepare BL=MyLib.buildLibrary

  Note that the require and prepare part of functors are placed just before the define part.

• In your define part, you must rebuild the image library by using a similar line:

  Lib={QTk.buildImageLibrary BL}

Compiling your functor now statically includes all the required data for rebuilding the image library, and all the necessary commands for creating a new one from this data. The original image library file is no more needed for the correct execution of your application.