Android, Titanium

Android orientation locking for Titanium

Locking the orientation of a Titanium Android app if fairly straightforward after you’ve done it once or twice.  I thought it would be helpful to outline the steps that I follow to lock several of my applications in a portrait orientation.

To start with you first must build your Titanium Android app.  It doesn’t matter if you have any functionality in your project yet.  You just need to make sure an AndroidManifest.xml file is created in your project’s build/android folder.  Once you have done a build, you will need to open your AndroidManifest.xml and look for the android:name property of your launch activity.  You can see an example of this in the below snippet found in our AndroidTest AndroidManifest.xml. Look for the .AndroidtestActivity line.  This is the line and pattern you will want to look for in your project’s AndroidManifest.xml file.

<?xml version="1.0" encoding="UTF-8"?>
<manifest xmlns:android="http://schemas.android.com/apk/res/android" >
	<application android:icon="@drawable/appicon" 
           android:label="AndroidTest" 
           android:name="AndroidtestApplication" 
           android:debuggable="false" 
           android:theme="@style/Theme.AppCompat">
		<activity 
                 android:name=".AndroidtestActivity" 
                 android:label="@string/app_name" 
                 android:theme="@style/Theme.Titanium"       
                 android:configChanges="keyboardHidden|orientation|screenSize">
		   <intent-filter>
		     <action android:name="android.intent.action.MAIN"/>
		     <category android:name="android.intent.category.LAUNCHER"/>
		    </intent-filter>
		</activity>
	</application>
</manifest>

You can see the naming convention is a period then your project name with the first letter capitalized followed by Activity.  In our example project this is .AndroidtestActivity. This is the pattern you will want to look for in your AndroidManifest.xml.

Once you have the activity name of your launch activity you will want to replace the default Android configuration with a new template.

First open your project’s tiapp.xml and locate the below default Android entry.

<android xmlns:android="http://schemas.android.com/apk/res/android"/>

Replace the default information with the below template.

    <android xmlns:android="http://schemas.android.com/apk/res/android">
        <manifest>
            <application>
                <activity
                    android:configChanges="keyboardHidden|orientation|screenSize"
                    android:screenOrientation="portrait"
                    android:name="[replace me]">
                    <intent-filter>
                        <action android:name="android.intent.action.MAIN"/>
                        <category android:name="android.intent.category.LAUNCHER"/>
                    </intent-filter>
                </activity>
                <activity
                    android:configChanges="keyboardHidden|orientation|screenSize"
                    android:name="org.appcelerator.titanium.TiActivity" 
                    android:screenOrientation="portrait"/>
                <activity
                    android:configChanges="keyboardHidden|orientation|screenSize"
                    android:name="org.appcelerator.titanium.TiTranslucentActivity"
                    android:screenOrientation="portrait" android:theme="@style/Theme.AppCompat.Translucent"/>
            </application>
        </manifest>
    </android>

Next replace the [replace me] placeholder with the name of the launch activity you found earlier.  The below example shows this replacement being done for our AndroidTest app.  Please remember to remove the brackets when making the replacement.

    <android xmlns:android="http://schemas.android.com/apk/res/android">
        <manifest>
            <application>
                <activity
                    android:configChanges="keyboardHidden|orientation|screenSize"
                    android:screenOrientation="portrait"
                    android:name=".AndroidtestActivity">
                    <intent-filter>
                        <action android:name="android.intent.action.MAIN"/>
                        <category android:name="android.intent.category.LAUNCHER"/>
                    </intent-filter>
                </activity>
                <activity
                    android:configChanges="keyboardHidden|orientation|screenSize"
                    android:name="org.appcelerator.titanium.TiActivity" 
                    android:screenOrientation="portrait"/>
                <activity
                    android:configChanges="keyboardHidden|orientation|screenSize"
                    android:name="org.appcelerator.titanium.TiTranslucentActivity"
                    android:screenOrientation="portrait" android:theme="@style/Theme.AppCompat.Translucent"/>
            </application>
        </manifest>
    </android>

Next you will need to tell Alloy to only create Windows with a portrait orientation.  This is super easy and can be done by adding one class to your app.tss as shown below.  Your app.tss can be located in your app/styles folder.  If your project doesn’t already contain an app.tss you can create one by simply creating a file called app.tss in your project’s style folder.  To learn more about global styles please read the documentation available here.  The following snippet creates a global style for the windows in your project setting the orientation to portrait.

"Window" : {
	orientationModes :[
		Ti.UI.PORTRAIT
	]
}
FAQ:
  • Q: Why lock at the Android Activity level, isn’t adding the Alloy style enough?
  • A: Unfortunately no. The Alloy style is applied after the window is created. So if the device is held in a landscape orientation you will see the window open and turn. Locking at the Android Activity level stops this behavior.
  • Q: Does this mean all of my Ti.UI.Window object will be locked in portrait?
  • A: Yes, this locks both at the Android Activity and Titanium object levels.
  • Q: Can I later change the orientation by updating my Ti.UI.Window orientation?
  • A: No, orientation is locked at the Android Activity level as well.