## 8.3 Bitmaps

### 8.3.1 Description

A bitmap is an image whose pixels can display either of two colors or be transparent. Four things define a bitmap: a background color, a foreground color, and two bitmaps, called the source and the mask. Each of the bitmaps specifies 0/1 values for a rectangular array of pixels, and the two bitmaps must have the same dimensions. For pixels where the mask is zero, the image displays nothing, producing a transparent effect. For other pixels, the image displays the foreground color if the source data is one and the background color if the source data is zero.

In QTk, bitmaps are built by the `QTk.newImage` function. This function takes one parameter: a record of the form `bitmap(param1:value1 ... paramX:valueX)` and returns an object allowing to reference that bitmap and change it as needed. The valid parameters and methods are described below.

### 8.3.2 Parameters

- `background:C`: Specifies a background color for the image. If this option is set to `nil` then the background pixels will be transparent. This effect is achieved by using the source bitmap as the mask bitmap, ignoring any `maskdata`, `maskfile` or `maskurl` options.

- `data:VS`: Specifies the contents of the source bitmap as a string. The string must adhere to X11 bitmap format (e.g., as generated by the bitmap program).

- `file:VS`: `VS` gives the name of a file whose contents define the source bitmap. The file must adhere to X11 bitmap format (e.g., as generated by the bitmap program).

- `url:VS`: `VS` gives the url of a file whose contents define the source bitmap. The file must adhere to X11 bitmap format (e.g., as generated by the bitmap program).

- `foreground:C`: Specifies a foreground color for the image.

- `maskdata:VS`: Specifies the contents of the mask as a string. The string must adhere to X11 bitmap format (e.g., as generated by the bitmap program).

- `maskfile:VS`: `VS` gives the name of a file whose contents define the mask. The file must adhere to X11 bitmap format (e.g., as generated by the bitmap program).

- `maskurl:VS`: `VS` gives the url of a file whose contents define the mask. The file must adhere to X11 bitmap format (e.g., as generated by the bitmap program).

### 8.3.3 Interface

- `set(parameter1:value1 ... parameterX:valueX)`: Changes the value of one or more parameters. `parameterX` must be a valid parameter for the widget. `valueX` must be a valid value for the parameter.

- `get(parameter1:Variable1 ... parameterX:VariableX)`: Obtains the value of one or more parameters. `parameterX` must be a valid parameter for the widget. `VariableX` must be free variables that will receive the current value of the parameters.