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.
|
screensize |
See Multiple Resolutions for more information about how to handle different screen sizes.
|
density |
See Multiple Resolutions for more information about how to handle different screen densities.
|
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.
|
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.
|
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.
|
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.pngres/image-normal/myImage.pngres/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.