Adding Resources

Adding built-in resources to DlangUI application

Built in resources are files which are imported with import "filename" and built inside program executable.

Directory structure

In your application directory, create directory structure like

views
    res          -- DlangUI resources directory
    i18n         -- translation files
    hdpi         -- high resolution drawables
    mdpi         -- medium resolution drawables
    ldpi         -- low resolution drawables
    shaders      -- custom shaders

i18n, hdpi, mdpi, ldpi, shaders are standard directory names for different resource types. You can use more directories for your custom type resources or just place them inside res/ directory

Resource list file

Since D compiler cannot list files available for import "", all resource files must be explicitly listed in *.list raw utf8 text file, e.g. views/resources.list

Filename may be arbitrary with .list extension.

Sample resource list file views/resources.list

res/i18n/en.ini
res/i18n/fr.ini
res/mdpi/my_app_logo.png
res/hdpi/hdpi_my_app_logo.png
res/theme_custom1.xml
res/cool_button.png

Console mode resources

For transparent support of Console mode application, add one more resource list file with the same name as main file, but prefixed with console_ - e.g. for resources.list, add console_resources.list

DUB.JSON changes

Resource directories must be added to dub.json of your application.

"stringImportPaths": ["views", "views/res", "views/res/i18n", "views/res/mdpi"],

Importing built-in resources in application

Import your custom resources in UIAppMain function:

/// entry point for dlangui based application
extern (C) int UIAppMain(string[] args) {
    ...
    // embed resources listed in views/resources.list into executable
    embeddedResourceList.addResources(embedResourcesFromList!("resources.list")());

Standard resources

Unless dlangui library is built without EmbedStandardResources version defined, dlangui library includes standard resources (themes, icons, drawables, translations).

You can check dlangui/views/res for list of standard resources.

If you add resource with the same name as standard resource into your application, resource copy from application will be used.

Using resources in your application

You can use drawables from resources by specifying their ID everywhere resource id is acceptable.

For images, ID of resource is resource filename with stripped out extensions like .png, .jpeg and stripped out DPI prefixes like hdpi_ or ldpi_. As well, for nine-patch PNGs, .9.png is stripped, but it is handled as nine-patch drawable.

E.g. you can use views/res/my_editbox_background.png and views/res/hdpi/hdpi_my_app_logo.jpg

editBox.backgroundDrawable = "my_editbox_background";
auto image = new ImageWidget(null, "my_app_logo");

// getting resource image DrawBuf reference from cache
DrawBufRef logo = imageCache.get("my_app_logo");
// loading tx_fabric.jpg drawable; apply tiling by adding of .tiled suffix
DrawableRef bg = drawableCache.get("tx_fabric.tiled");

Useful functions to get arbitrary resource:

/// load resource bytes from embedded resource or file
immutable(ubyte[]) loadResourceBytes(string filename);
// load text resource
string loadTextResource(string resourceId);

Multiple screen DPI support for resources

Directories mdpi, ldpi, hdpi, xhdpi are intended for holding copies of drawable resources for different screen DPIs, like in Android.

Due to DMD issue with support of relative paths in import directive under Windows (seems to be fixed in recent compiler versions), there is a workaround for supporting of different screen DPIs. Drawable resources except mdpi are prefixed with DPI prefix:

res/mdpi/my_app_logo.png
res/hdpi/hdpi_my_app_logo.png

Resource "my_app_logo" will be chosen automatically based on screen DPI - either mdpi or hdpi version.

Later this behavior will be fixed - it will be enough to place file with same name into different DPI subdirs, w/o extra prefixes.