# Class URLImage

java.lang.Object
com.codename1.ui.Image
com.codename1.ui.EncodedImage
com.codename1.ui.URLImage

All Implemented Interfaces:
  `ActionSource`

public final class URLImage extends EncodedImage

`URLImage` allows us to create an image from a URL. If the image was downloaded already it is fetched from cache; if not it is downloaded optionally scaled/adapted and placed in cache.

By default an image is fetched lazily as it is asked for by the GUI unless the fetch() method is invoked in which case the IO code is executed immediately.

This sample code show a `URLImage` that is fetched to the title area background and scaled/cropped to fit device specific dimensions.

    Toolbar.setGlobalToolbar(true);

    Form hi = new Form("Toolbar", new BoxLayout(BoxLayout.Y_AXIS));
    EncodedImage placeholder = EncodedImage.createFromImage(Image.createImage(hi.getWidth(), hi.getWidth() / 5, 0xffff0000), true);
    URLImage background = URLImage.createToStorage(placeholder, "400px-AGameOfThrones.jpg",
            "http://awoiaf.westeros.org/images/thumb/9/93/AGameOfThrones.jpg/400px-AGameOfThrones.jpg");
    background.fetch();
    Style stitle = hi.getToolbar().getTitleComponent().getUnselectedStyle();
    stitle.setBgImage(background);
    stitle.setBackgroundType(Style.BACKGROUND_IMAGE_SCALED_FILL);
    stitle.setPaddingUnit(Style.UNIT_TYPE_DIPS, Style.UNIT_TYPE_DIPS, Style.UNIT_TYPE_DIPS, Style.UNIT_TYPE_DIPS);
    stitle.setPaddingTop(15);
    SpanButton credit = new SpanButton("This excerpt is from A Wiki Of Ice And Fire. Please check it out by clicking here!");
    credit.addActionListener((e) -> Display.getInstance().execute("http://awoiaf.westeros.org/index.php/A_Game_of_Thrones"));
    hi.add(new SpanLabel("A Game of Thrones is the first of seven planned novels in A Song of Ice and Fire, an epic fantasy series by American author George R. R. Martin. It was first published on 6 August 1996. The novel was nominated for the 1998 Nebula Award and the 1997 World Fantasy Award,[1] and won the 1997 Locus Award.[2] The novella Blood of the Dragon, comprising the Daenerys Targaryen chapters from the novel, won the 1997 Hugo Award for Best Novella. ")).
            add(new Label("Plot introduction", "Heading")).
            add(new SpanLabel("A Game of Thrones is set in the Seven Kingdoms of Westeros, a land reminiscent of Medieval Europe. In Westeros the seasons last for years, sometimes decades, at a time.\n\n" +
                "Fifteen years prior to the novel, the Seven Kingdoms were torn apart by a civil war, known alternately as \"Robert's Rebellion\" and the \"War of the Usurper.\" Prince Rhaegar Targaryen kidnapped Lyanna Stark, arousing the ire of her family and of her betrothed, Lord Robert Baratheon (the war's titular rebel). The Mad King, Aerys II Targaryen, had Lyanna's father and eldest brother executed when they demanded her safe return. Her second brother, Eddard, joined his boyhood friend Robert Baratheon and Jon Arryn, with whom they had been fostered as children, in declaring war against the ruling Targaryen dynasty, securing the allegiances of House Tully and House Arryn through a network of dynastic marriages (Lord Eddard to Catelyn Tully and Lord Arryn to Lysa Tully). The powerful House Tyrell continued to support the King, but House Lannister and House Martell both stalled due to insults against their houses by the Targaryens. The civil war climaxed with the Battle of the Trident, when Prince Rhaegar was killed in battle by Robert Baratheon. The Lannisters finally agreed to support King Aerys, but then brutally... ")).
            add(credit);

    ComponentAnimation title = hi.getToolbar().getTitleComponent().createStyleAnimation("Title", 200);
    hi.getAnimationManager().onTitleScrollAnimation(title);
    hi.show();

