Omnis Technical Note TNJC0007Dec 2013

JavaScript Components: High Definition Icons

for Omnis Studio 6.x or above

In Omnis Studio 6.x or above you can create high definition (HD) icons for various JavaScript Components and assign the image to a component by specifying the icon ID or $iconid. These icon images are not stored in Omnis itself, as in previous versions, rather they are stored in the 'html/icons' folder in your Omnis development folder or in the Omnis App Server when you deploy your application.

When Omnis references an Icon ID it will search for the icon in the ‘html/icons’ folder, then it will search the #ICONS icon file in the current library and then any other Icon datafiles (the old method of adding icons to an icon datafile continues to work in Studio 6.x or above). This new method of storing and assigning component icons only works with JavaScript Client based remote forms (not for Web Client plug-in or iOS Client remote forms).

Creating component icons

You can create your icons in any third-party image editing software and place the images directly in the 'hotml/icons' folder in the Omnis tree. The images can be 1.5 or 2 times the resolution (pixel density) of images that are used for standard monitors, which means such images will be rendered in high definition on the most recent smartphones and tablets, such as the Apple® iPhone 5 or Samsung® Galaxy S4. Therefore, you need to create an icon at twice the standard size for displaying on high definition devices – when such an image is displayed it will be scaled down to the correct physical size.

The image files must be saved using the PNG file type and placed in a sub-folder of the ‘html/icons’ folder in the main Omnis product tree. Each sub-folder in the ‘html/icons’ folder represents what is called an “icon set” which is a named collection of icons. Note that an icon set cannot be named ‘datafile’ or ‘lib’ since those names are already used in the icons folder. Any files and folders that do not conform to the naming conventions are ignored. (Note the 'icons' folder in the root of the Omnis development tree contains the old icon datafiles and is not used for icon sets.)

Image File names

Each image file within an icon set must conform to the following naming convention:

<text>_<id>_<size><state>_<resolution>.png

The <text> part of the filename is the name of the image used in the icon picker dialog when you set an object’s $iconid in the Property Manager. The <id> is the positive integer id to be used as the icon id. It can be in the range 1 to 10000000.

The <size> is the CSS pixel size of the image, i.e. the resolution independent size of the image, meaning that for all resolutions of the same image this has the same value. The value of <size> has the form <width>x<height>, where the values 16x16, 32x32 and 48x48 are special values since they correspond to the standard icon sizes supported by Omnis. The <state> is only included for multi-state icons: c is included for the checked state, h is highlighted, x is checked highlighted, or if not included (empty) specifies the normal state of the icon.

The <resolution> is the factor by which the pixel density is greater than a standard monitor and is one of the following: “_2x” for HD devices such as the Retina display, or “_15x” for some devices e.g. certain Android phones that have a 1.5x pixel density. An empty string is the default and is for standard resolution devices, equivalent to _1x. The following are example file names:

pencil_1657_16x16.png Normal state 16x16 icon with ID 1657 for standard resolution devices
pencil_1657_16x16_2x.png Normal state 16x16 icon with ID 1657 for HD resolution devices
check_1658_32x32c_2x.png Checked state 32x32 icon with ID 1658 for HD resolution devices

Note that the image file names are case insensitive and they must be unique across all platforms and file systems (that is the case of file names is ignored).

You do not have to create an icon image for all resolutions – Omnis will use an icon image closest to the resolution being referenced, scaling as appropriate, and as with all image scaling it is better to force Omnis to scale an image down than to scale it up. Therefore, you may like to provide the highest possible resolution image for your icons and allow Omnis to scale the images to display the lower resolutions, however for best results you could supply an image for all possible sizes and resolutions.

When the JavaScript Client connects, it sends its resolution to the Omnis App Server. This allows the server to use the appropriate icon when setting iconid properties in server methods.

Non-standard Size Images

You can create images with a size other than the standard sizes (16x16, 32x32, 48x48) by creating the image at a non-standard size and including the image size in the file name when the file is saved. For example, you can create an image 100x200 pixels and name it something like “mygraphic_1688_100x200.png”.

Setting the Icon set in your library

To specify which icons are to be used for a library you must set the $iconset library preference to the name of an icon set in your ‘html/icons’ folder. When using this library, and when looking up an icon for the JavaScript client, Omnis will search for icons within this icon set before following the current icon search path in the #ICONS file in the library, then omnispic.df1, and so on.

Setting the Icon ID for objects

When you set the $iconid of an object using the Property Manager, the icon set for the current library will be shown in the Icon picker dialog ($iconset must be set for the library for the icon set to appear) allowing you to select one of the icons in the set. You can select the icon required and the Icon ID will be assigned to $iconid for the object. Alternatively, if you know the ID of the icon you want to assign to a component, enter the ID into the $iconid property for the component. You will also need to specify the size constant to force Omnis to load the correct physical size: either k16x16, k32x32, or k48x48. Omnis should chose the correct resolution for the specified physical size from the icons in your icon set based on the icon ID and the resolution of the current display.

Deploying HD Icons

You need to copy your icon sets and images files to the Omnis App Server when you are ready to deploy your web or mobile app. If the icons are not copied to the 'html/icons' folder on the Server they will appear to be missing from your app.

Note that for standalone apps using the wrappers the icons needed for your mobile app will be bundled in the SCAF. If any icons change on the Omnis App Server they will be updated on the client when the standalone application files are updated.

Example library & Icon set

Download the example library and icons from Github: https://github.com/OmnisStudio/Omnis-HDIcons (requires Studio 8.1.2 or above)
(or the archive iconset.zip suitable for 6.0.1 or above).

Import the library downloaded from Github (or unzip the file/s), place the 'myicons' folder and its contents in the 'html/icons' folder in your Omnis Studio tree as shown.

icons folder

Open the icons.lbs library and note that the $iconset preference of the library is set to 'myicons' (to view this select the library, open the Property Manager and click on the Prefs tab). Open the 'rform' remote form and click on one of the buttons. Open the Property Manager or bring it to the front and click on the Appearance tab.

icons folder

In the above screen, you will see that for the selected button the $iconid is set to ID 88889 and the size k48x48. This icon ID corresponds to a number of image files in the 'myicons' folder, but depending on the icon size specified and the resolution of your display the correct image file is displayed. In this case, the 'save_88889_48x48.png' image will be displayed for standard displays and the 'save_88889_48x48_2x.png' will be displayed for high resolution displays such as a Retina display.

Testing Icons on a mobile device

When you test the remote form in a web browser the correct icons will be displayed for your current display. To test the form on a mobile device, you need to keep the library open and enter the following URL in the browser on your device: http://<your-ip-address>:<omnis-port-number>/jschtml/rform.htm. To find the port number of your Omnis Studio, test the remote using Ctrl/Cmnd-T and the port number will be displayed in the browser on your development computer, such as: http://127.0.0.1:49812/jschtml/rform.htm: enter this URL on your mobile device substituting the ip-address of your local host with the real ip-address of your development computer running Omnis (you can use the ipconfig command to find the IP address of your development computer, via the Command prompt on a PC or the Terminal on a Mac).

If you are viewing this form on a Retina display and want to prove that the high resolution images are being displayed, you can remove or move the '2x' images from the 'myicons' icon set and re-open the remote form: in this case you should see the low resolution images only.

To find out more about creating component icons, refer to the 'JavaScript Components' chapter in the ‘Creating Web & mobile Apps’ manual which you can view here.