UserGuide:iOS Apps

iOS Project Overview

iOS Project Items

When you create your first iOS project, you get the following project items added automatically:

App: The App object works similarly to how it works for desktop and web projects. In the App Inspector, you can set the Default Screen to use for iPhone and iPad-sized devices. Leave a device screen blank if you do not want it to have a native UI for the device. For example, to prevent an app from working on iPhone, select "None" for the Default iPhone Screen property. If you do not want the app to run natively on an iPad, select "None" for the Default iPad Screen property. Keep in mind that the app will still run on the iPad, but will do so by running the iPhone app in the OS "scaled" mode.
iPhoneScreen: Specifies the initial screen displayed when the app is started on iPhone-sized devices.
iPadScreen: Specifies the initial screen displayed when the app is started on iPad-sized devices.
View1: This the main layout where you place controls. It is roughly equivalent to a Window or WebPage in desktop and web projects.
App Icon: This item is where you place the various size app icons for the app. You can use the ImageMaker utility (in the Extras/iOS Utilities folder of the Xojo installation) to create the image files and then drag them into the various sized areas.
Launch Images: This item contains the various size launch images for the app. Launch images are used kind of like a "splash screen" while the app is actually launching. Typically these are screen shots of your empty View so that it makes it look like your app is starting quickly, but they can be almost anything. There are a variety of sizes for all the devices. In particular, the iPhone 5 size is required in order for an iOS app to fill the screen on iPhone 5 and larger devices.

To prevent an app from working on iPhone, select "None" for the Default iPhone Screen App property. If you do not want the app to run natively on an iPad, select "None" for the Default iPad Screen App property. Keep in mind that the app will still run on the iPad, but will do so by running the iPhone screen in the iOS "scaled" mode.

App Object

The App object work similarly to how it works for desktop and web projects. For an iOS project, the App object is a subclass of iOSApplication. You use it to specify the default screen layouts for the devices. You can add events, properties and methods to the App object. Use the App prefix to refer to public properties and methods elsewhere in your code. For example, to refer to the property UserName added to the App object in a class of the project, you would write:

App.UserName = "Billy"

Event Handlers

The Application class for an iOS application has event handlers. They are:

LowMemoryWarning: Called when iOS is running low on memory.
Open: Called when your application first starts.
UnhandledException: Called when an exception was raised in any of your code and the exception was not handled by its own Try...Catch block.

Properties

Default iPhone Screen: The Screen to display when an iPhone-sized device is used. Set this to "None" to prevent the app from working on an iPhone.
Default iPad Screen: The Screen to display when an iPad-sized device is used. Set this to "None" when you do not want a native iPad app. The app will still run on the iPad, but will do so by running the iPhone screen in the iOS "scaled" mode.

Usage

The LowMemoryWarning event handler gets called when iOS is running low on memory. Since iOS does not use virtual memory, it has to purge apps from memory when the OS detects memory is running low. Implement this event handler if your app reserves a lot of memory (large Text arrays, for example) so that you can release the memory. If you do not release the memory quick enough, iOS will just terminate the app.

The Open event handler is called when the app is launched (or relaunched if it was removed from memory). It is not called if your app remains in memory and the user switches back to it from another app. The Open event handler is a great place for app initialization code.

The UnhandledException event handler is called when an exception was raised in any of your code and the exception was not handled by its own Try...Catch block. Return True to allow your app to continue, essentially ignoring the exception (this may cause instability depending on the cause of the exception). This event is commonly used to log error information or maybe save state before the app quits. You might find it useful to put a Break statement in this event handler so that the debugger is displayed when an unhandled exception occurs. In addition, you can add some code to save the stack to an array so you can review it in the debugger:

Var stack() As StackFrame = exc.CallStack
Break

Screens

In the Inspector for App, you can specify the default screens to use when the app is run on an iPhone or an iPad. A Screen is a project item that specifies the type of layout and supported orientations. Two Screens are added by default with new projects: iPhoneScreen and iPadScreen. When you click on a Screen you are shown a preview of how it might look on the device. Refer to the UserGuide:iOS Screens topic for more information.

