GUI Archive

A GUI Archive is a .zip file which contains one or more guiDesigner projects. This includes the .gui file along with any assets such as graphics, scripts, sounds, etc.

As of v4.1 onwards, iViewer is capable of automatically loading a specific GUI file in an archive based on a naming structure described below. This allows a single archive to include GUIs for various screen sizes (iPhones, iPads, etc).

Each GUI file can be in a separate folder with its own assets, or in a single folder sharing assets, or a mix! All depends how your assets are referenced in your guiDesigner project.

iViewer v4.1 onwards supports archives with multiple GUI files inside. The GUI file that is loaded is determined based on the size of the screen of the device loading the archive.

This is achieved by the naming of your GUI file or folder within the archive. Any part of the full path to the GUI file within the archive must match one of the following strings to be loaded correctly. The string search is case-insensitive, so ipad or iPad will work the same.

So the path to the file could be GUI-iPad/myproject.gui or even a file in any folder of the zip named myproject-GUI-iPad.gui and it will be chosen for iPads.

Android devices choose which GUI file to load based on a few different file naming options, checked in the following order:

1. Check for filepath matching the width and height of the screen in the either orientation (first checks for portrait orientation) (eg. 1080w2280h)
2. Check for a filepath matching just the height of the screen in either orientation (first checks for portrait orientation) followed by a h character (eg. 1024h)
3. Check for the closest matching iOS screen ratio. So if the Android device was close to the ratio of an iPhone XR (896 / 414 = ratio 2.1642512077), it would check for a filepath matching GUI-896h. If still no match for the closest iOS string, it will continue to look for the next smallest resolution.
4. If the device matches the same ratio as a 768×1024 iPad, then it will also check or GUI-iPad
5. If still no GUI found, it will simply use the first found GUI file.

iPhone and iPad devices choose which GUI file to load based on a few different file naming options, checked in the following order:

1. Check for filepath matching the logical height of the device, prefixed by GUI-. For example logical resolution of iPhone XR is 414w x 896h, so it will look for a filepath matching GUI-896h.
2. Check for a filepath matching the next smallest logical height, eg. GUI-812h.
3. Check for a filepath matching GUI
4. If still no GUI found, it will simply use the first found GUI file.

Here is a list of the GUI sizes (in their search order) and the devices that support it:

• GUI-iPadPro = iPad Pro 12.9”
• GUI-1366h = iPad Pro 12.9”
• GUI-1194h = iPad Pro 11”
• GUI-1112h = iPad Air 10.5”
• GUI-iPad = iPad (all other models)
• GUI-1024h = iPad (all other models)
• GUI-896h = iPhone XS Max, XR
• GUI-812h = iPhone XS, X
• GUI-736h = iPhone 8+, 7+, 6S+, 6+
• GUI-667h = iPhone 8, 7, 6S, 6
• GUI-568h = iPhone SE, 5S, 5, 5C
• GUI = iPhone 4S, 4, 3GS, 3G, 2G

What happens when your GUI page size does not match the device resolution? Read on.

Within guiDesigner, in your project properties, there is a special property for page positioning that only affects android devices.
When the project page size does not match the device resolution, you can choose to scale the project a variety of ways. See here for more info.

If the GUI is smaller than the device resolution, it will be scaled to fill the screen, maintaining aspect ratio. So black bars will be visible if the GUI does not fully fill the screen.
If the GUI is larger than the device resolution, it will be rendered in the middle of the screen and cropped to suit the screen.

A great resource for all iOS device resolutions and screen sizes:
https://iosref.com/res/

For more info on iPhone logical resolutions (Points), see this excellent guide: https://www.paintcodeapp.com/news/ultimate-guide-to-iphone-resolutions