Migrating resources from NeoMAD 3.X

In NeoMAD 3.X, the developer has to declare all the used resources inside the URS file (project descriptor).

Resources are declared in the URS file using the following elements: <strings>, <image>, <rawdata>, <music>, <font>, <layout> and <resourcelot>.

Except for the <strings> element, all of these elements must be contained in <resourcelot> elements. The <resourcelot> elements have no effect on resource organization in the generated binary, but make the URS organization clearer.

NeoMAD 4.0 has introduced a simplest way to declare resources through a NeoMAD project:

Now, resources should be present in a res folder structure and should be respect some constraints.

For texts, the CSV file has been replaced by XML format, but the CSV format will be kept to help translations.

Texts (CSV file)

NeoMAD 4.X provides an automatic way to convert CSV into XML format.

Here is an example of the declaration of a CSV file in the URS file:

<strings path="res/Strings/strings.csv" />

The first build time, NeoMAD 4.X see that a CSV exists and should be converted into XML new format.

For the next build, NeoMAD will prevent the developer that the CSV is ignored because it has been already converted before. Be sure that CSV and XML files does not contain differences, otherwise only the XML file is used for the application.

The CSV Format

The CSV file can be encoded in ASCII (Latin 1), which is the default encoding, or in UTF-8.

The structure of the CSV file is described as follows:

  • the first line describes the various languages that will be implemented in the application separated in columns (the separator is a ;); language names must be compliant with ISO 639-1 and can be followed by the region code in the ISO 3166-1 format (e.g. en, en-US, fr, fr-FR, fr-CA).
  • each following line describes a string: this consists of an identifier and the various translations of the text organized in columns (separated by ;)

For each text defined in this file NeoMAD will automatically create a constant in Res.java.

e.g. Here is a simple CSV file that only defines one text for two languages:

ID;en;fr
TXT_HELLO;Hello World !;Bonjour le monde !

NeoMAD will declare a new constant for this text in the string inner class of Res.java:

public final static int TXT_HELLO_WORLD = 0;

The XML format

Each language or locale should declare an XML file which contain Res.string translation.

See String Resources

Compilation Options

If the project is compiled with the -l1 option (first language) the application will display Hello World!. If the project is compiled with the -l2 option (second language) it will display Bonjour le monde !.

If the project is compiled with the -m1,2 parameter, both languages will be available in the application and the ResManager.setLanguage() method must be used to select the current language.

ResourceLot

Resources (rawdata, image, font, layout, background) should not be declared in 4.0 version.

res path should respect pattern (See details).

res/
  image/
    filename.png

Converting image declaration

Images must be in PNG or JPG format. They are declared using the <image> tag in the URS file. The name attribute corresponds to the constant that will be used to access this resource from the application classes. The path attribute is used to give the path to the image file on the disk.

  • First, be sure that image name is the same as image filename
<resourcelot>
   <image name="myImageName" path="res/image/myImageName.png"/>
</resourcelot>

Theses tips are also available for other resources (music, rawdata, font).

Applying resource variation

<resourcepath default="">
  <variation name="" />

  <variation density="MEDIUM" screensize="NORMAL" value=""/>
</resourcepath>

resourcepath default attribute is used when no varation with MEDIUM density and NORMAL screen size is provided. Otherwise, the value given by MEDIUM-NORMAL combination will be used.

Applying application cloning

In NeoMAD 3.X, Cloning an app consists in declaring constants in the Constants.java file and using them inside resourcelot declaration paths.

NeoMAD 4.X introduces new URS tags : res, variants.

See Resource Variants Chapter for further information.

Incompatibilities

In iOS, NeoMAD 3.X has a wrong cross-platform translation :

Image for retina are declared with @2x in the iOS platform and corresponds in NeoMAD 3.X as HIGH density.

In NeoMAD 4.X:

Image for retina are declared with @2x in the iOS platform and corresponds in NeoMAD 4.X as xhdpi density (not hdpi).

Reasons:

  • @2x means that the resource will be scaled with a 2.0x factor form medium density.
  • xhdpi means that the resource will be scaled with a 2.0x factor form medium density.
  • hdpi means that the resource will be scaled with a 1.5x factor form medium density.
  • mdpi means that the resource will be scaled with a 1.0x factor form medium density.

The screensize and densities table has been updated in NeoMAD 4.X for providing the best cross-platform translation.