# Titanium.App > The top-level App module is mainly used for accessing information about the application at runtime, and for sending or listening for system events. - Source: https://titaniumsdk.com/docs/sdk/12.6.3/Titanium.App - Titanium SDK version: 12.6.3 - Kind: module - Platforms: Android, iPhone, iPad, macOS - Since: Titanium SDK 0.1 - Extends: Titanium.Module - Inheritance: Titanium.Module > Titanium.Proxy The `App` module exposes a number of properties set in the `tiapp.xml` file. Three of these properties, the application name, ID, and URL, must be specified when the application is created. While most values may be changed by editing the `tiapp.xml` file after creating the project, the GUID is automatically generated and should not be changed. To access other application properties set in the `tiapp.xml` file not exposed by the `Titanium.App` module, see [Titanium.App.Properties](https://titaniumsdk.com/docs/sdk/Titanium.App.Properties.md). #### iOS Application Life Cycle At any given moment, you applications can be in one of the following possible states: * Not running: The app has not been launched or was running but was terminated by the system. * Inactive: The app is running in the foreground but is currently not receiving events. An app usually stays in this state only briefly as it transitions to a different state. The `pause` event is fired during this state. * Active: The app is running in the foreground and is receiving events. This is the normal mode for foreground apps. * Background: The app is in the background and executing code. Most apps enter this state briefly on their way to being suspended. * Suspended: The app is in the background but is not executing code. The system moves apps to this state automatically and does not notify them before doing so. While suspended, an app remains in memory but does not execute any code. The `paused` event is fired during this state. The system tries to keep as many apps in memory at the same time as it can, but when memory runs low it terminates suspended apps to reclaim that memory. Apps that consume large amounts of memory while in the background are the first apps to be terminated. **Responding To Interruptions** ***System Alerts*** When an **alert-based** interruption occurs, such as an incoming phone call, the app moves temporarily to the inactive state, and fires the `pause` event. The system then displays an alert to the user. The app remains in this state until the user dismisses the alert. At this point, the app either returns to the active state and fires the `resumed` event; or moves to the background state and fires the `paused` event. Alert-based interruptions result in temporary loss of control by your app and results in `pause` event being fired. Your app continues to run in the foreground, but it does not recieve touch events from the system. (It does continue to receive notifications and other types of events, such as accelerometer events.) When your app is moved back to the active state, the `resumed` event is fired. The same set of events takes place when user **double taps on the home button**. ***Sleep/Wake Button*** Pressing the **Sleep/Wake** button is another type of interruption that causes your app to move to an inactive state. When the app is in the foreground and the **Sleep/Wake button** is pressed, the the system fires the `pause` event followed by the `paused` event and becomes inactive. This is an intentionally behavioral change by Apple to conserve battery when the Sleep/Wake button is pressed. On waking up the app fires the `resume` event followed by the `resumed` event and returns the app to normal state. ***Home Button*** Pressing the **home button** is another kind of interruption. The app fires `pause` and `paused`events before going into background. When app is reopened it fires the `resume` event followed by the `resumed` event, returning the app to the normal state.
Lifecycle events fired during different interruptions
Type of Interruption Going into Background Coming into Foreground
Alert-Based/Fast App Switching pause resumed
Sleep/Wake Button pause paused resume resumed
Home Button (backgrounding) pause paused resume resumed
***Blur and Focus Events*** When using the iOS pause/resume feature, the `blur` and `focus` events do not fire before the application enters the background or after it returns to the foreground, respectively. Instead, the application needs to monitor the `pause` and `resumed` events, which relies on the underlying iOS events to determine the application state rather than the UI events. #### Application Level Events Application-level events are custom events that are defined globally for your application. By convention, application-level events are set on the `Titanium.App` module, like this: ``` js Ti.App.addEventListener('app:myCustomEvent', myHandlerFunction); ``` Adding a prefix (like 'app:' in this example) is optional, but can help ensure that your custom event names don't conflict with any future Titanium events. Application-level event listeners can be added and fired from any context, including from inside a web view, so they are ideal for communicating between separate parts of your application. When you add an event listener on a Titanium module (such as `Ti.App` or [Ti.Geolocation](https://titaniumsdk.com/docs/sdk/Titanium.Geolocation.md)), the event listener function is referenced from the global context. This means the event listener function and any objecst it references can't be garbage collected until the event listener is removed. This can lead to memory leaks if application-level event listeners are added and not removed. See also: [Event Handling](https://titaniumsdk.com/guide/Titanium_SDK/Titanium_SDK_How-tos/User_Interface_Fundamentals/Event_Handling.html) in the Titanium Mobile Guides. #### System Level Accessibility Events System-level Accessibility events include: * Events your application fires to alert the device's accessibility system of some condition or to ask it to do something. * Events fired by the device's accessibility system and listened for in your application. Currently there are four system-level accessibility events. Three of them are available for your application to fire, and one of them is for your application to listen for. ##### Firing Accessibility Events. The following accessibility events can be fired by your application to alert the accessibility system of a particular condition or to ask it to perform an action. These events are fired using [Titanium.App.fireSystemEvent](https://titaniumsdk.com/docs/sdk/Titanium.App.md#fireSystemEvent), which is available in Titanium Mobile 3.0.0. * [Titanium.App.EVENT_ACCESSIBILITY_ANNOUNCEMENT](https://titaniumsdk.com/docs/sdk/Titanium.App.md#EVENT_ACCESSIBILITY_ANNOUNCEMENT), available in iOS and Android, asks the device's accessibility system to make an announcement. The announcement itself is a string passed as the second argument to [Titanium.App.fireSystemEvent](https://titaniumsdk.com/docs/sdk/Titanium.App.md#fireSystemEvent). *How* the device's accessibility actually makes that announcement depends on what accessibility services are activated on the device. The most common are VoiceOver on iOS and TalkBack on Android. Each of those would read the announcement aloud. ``` js Ti.App.fireSystemEvent(Ti.App.EVENT_ACCESSIBILITY_ANNOUNCEMENT, "Welcome to my App"); ``` * [Titanium.App.iOS.EVENT_ACCESSIBILITY_LAYOUT_CHANGED](https://titaniumsdk.com/docs/sdk/Titanium.App.iOS.md#EVENT_ACCESSIBILITY_LAYOUT_CHANGED), available only on iOS, can be used to alert the accessibility system that the layout of the screen has changed, such as when an element appears or disappears. When your application fires this event, Titanium calls `UIAccessibilityLayoutChangedNotification` in the iOS [UIAccessibility Protocol](https://developer.apple.com/documentation/uikit/accessibility/uiaccessibility). No second parameter is required when firing this event with [Titanium.App.fireSystemEvent](https://titaniumsdk.com/docs/sdk/Titanium.App.md#fireSystemEvent). * [Titanium.App.iOS.EVENT_ACCESSIBILITY_SCREEN_CHANGED](https://titaniumsdk.com/docs/sdk/Titanium.App.iOS.md#EVENT_ACCESSIBILITY_SCREEN_CHANGED), available only on iOS, can be used to alert the accessibility system when a new view appears that comprises a major portion of the screen. When your application fires this event, Titanium calls `UIAccessibilityScreenChangedNotification` in the iOS [UIAccessibility Protocol](https://developer.apple.com/documentation/uikit/accessibility/uiaccessibility). No second parameter is required when firing this event with [Titanium.App.fireSystemEvent](https://titaniumsdk.com/docs/sdk/Titanium.App.md#fireSystemEvent). ##### Listening for Accessibility Events Currently there is only one system accessibility event which your application can listen for using [Titanium.App.addEventListener](https://titaniumsdk.com/docs/sdk/Titanium.App.md#addEventListener), namely [Titanium.App.accessibilitychanged](https://titaniumsdk.com/docs/sdk/Titanium.App.md#accessibilitychanged). This event, available on iOS and on Android (for devices running Ice Cream Sandwich or greater), is fired when the device's accessibility service is turned on or off. The object passed as a parameter to the listener function contains an `enabled` property which is `true` if the accessibility service is now turned on, or `false` otherwise. ## Properties ### accessibilityEnabled - Type: Boolean - Platforms: Android, iPhone, iPad, macOS - Permission: read-only Indicates whether Accessibility is enabled by the system. ### arguments - Type: launchOptions - Platforms: iPhone, iPad, macOS - Since: Titanium SDK 10.0.1 The arguments passed to the application on startup. On Android, fetch the [Ti.Android.rootActivity](https://titaniumsdk.com/docs/sdk/Titanium.Android.md#rootActivity) object and read its [intent](https://titaniumsdk.com/docs/sdk/Titanium.Android.Activity.md#intent) property to retrieve the parameters used to launch the application activity. Note that this [intent](https://titaniumsdk.com/docs/sdk/Titanium.Android.Activity.md#intent) will change when a "[newintent](https://titaniumsdk.com/docs/sdk/Titanium.Android.Activity.md#newintent)" event has been fired. ### copyright - Type: String - Platforms: Android, iPhone, iPad, macOS - Permission: read-only Application copyright statement, determined by `tiapp.xml`. ### currentService - Type: Titanium.App.iOS.BackgroundService - Platforms: iPhone, iPad, macOS - Permission: read-only A reference to the currnet background service running when the application is placed in the background. ### deployType - Type: String - Platforms: Android, iPhone, iPad, macOS - Permission: read-only Build type that reflects how the application was packaged. Returns one of the following values: * `development` (Simulator) * `test` (Device) * `production` (App Store / Adhoc) ### description - Type: String - Platforms: Android, iPhone, iPad, macOS - Permission: read-only Application description, determined by `tiapp.xml`. ### disableNetworkActivityIndicator - Type: Boolean - Platforms: iPhone, iPad, macOS - Since: Titanium SDK iPhone 3.0.0, iPad 3.0.0, macOS 9.2.0 - Default: `false` Prevents network activity indicator from being displayed. Setting this property to true disables display of the network activity indicator when network activity is in progress. If the network activity indicator is currently visible, it is hidden immediately. **NOTE: In general, the user should always be made aware of network activity. The network activity indicator should only be disabled for very brief network activity (a few seconds).** ### EVENT_ACCESSIBILITY_ANNOUNCEMENT - Type: String - Platforms: Android, iPhone, iPad, macOS - Since: Titanium SDK Android 3.0.0, iPhone 3.0.0, iPad 3.0.0, macOS 9.2.0 - Permission: read-only Convenience constant for system event "accessibilityannouncement". ### EVENT_ACCESSIBILITY_CHANGED - Type: String - Platforms: Android, iPhone, iPad, macOS - Since: Titanium SDK Android 3.0.0, iPhone 3.0.0, iPad 3.0.0, macOS 9.2.0 - Permission: read-only Convenience constant for system event "accessibilitychanged". ### forceSplashAsSnapshot - Type: Boolean - Platforms: iPhone, iPad, macOS Shows the application's splash screen on app resume. Note: This only works on device. When the app goes to the background a screenshot of the current app state is taken. When the app resumes that screenshot is shown for brief moment. To disable this behavior, set this property to `true` and the default splash screen will show on app resume instead. ### guid - Type: String - Platforms: Android, iPhone, iPad, macOS - Permission: read-only Application globally-unique ID, determined by `tiapp.xml`. This value is system-generated and consistent through all versions. ### id - Type: String - Platforms: Android, iPhone, iPad, macOS - Permission: read-only Application ID, from `tiapp.xml`. The application ID is a required property that must be specified when creating a new project. ### idleTimerDisabled - Type: Boolean - Platforms: iPhone, iPad, macOS Determines whether the screen is locked when the device is idle. Set to `true` to disable the timer. For Android look at [Titanium.UI.View.keepScreenOn](https://titaniumsdk.com/docs/sdk/Titanium.UI.View.md#keepScreenOn). ### installId - Type: String - Platforms: iPhone, iPad, macOS - Since: Titanium SDK iPhone 2.0.0, iPad 2.0.0, macOS 9.2.0 - Permission: read-only The install ID for this application. The application install ID is a unique identifier (UUID) for this install of the application. It is not modified by application updates; only when an application is initially installed, or removed and re-installed. ### keyboardVisible - Type: Boolean - Platforms: iPhone, iPad, macOS - Permission: read-only Indicates whether or not the soft keyboard is visible. ### name - Type: String - Platforms: Android, iPhone, iPad, macOS - Permission: read-only Application name, determined by `tiapp.xml`. ### proximityDetection - Type: Boolean - Platforms: Android, iPhone, iPad, macOS - Since: Titanium SDK Android 3.3.0, macOS 9.2.0 - Default: `false` Determines whether proximity detection is enabled. Set to `true` to receive [Titanium.App.proximity](https://titaniumsdk.com/docs/sdk/Titanium.App.md#proximity) events. ### proximityState - Type: Boolean - Platforms: Android, iPhone - Since: Titanium SDK 3.3.0 - Permission: read-only Indicates the state of the device's proximity sensor, according to the [Titanium.App.proximity](https://titaniumsdk.com/docs/sdk/Titanium.App.md#proximity) event. This property is `true` when the proximity sensor is close to the user. When [Titanium.App.proximityDetection](https://titaniumsdk.com/docs/sdk/Titanium.App.md#proximityDetection) is disabled, the value of this property is undefined. ### publisher - Type: String - Platforms: Android, iPhone, iPad, macOS - Permission: read-only Application publisher, from `tiapp.xml`. ### sessionId - Type: String - Platforms: Android, iPhone, iPad, macOS - Permission: read-only Unique session identifier for the current continuous run of the application. ### trackUserInteraction - Type: Boolean - Platforms: iPhone, iPad, macOS - Since: Titanium SDK iPhone 7.5.0, iPad 7.5.0, macOS 9.2.0 Indicates whether or not the user interaction shoud be tracked. Use the [Titanium.App.userinteraction](https://titaniumsdk.com/docs/sdk/Titanium.App.md#userinteraction) event to get notified about user interaction. For Android, user-interactions are controlled by the event and do not require this property to be set explicitely. For iOS, this is done to prevent additional overhead. ### url - Type: String - Platforms: Android, iPhone, iPad, macOS - Permission: read-only Application URL, from `tiapp.xml`. ### version - Type: String - Platforms: Android, iPhone, iPad, macOS - Permission: read-only Application version, from `tiapp.xml`. ## Methods ### fireSystemEvent - Platforms: Android, iPhone, iPad, macOS - Since: Titanium SDK Android 3.0.0, iPhone 3.0.0, iPad 3.0.0, macOS 9.2.0 Fire a system-level event such as [Titanium.App.EVENT_ACCESSIBILITY_ANNOUNCEMENT](https://titaniumsdk.com/docs/sdk/Titanium.App.md#EVENT_ACCESSIBILITY_ANNOUNCEMENT). Parameters: - `eventName` (String): The name of the event to fire. - `param` (String, optional): A parameter to be passed to the system event. ### getArguments - Platforms: iPhone, iPad, macOS - DEPRECATED since 10.0.0. Use the property instead Returns the arguments passed to the application on startup. On Android, fetch the [Ti.Android.rootActivity](https://titaniumsdk.com/docs/sdk/Titanium.Android.md#rootActivity) object and read its [intent](https://titaniumsdk.com/docs/sdk/Titanium.Android.Activity.md#intent) property to retrieve the parameters used to launch the application activity. Note that this [intent](https://titaniumsdk.com/docs/sdk/Titanium.Android.Activity.md#intent) will change when a "[newintent](https://titaniumsdk.com/docs/sdk/Titanium.Android.Activity.md#newintent)" event has been fired. Returns: launchOptions ## Events ### accessibilitychanged - Platforms: Android, iPhone, iPad, macOS - Since: Titanium SDK Android 3.0.0, iPhone 3.0.0, iPad 3.0.0, macOS 9.2.0 Fired by the system when the device's accessibility service is turned on or off. Event properties: - `enabled` (Boolean): Whether accessibility is now enabled or disabled. ### close - Platforms: Android, iPhone, iPad, macOS - Since: Titanium SDK Android 8.3.0, iPhone 1.5.0, iPad 1.5.0, macOS 9.2.0 Fired by the system when the application is about to be terminated. It is the last event that can be received before the application gets closed. ### keyboardframechanged - Platforms: iPhone, iPad, macOS - Since: Titanium SDK iPhone 3.0.0, iPad 3.0.0, macOS 9.2.0 Fired when the soft keyboard is presented, on and off the screen. This event fires when the application presents the soft keyboard on/off the screen . The event returns the dictionary `keyboardFrame` containing `x`, `y`, `height` and `width` keys, corresponding to the frame of the keyboard with respect to the screen coordinates. On Titanium SDK 4.0.0 and later the event also contains a second parameter `animationDuration` representing the duration of the animation for the presentation and dismissal of the soft keyboard. Note that the keyboard `height` and `width` properties will not be accurate when the keyboard is being dissmissed. Event properties: - `keyboardFrame` (Dimension): A dictionary with keys x, y, width and height representing the frame of keyboard on screen. - `animationDuration` (Number): The duration of the keyboard animation. This parameter is only available on Titanium SDK 4.0.0 and later. ### memorywarning - Platforms: iPhone, iPad, macOS - Since: Titanium SDK iPhone 3.2.3, iPad 3.2.3, macOS 9.2.0 Fired when the app receives a warning from the operating system about low memory availability. ### pause - Platforms: Android, iPhone, iPad, macOS - Since: Titanium SDK Android 7.5.0, iPhone 0.8, iPad 0.8, macOS 9.2.0 Fired when the application transitions from active to inactive state on a multitasked system. This event fires when the user leaves the application or for certain types of temporary interruptions such as a notification or incoming phone call. On an iPad application with split view enabled, the event will be called once the application is put in the background and a different split view application is focused. See the `applicationWillResignActive` section of the official Apple documentation about [Monitoring Application State Changes](https://developer.apple.com/documentation/uikit/uiapplicationdelegate/1622950-applicationwillresignactive) for the exact behavior that triggers this event. Note that calls to functions that modify the UI during this event may be partially executed, **up to** the UI call before the suspension. See [paused](https://titaniumsdk.com/docs/sdk/Titanium.App.md#paused) event. If this happens, the remainder of the code will be executed after the application is resumed, but before the `resume` event is triggered. ### paused - Platforms: Android, iPhone, iPad, macOS - Since: Titanium SDK Android 7.5.0, iPhone 2.1.0, iPad 2.1.0, macOS 9.2.0 Fired when the application transitions to the background on a multitasked system. This event fires when putting the application in the background using the home button or when using the sleep/wake or power button. This event fires when the user leaves the application. See the `applicationDidEnterBackground` section of the official Apple documentation about [Monitoring Application State Changes](https://developer.apple.com/documentation/uikit/uiapplicationdelegate/1622997-applicationdidenterbackground?language=objc) for the exact behavior that triggers this event. ### proximity - Platforms: Android, iPhone - Since: Titanium SDK 3.3.0 Fired when the proximity sensor changes state. The proximity sensor detects whether the device is being held up to the user's ear, and shuts down the display. Proximity events are only fired when [proximityDetection](https://titaniumsdk.com/docs/sdk/Titanium.App.md#proximityDetection) is `true`. Event properties: - `state` (Boolean): Proximity state value. ### resume - Platforms: Android, iPhone, iPad, macOS - Since: Titanium SDK Android 7.5.0, iPhone 0.8, iPad 0.8, macOS 9.2.0 Fired when the application returns to the foreground on a multitasked system. This event fires when putting the application in the background using the home button and when using the sleep/wake or power button. Note that this event does not fire for pauses resulting from notifications or incoming phone calls. See the `applicationWillEnterForeground` section of the official Apple documentation about [Monitoring Application State Changes](https://developer.apple.com/documentation/uikit/uiapplicationdelegate/1623076-applicationwillenterforeground) for the exact behavior that triggers this event. ### resumed - Platforms: Android, iPhone, iPad, macOS - Since: Titanium SDK Android 7.5.0, iPhone 0.8, iPad 0.8, macOS 9.2.0 Fired when the application returns to the foreground. This event fires when the application enters the foreground with the `resume` event or returns to focus after a notification or incoming phone call. On an iPad with split view enabled, this event will be called every time the application resized. See the `applicationDidBecomeActive` section of the official Apple documentation about [Monitoring Application State Changes](https://developer.apple.com/documentation/uikit/uiapplicationdelegate/1622956-applicationdidbecomeactive) for the exact behavior that triggers this event. Note: This event will not be fired for URL's in iOS 10+ that are handled by the or [Titanium.UI.WebView](https://titaniumsdk.com/docs/sdk/Titanium.UI.WebView.md), because Apple does not call the `applicationDidBecomeActive` for URL-handling anymore. Instead, use the `handleurl` event in [Titanium.App.iOS](https://titaniumsdk.com/docs/sdk/Titanium.App.iOS.md). ### shortcutitemclick - Platforms: Android, iPhone, iPad, macOS - Since: Titanium SDK Android 7.5.0, iPhone 7.5.0, iPad 7.5.0, macOS 9.2.0 Fired when a [Titanium.UI.ShortcutItem](https://titaniumsdk.com/docs/sdk/Titanium.UI.ShortcutItem.md) is clicked. Event properties: - `id` (String): Identifier of the clicked shortcut item. ### significanttimechange - Platforms: iPhone, iPad, macOS - Since: Titanium SDK iPhone 3.1.0, iPad 3.1.0, macOS 9.2.0 Fired when there is a significant change in the time. Examples of significant time changes include the arrival of midnight, an update to the time by a carrier, and the change to daylight savings time. If your application is currently in `paused` state, this message will be is queued until your application returns to the foreground, at which point it is delievered. If multiple changes occur, only the most recent one is delievered. ### started - Platforms: Android, iPhone, iPad, macOS - Since: Titanium SDK 8.0.0 Fired after the "app.js" or "alloy.js" gets executed during application startup. The intention of this event is for modules to defer firing their own startup related events until the app developer's main script has had a chance to add listeners for them. ### uncaughtException - Platforms: Android, iPhone, iPad, macOS - Since: Titanium SDK 4.1.0 Fired when an uncaught JavaScript exception occurs. This event will occur in both production and development builds, allowing you to warn the user that an error has occured, and log more information to help you fix any bugs. Event properties: - `message` (String): The error message. - `line` (Number): The line where the error occurred. - `sourceId` (Number): A unique identification for the source file. - `type` (String): The type of error. - `sourceURL` (String): The URL to the source file. - `title` (String): The title for the error. - `sourceName` (String): The name of the source file. - `lineSource` (String): The line source reference. - `lineOffset` (Number): The offset on the line where the error occurred. (Deprecated since 9.0.0. Use `column` instead.) - `javascriptStack` (String): The javascript stack trace of the exception. (Deprecated since 9.0.0. Use `stack` instead.) - `javaStack` (String): The java stack trace of the exception. (Deprecated since 9.0.0. Use `nativeStack` instead.) - `stack` (String): The javascript stack trace of the exception. - `nativeStack` (String): The native platform stack trace of the exception. - `column` (Number): The column offset on the line where the error occured. ### userinteraction - Platforms: Android, iPhone, iPad, macOS - Since: Titanium SDK Android 7.5.0, iPhone 7.5.0, iPad 7.5.0, macOS 9.2.0 Called whenever an interaction with the window occurred. To be used together with the [Titanium.App.trackUserInteraction](https://titaniumsdk.com/docs/sdk/Titanium.App.md#trackUserInteraction) property. Implement this method if you wish to know that the user has interacted with the device in some way while your app is running. Note that this callback will be invoked for the touch down action that begins a touch gesture, but may not be invoked for the touch-moved and touch-up actions that follow. See also: - Android: See the [onUserInteraction](https://developer.android.com/reference/android/app/Activity.html#onUserInteraction()) callback - iOS: See the [sendEvent](https://developer.apple.com/documentation/uikit/uiapplication/1623043-sendevent) delegate ## Inherited members 7 members are inherited. Each is documented on the type that declares it. - [Titanium.Proxy](https://titaniumsdk.com/docs/sdk/12.6.3/Titanium.Proxy.md): `addEventListener`, `apiName`, `applyProperties`, `bubbleParent`, `fireEvent`, `lifecycleContainer`, `removeEventListener` --- - This corpus documents Titanium SDK 13.4.1. Anything here that does not name a version describes 13.4.1. - Titanium is maintained by TiDev. The Appcelerator toolchain is retired: there is no `appc` CLI, no Appcelerator Studio and no hosted build service. The supported CLI is `titanium` on npm, invoked as `ti`.