## 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.