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.

public void showForm() {
    Form hi = new Form("InfiniteScrollAdapter", new BoxLayout(BoxLayout.Y_AXIS));

    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(), () -> {
        java.util.List> data = fetchPropertyData("Leeds");
        MultiButton[] cmps = new MultiButton[data.size()];
        for(int iter = 0 ; iter  currentListing = data.get(iter);
            if(currentListing == null) {
                InfiniteScrollAdapter.addMoreComponents(hi.getContentPane(), new Component[0], false);
                return;
            }
            String thumb_url = (String)currentListing.get("thumb_url");
            String guid = (String)currentListing.get("guid");
            String summary = (String)currentListing.get("summary");
            cmps[iter] = new MultiButton(summary);
            cmps[iter].setIcon(URLImage.createToStorage(placeholder, guid, thumb_url));
        }
        InfiniteScrollAdapter.addMoreComponents(hi.getContentPane(), cmps, true);
    }, true);
    hi.show();
}
int pageNumber = 1;
java.util.List> fetchPropertyData(String text) {
    try {
        ConnectionRequest r = new ConnectionRequest();
        r.setPost(false);
        r.setUrl("http://api.nestoria.co.uk/api");
        r.addArgument("pretty", "0");
        r.addArgument("action", "search_listings");
        r.addArgument("encoding", "json");
        r.addArgument("listing_type", "buy");
        r.addArgument("page", "" + pageNumber);
        pageNumber++;
        r.addArgument("country", "uk");
        r.addArgument("place_name", text);
        NetworkManager.getInstance().addToQueueAndWait(r);
        Map result = new JSONParser().parseJSON(new InputStreamReader(new ByteArrayInputStream(r.getResponseData()), "UTF-8"));
        Map response = (Map)result.get("response");
        return (java.util.List>)response.get("listings");
    } catch(Exception err) {
        Log.e(err);
        return null;
    }
}

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);

  • 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:

    • 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:

    • 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:

    • 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

    • 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

    • 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()
      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