This sample code shows the usage of the nestoria API to fill out an infinitely scrolling list in it we use `URLImage` to fetch the icon.

    Form hi = new Form("InfiniteScrollAdapter", BoxLayout.y());

    Style s = UIManager.getInstance().getComponentStyle("MultiLine1");
    FontImage p = FontImage.createMaterial(FontImage.MATERIAL_PORTRAIT, s);
    EncodedImage placeholder = EncodedImage.createFromImage(
            p.scaled(p.getWidth() * 3, p.getHeight() * 3),
            false);

    InfiniteScrollAdapter.createInfiniteScroll(hi.getContentPane(), () -> {
        MultiButton[] cmps = new MultiButton[10];
        for (int i = 0; i < cmps.length; i++) {
            String imageKey = "listing-" + i;
            String imageUrl = "https://example.com/images/" + i + ".png";
            MultiButton row = new MultiButton("Listing " + i);
            row.setIcon(URLImage.createToStorage(placeholder, imageKey, imageUrl));
            cmps[i] = row;
        }
        InfiniteScrollAdapter.addMoreComponents(hi.getContentPane(), cmps, true);
    }, true);
    hi.show();

You can use adapters with masks using syntax similar to this to create a round image mask for a `URLImage`:

    Image roundMask = Image.createImage(placeholder.getWidth(), placeholder.getHeight(), 0xff000000);
    Graphics gr = roundMask.getGraphics();
    gr.setColor(0xffffff);
    gr.fillArc(0, 0, placeholder.getWidth(), placeholder.getHeight(), 0, 360);

    URLImage.ImageAdapter ada = URLImage.createMaskAdapter(roundMask);
    Image i = URLImage.createToStorage(placeholder, "fileNameInStorage", "http://xxx/myurl.jpg", ada);

- ## Nested Class Summary

  Nested Classes
  Modifier and Type
  Class
  Description
  `static interface`
  `URLImage.ErrorCallback`
  Invoked in a case of an error
  `static interface`
  `URLImage.ImageAdapter`
  Allows applying resize logic to downloaded images you can use constant resize behaviors defined in this class.
  `static interface`
  `URLImage.RequestDecorator`
  Decorator hook applied to the `ConnectionRequest` that loads a network-backed `URLImage`.

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `static final int`
  `FLAG_RESIZE_FAIL`
  Flag used by `java.lang.String, com.codename1.ui.Image, int)`.
  `static final int`
  `FLAG_RESIZE_SCALE`
  Flag used by `java.lang.String, com.codename1.ui.Image, int)` Equivalent to `#RESIZE_SCALE`.
  `static final int`
  `FLAG_RESIZE_SCALE_TO_FILL`
  Flag used by `java.lang.String, com.codename1.ui.Image, int)`.
  `static final URLImage.ImageAdapter`
  `RESIZE_FAIL`
  Will fail if the downloaded image has a different size from the placeholder image
  `static final URLImage.ImageAdapter`
  `RESIZE_SCALE`
  Scales the image to match the size of the new image exactly
  `static final URLImage.ImageAdapter`
  `RESIZE_SCALE_TO_FILL`
  Scales the image to match to fill the area while preserving aspect ratio

