UserGuide

iOS Screens

From Xojo Documentation

A Screen defines how your initial layout appears on the iOS device. By default your iOS project contains two screens: iPhoneScreen and iPadScreen You can change the preview mode for the screen by using the toolbar buttons to change the orientation (portrait or landscape) and the device type. These settings affect the preview only, are not saved, and do not affect how the app runs in the Simulator or on the device. Use the Supported Orientations settings to control how the app displays when run.

The Inspector for a Screen has two sections of importance: Screen Layout and Supported Orientations.

The Screen Layout setting allows you to specify the Content property, which determines how the display looks and works. There are three choices: View, Split and Tabs.

Screen Layout

Mail Split View

A Screen have have several layouts styles, including just a single View, a Split of two views and tabs for multiple views.

View

By default, Screen Layout simply points to View1. This is the initial view that will be displayed on the screen, filling it entirely. You can change this to point to any View that is in your project. New Views can be displayed over this default view by calling the PushTo method on View. You can also use the CurrentScreen property to change the initial screen.

Split

A Split layout (SplitView) allows you to split the screen into two sections: a master on the left and a detail on the right. Each of these sections is its own View. This layout is only available on the iPadScreen used by iPad-sized devices. In landscape orientation, the master and detail appear on the screen at the same time.

iOS Split Settings

In portrait orientation, only the details view appears. Swipe from the left edge of the screen to the right to show the master view. The Mail app included with iOS is an example of a SplitView in action (when displayed in landscape orientation). It displays the email messages on the left and the selected message in the detail area on the right.

You can also have each section of a Split be a Tab for further granularity.

Tabs

Much like with a desktop app, the tabs layout allows you to have multiple views that the user can select by using the tab control. In the case of iOS apps, the tab control is displayed at the bottom of the screen. For an example, the iOS Clock app uses tabs at the bottom to select the type of clock you want to use. Use the Edit button for the Tabs property to add or remove tabs, specifying their name or icon. Use the Tab Content property to specify the initial View to display for each tab.

iOS Tab Settings

You need to click on each tab on the Screen to change the selected tab so that you can set the Tab Content property for it.

Supported Orientations

You can control the types of orientations that are allowed using the Supported Orientation settings of the Inspector for the iPhone and iPad screens. There are four options:

  • Portrait (Home on Bottom)
  • Landscape (Home on Left)
  • Landscape (Home on Right)
  • Portrait (Home on Top)

By default, each of these settings is set to ON. If you want to disable an orientation for your app, set it to NO. For example, it is common for iPhone apps to have Portrait (Home on Top) disabled and many iPhone apps also have Landscape orientations disabled.

App Multitasking

Starting with iOS 9, some iPads support app multitasking which allows you to use more than one app at a time on the device. Your app automatically supports this if all the "Supported Orientations" are turned on. If you turn off any supported orientations, then your app cannot be used by iOS app multitasking.

For iOS apps made with Xojo 2016r3 and earlier: If any supported orientations are turned off you will need to manually include a plist file to tell the app store that your app does not support app multitasking (and avoid the ITMS-90474 error):

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
   <key>UIRequiresFullScreen</key>
   <true></true>
</dict>
</plist>

Device Rotation

When the user rotates the device to change its orientation, the Resized event handler on the currently displayed View is called. In this event handler, you can check the size of the View (using its Size method) to see if it is now in portrait or landscape. With this information, you can then decide to reposition controls or to display a completely different view, allowing you to have one view for portrait and one for landscape. To check if the view is in landscape, check if the height is greater than the width:

If Self.Size.Height > Self.Size.Width Then
// Landscape
End If

To check if the view is portrait, check if the height is less than the width:

If Self.Size.Height < Self.Size.Width Then
// Portrait
End If

If you not use any special processing, the auto-layout rules you have specified for the controls on the view will adjust your controls. For example, a text field may expand to use more available width when a device is rotated from portrait to landscape.

Changing Screens at Run-Time

You can add additional screens (in addition to the default iPhoneScreen and iPadScreen) to your project. You can then switch these screens to display at run-time by using the iOSApplication.CurrentScreen property like this:

Dim s As New MySpecialScreen
App.CurrentScreen.Content = s.Content

When you do this the screen is immediately replaced and the View hierarchy that is accessible with the Back button on the Navigation bar is lost.

Example Projects

  • Examples/Navigation/NavigationExample
  • Examples/Navigation/PushToExample
  • Examples/Navigation/SplitViewExample

See Also

iOSScreen class; UserGuide:iOS Views, UserGuide:iOS UI topics