Skip to content

Images

Jump to bottom Edit New page
Steve Hannah edited this page Aug 9, 2017 · 12 revisions

Images are supported as both "inputs" of the stylesheet, and as outputs to the compiled resource file. "Input" images are usually specified via the background-image property in a selector. "Output" images are always saved as multi-images inside the resource file.

Image DPI and Device Densities

In order to appropriately size the image, the CSS compiler needs to know what the source density of the image is. E.g. if an image is 160x160 pixels with a source density of 160dpi (i.e. medium density - or the same as an iPhone 3G), then the resulting multi-image will be sized at 160x160 for medium density devices and 320x320 on very high density devices (e.g. iPhone 4S Retina) - which will result in the same perceived size to the user of 1x1 inch.

However if the image has a source density of 320dpi, then the resulting multi-image would be 80x80 pixels on medium density devices and 160x160 pixels on very high density devices.

Some images have this density information embedded in the image itself so that the CSS processor will know how to resize the image properly. However, it is usually better to explicitly document your intentions by including the cn1-source-dpi property as follows:

SomeStyle {
    background-image: url(images/my-image.png);
    cn1-source-dpi: 160;
}
Note
 cn1-source-dpi values are meant to fall into threshold ranges. Values less than or equal to 120, are interpreted as low density. 121 - 160 are medium density (iPhone 3GS). 161 - 320, very high density (iPhone 4S). 321 - 480 == HD. 481 and higher == 2HD. In general, you should try to use images that are one of these DPIs exactly: 160, 320, or 480, then images will be scaled up or down to the other densities accordingly.

Multi-Images vs Regular Images

By default all images are imported as multi-images. If you want to import an image as a "regular" image, you can simply set cn1-source-dpi to 0. E.g.

SomeStyle {
    background-image: url(images/my-image.png);
    cn1-source-dpi: 0;
}

Multi-Images as Inputs

If you have already generated images in all of the appropriate sizes for all densities, you can provide them in the same file structure used by the Codename One XML resource files: The image path is a directory that contains images named after the density that they are intended to be used for. The possible names include:

  1. verylow.png

  2. low.png

  3. medium.png

  4. high.png

  5. veryhigh.png

  6. 560.png

  7. hd.png

  8. 2hd.png

  9. 4k.png

E.g. Given the CSS directives:

MyStyle {
    background-image: url(images/mymultiimage.png);
}

The files would look like:

css/
 +--- mycssfile.css
 +--- images/
       +--- mymultiimage.png/
             +--- verylow.png
             +--- low.png
             +--- medium.png
              ... etc...