- ## Method Summary

  Modifier and Type
  Method
  Description
  `boolean`
  `animate()`
  Advances this image's animation state, if it is animated.
  `static Image`
  `createCachedImage(String imageName, String url, Image placeholder, int resizeRule)`
  Creates an image that will be downloaded on the fly as necessary.
  `static URLImage.ImageAdapter`
  `createMaskAdapter(Image imageMask)`
  Creates an adapter that uses an image as a Mask, this is roughly the same as SCALE_TO_FILL with the exception that a mask will be applied later on.
  `static URLImage.ImageAdapter`
  `createMaskAdapter(Object mask)`
  `static URLImage`
  `createToFileSystem(EncodedImage placeholder, String file, String url, URLImage.ImageAdapter adapter)`
  Creates an image the will be downloaded on the fly as necessary
  `static URLImage`
  `createToStorage(EncodedImage placeholder, String storageFile, String url)`
  Creates an image the will be downloaded on the fly as necessary with RESIZE_SCALE_TO_FILL as the default behavior
  `static URLImage`
  `createToStorage(EncodedImage placeholder, String storageFile, String url, URLImage.ImageAdapter adapter)`
  Creates an image the will be downloaded on the fly as necessary
  `static URLImage`
  `createToStorage(EncodedImage placeholder, String storageFile, String url, URLImage.ImageAdapter adapter, URLImage.RequestDecorator decorator)`
  Same as `#createToStorage(EncodedImage, String, String, ImageAdapter)`, plus a per-call `RequestDecorator` applied to the `ConnectionRequest` that fetches the image bytes.
  `void`
  `fetch()`
  Images are normally fetched from storage or network only as needed, however if the download must start before the image is drawn this method can be invoked.
  `static URLImage.RequestDecorator`
  `getDefaultRequestDecorator()`
  Returns the global default decorator installed via `#setDefaultRequestDecorator(RequestDecorator)`, or `null`.
  `static URLImage.ErrorCallback`
  `getExceptionHandler()`
  The exception handler is used for callbacks in case of an error
  `byte[]`
  `getImageData()`
  Returns the byte array data backing the image allowing the image to be stored and discarded completely from RAM.
  `protected Image`
  `getInternal()`
  Returns the actual image represented by the encoded image, this image will be cached in a weak/soft reference internally.
  `boolean`
  `isAnimation()`
  Returns true if this is an animated image
  `void`
  `lock()`
  Block this method from external callers as it might break the functionality
  `boolean`
  `requiresDrawImage()`
  New label optimizations don't invoke drawImage and instead just pass the native image directly to the underlying renderer.
  `static void`
  `setDefaultBearerToken(String token)`
  Convenience for the most common case: every URLImage fetch should carry the same `Authorization: Bearer <token>` header.
  `static void`
  `setDefaultRequestDecorator(URLImage.RequestDecorator decorator)`
  Installs a global `RequestDecorator`.
  `static void`
  `setExceptionHandler(URLImage.ErrorCallback aExceptionHandler)`
  The exception handler is used for callbacks in case of an error
  `void`
  `unlock()`
  Block this method from external callers as it might break the functionality

  ### Methods inherited from class EncodedImage

  `asyncLock, create, create, create, create, create, createFromImage, createFromRGB, createMulti, dispose, drawImage, drawImage, getGraphics, getHeight, getImage, getWidth, isDisposed, isLocked, isOpaque, modifyAlpha, modifyAlpha, resetCache, rotate, scale, scaled, scaledEncoded, scaledHeight, scaledSmallerRatio, scaledWidth, subImage, toRGB`

  ### Methods inherited from class Image

  `addActionListener, applyMask, applyMask, applyMaskAutoScale, createImage, createImage, createImage, createImage, createImage, createImage, createImage, createIndexed, createMask, createSVG, exifRotation, exifRotation, exifRotation, fill, fireChangedEvent, flipHorizontally, flipVertically, getExifOrientationTag, getExifOrientationTag, getImageName, getRGB, getRGB, getRGBCached, getSVGDocument, isAlphaMutableImageSupported, isJPEG, isPNG, isSimdOptimizationsEnabled, isSVG, isSVGSupported, mirror, modifyAlphaWithTranslucency, removeActionListener, resetSimdOptimizationsEnabled, rotate180Degrees, rotate270Degrees, rotate90Degrees, scaledLargerRatio, setImageName, setSimdOptimizationsEnabled`

  ### Methods inherited from class Object

  `clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- ## Field Details

  - ### FLAG_RESIZE_FAIL

    public static final int FLAG_RESIZE_FAIL
    Flag used by `java.lang.String, com.codename1.ui.Image, int)`. Equivalent to `#RESIZE_FAIL`
    See Also:
      - Constant Field Values

  - ### RESIZE_FAIL

    public static final URLImage.ImageAdapter RESIZE_FAIL
    Will fail if the downloaded image has a different size from the placeholder image

  - ### FLAG_RESIZE_SCALE

    public static final int FLAG_RESIZE_SCALE
    Flag used by `java.lang.String, com.codename1.ui.Image, int)` Equivalent to `#RESIZE_SCALE`.
    See Also:
      - Constant Field Values

  - ### RESIZE_SCALE

    public static final URLImage.ImageAdapter RESIZE_SCALE
    Scales the image to match the size of the new image exactly

  - ### FLAG_RESIZE_SCALE_TO_FILL

    public static final int FLAG_RESIZE_SCALE_TO_FILL
    Flag used by `java.lang.String, com.codename1.ui.Image, int)`. Equivalent to `#RESIZE_SCALE_TO_FILL`.
    See Also:
      - Constant Field Values

  - ### RESIZE_SCALE_TO_FILL

    public static final URLImage.ImageAdapter RESIZE_SCALE_TO_FILL
    Scales the image to match to fill the area while preserving aspect ratio

