====== 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.

<WRAP center round important 90%>
Prior to v4.1, iViewer would simply load the first .gui file it found in the archive.
</WRAP>

<WRAP center round alert 90%>
A zip file cannot contain other zip files within it!
</WRAP>



===== Multiple GUI Files =====

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 ====
Android devices choose which GUI file to load based on a few different file naming options, checked in the following order:

  - Check for filepath matching the width and height of the screen in the either orientation (first checks for portrait orientation) (eg. ''1080w2280h'')
  - 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'')
  - 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.
  - If the device matches the same ratio as a 768x1024 iPad, then it will also check or ''GUI-iPad''
  - If still no GUI found, it will simply use the first found GUI file.

==== iPads and iPhones ====

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

  - 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''.
  - Check for a filepath matching the next smallest logical height, eg. ''GUI-812h''.
  - Check for a filepath matching ''GUI''
  - 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

==== Scaling & Positioning ====

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

=== Android ===

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. [[software:gui-designer:project-properties#positioning-android-only|See here for more info]].

=== iOS ===

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