Note
 Multi-image inputs are only supported for local URLs. You cannot use remote (e.g. http://) urls with multi-image inputs.

Image Constants

Theme constants can be images. The convention is to suffix the constant name with "Image" so that it will be treated as an image. In addition to the standard url() notation for specifying a constant image, you can provide a simple string name of the image, and the CSS processor will try to find an image by that name specified as a background image for one of the styles. If it cannot find one, it will look inside a special directory named "res" (located in the same directory as the CSS stylesheet), inside which it will look for a directory named the same as the stylesheet, inside which it will look for a directory with the specified multi-image. This directory structure is the same as used for Codename One’s XML resources directory.

E.g. In the CSS file "mycssfile.css":

radioSelectedFocusImage: "Radio_btn_Press.png";

Will look for a directory located at res/mycssfile.css/Radio_btn_Press.png/ with the following images:

  1. verylow.png

  2. low.png

  3. medium.png

  4. high.png

  5. veryhigh.png

  6. 560.png

  7. hd.png

  8. 2hd.png

  9. 4k.png

It will then create a multi-image from these images and include them in the resource file.

Image Recipes

Import Multiple Images In Single Selector

It is quite useful to be able to embed images inside the resource file that is generated from the CSS stylesheet so that you can access the images using the Resources.getImage() method in your app and set it as an icon on a button or label. In this case, it is easier to simply create a dummy style that you don’t intend to use and include multiple images in the background-image property like so:

Images {
    background-image: url(images/NowLogo.png),
        url(images/Username-icon.png),
        url(images/Password-icon.png),
        url(images/Name-icon.png),
        url(images/Email-icon.png),
        url(images/SeaIce.png),
        url(images/Back-icon.png),
        url(images/Source-icon.png),
        url(images/Date-icon.png),
        url(images/Arrow-right.png),
        url(images/Share-icon.png),
        url(images/Text-icon.png),
        url(images/Comments-icon.png),
        url(images/RedPlanet.png),
        url(images/News-icon.png),
        url(images/Channels-icon.png),
        url(images/Bookmarks-icon.png),
        url(images/Overview-icon.png),
        url(images/Calendar-icon.png),
        url(images/Timeline-icon.png),
        url(images/Profile-icon.png),
        url(images/Widgets-icon.png),
        url(images/Settings-icon.png),
        url(images/Bookmark-icon.png);
}

Then in Java, I might do something like:

Resources theme = Resources.openLayered("/theme.css.res");

Label bookmark = new Label(theme.getImage("Bookmark-icon.png"));

Loading Images from URLs

You can also load images from remote URLs. E.g.

Images {
    background-image: url(http://solutions.weblite.ca/logo.png);
}

Generating 9-Piece Image Borders

If you intend to use an input image as the basis of a 9-piece image border, you’ll need to specify the "slice" points - where the image should be sliced to produce the 9 images. These are specified with the cn1-9patch directive, which takes 4 pixel values to indicate the top, right, bottom, and left slice offsets.

E.g. Suppose you want the image to be sliced in such a way that the left slices are 10 pixels wide, the top slices are 5 pixels high, the right slices are 8 pixels wide, and the bottom slices are 4 pixels high, you would have:

MyStyle {
    background-image: url(myimage.png);
    cn1-9patch: 5px 8px 4px 10px;
}
Tip
 The order (top, right, bottom, left) is the same as the standard order for CSS padding, borders, and margins.

Image Backgrounds

Component backgrounds in Codename One are a common source of confusion for newcomers because there are 3 different properties that can be used to define what a component’s background looks like, and they have priorities:

  1. Background Color - You can specify an RGB color to be used as the background for a component.

  2. Background Image - You can specify an image to be used as the background for a component. Codename One includes settings to define how the image is treated, e.g. scale/fill, tile, etc. If a background image is specified, it will override the background color setting - unless the image has transparent regions.

  3. Image Border - You can define a 9-piece image border which will effectively cover the entire background of the component. If an image border is specified, it will override the background image of the component.

A common scenario that I run into is trying to set the background color of a component and see no change when I preview my form because the style had an image background defined - which overrides my background color change.

The potential for confusion is mitigated somewhat, but still exists when using CSS. You can make your intentions explicit by adding the cn1-background-type property to your style. Possible values include:

  1. cn1-image-scaled

  2. cn1-image-scaled-fill

  3. cn1-image-scaled-fit

  4. cn1-image-tile-both

  5. cn1-image-tile-valign-left

  6. cn1-image-tile-valign-center

  7. cn1-image-tile-valign-right

  8. cn1-image-tile-halign-top

  9. cn1-image-tile-halign-center

  10. cn1-image-tile-halign-bottom

  11. cn1-image-align-bottom

  12. cn1-image-align-left

  13. cn1-image-align-right

  14. cn1-image-align-center

  15. cn1-image-align-top-left

  16. cn1-image-align-top-right

  17. cn1-image-align-bottom-left

  18. cn1-image-align-bottom-right

  19. cn1-image-border

  20. cn1-none

  21. none

Example Setting Background Image to Scale Fill

MyContainer {
    background-image: url(myimage.png);
    cn1-background-type: cn1-image-scaled-fill;
}

Image Compression

CN1 resource files support both PNG and JPEG images, but PNG is the default. Multi-images that are generated by the CSS compiler will be PNG if they include alpha transparency, and JPEG otherwise. This is to try to reduce the file size as much as possible while not sacrificing quality.

Add a custom footer
Add a custom sidebar
Clone this wiki locally