- ## Method Details

  - ### setDefaultRequestDecorator

    public static void setDefaultRequestDecorator(URLImage.RequestDecorator decorator)
    Installs a global `RequestDecorator`. Pass `null` to clear the existing default. The decorator runs on every URLImage's `ConnectionRequest` immediately before it's queued.

  - ### getDefaultRequestDecorator

    public static URLImage.RequestDecorator getDefaultRequestDecorator()
    Returns the global default decorator installed via `#setDefaultRequestDecorator(RequestDecorator)`, or `null`.

  - ### setDefaultBearerToken

    public static void setDefaultBearerToken(String token)

    Convenience for the most common case: every URLImage fetch should carry the same `Authorization: Bearer <token>` header. Equivalent to `setDefaultRequestDecorator(req -> req.addRequestHeader( "Authorization", "Bearer " + token))`.

    Pass `null` to clear. Subsequent calls replace the previously-set header value; the same `Authorization` header is not appended twice.

  - ### getExceptionHandler

    public static URLImage.ErrorCallback getExceptionHandler()

    The exception handler is used for callbacks in case of an error

    ###### Returns

    the exceptionHandler

  - ### setExceptionHandler

    public static void setExceptionHandler(URLImage.ErrorCallback aExceptionHandler)

    The exception handler is used for callbacks in case of an error

    ###### Parameters

    - `aExceptionHandler`: the exceptionHandler to set

  - ### createMaskAdapter

    public static URLImage.ImageAdapter createMaskAdapter(Image imageMask)

    Creates an adapter that uses an image as a Mask, this is roughly the same as SCALE_TO_FILL with the exception that a mask will be applied later on. This adapter requires that the resulting image be in the size of the imageMask!

    See the sample usage code below that implements a circular image masked downloader:

        Image roundMask = Image.createImage(placeholder.getWidth(), placeholder.getHeight(), 0xff000000);
        Graphics gr = roundMask.getGraphics();
        gr.setColor(0xffffff);
        gr.fillArc(0, 0, placeholder.getWidth(), placeholder.getHeight(), 0, 360);

        URLImage.ImageAdapter ada = URLImage.createMaskAdapter(roundMask);
        Image i = URLImage.createToStorage(placeholder, "fileNameInStorage", "http://xxx/myurl.jpg", ada);

    ###### Parameters

    - `imageMask`: @param imageMask the mask image see the createMask() method of image for details of what a mask is, it will be used as the reference size for the image and resulting images must be of the same size!

    ###### Returns

    the adapter

  - ### createMaskAdapter

    public static URLImage.ImageAdapter createMaskAdapter(Object mask)

  - ### createToStorage

    public static URLImage createToStorage(EncodedImage placeholder, String storageFile, String url)

    Creates an image the will be downloaded on the fly as necessary with RESIZE_SCALE_TO_FILL as the default behavior

    ###### Parameters

    - `placeholder`: @param placeholder the image placeholder is shown as the image is loading/downloading and serves as the guideline to the size of the downloaded image.

    - `storageFile`: the file in storage to which the image will be stored

    - `url`: the url from which the image is fetched

    ###### Returns

    a URLImage that will initialy just delegate to the placeholder

  - ### createToStorage

    public static URLImage createToStorage(EncodedImage placeholder, String storageFile, String url, URLImage.ImageAdapter adapter)

    Creates an image the will be downloaded on the fly as necessary

    ###### Parameters

    - `placeholder`: @param placeholder the image placeholder is shown as the image is loading/downloading and serves as the guideline to the size of the downloaded image.

    - `storageFile`: the file in storage to which the image will be stored

    - `url`: the url from which the image is fetched

    - `adapter`: @param adapter the adapter used to adapt the image into place, it should scale the image if necessary

    ###### Returns

    a URLImage that will initialy just delegate to the placeholder

  - ### createToStorage

    public static URLImage createToStorage(EncodedImage placeholder, String storageFile, String url, URLImage.ImageAdapter adapter, URLImage.RequestDecorator decorator)

    Same as `#createToStorage(EncodedImage, String, String, ImageAdapter)`, plus a per-call `RequestDecorator` applied to the `ConnectionRequest` that fetches the image bytes. Use when the URL requires authentication, custom headers, or other `ConnectionRequest` configuration not covered by the default.

    If a global default decorator is also installed via `#setDefaultRequestDecorator(RequestDecorator)`, the global default runs first, then the per-call decorator -- so the per-call decorator can override headers set by the default.

  - ### createToFileSystem

    public static URLImage createToFileSystem(EncodedImage placeholder, String file, String url, URLImage.ImageAdapter adapter)

    Creates an image the will be downloaded on the fly as necessary

    ###### Parameters

    - `placeholder`: @param placeholder the image placeholder is shown as the image is loading/downloading and serves as the guideline to the size of the downloaded image.

    - `file`: the file in the file system to which the image will be stored

    - `url`: the url from which the image is fetched

    - `adapter`: @param adapter the adapter used to adapt the image into place, it should scale the image if necessary

    ###### Returns

    a URLImage that will initialy just delegate to the placeholder

  - ### createCachedImage

    public static Image createCachedImage(String imageName, String url, Image placeholder, int resizeRule)

    Creates an image that will be downloaded on the fly as necessary. On platforms that support a native image cache (e.g. Javascript), the image will be loaded directly from the native cache (i.e. it defers to the platform to handle all caching considerations. On platforms that don't have a native image cache but do have a caches directory `FileSystemStorage#hasCachesDir()`, this will call `java.lang.String, java.lang.String, com.codename1.ui.URLImage.ImageAdapter)` with a file location in the caches directory. In all other cases, this will call `java.lang.String, java.lang.String)`.

    ###### Parameters

    - `imageName`: The name of the image.

    - `url`: the URL from which the image is fetched

    - `placeholder`: @param placeholder the image placeholder is shown as the image is loading/downloading and serves as the guideline to the size of the downloaded image.

    - `resizeRule`: One of `#FLAG_RESIZE_FAIL`, `#FLAG_RESIZE_SCALE`, or `#FLAG_RESIZE_SCALE_TO_FILL`.

    ###### Returns

    a Image that will initially just delegate to the placeholder

  - ### fetch

    public void fetch()
    Images are normally fetched from storage or network only as needed, however if the download must start before the image is drawn this method can be invoked. Notice that "immediately" doesn't mean synchronously, it just means that the image will be added to the queue right away but probably won't be available by the time the method completes.

  - ### getInternal

    protected Image getInternal()

    Returns the actual image represented by the encoded image, this image will be cached in a weak/soft reference internally. This method is useful to detect when the system actually created an image instance. You shouldn't invoke this method manually!

    ###### Returns

    drawable image instance

    Overrides:
      `getInternal` in class `EncodedImage`

  - ### requiresDrawImage

    public boolean requiresDrawImage()
    Description copied from class: `Image`

    New label optimizations don't invoke drawImage and instead just pass the native image directly to the underlying renderer. This is problematic for some image types specifically timeline & FontImage and this method allows these classes to indicate that they need that legacy behavior of calling drawImage.

    ###### Returns

    true if a drawImage call is a required

    Overrides:
      `requiresDrawImage` in class `Image`

  - ### getImageData

    public byte[] getImageData()

    Returns the byte array data backing the image allowing the image to be stored and discarded completely from RAM.

    ###### Returns

    byte array used to create the image, e.g. encoded PNG, JPEG etc.

    Overrides:
      `getImageData` in class `EncodedImage`

  - ### animate

    public boolean animate()

    Advances this image's animation state, if it is animated.

    ###### Returns

    `true` if the animation state changed.

    Overrides:
      `animate` in class `Image`

  - ### lock

    public void lock()
    Block this method from external callers as it might break the functionality
    Overrides:
      `lock` in class `EncodedImage`

  - ### unlock

    public void unlock()
    Block this method from external callers as it might break the functionality
    Overrides:
      `unlock` in class `EncodedImage`

  - ### isAnimation

    public boolean isAnimation()

    Returns true if this is an animated image

    ###### Returns

    true if this image represents an animation

    Overrides:
      `isAnimation` in class `EncodedImage`