Build Settings

The Build Settings section of the Navigator contains the build-specific settings for your app.

Shared

The Inspector for Shared settings contains these properties:

Major Version (MajorVersion): The Major version for your app. Version numbers are usually written as 1.2.3.4, where “1” is the major version.
Minor Version (MinorVersion): The Minor version for your app. Version numbers are usually written as 1.2.3.4, where “2” is the minor version.
Bug Version (BugVersion): The Bug version for your app. Version numbers are usually written as 1.2.3.4, where “3” is the bug version.
Stage Code (StageCode): Used to indicate the type of app you are building (Development, Alpha, Beta, Final).
Non Release Version (NonReleaseVersion): The Non Release (build) version for your app. Version numbers are usually written as 1.2.3.4, where “4” is the non release version.
Auto Increment Version Info: When ON, the Non Release Version is increased by one each time you do a Build (but not when you Run).
Short Version (ShortVersion): A short text description for your app. Usually this contains just the version number (such as 1.2.3.4) and is displayed by some operating systems in Get Info or Property windows for the app.
Long Version (LongVersion): A longer text description for your app. Usually this contains the app name, copyright, version and other information. This is displayed by some operating systems in Get Info or Property windows for the app.
Package Info (PackageInfo): A text description for your app that may be displayed by some operating systems in Get Info or Property windows for the app.
Use Builds Folder: When ON, a separate folder is placed alongside the project file.
Include Function Names: When ON, the actual names of your function calls are embedded in the built app. This is useful for debugging purposes and for getting stack traces.
Language: Allows you to specify the language to use to resolve dynamic constants.
Optimization: Used for App Store builds (which use the LLVM compiler). There are these choices:
Default: Optimized for fast build times.
Moderate: A balance between build times and math-related code execution time.
Aggressive: Longer build times, but code is more optimized for faster math-related code execution time.
Simple Reference: When ON, you do not have to use namespace prefixes with any of the new framework classes used by iOS projects.
Command Line Arguments: These are the command-line arguments that are passed to your app when you run it in Debug mode.
Destination: Specifies the path where the app is located when you run it in Debug mode. If not specified, then the app is placed alongside your project file (or in a folder alongside the project file on Windows and Linux).

iOS

iOS Build Settings

The section of the Build Settings contains iOS-specific settings, including:

iOS App Name: The actual name for your iOS app. This is the name that appears on the Springboard in iOS and is the name of the actual app file.
Bundle Identifier: The bundle identifier is used by iOS as a unique descriptor for your app. It is usually specified as a reverse domain name, such as com.xojo.myapp. A bundle identifier is required for iOS apps. When submitting to the App Store, this bundle must match the bundle for the app information you created in iTunes Connect.
Team: This is the Team to use for certificates when code signing the iOS app. You have to code sign the app before it can be installed to a device or submitted to the App Store.
Build for App Store: When ON, this creates a signed package file that can be submitted to the App Store using iTunes Connect and Xcode's Application Loader. You can access this property from IDE Scripting using the name "BuildForAppStore".
Simulator Device: When debugging, this indicates the type of Simulator device to run your app on.
Architecture: Currently only 32-bit is available for debugging.

By clicking on the Advanced (Gear) tab in the Inspector you can also set the Entitlements for your iOS app. You can specify your own Info.plist that is configured with the entitlements you need or you can turn the invidividual entitlements on using the Inspector properties. Some entitlements have additional settings you'll need to make by clicking on the Options button next to the entitlement. Note that turning on an entitlement does not enable features in your app, it only requests permission (from iOS) for your iOS app to make use of the features. Do not enable entitlements for features that your app does not use or your app will likely be rejected when submitted to the App Store. Refer to Apple's Entitlements docs for more information.

Build Folder Names

Type	Architecture	Folder Name
Build	ARM	iOS
Debug	ARM	iOS Simulator

iOS App Deployment

Refer to this topic for an overview of the various ways that you can deploy iOS apps:

UserGuide:iOS Deployment Overview

UserGuide

iOS Apps

From Xojo Documentation

Contents