Xojo Documentation Xojo Documentation

A Split layout (also referred to as a split view or a split screen) 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 (or Tab). This layout is only available for iPads so you set it up on the iPadScreen used by iPad-sized devices. In landscape orientation, the master and detail appear on the screen at the same time.

In portrait orientation, by default only the detail section appears. Swipe from the left edge of the screen to the right to show the master section. See below for Declare commands to force the split to display both sections in portrait.

The Mail app included with iOS is an example of a split screen in action. When displayed in landscape orientation it displays the email messages on the left and the selected message in the detail section on the right.

Split Screen Example

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

Split Screen Layout

You configure a split screen in the iPadScreen project item. In its Inspector, go to the Content property and change the value to "Split". This displays two additional properties:

• Left (Main)
• Right (Detail)

For these two sections you can specify a View to display or you can choose to set up tabs that display within the sections. Change the layout control to "Landscape" to see how the two sections will look side-by-side.

Be sure to select an iPad device in the iOS settings to run and test the split in the iOS Simulator.

You use the iOSView.ParentSplitView property to see if a split is active. If it is not Nil then a split is active. This returns an iOSSplitView with the properties Detail and Master that allow you to get the views (or tabs) that are set for those sections. You can use these properties to cause other views to be displayed in the sections at run time.

This code (which, for example, could be on a table in the master view) changes the detail section to display a view containing customer details:

If Self.ParentSplitView <> Nil Then
Var details As New CustomerDetailsView
Self.ParentSplitView.Details = details
End If

This code pushes a new view onto whatever view is displayed in the details section:

If Self.ParentSplitView <> Nil Then
If Self.ParentSplitView.Detail IsA iOSView Then
Var info As New InfoView
iOSView(Self.ParentSplitView.Detail).PushTo(info)
End If
End If

Dynamic Split Screen

You can also create split screens at run time using the iOSSplitView class and the iOSApplication.CurrentScreen property. You can manually create a new iOSSplitView in your code, assign views to the Master and Detail properties and then assign the split to the iOSApplication.CurrentScreen property. This technique allows your app to switch between a split and a non-split screen.

To check if a split is available for use, you can use the iOSSplitView.Available shared method. You do not want to set up a split on an iPhone because only the Detail section will be visible and there will be no way to get to the Master section. This code sets up a split:

If iOSSplitView.Available Then
Var split As New iOSSplitView

Var master As New MasterView
split.Master = master

Var detail As New DetailView
split.Detail = detail

App.CurrentScreen.Content = split
End If

Using the Split Screen in Portrait

A split screen does not display both master and detail sections by default when the iPad is in portrait. Instead only the detail section is displayed. You can get to the master section by swiping from the left edge of the iPad (this technique is difficult to do in the iOS Simulator). However, you can force a split view to display both sections when the iPad is in portrait with a simple Declare command. This enum and method extend the iOSSplitView class to allow you to change how it is displayed:

Public Enum ScreenDisplayMode
Automatic = 0
PrimaryHidden
AllVisible
PrimaryOverlay
End Enum

Sub DisplayMode(Extends scr As iOSSplitView, Assigns mode As ScreenDisplayMode)
Declare Sub setPreferredDisplayMode Lib "UIKit" _
selector "setPreferredDisplayMode:" (obj As Ptr, mode As Integer)
Var intMode As Integer = Integer(mode)
setPreferredDisplayMode(scr.ViewControllerHandle, intMode)
End Sub

You can put these both on a module (and make sure they are set to Global scope). Now in your code you can change how the split displays. To force the split to always display in portrait you use this code:

Self.ParentSplitView.DisplayMode = ScreenDisplayMode.AllVisible

Because of the way the views are initialized, you should use the above code in the Activate event handler for the view that is displayed in the detail section.

Example Projects

• Examples/iOS/Controls/Navigation/SplitViewExample
• Examples/Sample Applications/EddiesElectronics/iOS/EEiOS

See Also

iOSSplitView, iOSView classes; UserGuide:iOS UI topic