📘

Sourcecode

Please see the UgPagesDemo project for the source code created in this chapter. See Installing examples for information on how to download the examples.

Introduction

The page is the core UI component within SCADE. Each mobile application consists of a set of pages.

• A page represents the screen content of a mobile device
• It uses a grid layout as its base layout
• Each page inherits page specific functionality from the SCDLatticePageAdapter class

Page navigation

When using the application, the user most likely navigates between some pages

• The default application already consists of a registered page, the main page
• To add additional pages, the developer has to create a new page, register it and navigate to it

Lets build a very simple example application that navigates between two different pages, main.page and settings.page

Create a new project and add a new settings page

1. Create new project (not shown)
2. Use New / ⌘N | Page to add a new page. Call the page settings.page
3. Add a button to each of the pages to switch between pages

Register the settings page

Each page must be known to the SCADE mobile application. A page is registered by calling the load method in the SCDApplication:

1. Open the start.swift file
2. add property settingspage of type SettingsPageAdapter and make it optional
3. instantiate settingspage and register the page using .load("settings.page")

🚧

Case sensitivity - Watch out and use case sensitive spelling always

Please be aware that the name of the page used in .load() is case sensitive, even if you OSX file system is configured to NOT be case sensitive.

Case sensitivity differs across different platforms, and therefore always needs to be case sensitive.

import ScadeKit

class SampleApp :  SCDApplication {

    let window = SCDLatticeWindow()
    let mainAdapter = MainPageAdapter()
    var settingspage : SettingsPageAdapter?
     
    override func onFinishLaunching() {
 
        mainAdapter.load("main.page")
        mainAdapter.show(window)

// Instantiate and load the page
		settingspage = SettingsPageAdapter()
		
		// loading the page registers the page as part of SCDApplication
		settingspage.load("settings.page")
    }
}

⌫ Smaller API cleanup will be done in one of the next versions. For instance, we will add additional constructor SettingsPageAdapter("settings.page")

Add logic to nagivate between the pages

Go and GoWith methods

1. add an OnClick event handler to each button on each page

2. use the self.navigation!.go() method to switch between pages

• Goto a page using an animation effect. Default animation is FORWARD_PUSH

self.navigation!.go("<name of page>", transition : "FORWARD_PUSH|BACKWARD_PUSH")

4. Alternatively, use the goWith method to pass data

self.navigation!.goWith("<name of page", data : <AnyDataObject>, transition : "FORWARD_PUSH")

Below the code for switching to the settings page from the main page when clicking the button

import ScadeKit

class MainPageAdapter: SCDLatticePageAdapter {

	// page adapter initialization
	override func load(_ path: String) {		
		super.load(path)
		let btn1 = self.page!.getWidgetByName("button1") as! SCDWidgetsButton
		btn1.onClick.append( SCDWidgetsEventHandler{ _ in self.gotoSettingsPage() })
	}
 
	func gotoSettingsPage() {
		
		// You can use either FORWARD_PUSH or BACKWARD_PUSH to specify 
		// the animation to change between pages
		self.navigation!.go("settings.page", transition : "FORWARD_PUSH")
	}
}

⌫ Will will introduce enumerations to specify the transition effect type shortly

Using the load method

The load method happens only once, when the page is loaded. You want to use the load method to

• setup and initialize data structures
• create references to UI objects
• setup events
• you may want to code data loading logic. Alternatively leave this to the enter event

The following sample page implementation illustrates the use of the methods:

import ScadeKit

class SamplePageAdapter: SCDLatticePageAdapter {

	// page adapter initialization
	override func load(_ path: String) {		
		super.load(path)
		
		// Use the load method after calling the super
		// to setup references. At this point, you CANNOT 
		// call any native control's functionality
		
		let button1 = self.page!.getWidgetByName("button1") as! SCDWidgetsButton
		button1.onClick.append(SCDWidgetsEventHandler{ _ in print("do sth")})
	}
}

📘

Best practice

• Use the load() method to setup references and events
• Code a loadData() or similar method that takes care of the loading of the data that is to be displayed
• execute the loadData() at the end of the load method to load data once
• in the method attached to the onEnter event, add logic that checks if you want to (re)load / refresh the data and if that's the case, load the data again

Page events

Page events occur when you enter or exit a page.

There are different page events that you can listen to:

• onEnter event is triggered when the user is entering the page using the navigation.go method
• onExit event is triggered when the user leaves the page

Both events should be setup in the load method of the page

• Add an event handler of type SCDWigetsEnterEventHandler to
• add an exit event of type SCDWidgetsExitEventHandler
• the enterEvent object is of Type SCDWidgetsEnterEvent
  • SCDWidgetsEnterEvent has one property data
  • data is containing the object passed in the goWith(,data) method
  • make sure do deal with optionality using ! and ? operators to unwrap the data

func enterPage(event:SCDWidgetsEnterEvent) {
		
    // We assume we passed a String object in the 
    // navigation.go() method
    let data = event.data as! String
    print("My past data :\(data)")
}

Processing page click event

A page click event is triggered when clicking on a page. To process a click event on a page, use onClick

• use SCDWidgetsEventHandler
• use SCDWidgetsEvent (if necessary) to type the event

// React to onClick events
self.page!.onClick.append( SCDWidgetsEventHandler { (event:SCDWidgetsEvent?) in print(event) })

// this version might be shorter, as the event itself doesnt hold much useful information
self.page!.onClick.append( SCDWidgetsEventHandler { _ in print("page clicked") })