# BackgroundImage
Class
## About
`BackgroundImage` stores a portable image source together with fill and repeat behavior. It is used by the document, nodes, table cells, and columns so screen rendering and HTML export share one model.
## Enumerations
| Name | Value | Description |
| --- | :---: | --- |
| Fills | ActualSize <br > Stretch <br > Fit <br > Fill | (None) |
| Repeats | NoRepeat <br > RepeatX <br > RepeatY <br > Repeat | (None) |
## Event Definitions
| Name | Parameters | Return Type | Description |
| --- | :---: | :---: | --- |
| ImageChanged | (None) | (None) | Raised when the image, fill, or repeat configuration changes. |
| LoadFailed | message As String | (None) | Raised when a background image could not be loaded. |
## Methods
| Name | Parameters | Return Type | Description |
| --- | :---: | :---: | --- |
| ApplyCSS | declarations As Dictionary | (None) | Applies supported CSS background-image, background-size, and background-repeat declarations. |
| Clear | (None) | (None) | Removes the background image and cancels any pending download. |
| Constructor | (None) | (None) | Creates an empty background image configuration. |
| Destructor | (None) | (None) | Releases network resources owned by this background image. |
| Draw | g As Graphics <br> bounds As Rect | (None) | Draws the configured image in the supplied bounds using its fill and repeat modes. |
| FromJSON | data As JSONItem | (None) | Restores a background image configuration from JSON data. |
| SetImage | value As Picture | (None) | Replaces the background with the supplied in-memory image. |
| SetResource | file As FolderItem | (None) | Loads a background image from a local PNG, JPEG, or GIF file. |
| SetResource | value As String | (None) | Loads a background image from an HTTPS URL, a data URI, or a BASE64-encoded PNG, JPEG, or GIF. |
| ToCSS | (None) | String | Returns CSS background declarations for the current image, fill, and repeat settings. |
| ToJSON | (None) | JSONItem | Returns the background image configuration as JSON data. |
## Properties
| Name | Type | Default Value | Description |
| --- | :---: | :---: | --- |
| FillMode | Fills | (None) | Gets or sets how the image is scaled within its bounds. |
| Image | Picture | (None) | Returns the currently loaded background picture, or Nil when none is available. |
| IsLoading | Boolean | (None) | Returns whether a remote background image is currently being downloaded. |
| LocalFile | FolderItem | (None) | Gets or sets the local image file selected for this background. |
| RepeatMode | Repeats | (None) | Gets or sets how the background image repeats within its bounds. |
| Source | String | (None) | Returns the URL or self-contained data URI used to load the background image. |
| URL | String | (None) | Gets or sets the remote image URL selected for this background. |
## Notes
Background image configuration is shared across drawing, persistence, and HTML export.
### Fill and Repeat
Fill mode controls scaling within the destination bounds: actual size, stretch, fit, or fill. Repeat mode controls horizontal and vertical tiling. `ToCSS`, `ToJSON`, and `ApplyCSS` preserve the same configuration used by `Draw`.
### JSON Format
`ToJSON` stores `source` as a string, `fill` as an integer, and `repeat` as an integer.
`Fills` values are `0` ActualSize, `1` Stretch, `2` Fit, and `3` Fill. `Repeats` values are `0` NoRepeat, `1` RepeatX, `2` RepeatY, and `3` Repeat. `FromJSON` clamps values outside either supported range.
A local file or in-memory picture is represented by a `data:image/...;base64,...` source. A remote image retains its HTTP or HTTPS URL. The containing document or node omits the entire background-image object when no source is assigned.
`fill` is omitted when it is Fill and `repeat` when it is NoRepeat; `FromJSON` uses those defaults for missing names.
### Sources
Use `SetResource(FolderItem)` for a local PNG, JPEG, or GIF. The image is read immediately and converted to a data URI. Use `SetImage` for an in-memory `Picture`. Use `SetResource(String)` for an HTTP or HTTPS URL, data URI, or raw Base64 image value.
Remote URL loading is asynchronous. `ImageChanged` is raised when state or loaded image data changes, and `LoadFailed` reports resources that could not be decoded or downloaded. HTML and JSON import preserve remote URLs without downloading them; after applying the application's URL and network policy, call `SetResource` explicitly to fetch a trusted URL. Local, remote, and encoded image payloads are size bounded.
## Examples
A background image object is owned by its editor, node, cell, or column.
### Document Background
```xojo
Editor.BackgroundImage.SetResource(imageFile)
Editor.BackgroundImage.FillMode = GraffitiProEditor.BackgroundImage.Fills.Fill
Editor.BackgroundImage.RepeatMode = GraffitiProEditor.BackgroundImage.Repeats.NoRepeat
```