Providing resources¶

In a NeoMAD project, all the data embedded in the application besides java classes is called resources. These resources can be of several types: strings, raw (binary data), music, image, font and XMLs (Layouts…).

During the application building process, NeoMAD incorporates resources in the generated binaries with the expected format and structure depending on the target platform.

NeoMAD also creates a Res.java file containing constants to identify the application’s resources. In the source code the resources will be accessed through methods from the ResManager interface (such as ResManager.getString(), ResManager.getImage(), etc) or constructors of UI element classes (such as TextArea(int resId), ImageLabel(int resId), etc). All these methods take the resource id from Res.java as their parameter.

Note

The Res class is automatically generated by NeoMAD at compilation time. This means that the constants used to access resources will only be declared in the project source code once it has been compiled.

Here is an example of a basic project structure that could be found in a NeoMAD project:

MyProject/
 src/
     com/
         company/
             application/
                 MyApplication.java
                 MyScren.java
 res/
     icon/
         icon-48.png
     image/
         graphic.png
     layout/
         main.xml
         info.xml
     string/
         strings-en.xml

Note

NeoMAD checks rejected resource files by providing errors and/or warnings:

Do not provide files inside res folder directly.
Be sure to respect res path rules (See details in next chapters)
the filename should be unique (whatever the filename case)

Here is the list of resource types you will be able to provide in your application.

Directory	Resource Type
`background/`	XML files that define linear gradient background for a view
`font/`	True-Type fonts (.ttf)
`icon/`	Bitmap files (.png)
`image/`	Bitmap files (.png, .jpg)
`layout/`	XML files that define a user interface layout. See Layout Resource.
`music/`	Music resources (.mp3, .wav, .mid, .ott)
`raw/`	Arbitrary files to save in their raw form. To open these resources with a raw InputStream, call ResManager.openRaw() with the resource ID, which is Res.raw.filename.
`splash/`	Bitmap files (.png)
`string/`	Text strings for your application
`style/`	XML files that contain style resource
`values/`	XML files that contain simple values, such as dimens, and colors. * colors.xml for color values. * bools.xml for boolean values. * dimens.xml for dimension values. * integers.xml for integer values. * xmlfonts.xml for fonts.

Resource requirements¶

Some resource types, like icons and splashes, need to respect guidelines. In particular, different sizes need to be provided for a same resource, in order to display well on all devices. For each of these sizes, one of these four levels of requirements applies:

Required for build: the project cannot be built if the resource is not present.
Required for store: the project can be built if the resource is not present, but the resource will be needed to submit the application to the store.
Recommended for store: the project can be built if the resource is not present and the application can be submitted to the store. To ensure the best integration on all devices, the resource should be provided.
Optional: the resource may be provided to ensure a better display on all devices.

The list of resource requirements can be found in the section related to each resource type:

Providing Alternative Resources¶

MyProject/
    res/
        image/
            graphic.png
        image-hdpi/
            graphic.png
        layout/
            main.xml
            info.xml
        layout-hdpi/
            main.xml
        string/
            strings-en.xml
            strings-fr.xml

Qualifier name rules¶

Here are some rules about using configuration qualifier names:

You can specify multiple qualifiers for a single set of resources, separated by dashes.

For example, image-small-ldpi applies to devices with small screen size and low density.

Qualifier	Description
`platform`	Provides resources for one platform. `android` `ios`
`screensize`	See Multiple Resolutions for more information about how to handle different screen sizes. `small` `normal` `large` `xlarge`
`density`	See Multiple Resolutions for more information about how to handle different screen densities. `ldpi`: Low-density screens; approximately 120dpi. `mdpi`: Medium-density (on traditional HVGA) screens; approximately 160dpi. `hdpi`: High-density screens; approximately 240dpi. `xhdpi`: Extra-high-density screens; approximately 320dpi. `xxhdpi`: Extra-extra-high-density screens; approximately 480dpi. `xxxhdpi`: approximately 640dpi.
`locale`	The locale is defined by a two-letter ISO 639-1 language code, optionally followed by a two letter ISO 3166-1-alpha-2 region code. `en` `fr` `en-US` `fr-FR` `...`
`iconsize`	An icon is a squared image. The iconsize qualifier is represented by an integer, which is the size of the side of the image. See the ‘Icon resources’ section for a list of authorized sizes, e.g. `48` `62` `76` `...`
`splashsize`	A splash is a rectangular image. The splashsize qualifier is represented by two integers separated by a ‘x’, which respectively represent the width and height of the image. See the ‘Splash resources’ section for a list of authorized sizes, e.g. `240x400` `480x800` `800x480` `...`

Group rules¶

Respect the order of qualifier name position in the rule !

The qualifiers must respect the order listed in the table below (column Path rule).

For example: Wrong: image-hdpi-small/ Correct: image-small-hdpi/

Qualifier	Path rule
`Background`	res/background(`-platform`)(`-screensize`)(`-density`)/filename.(`xml`)
`Font`	res/font(`-platform`)/filename.(`ttf`)
`Icon`	res/icon(`-platform`)/icon(`-iconsize`).(`png`)
`Image`	res/image(`-platform`)(`-screensize`)(`-density`)/filename.(`png\|jpg`)
`Layout`	res/layout(`-platform`)(`-screensize`)(`-density`)/filename.(`xml`)
`Music`	res/music(`-platform`)/filename.(`mp3\|ott\|wma\|wav`)
`Raw`	res/raw(`-platform`)/filename.extension
`Splash`	res/splash(`-platform`)/splash(`-splashsize`).(`png`)
`String`	res/string(`-platform`)/strings(`-locale`).(`xml`)
`Style`	res/style(`-platform`)(`-screensize`)(`-density`)/filename.(`xml`)
`Values`	res/values(`-platform`)(`-screensize`)(`-density`)/filename.(`xml`)

Finding the Best-matching Resource¶

When a resource for which you provide alternatives needs to be loaded, which alternative will be used?

This selection is made at runtime, depending on the current device configuration.

To demonstrate how NeoMAD selects an alternative resource, assume each of the following image directories contains a different version of the same image:

res/image/myImage.png (default)

res/image-mdpi/myImage.png

res/image-normal/myImage.png

res/image-normal-mdpi/myImage.png

Assume the application is currently running on a device with the following configuration:

ScreenSize: normal
Density: hdpi

1. Compute candidates¶

NeoMAD computes candidates that are acceptable based on the current device configuration.

Acceptable alternatives are images in folders that have screen sizes and densities that are smaller than or equal to the current devices ones. Resources made for bigger screen sizes and densities than the current one can not be considered as acceptable, as they would be too big for the current device. The acceptable alternatives are then ordered from the most suited to the least, or said differently from the nearest configuration to the furthest, the screen size being prioritary over the density.

Following on the previous example, the result of the computation ordered by preference is:

normal-hdpi
normal-mdpi
normal-ldpi
normal
small-hdpi
small-mdpi
small-ldpi
small
hdpi
mdpi
ldpi
default

2. Eliminate qualifiers¶

After computing the candidates, there may be some combinations that do not exist for the resource.

In the example above, only the following variations exist for the resource Res.image.myImage:

normal-mdpi
normal
default

3. Select the highest-precedence¶

The best candidate for the image resource is the first of the previous list, which is the existing image variation that is the nearest of the current device configuration. In the example given below, the best choice is “normal-mdpi”, so the image located in res/normal-mdpi will be loaded.