Omnis Technical Note TNJC0007Dec 2013
for Omnis Studio 6.x to 10.1.x
For Studio 10.2 onwards you are advised to use SVG image files for JS component icons, see TNJC0010.
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:
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.
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
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.
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.
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.